``` Only a `const` initialised with a string literal is followed, and a name declared twice in one file is left alone rather than guessed at. A key the call site computes at runtime has no class to name, so it is reported as `dynamic-style-access` and its definitions stay in Plumeria. ### Dynamic function styles [#dynamic-function-styles] Function styles such as `(width) => ({ width })` are converted into CSS custom properties (e.g. `----`). In JSX, the codemod passes argument values through the inline `style` prop: ```diff -

``` The key is written as a computed string because React's `CSSProperties` has no room for a custom property. If an existing `style` prop is present, the CSS variables are merged into it. ### Style composition [#style-composition] An array with no condition in it collapses into a single class that `composes` its members, so the call site reads as one name: ```diff -

``` ```css title="ButtonLink.module.css" .buttonBaseMedium { composes: button base medium; } ``` `composes` copies nothing, so the stylesheet does not grow, and the reverse migration reads it straight back into an array. Any other array is joined as it stands. `filter` is added only where a condition can make a member falsy, so that branch drops out at runtime: ```diff -

``` ### Previewing the migration [#previewing-the-migration-1] Start with `-d` or `--dry-run` to inspect the exported style modules and rewritten sources without writing files: ```sh title="Terminal" npx @plumeria/codemod migrate --from plumeria --dry-run ``` ``` src/Card.tsx -> src/Card.module.css global styles -> src/styles/global.css 1 style module(s) would be exported, 1 source file(s) rewritten. Run without --dry-run to apply. ``` ### What it reports instead of converting [#what-it-reports-instead-of-converting-1] Constructs that cannot be statically resolved or exported without changing runtime behavior are reported, and the original Plumeria definitions are left in place: ``` src/Card.tsx 8:5 dynamic-value The value of `color` cannot be represented statically. 12:3 spread-create Top-level spreads cannot name a CSS Module class. ``` * Dynamic values, computed properties, or runtime function calls in style objects * Object spreads in top-level `css.create` or style definitions, other than `css.marker` * Existing `*.module.css` target files are reported as `target-exists` and will not be overwritten ### Composition order after the export [#composition-order-after-the-export] `classStyle={[styles.b, styles.a]}` resolves `color` to `styles.a`: the rightmost style wins the merge. A stylesheet has no array to read — both classes land on the element and the cascade decides — so the export reproduces the array order by three means, in order of cost. **Declaration order.** Every composition in the project is read as a constraint, and the classes are emitted in an order that satisfies all of them at once. Most projects need nothing else, and nothing is duplicated. A constraint is only recorded where the two classes actually disagree, measured per at-rule and per selector. `.wide { width }` and `.narrow { @media (…) { width } }` name the same property but never contend — an at-rule declaration already outranks a base one — so they impose no order. Not every disagreement is the array's to settle. Where one property covers another — `padding` against `padding-top` — Plumeria gives the longhand more specificity, so it wins wherever the two meet and the call site order never enters into it. The export writes the shorthand first instead, inside a rule and between rules alike, which reaches the same answer without the array. Only a partial overlap, `borderColor` against `borderTop`, is left for the call site to decide. **A composed class.** When two call sites compose the same pair in opposite orders, no declaration order satisfies both. If either call site has no condition in it, it collapses into a class of its own and stops asking. **An override class.** What is left is a call site whose members are decided at runtime. It carries an extra class holding only the disputed declarations, applied under the same condition as the style that has to win: ```diff title="Panel.tsx" -

``` ```css title="Panel.module.css" .surfaceOverRaised:not(#\#) { padding: 8px; color: black; } ``` `:not(#\#)` matches no element and adds an id to the specificity, so the override outranks both classes wherever it lands. It is named after the call site that needs it, so two call sites never fight over one. Anything none of the three settles is reported as `composition-order` and left in Plumeria. ### Running it twice [#running-it-twice] The migration is idempotent. The first run converts; every run after it is a fixed point: $f(f(x)) = f(x)$ A second run finds no `css.create` to export, reports `target-exists` for the definition files it deliberately left behind, and writes nothing. The generated block in `global.css` is fenced by a marker comment and replaced rather than appended, so it does not grow. This holds even when the first run left styles behind: clear a report, run again, and only the newly resolvable files move. Plumeria's own documentation site and end-to-end site go through the whole cycle on every CI run — exported, exported again, adopted back, adopted back again, and exported once more. Each pass has something to prove: the export must not leave a type error behind or name a class it never wrote, the second export must move nothing, the adoption must not leave a consumer reading a `*.module.css`, the second adoption must move nothing, and the project that came back must export again without a new report or a new type error. Byte equality with the first export is not the claim. A round trip folds a constant that only named a style key and gives a merged class a name, and exporting that reaches further than the first export did — the point is that nothing breaks and nothing new is refused. The exported site is also served and compared against the Plumeria one screenshot by screenshot, so the cycle is measured on the rendered page and not only in the source. ## Renaming the styling prop [#renaming-the-styling-prop] ```sh title="Terminal" npx @plumeria/codemod rename-prop [paths...] ``` `paths` default to the current directory. `dist`, `build`, `out`, `.next` and `coverage` are always skipped, and the transform reads `.js`, `.jsx`, `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts` and `.cts`. | Option | Description | | ----------------- | ---------------------------------------- | | `-d`, `--dry-run` | report what would change without writing | | `--no-types` | leave TypeScript declarations untouched | | `-h`, `--help` | show usage | | `-v`, `--version` | show the version | Start with `--dry-run`: ```sh title="Terminal" npx @plumeria/codemod rename-prop classStyle sx --dry-run ``` ``` src/Card.tsx 3 src/page.tsx 1 4 occurrence(s) in 2 file(s) would become "sx". Run without --dry-run to apply. 2 occurrence(s) need a manual rename — "classStyle" is bound to a local name there: src/Card.tsx:8:24 src/Card.tsx:12:71 ``` Drop the flag to apply. The report is the same, with the count confirmed rather than predicted: ``` ✔ renamed 4 occurrence(s) of "classStyle" to "sx" in 2 file(s). ``` If the git working tree is dirty, it says so before writing — the rewrite is much easier to undo from a clean tree. ## What it rewrites [#what-it-rewrites] **JSX attributes.** ```diff -

``` **Property signatures annotated with `Style`.** That covers your `plumeria.d.ts` as well as the props of your own components: ```diff interface CardProps { - classStyle?: Style; + sx?: Style; } ``` The annotation has to be `Style` or `Plumeria.Style`, so an unrelated interface that happens to use the same key is left alone. Pass `--no-types` to skip declarations entirely. ## What it reports instead of rewriting [#what-it-reports-instead-of-rewriting] Where the prop is destructured, or read off an object, the name is a local binding and not only a prop: ```tsx const Card = ({ classStyle }: CardProps) =>

; const Panel = (props: CardProps) =>

; ``` The attribute is safe to rewrite; the binding is a judgement call about the surrounding code. Those sites are listed with their positions so you can finish them by hand: ```diff const Card = ({ classStyle, title }: CardProps) => ( -

{title}

); ``` Renaming the parameter as well is the usual next step — the codemod just will not guess it for you. ## Names it refuses [#names-it-refuses] `` has to be a valid identifier, has to differ from ``, and cannot be a prop React already handles — `className`, `key`, `ref`, `children` or `style`: ``` ✖ "style" is already used by React ``` Files that fail to parse are reported at the end and the command exits with `1`, so a broken file cannot be mistaken for a file with nothing to rename. ## After the rewrite [#after-the-rewrite] The codemod changes your source; it does not change your configuration. Point the toolchain at the new name: ```ts title="next.config.ts" export default withPlumeria({}, { styleProp: 'sx' }); ``` ```ts title="eslint.config.ts" export default [ { settings: { plumeria: { styleProp: 'sx' } }, }, ]; ``` And point the type declaration at the same name — see [classStyle & use()](/docs/api-reference/javascript/use) for the reference that declares the prop. One practical note: the codemod does not reformat. If the new name is longer than the old one, lines that were near your print width can cross it. Run your formatter afterwards. ## It is not only for migrations [#it-is-not-only-for-migrations] The names are arguments, so the transform is not tied to any particular release. Renaming the prop to whatever suits your codebase is the same command: ```sh title="Terminal" npx @plumeria/codemod rename-prop styleName classStyle npx @plumeria/codemod rename-prop classStyle sx ``` --- # API Reference Source: https://plumeria.dev/docs/api-reference Plumeria provides a set of powerful APIs and plugins to help you build type-safe, performant styles. ## JavaScript API [#javascript-api] The core JavaScript APIs for defining styles, themes, and animations. ## Plugins [#plugins] Integrate Plumeria with your favorite tools and frameworks. ## Tools [#tools] Command line tools for maintaining a Plumeria codebase. --- # Editor integration Source: https://plumeria.dev/docs/getting-started/editor-integration
## className snippet for style macro [#classname-snippet-for-style-macro] In VScode create a shortcut for the style.use() object expansion in className.\ `shift + command + p >`\ `select >` Snippets: Configure Snippets\ `select >` typescriptreact.json (TypeScript JSX) or javascriptreact.json (JavaScript JSX) ```json title="typescriptreact.json" { "classStyle": { "prefix": "class", "body": "classStyle={$1}", "description": "Plumeria classStyle", } } ``` This will make the snippet appear at the top. ```json title="settings.json" { // ...other settings "editor.snippetSuggestions": "top", // ... } ``` ### Macro Usage [#macro-usage] ```jsx

-> Enter ->

``` ## ESLint [#eslint] It is the plumeria [Linter `@plumeria/eslint-plugin` package](https://www.npmjs.com/package/@plumeria/eslint-plugin)\ The eslint-plugin `plumerialint` command is integrated with `oxlint`. ```sh title="Terminal" npm i --save-dev @plumeria/eslint-plugin oxlint ``` ```sh title="Terminal" pnpm i --save-dev @plumeria/eslint-plugin oxlint ``` ```sh title="Terminal" yarn add -D @plumeria/eslint-plugin oxlint ``` By incorporating it into your build pipeline, you can proactively detect style warnings and errors and immediately terminate the build midway: `plumerialint`. ```json title="package.json" "build": "plumerialint && css && next build", ``` ```js title="eslint.config.ts" import eslint from '@eslint/js'; import tseslint from 'typescript-eslint'; import { defineConfig } from 'eslint/config'; import plumeria from '@plumeria/eslint-plugin'; export default defineConfig( eslint.configs.recommended, tseslint.configs.recommended, plumeria.configs.recommended, // [!code ++] { files: ['**/*.{ts,tsx}'], } ); ``` ```js title="eslint.config.js" const eslint = require('@eslint/js'); const tseslint = require('typescript-eslint'); const { defineConfig } = require('eslint/config'); const { plumeria } = require('@plumeria/eslint-plugin'); module.exports = defineConfig( eslint.configs.recommended, tseslint.configs.recommended, plumeria.flatConfigs.recommended, // [!code ++] { files: ['**/*.{ts,tsx}'], } ); ``` ```json title=".eslintrc.json" { "plugins": ["@plumeria"], "extends": ["plugin:@plumeria/recommended"], "rules": {} } ``` You can jump to definitions from styles even if they are not written in JSX `command or Alt + click`. --- # Getting started Source: https://plumeria.dev/docs/getting-started If you're new to Plumeria, you can follow these steps to get started. ## Install Plumeria [#install-plumeria] ```bash title="Terminal" npm install -D @plumeria/core ``` ```bash title="Terminal" yarn add -D @plumeria/core ``` ```bash title="Terminal" pnpm add -D @plumeria/core ``` To learn more about installing `@plumeria`, see the [installation guide](/docs/getting-started/installation). ## Choose your learning path [#choose-your-learning-path] --- # Installation Source: https://plumeria.dev/docs/getting-started/installation ## Installing `core` [#installing-core] The core package is type definitions only. bundle and runtime are not included.\ Skip to your bundler: [Next.js](/docs/getting-started/installation#nextjs) / [Vite](/docs/getting-started/installation#vite) {/* prettier-ignore */} ```sh title="Terminal" npm i -D @plumeria/core ``` {/* prettier-ignore */} ```sh title="Terminal" yarn add -D @plumeria/core ``` {/* prettier-ignore */} ```sh title="Terminal" pnpm i -D @plumeria/core ``` ## ESLint Setup [#eslint-setup] By implementing `ESLint`, you can automatically organize the order of CSS properties and format line breaks, creating a more efficient environment than manual maintenance. The plumerialint command installs [`@plumeria/eslint-plugin`](/docs/getting-started/editor-integration).\ Setting `languageOptions.parserOptions.projectService` to `true` enables `"@plumeria/no-invalid-selector-nesting"` by utilizing TypeScript type information. ```ts import eslint from '@eslint/js'; import tseslint from 'typescript-eslint'; import { defineConfig } from 'eslint/config'; import { plumeria } from '@plumeria/eslint-plugin'; export default defineConfig( eslint.configs.recommended, tseslint.configs.recommended, plumeria.flatConfigs.recommended, { files: ['**/*.{ts,tsx}'], languageOptions: { parserOptions: { projectService: true }, }, } ); ``` `oxlint` is required to run the `plumerialint` command.\ Integrating `plumerialint` into your build pipeline allows for proactive error detection. ```sh pnpm i -D oxlint rimraf ``` For `Next`, we recommend running rimraf to clean up the cache to accommodate the differences between versions: ```json title="package.json" "scripts": { "predev": "rimraf .next", "prebuild": "rimraf .next", "dev": "next dev", "build": "plumerialint -- next build", "start": "next start", }, ``` ```json title="package.json" "scripts": { "dev": "vite", "build": "plumerialint -- tsc -b && vite build", }, ``` ## Integration [#integration] ## Next.js [#nextjs] {/* prettier-ignore */} ```sh title="Terminal" npm i -D @plumeria/next-plugin ``` ```sh title="Terminal" yarn add -D @plumeria/next-plugin ``` ```sh title="Terminal" pnpm add -D @plumeria/next-plugin ``` ### plumeria.d.ts [#plumeriadts] `@plumeria/core` ships no prop declaration of its own, so name the styling prop your project compiles with. ```ts title="plumeria.d.ts" /* application root */ /// ``` ### next.config.ts [#nextconfigts] It works with both Turbopack and Webpack. ```ts title="next.config.ts" import type { NextConfig } from "next"; import { withPlumeria } from "@plumeria/next-plugin"; const nextConfig: NextConfig = { /* config options here */ }; export default withPlumeria(nextConfig); ``` *** ## Vite [#vite] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm add -D @plumeria/unplugin ``` ### vite.config [#viteconfig] ```ts title="vite.config.ts" import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react-swc'; import plumeria from '@plumeria/unplugin'; export default defineConfig({ plugins: [react(), plumeria.vite()], }); ``` --- # Selector rules Source: https://plumeria.dev/docs/getting-started/selector-rules ## Nesting [#nesting] Pseudo-elements(class) and media nesting rules.\ Queries(media・container) can only be pseudo nest once, but pseudo cannot nest queries. ```ts title="TypeScript" {1} import * as css from '@plumeria/core'; const styles = css.create({ list: { '@media (max-width: 768px)': { // [!code ++] ':hover': { // [!code ++] listStyleType: 'none', // [!code ++] }, // [!code ++] }, // [!code ++] }, }); ``` *** Unacceptable examples: ```ts title="TypeScript" {1} import * as css from '@plumeria/core'; const styles = css.create({ list: { ':hover': { '@media (max-width: 768px)': { // [!code --] background: 'skyblue', // [!code --] }, // [!code --] }, }, }); ``` ## Reason [#reason] This design intentionally avoids reverse nesting. * Type system limitations (recursive types) * Avoiding reverse nesting complexity * Ensuring consistent nesting patterns --- # Bun Source: https://plumeria.dev/docs/integration/bun [`examples/bun`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-bun) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in bun.\ The unplugin compiles Plumeria styles into the CSS asset produced by bun. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```ts title="scripts/build.js" import plumeria from '@plumeria/unplugin'; await Bun.build({ entrypoints: ['./src/index.tsx'], outdir: './dist', plugins: [plumeria.bun()], }); ``` --- # Component Library Source: https://plumeria.dev/docs/integration/component-library A component library built with Plumeria ships already compiled. The class names sit in the JavaScript and the rules sit in a stylesheet, so the people installing it need no bundler plugin, no PostCSS step, and no dependency on Plumeria. Every bundler in this section produces that dist. [esbuild](/docs/integration/esbuild) is the fastest of them, so it is the one shown here. ## What ends up in dist [#what-ends-up-in-dist] Given a component like this: ```tsx title="src/index.tsx" import * as css from '@plumeria/core'; const styles = css.create({ card: { display: 'flex', padding: '16px', borderRadius: '8px' }, title: { fontSize: '18px', fontWeight: 'bold' }, }); export const Card = ({ title }: { title: string }) => (

{title}

); ``` the build emits this: ```js title="dist/index.js" import './index.css'; import { jsx } from 'react/jsx-runtime'; var Card = ({ title }) => jsx('div', { className: 'xxp6epoh xqqbxt1d xyqr9vb7', children: jsx('h2', { className: 'xpdfgu2b xybc5i37', children: title }), }); export { Card }; ``` ```css title="dist/index.css" .xxp6epoh { display: flex; } .xqqbxt1d { padding: 16px; } .xyqr9vb7 { border-radius: 8px; } .xpdfgu2b:not(#\#) { font-size: 18px; } .xybc5i37:not(#\#) { font-weight: 700; } ``` The `css.create` call and the `@plumeria/core` import are gone. What is left is a string literal per element and a flat list of rules — nothing that merges objects or builds class names while your users render. ## Build [#build] Extracting CSS means the bundler takes the import out of the JavaScript, which is right for an app — the HTML links the stylesheet — and wrong for a library, where there is no HTML. Point the built JavaScript back at its stylesheet and your users inherit it by importing the component. ```js title="build.js" import esbuild from 'esbuild'; import fs from 'node:fs'; import plumeria from '@plumeria/unplugin'; await esbuild.build({ entryPoints: ['src/index.tsx'], bundle: true, outfile: 'dist/index.js', external: ['react', 'react/jsx-runtime'], plugins: [plumeria.esbuild({ include: /\.[jt]sx?$/ })], loader: { '.tsx': 'tsx', '.ts': 'ts' }, format: 'esm', jsx: 'automatic', }); fs.writeFileSync( 'dist/index.js', `import './index.css';\n${fs.readFileSync('dist/index.js', 'utf-8')}`, ); ``` **Build tools — esbuild, Bun, Rollup, Rolldown.** They emit the files you asked for and stop. The stylesheet is extracted and left unattached, so the line above is what connects it. This is the usual path for shipping a library. **Bundlers — Vite, Webpack, Rspack, Farm.** They own the whole graph, so they follow the import and wire the stylesheet in themselves — into the HTML they emit, or into the JavaScript. Either way you write nothing. Point one at a library, where there is no application to wire, and the line is needed again. ## Publish [#publish] Plumeria belongs in `devDependencies`. It runs while you build and has nothing to do at your users' runtime. ```json title="package.json" { "name": "your-lib", "type": "module", "files": ["dist"], "exports": { ".": "./dist/index.js" }, "peerDependencies": { "react": ">=18" }, "devDependencies": { "@plumeria/core": "^18.1.2", "@plumeria/unplugin": "^18.1.2" } } ``` ## What your users write [#what-your-users-write] ```tsx title="app.tsx" import { Card } from 'your-lib'; export const App = () => ; ``` That is the whole integration. The component brings its own stylesheet, their bundler config is untouched, and their `package.json` never names `@plumeria/*`, whatever they build with. --- # esbuild Source: https://plumeria.dev/docs/integration/esbuild [`examples/esbuild`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-esbuild) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in esbuild.\ The unplugin compiles Plumeria styles into the CSS asset produced by esbuild. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```ts title="scripts/build.js" import esbuild from 'esbuild'; import plumeria from '@plumeria/unplugin'; esbuild .build({ entryPoints: ['src/index.tsx'], bundle: true, outfile: 'dist/bundle.js', plugins: [ plumeria.esbuild({ include: /\.[jt]sx?$/, }), ], loader: { '.tsx': 'tsx', '.ts': 'ts', }, format: 'esm', minify: false, }) .catch(() => process.exit(1)); ``` --- # Farm Source: https://plumeria.dev/docs/integration/farm [`examples/farm`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-farm) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in Farm.\ It compiles styles into CSS via AST parsing, with HMR support. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```ts title="farm.config.ts" import { defineConfig } from '@farmfe/core'; import plumeria from '@plumeria/unplugin'; export default defineConfig({ plugins: [ plumeria.farm({ devEmitToDisk: true, }), ], }); ``` --- # Frameworks Source: https://plumeria.dev/docs/integration/frameworks Plumeria compiles the `css` calls, not the component. Any framework Vite can build reaches it through the same [`@plumeria/unplugin`](/docs/integration/vite) entry — put `plumeria.vite()` in `plugins` beside the framework plugin. ```ts title="vite.config.ts" import { defineConfig } from 'vite'; import vue from '@vitejs/plugin-vue'; import plumeria from '@plumeria/unplugin'; export default defineConfig({ plugins: [vue(), plumeria.vite()], }); ``` That file is the whole integration. [`examples/vite-vue-ts`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-vue-ts), [`examples/vite-svelte-ts`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-svelte-ts), [`examples/vite-solid`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-solid), [`examples/vite-preact`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-preact), [`examples/vite-qwik`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-qwik), [`examples/react-router`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-react-router) and [`examples/storybook`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-storybook) are that file with the framework plugin swapped. ## The styling prop [#the-styling-prop] `@plumeria/core/class-style` declares `classStyle` on React's `HTMLAttributes` and `SVGAttributes`, so anything rendering through the React namespace needs one line: ```ts title="plumeria.d.ts" /// ``` A framework that keeps its JSX types in its own module cannot be reached that way. Module augmentation resolves the package from the file that writes it, and `@plumeria/core` does not depend on your framework, so the declaration has to live in your project: ```ts title="types.d.ts" import 'preact'; import type { Style } from '@plumeria/core'; declare module 'preact' { namespace JSX { interface HTMLAttributes { classStyle?: Style; } interface SVGAttributes { classStyle?: Style; } } } ``` ```ts title="types.d.ts" import '@builder.io/qwik'; import type { Style } from '@plumeria/core'; declare module '@builder.io/qwik' { interface HTMLAttributes extends JSX.HTMLAttributes { classStyle?: Style; } interface SVGAttributes extends JSX.SVGAttributes { classStyle?: Style; } } ``` Declare `SVGAttributes` even where the framework has it extend `HTMLAttributes` and one interface would do — Qwik's extends `AriaAttributes` instead, and an `

card

``` The lint rules read the same TypeScript, so the style module is covered by them. The plugin receives the component file whole, before the framework splits its script block out, so a `css.create` written inside one fails the build on the surrounding markup: ``` [plugin @plumeria/unplugin:vite] src/components/HelloWorld.vue Error: x Expected ' --- # Integration Source: https://plumeria.dev/docs/integration Plumeria's Integration is broken up into the following sections: ## Bundlers [#bundlers] ## Frameworks [#frameworks] ## Distribution [#distribution] --- # Next.js Source: https://plumeria.dev/docs/integration/next [`examples/nextjs`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-nextjs) shows how to use [`@plumeria/next-plugin`](https://www.npmjs.com/package/@plumeria/next-plugin) in Next.js.\ It compiles styles into CSS via AST parsing, with HMR support. ## Installation [#installation] ```sh title="Terminal" npm i --save-dev @plumeria/next-plugin ``` ```sh title="Terminal" yarn add -D @plumeria/next-plugin ``` ```sh title="Terminal" pnpm i --save-dev @plumeria/next-plugin ``` ## next.config.ts [#nextconfigts] `withPlumeria` works with both Turbopack and Webpack. ```ts title="next.config.ts" import type { NextConfig } from "next"; import { withPlumeria } from "@plumeria/next-plugin"; const nextConfig: NextConfig = { /* config options here */ }; export default withPlumeria(nextConfig); ``` `withPlumeria` accepts a second argument for compiler options: ```ts title="next.config.ts" export default withPlumeria(nextConfig, { include: ['./app/**/*.{ts,tsx}', './components/**/*.{ts,tsx}'], exclude: ['**/node_modules/**', '**/.next/**'], styleProp: 'sx', }); ``` * `include` — Globs the stylesheet is compiled from. The default is every `js/jsx/ts/tsx` file. * `exclude` — Globs excluded from that compilation. The default is `node_modules`, `dist` and `.next`. * `styleProp` — The JSX prop that carries styles. The default is `'classStyle'`. ## plumeria.d.ts [#plumeriadts] `@plumeria/core` ships no prop declaration of its own, so name the styling prop your project compiles with. For the default name (`classStyle`), reference the declaration that ships with the package: ```ts title="plumeria.d.ts" /// ``` If you set a custom `styleProp` (such as `'sx'`), declare the same name for TypeScript instead: ```ts title="plumeria.d.ts" import type { Style } from '@plumeria/core'; declare global { namespace React { interface HTMLAttributes { sx?: Style; } interface SVGAttributes { sx?: Style; } } } ``` The `styleProp` in `next.config.ts` and the property name in `plumeria.d.ts` must match. If they disagree, the prop type-checks but is never compiled away. --- # Rolldown Source: https://plumeria.dev/docs/integration/rolldown [`examples/rolldown`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-rolldown) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in rolldown.\ The unplugin compiles Plumeria styles into the CSS asset produced by rolldown. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```js title="rolldown.config.js" import { defineConfig } from 'rolldown'; import plumeria from '@plumeria/unplugin'; import postcss from 'rollup-plugin-postcss'; export default defineConfig({ input: 'src/index.tsx', output: { dir: 'dist', }, moduleTypes: { css: 'empty', }, plugins: [plumeria.rolldown(), postcss({ extract: true })], }); ``` --- # Rollup Source: https://plumeria.dev/docs/integration/rollup [`examples/rollup`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-rollup) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in rollup.\ The unplugin compiles Plumeria styles into the CSS asset produced by rollup. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```js title="rollup.config.js" import plumeria from '@plumeria/unplugin'; import resolve from '@rollup/plugin-node-resolve'; import commonjs from '@rollup/plugin-commonjs'; import replace from '@rollup/plugin-replace'; import esbuild from 'rollup-plugin-esbuild'; import postcss from 'rollup-plugin-postcss'; export default { input: 'src/index.tsx', output: { dir: 'dist', format: 'esm', }, plugins: [ plumeria.rollup(), postcss({ extract: true }), resolve({ extensions: ['.js', '.jsx', '.ts', '.tsx'] }), commonjs(), replace({ 'process.env.NODE_ENV': JSON.stringify('development'), preventAssignment: true, }), esbuild({ include: /\.[jt]sx?$/, sourceMap: false, minify: false, target: 'es2022', jsx: 'automatic', }), ], }; ``` --- # Rspack Source: https://plumeria.dev/docs/integration/rspack [`examples/rspack`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-rspack) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in Rspack.\ It compiles styles into CSS via AST parsing, with HMR support. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```ts title="rspack.config.js" import { rspack } from '@rspack/core'; import { ReactRefreshRspackPlugin } from '@rspack/plugin-react-refresh'; import plumeria from '@plumeria/unplugin'; const isDev = process.env.NODE_ENV === 'development'; export default { entry: './src/index.tsx', output: { filename: 'bundle.js', clean: true, }, resolve: { extensions: ['.ts', '.tsx', '.js'], }, module: { rules: [ { test: /\.tsx?$/, use: { loader: 'builtin:swc-loader', options: { jsc: { parser: { syntax: 'typescript', tsx: true }, transform: { react: { runtime: 'automatic', development: isDev, refresh: isDev, }, }, }, }, }, }, ], }, plugins: [ plumeria.rspack(), new rspack.HtmlRspackPlugin({ template: './src/index.html' }), isDev && new ReactRefreshRspackPlugin(), ].filter(Boolean), devServer: { hot: true, port: 3000, }, }; ``` --- # Vite Source: https://plumeria.dev/docs/integration/vite [`examples/vite-react`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-vite-react) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in Vite.\ It compiles styles into CSS via AST parsing, with HMR support. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```ts title="vite.config.ts" import { defineConfig } from 'vite'; import plumeria from '@plumeria/unplugin'; export default defineConfig({ plugins: [plumeria.vite()], }); ``` `plumeria.vite()` accepts an options object: ```ts title="vite.config.ts" export default defineConfig({ plugins: [ plumeria.vite({ include: ['./src/**/*.{ts,tsx}'], exclude: ['**/node_modules/**'], styleProp: 'sx', }), ], }); ``` * `include` — The path to the file to be converted. * `exclude` — The path to the file to be excluded from conversion. * `styleProp` — The JSX prop that carries styles. The default is `'classStyle'`. ## plumeria.d.ts [#plumeriadts] `@plumeria/core` ships no prop declaration of its own, so name the styling prop your project compiles with. For the default name (`classStyle`), reference the declaration that ships with the package: ```ts title="plumeria.d.ts" /// ``` If you set a custom `styleProp` (such as `'sx'`), declare the same name for TypeScript instead: ```ts title="plumeria.d.ts" import type { Style } from '@plumeria/core'; declare global { namespace React { interface HTMLAttributes { sx?: Style; } interface SVGAttributes { sx?: Style; } } } ``` The `styleProp` in `next.config.ts` and the property name in `plumeria.d.ts` must match. If they disagree, the prop type-checks but is never compiled away. --- # Webpack Source: https://plumeria.dev/docs/integration/webpack [`examples/webpack`](https://github.com/zss-in-js/plumeria/tree/main/examples/example-webpack) shows how to use [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) in Webpack.\ It compiles styles into CSS via AST parsing, with HMR support. ## Installation [#installation] ```sh title="Terminal" npm i -D @plumeria/unplugin ``` ```sh title="Terminal" yarn add -D @plumeria/unplugin ``` ```sh title="Terminal" pnpm i -D @plumeria/unplugin ``` ## Usage [#usage] ```js title="webpack.config.js" import plumeria from '@plumeria/unplugin'; export default { module: { rules: [ { test: /\.css$/, use: ['style-loader', 'css-loader'], }, ], }, plugins: [ plumeria.webpack(), ], }; ``` --- # Color Source: https://plumeria.dev/docs/reference/color ## Overview [#overview] 141 CSS named colors, supporting autocomplete in modern IDEs. Under is a all list of colors. | Color Name | Hex Code | Description | | ---------------------- | ------------------------------------------------ | ---------------------------------------------------------- | | `aliceblue` | `#F0F8FF` | A pale blue tint, ideal for light backgrounds. | | `antiquewhite` | `#FAEBD7` | A soft, warm white with a hint of peach. | | `aqua` | `#00FFFF` | Bright cyan, suitable for vibrant accents. | | `aquamarine` | `#7FFFD4` | A light cyan-green, great for fresh designs. | | `azure` | `#F0FFFF` | A very pale cyan, nearly white, for subtle backgrounds. | | `beige` | `#F5F5DC` | A warm, neutral color for backgrounds or text. | | `bisque` | `#FFE4C4` | A soft peach color, ideal for warm UI elements. | | `black` | `#000000` | Pure black, often used for text or borders. | | `blanchedalmond` | `#FFEBCD` | A creamy beige, suitable for subtle highlights. | | `blue` | `#0000FF` | Bright blue, great for links or buttons. | | `blueviolet` | `#8A2BE2` | A rich purple-blue, ideal for creative designs. | | `brown` | `#A52A2A` | A deep reddish-brown, suitable for earthy tones. | | `burlywood` | `#DEB887` | A warm tan, great for natural-themed UIs. | | `cadetblue` | `#5F9EA0` | A muted blue-green, ideal for calm designs. | | `chartreuse` | `#7FFF00` | A vivid green-yellow, suitable for highlights. | | `chocolate` | `#D2691E` | A rich brown, perfect for warm accents. | | `coral` | `#FF7F50` | A vibrant orange-pink, great for lively designs. | | `cornflowerblue` | `#6495ED` | A soft blue, ideal for buttons or backgrounds. | | `cornsilk` | `#FFF8DC` | A pale yellow, suitable for light backgrounds. | | `crimson` | `#DC143C` | A deep red, great for bold accents or alerts. | | `cyan` | `#00FFFF` | Bright cyan, alias for aqua, for vibrant accents. | | `darkblue` | `#00008B` | A deep blue, suitable for strong contrasts. | | `darkcyan` | `#008B8B` | A deep cyan, great for calm, rich designs. | | `darkgoldenrod` | `#B8860B` | A dark golden yellow, ideal for earthy tones. | | `darkgray` | `#A9A9A9` | A medium-dark gray, versatile for UI elements. | | `darkgreen` | `#006400` | A deep green, suitable for natural themes. | | `darkgrey` | `#A9A9A9` | Alias for darkgray, for consistency. | | `darkkhaki` | `#BDB76B` | A muted khaki, great for earthy backgrounds. | | `darkmagenta` | `#8B008B` | A deep purple, ideal for bold accents. | | `darkolivegreen` | `#556B2F` | A dark olive shade, suitable for natural designs. | | `darkorange` | `#FF8C00` | A vibrant orange, great for attention-grabbing elements. | | `darkorchid` | `#9932CC` | A rich purple, ideal for creative designs. | | `darkred` | `#8B0000` | A deep red, perfect for error states or accents. | | `darksalmon` | `#E9967A` | A muted orange-pink, great for warm designs. | | `darkseagreen` | `#8FBC8F` | A soft green, ideal for calm backgrounds. | | `darkslateblue` | `#483D8B` | A deep blue-purple, suitable for rich designs. | | `darkslategray` | `#2F4F4F` | A dark gray with a blue tint, great for muted UIs. | | `darkslategrey` | `#2F4F4F` | Alias for darkslategray, for consistency. | | `darkturquoise` | `#00CED1` | A vibrant cyan, great for fresh accents. | | `darkviolet` | `#9400D3` | A deep purple, ideal for bold creative elements. | | `deeppink` | `#FF1493` | A bright pink, perfect for vibrant highlights. | | `deepskyblue` | `#00BFFF` | A bright blue, great for lively buttons or links. | | `dimgray` | `#696969` | A medium-dark gray, versatile for text or borders. | | `dimgrey` | `#696969` | Alias for dimgray, for consistency. | | `dodgerblue` | `#1E90FF` | A vibrant blue, ideal for buttons or links. | | `firebrick` | `#B22222` | A deep red-brown, suitable for error states. | | `floralwhite` | `#FFFAF0` | A soft white with a hint of peach, great for backgrounds. | | `forestgreen` | `#228B22` | A rich green, ideal for natural themes. | | `fuchsia` | `#FF00FF` | Bright magenta, great for bold accents. | | `gainsboro` | `#DCDCDC` | A light gray, suitable for subtle backgrounds. | | `ghostwhite` | `#F8F8FF` | A very pale blue-white, ideal for light backgrounds. | | `gold` | `#FFD700` | A bright yellow-gold, great for highlights. | | `goldenrod` | `#DAA520` | A warm golden yellow, ideal for earthy tones. | | `gray` | `#808080` | A neutral gray, versatile for text or backgrounds. | | `green` | `#008000` | A standard green, great for natural themes. | | `greenyellow` | `#ADFF2F` | A bright yellow-green, ideal for success states. | | `grey` | `#808080` | Alias for gray, for consistency. | | `honeydew` | `#F0FFF0` | A very pale green, great for subtle backgrounds. | | `hotpink` | `#FF69B4` | A vibrant pink, perfect for lively accents. | | `indianred` | `#CD5C5C` | A muted red, suitable for warm designs. | | `indigo` | `#4B0082` | A deep blue-purple, ideal for rich designs. | | `ivory` | `#FFFFF0` | A soft white with a hint of yellow, great for backgrounds. | | `khaki` | `#F0E68C` | A light yellow-brown, ideal for earthy tones. | | `lavender` | `#E6E6FA` | A pale purple, great for soft backgrounds. | | `lavenderblush` | `#FFF0F5` | A very pale pink, ideal for subtle backgrounds. | | `lawngreen` | `#7CFC00` | A bright green, great for vibrant highlights. | | `lemonchiffon` | `#FFFACD` | A pale yellow, suitable for light backgrounds. | | `lightblue` | `#ADD8E6` | A soft blue, ideal for calm designs. | | `lightcoral` | `#F08080` | A muted coral, great for warm accents. | | `lightcyan` | `#E0FFFF` | A very pale cyan, ideal for light backgrounds. | | `lightgoldenrodyellow` | `#FAFAD2` | A pale yellow, great for subtle highlights. | | `lightgray` | `#D3D3D3` | A light gray, versatile for backgrounds. | | `lightgreen` | `#90EE90` | A soft green, ideal for fresh designs. | | `lightgrey` | `#D3D3D3` | Alias for lightgray, for consistency. | | `lightpink` | `#FFB6C1` | A soft pink, great for feminine designs. | | `lightsalmon` | `#FFA07A` | A light orange-pink, ideal for warm accents. | | `lightseagreen` | `#20B2AA` | A vibrant teal, great for fresh designs. | | `lightskyblue` | `#87CEFA` | A soft blue, ideal for calm backgrounds. | | `lightslategray` | `#778899` | A medium gray with a blue tint, versatile for UI. | | `lightslategrey` | `#778899` | Alias for lightslategray, for consistency. | | `lightsteelblue` | `#B0C4DE` | A soft blue-gray, great for calm designs. | | `lightyellow` | `#FFFFE0` | A pale yellow, suitable for light backgrounds. | | `lime` | `#00FF00` | Bright green, great for vibrant highlights. | | `limegreen` | `#32CD32` | A vivid green, ideal for success states. | | `linen` | `#FAF0E6` | A soft white with a hint of pink, great for backgrounds. | | `magenta` | `#FF00FF` | Bright magenta, alias for fuchsia, for bold accents. | | `maroon` | `#800000` | A deep red-brown, suitable for rich designs. | | `mediumaquamarine` | `#66CDAA` | A medium cyan-green, great for fresh designs. | | `mediumblue` | `#0000CD` | A medium blue, ideal for links or buttons. | | `mediumorchid` | `#BA55D3` | A medium purple, great for creative accents. | | `mediumpurple` | `#9370DB` | A soft purple, ideal for calm designs. | | `mediumseagreen` | `#3CB371` | A medium green, great for natural themes. | | `mediumslateblue` | `#7B68EE` | A medium blue-purple, ideal for creative UIs. | | `mediumspringgreen` | `#00FA9A` | A bright green, great for vibrant highlights. | | `mediumturquoise` | `#48D1CC` | A medium cyan, ideal for fresh designs. | | `mediumvioletred` | `#C71585` | A deep pink-purple, great for bold accents. | | `midnightblue` | `#191970` | A very dark blue, ideal for strong contrasts. | | `mintcream` | `#F5FFFA` | A very pale green, great for subtle backgrounds. | | `mistyrose` | `#FFE4E1` | A soft pink, ideal for feminine designs. | | `moccasin` | `#FFE4B5` | A warm peach, great for warm backgrounds. | | `navajowhite` | `#FFDEAD` | A light peach, suitable for soft backgrounds. | | `navy` | `#000080` | A very dark blue, often used for backgrounds or text. | | `oldlace` | `#FDF5E6` | A pale, creamy white, great for backgrounds. | | `olive` | `#808000` | A muted yellow-green, suitable for earthy themes. | | `olivedrab` | `#6B8E23` | A dark olive green, ideal for natural designs. | | `orange` | `#FFA500` | A bright orange, perfect for attention-grabbing elements. | | `orangered` | `#FF4500` | A strong red-orange, great for bold accents. | | `orchid` | `#DA70D6` | A light purple, ideal for creative designs. | | `palegoldenrod` | `#EEE8AA` | A soft yellow, suitable for subtle highlights. | | `palegreen` | `#98FB98` | A light green, great for fresh backgrounds. | | `paleturquoise` | `#AFEEEE` | A pale cyan, ideal for calm designs. | | `palevioletred` | `#DB7093` | A soft pink-purple, great for feminine accents. | | `papayawhip` | `#FFEFD5` | A creamy peach, suitable for light backgrounds. | | `peachpuff` | `#FFDAB9` | A soft peach, great for warm backgrounds. | | `peru` | `#CD853F` | A medium brown, ideal for earthy themes. | | `pink` | `#FFC0CB` | A classic pink, perfect for feminine or playful designs. | | `plum` | `#DDA0DD` | A soft purple, suitable for subtle accents. | | `powderblue` | `#B0E0E6` | A light blue, great for calm backgrounds. | | `purple` | `#800080` | A deep purple, ideal for creative themes. | | `rebeccapurple` | `#663399` | A rich purple, named after Rebecca Meyer. | | `red` | `#FF0000` | Pure red, great for alerts or accents. | | `rosybrown` | `#BC8F8F` | A muted brown with a pink tint, suitable for soft designs. | | `royalblue` | `#4169E1` | A vivid blue, ideal for buttons or links. | | `saddlebrown` | `#8B4513` | A deep brown, great for natural or rustic themes. | | `salmon` | `#FA8072` | A soft orange-pink, suitable for warm accents. | | `sandybrown` | `#F4A460` | A warm tan, great for earthy backgrounds. | | `seagreen` | `#2E8B57` | A deep green, ideal for natural designs. | | `seashell` | `#FFF5EE` | A pale pink-white, perfect for subtle backgrounds. | | `sienna` | `#A0522D` | A reddish-brown, suitable for earthy accents. | | `silver` | `#C0C0C0` | A light gray, versatile for backgrounds or text. | | `skyblue` | `#87CEEB` | A light blue, great for calm, airy designs. | | `slateblue` | `#6A5ACD` | A medium blue-purple, ideal for creative UIs. | | `slategray` | `#708090` | A medium gray with a blue tint, suitable for UI elements. | | `slategrey` | `#708090` | Alias for slategray, for consistency. | | `snow` | `#FFFAFA` | A very pale pink-white, ideal for light backgrounds. | | `springgreen` | `#00FF7F` | A bright green, perfect for lively highlights. | | `steelblue` | `#4682B4` | A medium blue, great for professional designs. | | `tan` | `#D2B48C` | A light brown, suitable for natural backgrounds. | | `teal` | `#008080` | A dark cyan, ideal for modern designs. | | `thistle` | `#D8BFD8` | A soft purple, great for subtle backgrounds. | | `tomato` | `#FF6347` | A vibrant red-orange, suitable for bold accents. | | `turquoise` | `#40E0D0` | A bright cyan-green, perfect for fresh highlights. | | `violet` | `#EE82EE` | A light purple, ideal for creative elements. | | `wheat` | `#F5DEB3` | A light tan, great for warm backgrounds. | | `white` | `#FFFFFF` | Pure white, commonly used for backgrounds. | | `whitesmoke` | `#F5F5F5` | A very light gray, ideal for subtle backgrounds. | | `yellow` | `#FFFF00` | Bright yellow, perfect for highlights or warnings. | | `yellowgreen` | `#9ACD32` | A medium yellow-green, great for fresh accents. | --- # References Source: https://plumeria.dev/docs/reference ## CSS Reference [#css-reference] Quick reference guides for CSS features you can use in Plumeria. --- # Pseudo Source: https://plumeria.dev/docs/reference/pseudo ## Overview [#overview] This page provides a comprehensive reference for CSS pseudo-classes and pseudo-elements that you can use in Plumeria with `css.create()`. All standard CSS pseudo-selectors are supported and can be used as keys in your style objects. ## Usage [#usage] ```ts import * as css from '@plumeria/core'; const styles = css.create({ button: { background: 'blue', ':hover': { background: 'darkblue', }, ':active': { background: 'navy', }, '::before': { content: '"→ "', }, }, }); ``` *** ## Pseudo-Classes [#pseudo-classes] Pseudo-classes target elements based on their state, position, or user interaction. ### Interactive States [#interactive-states] | Pseudo-Class | Description | Example Use Case | | ---------------- | ------------------------------------------------ | ------------------------------------ | | `:hover` | Element when mouse hovers over it | Change background on hover | | `:active` | Element when being activated (clicked) | Button press effect | | `:focus` | Element that has focus | Input field outline | | `:focus-visible` | Element with visible focus (keyboard navigation) | Show focus ring for keyboard users | | `:focus-within` | Element containing a focused descendant | Style form when any input is focused | ### Form States [#form-states] | Pseudo-Class | Description | Example Use Case | | -------------------- | ----------------------------------- | ----------------------------------- | | `:checked` | Checked checkboxes or radio buttons | Style checked inputs | | `:disabled` | Disabled form elements | Gray out disabled buttons | | `:enabled` | Enabled form elements | Style active inputs | | `:required` | Required form elements | Highlight required fields | | `:optional` | Non-required form elements | Style optional fields | | `:valid` | Valid form elements | Green border for valid inputs | | `:invalid` | Invalid form elements | Red border for invalid inputs | | `:in-range` | Input values within valid range | Highlight valid range | | `:out-of-range` | Input values outside valid range | Highlight invalid range | | `:read-only` | Read-only form elements | Style read-only inputs | | `:read-write` | Editable form elements | Style editable textareas | | `:placeholder-shown` | Inputs showing placeholder | Style inputs with placeholders | | `:indeterminate` | Indeterminate checkboxes | Style indeterminate state | | `:default` | Default element in a group | Highlight default button | | `:autofill` | Auto-filled form elements | Customize autofill appearance | | `:state(name)` | Custom state for custom elements | Style custom element based on state | ### Structural Pseudo-Classes [#structural-pseudo-classes] | Pseudo-Class | Description | Example Use Case | | ---------------------- | ------------------------- | ------------------------- | | `:first-child` | First child of parent | Style first paragraph | | `:last-child` | Last child of parent | Style last list item | | `:only-child` | Only child of parent | Style lone element | | `:first-of-type` | First sibling of its type | Style first heading | | `:last-of-type` | Last sibling of its type | Style last paragraph | | `:only-of-type` | Only one of its type | Style single heading | | `:nth-child(n)` | Nth child of parent | Style every other row | | `:nth-last-child(n)` | Nth child from end | Style second-to-last item | | `:nth-of-type(n)` | Nth element of type | Style every third div | | `:nth-last-of-type(n)` | Nth of type from end | Style last few items | | `:empty` | Elements with no children | Hide empty containers | ### Link States [#link-states] | Pseudo-Class | Description | Example Use Case | | ------------ | ------------------------------- | ------------------------- | | `:link` | Unvisited links | Style unvisited anchors | | `:visited` | Visited links | Style visited links | | `:any-link` | Any link (visited or unvisited) | Style all links uniformly | ### Other Pseudo-Classes [#other-pseudo-classes] | Pseudo-Class | Description | Example Use Case | | ------------------------- | ---------------------------------------- | ---------------------------------- | | `:root` | Root element (html) | Define CSS variables | | `:target` | Element targeted by URL fragment | Highlight linked section | | `:not(selector)` | Elements not matching selector | Style all except specific class | | `:is(selector)` | Elements matching any selector | Combine multiple selectors | | `:where(selector)` | Like :is() but with zero specificity | Flexible selector grouping | | `:has(selector)` | Elements containing specific descendants | Style parent based on children | | `:lang(language)` | Elements with specific language | Style for specific languages | | `:dir(direction)` | Elements with text direction | Style for RTL/LTR | | `:fullscreen` | Element in fullscreen mode | Style fullscreen video | | `:modal` | Modal dialogs | Style modal elements | | `:open` | Open details/dialog elements | Style open accordions | | `:defined` | Defined custom elements | Style web components | | `:popover-open` | Popover element that is open | Style active popovers | | `:host` | Shadow DOM host element | Style host component | | `:host(selector)` | Shadow DOM host matching selector | Style host component conditionally | | `:host-context(selector)` | Shadow DOM host based on ancestor | Contextual component styling | *** ## Pseudo-Elements [#pseudo-elements] Pseudo-elements style specific parts of an element or insert generated content. ### Content Generation [#content-generation] | Pseudo-Element | Description | Example Use Case | | -------------- | ----------------------------- | ------------------------ | | `::before` | Insert content before element | Add icons or decorations | | `::after` | Insert content after element | Add arrows or indicators | ### Text Styling [#text-styling] | Pseudo-Element | Description | Example Use Case | | ------------------- | ------------------------------------- | ------------------------------ | | `::first-letter` | First letter of text | Drop caps | | `::first-line` | First line of text | Emphasize opening line | | `::selection` | Selected text | Custom highlight color | | `::target-text` | Element text targeted by URL fragment | Highlight target text fragment | | `::highlight(name)` | Custom highlight registered via API | Custom text highlighting | ### Form Elements [#form-elements] | Pseudo-Element | Description | Example Use Case | | ------------------------ | ---------------------- | ------------------------ | | `::placeholder` | Placeholder text | Style input placeholders | | `::marker` | List item markers | Custom bullet styles | | `::file-selector-button` | Button of a file input | Style file uploads | ### Media Elements [#media-elements] | Pseudo-Element | Description | Example Use Case | | ----------------- | ----------------------- | ----------------------------- | | `::cue` | WebVTT cues (subtitles) | Style video subtitles | | `::cue(selector)` | Specific WebVTT cues | Style specific subtitle parts | ### Other Pseudo-Elements [#other-pseudo-elements] | Pseudo-Element | Description | Example Use Case | | --------------------- | ------------------------------------ | ----------------------------- | | `::backdrop` | Dialog/fullscreen backdrop | Style modal background | | `::part(name)` | Shadow DOM parts | Style component internals | | `::slotted(selector)` | Slotted shadow DOM content | Style slot content | | `::spelling-error` | Spelling errors | Highlight misspellings | | `::grammar-error` | Grammar errors | Highlight grammar issues | | `::details-content` | Content container of details element | Style open accordion contents | *** ## View Transitions [#view-transitions] Special pseudo-elements for the View Transitions API. | Pseudo-Element | Description | | ------------------------------------ | ---------------------------- | | `::view-transition` | Root of view transition | | `::view-transition-group(name)` | Transition group | | `::view-transition-image-pair(name)` | Image pair during transition | | `::view-transition-old(name)` | Old content | | `::view-transition-new(name)` | New content | *** ## Notes [#notes] * All pseudo-classes start with a single colon (`:`) * All pseudo-elements start with double colons (`::`) * Some older pseudo-elements (like `::before` and `::after`) can use single colon for backwards compatibility * Functional pseudo-classes like `:nth-child()` accept arguments * Not all pseudo-classes work in all browsers - check compatibility when needed --- # Specificity Source: https://plumeria.dev/docs/reference/specificity ## Property priority [#property-priority] Plumeria assigns specificity from the shorthand-to-longhand property graph. Each step toward a more specific property adds one `:not(#\#)` to its atomic class. To simplify the examples, `hash(xxxxxxxx)` is written as `xatom`. ### Override only that value [#override-only-that-value] This ensures that longhand properties **add to** shorthand properties, regardless of the merge order: ```js const styles = css.create({ base: { margin: 10 }, custom: { marginTop: 20 }, }); // Both produce the same result classStyle={styles.base, styles.custom} classStyle={styles.custom, styles.base} // Result: margin 10px on all sides, except top is 20px ``` Normally, a later shorthand can reset an earlier longhand. The specificity hierarchy prevents that reset, so both of the following produce the same result: ```css xatom1 { padding: 20px; } xatom2:not(#\#) { padding-top: 10px; } ``` And this too ```css xatom2:not(#\#) { padding-top: 10px; } xatom1 { padding: 20px; } ``` Logical intermediate properties use the intermediate depth. For example: ```sh padding: 0 - :not(#\#) x 0 padding-block: 1 - :not(#\#) x 1 padding-block-start: 2 - :not(#\#) x 2 ``` Only the property's graph depth is added. A shorthand does not receive extra specificity to simulate the CSS cascade. ### Declarations in the same style [#declarations-in-the-same-style] Shorthand and longhand declarations remain independent atoms even when they are written in the same style. A later shorthand does not filter out an earlier longhand: ```js const styles = css.create({ base: { paddingTop: '20px', padding: '10px', }, }); ``` The longhand's higher specificity keeps the top value while the shorthand sets the remaining sides: ```css xatom1:not(#\#) { padding-top: 20px; } xatom2 { padding: 10px; } ``` These relationships are complex even in regular CSS. The ESLint rule enforces a consistent authoring order by placing longhand properties after their shorthands. ## `classStyle` prop merge styles [#classstyle-prop-merge-styles] Also, when `classStyle` prop has duplicate properties on its array, the style properties on the right always take precedence and duplicate properties on the left are filtered. In that case no filtered hash is generated. ```js const styles = css.create({ base: { fontSize: 10, }, custom: { fontSize: 16, }, }); // The right always wins classStyle={styles.base, styles.custom} // 16px classStyle={styles.custom, styles.base} // 10px ``` Generated as follows: ```css xatom { font-size: 16px; } ``` Or: ```css xatom { font-size: 10px; } ``` ## Conditional and nested rules [#conditional-and-nested-rules] Conditional rules such as `@media`, `@container`, and `@supports`, as well as nested selectors, receive one additional `:not(#\#)`. This lets a conditional or nested declaration override its base declaration without relying on where the generated rule appears in the stylesheet. A nested selector inside a condition receives both. ```sh base shorthand: property depth 0 base longhand: property depth shorthand in condition: property depth 0 + condition depth 1 longhand in condition: property depth + condition depth 1 nested selector: property depth + nested depth 1 nested selector in condition: property depth + nested depth 1 + condition depth 1 ``` Custom properties are exempt. They never receive a nested or condition depth. The optimizer merges identical selectors and identical at-rules recursively to reduce bundle size. Supported conditional at-rules are moved after base rules so a conditional shorthand can override a base longhand when their specificity is equal. A condition that matches a subset of another is then placed after it, so the narrower one wins everywhere both of them reach. Whether one condition implies another is not decidable in general, so only the comparable shapes are read — a `min-`, `max-` or range comparison on `width`, `height`, `inline-size` or `block-size`, joined with `and`, against the same media type or the same container. Anything else keeps the order it was written in, unless a comparable pair leaves no arrangement that also holds it still. ## What source order still decides [#what-source-order-still-decides] Every pair where one declaration contains the other is settled by specificity, so composing styles from different modules gives the same result no matter which module the bundler reached first. Four pairs have no containment to rank them by. Three of them are left to source order; the fourth is settled by the order the styles are composed in. ### The same property under two names [#the-same-property-under-two-names] `paddingTop` and `paddingBlockStart` are the same computed property in a horizontal writing mode, so they receive the same depth and neither can outrank the other. Plain CSS resolves this the same way. In a vertical writing mode they are two different edges and no longer compete. Which one an element renders under is decided at runtime and inherited, so no build-time setting can answer it; `no-order-dependent-overlap` reads the pair as one property, which is right for a horizontal or a mixed document and wrong only where an element is known to be vertical. Writing one spelling and not the other removes the question, and `no-logical-properties` or `no-physical-properties` enforces that. ```js const styles = css.create({ physical: { paddingTop: 4 }, logical: { paddingBlockStart: 10 }, }); ``` ### Two shorthands that cross [#two-shorthands-that-cross] `borderTop` sets three values on one edge. `borderBlockWidth` sets one value on two edges. They overlap on `border-top-width`, but neither contains the other, so there is nothing to rank them by. Writing the three declarations `borderTop` stands for turns the pair into a shorthand and a longhand, which specificity does rank; `expand-border-shorthands` does that rewrite. ```js const styles = css.create({ edge: { borderTop: '1px solid red' }, axis: { borderBlockWidth: 5 }, }); ``` ### Two conditions that overlap [#two-conditions-that-overlap] Two conditions that can match at the same time produce the same specificity. Where one of them matches a subset of the other, the optimizer settles the pair by placing the narrower one last, so the result no longer depends on where the two declarations were written or which module the compiler reached first. ```js const styles = css.create({ medium: { '@media (min-width: 600px)': { color: 'red' } }, wide: { '@media (min-width: 900px)': { color: 'blue' } }, }); ``` At a width of 1000px both queries apply and `blue` wins, written in either order. `no-order-dependent-overlap` still reports the reversed spelling, because the source then reads as though `red` would win. Two conditions that overlap without either containing the other — `600px` to `900px` against `700px` to `1000px` — are left to source order, and so is any pair the optimizer cannot compare. ### Two states that match at once [#two-states-that-match-at-once] Every nested selector receives the same depth, so `:hover` and `:focus` are ranked equally and an element that is both has nothing to settle the intersection. Two states on one pseudo-element are the same shape, because `:hover::before` and `:focus::before` address the same generated box. A state and a bare `::before` never compete, and neither do two different pseudo-elements, including two arguments of the same one such as `::part(icon)` and `::part(label)`. ```js const styles = css.create({ hovered: { ':hover': { color: 'red' } }, focused: { ':focus': { color: 'blue' } }, }); ``` Nothing in the pair ranks it, and nothing can. The property graph ranks by containment, and no such relation holds between two states — `:hover` is not a more specific description of an element than `:focus`. Composing the two styles is what says which one wins: ```js classStyle={[styles.hovered, styles.focused]} // blue where both hold classStyle={[styles.focused, styles.hovered]} // red where both hold ``` The atom from the source written further right receives one more `:not(#\#)`, so it wins where both states hold and changes nothing where only one does. That weighted atom is a class of its own, which is what lets both arrangements exist in one application without reaching each other. Reversing the array reverses the winner, and the module the bundler reached first no longer decides anything. Only a pair that is otherwise indistinguishable is weighted: the same condition, the same pseudo-element, the same property and the same selector specificity. Every axis that already decides is left alone — a differing `@media`, `@layer` or `@scope`, a longhand against its shorthand, `:host(.active)` against `:hover` — and so is an explicit `:hover:focus`, which stays above the weighting. Written in one style there is no composition to read, and the intersection falls back to source order: ```js const styles = css.create({ button: { ':hover': { color: 'red' }, ':focus': { color: 'blue' }, }, }); ``` `no-order-dependent-overlap` reports that pair. Declare `:hover:focus` if the intersection has a value of its own, or split the two into separate styles and compose them in the order that should win. Source order is stable inside a single style object, and the ESLint rule keeps that order consistent. Splitting one of the first three across two `css.create` calls is what makes the result depend on the bundler instead. Two states are the exception: splitting them is how the intent is stated. `no-order-dependent-overlap` reports all four when they meet in one style, the conditions only where one provably matches a subset of the other. ### Removing the first two entirely [#removing-the-first-two-entirely] Two optional rules take the room away instead of reporting it. Expanding a border shorthand into the three declarations it stands for turns a crossing pair into a shorthand and a longhand, and writing one spelling of a property and not the other means the same property can never appear twice: ```js import plumeria from '@plumeria/eslint-plugin'; export default [ plumeria.configs.recommended, { rules: { '@plumeria/expand-border-shorthands': 'warn', '@plumeria/no-logical-properties': 'warn', }, }, ]; ``` With both on, every pair on this page except the overlapping conditions and the two states becomes impossible to write. See [Optional rules](/docs/api-reference/plugins/eslint-plugin/optional-rules). --- # @plumeria/headlessui Source: https://plumeria.dev/docs/api-reference/components/headlessui `@plumeria/headlessui` is a curated set of essential headless primitives, built on [Radix UI](https://www.radix-ui.com/) ## Installation `headlessui` [#installation-headlessui] To use the headlessui integrated into `Radix UI`, configuration of `@plumeria/core` and your bundler is required. Please refer to the [Installation](getting-started/installation) section for details. {/* prettier-ignore */} ```sh title="Terminal" npm i @plumeria/headlessui ``` {/* prettier-ignore */} ```sh title="Terminal" yarn add @plumeria/headlessui ``` {/* prettier-ignore */} ```sh title="Terminal" pnpm i @plumeria/headlessui ``` ## How classStyle works [#how-classstyle-works] When `classStyle` is passed to a custom component, it is **automatically compiled to `className` and `style` at the call site — before the component ever runs**. Therefore, each `@plumeria/headlessui` component does not need to know about `classStyle` at all; it simply spreads `...props` onto the underlying Radix primitive. ```tsx import * as css from '@plumeria/core'; import { DialogTrigger } from '@plumeria/headlessui'; const styles = css.create({ primary: { padding: '10px', backgroundColor: 'navy', color: '#fff', }, }); // classStyle is compiled to className="xxxxxxxx" at this call site Open; ``` *** ## Interactive Demo [#interactive-demo] Below is a live demo of all six components from `@plumeria/headlessui`, styled with Plumeria. *** ## Components [#components] The following twenty-five component groups are exported. All components support `ref` forwarding and props spread. ### Accordion [#accordion] * `Item` * `Header` * `Trigger` * `Content` ### AlertDialog [#alertdialog] * `Trigger` * `Portal` * `Overlay` * `Content` * `Title` * `Description` * `Action` * `Cancel` ### Avatar [#avatar] * `Image` * `Fallback` ### Checkbox [#checkbox] * `Indicator` ### Collapsible [#collapsible] * `Trigger` * `Content` ### ContextMenu [#contextmenu] * `Trigger` * `Portal` * `Content` * `Group` * `Label` * `Item` * `CheckboxItem` * `RadioGroup` * `RadioItem` * `ItemIndicator` * `Separator` * `Arrow` * `Sub` * `SubTrigger` * `SubContent` ### Dialog [#dialog] * `Trigger` * `Portal` * `Overlay` * `Content` * `Title` * `Description` * `Close` ### DropdownMenu [#dropdownmenu] * `Trigger` * `Portal` * `Content` * `Group` * `Label` * `Item` * `CheckboxItem` * `RadioGroup` * `RadioItem` * `ItemIndicator` * `Separator` * `Arrow` * `Sub` * `SubTrigger` * `SubContent` ### Label [#label] ### Menubar [#menubar] * `Menu` * `Trigger` * `Portal` * `Content` * `Group` * `Label` * `Item` * `CheckboxItem` * `RadioGroup` * `RadioItem` * `ItemIndicator` * `Separator` * `Arrow` * `Sub` * `SubTrigger` * `SubContent` ### NavigationMenu [#navigationmenu] * `Sub` * `List` * `Item` * `Trigger` * `Link` * `Indicator` * `Content` * `Viewport` ### Popover [#popover] * `Trigger` * `Portal` * `Content` * `Close` * `Arrow` * `Anchor` ### Progress [#progress] * `Indicator` ### RadioGroup [#radiogroup] * `Item` * `Indicator` ### ScrollArea [#scrollarea] * `Viewport` * `Scrollbar` * `Thumb` * `Corner` ### Select [#select] * `Trigger` * `Value` * `Icon` * `Portal` * `Content` * `Viewport` * `Group` * `Label` * `Item` * `ItemText` * `ItemIndicator` * `ScrollUpButton` * `ScrollDownButton` * `Separator` * `Arrow` ### Separator [#separator] ### Slider [#slider] * `Track` * `Range` * `Thumb` ### Switch [#switch] * `Thumb` ### Tabs [#tabs] * `List` * `Trigger` * `Content` ### Toast [#toast] * `Provider` * `Viewport` * `Title` * `Description` * `Action` * `Close` ### Toggle [#toggle] ### ToggleGroup [#togglegroup] * `Item` ### Tooltip [#tooltip] * `Provider` * `Trigger` * `Portal` * `Content` * `Arrow` ### VisuallyHidden [#visuallyhidden] --- # @plumeria/inspector Source: https://plumeria.dev/docs/api-reference/components/inspector `@plumeria/inspector` is an interactive DevTools utility component that allows you to inspect elements, highlight components, and view their compiled Plumeria styles directly in the browser. *** ## Installation [#installation] To start using the inspector, install the `@plumeria/inspector` package in your project. {/* prettier-ignore */} ```sh title="Terminal" npm i @plumeria/inspector ``` {/* prettier-ignore */} ```sh title="Terminal" yarn add @plumeria/inspector ``` {/* prettier-ignore */} ```sh title="Terminal" pnpm i @plumeria/inspector ``` *** ## Basic Usage [#basic-usage] Import `Inspector` and render it at the root of your application (e.g., in a root layout or main entry point component). ```tsx title="app/layout.tsx" import { Inspector } from '@plumeria/inspector'; import type { ReactNode } from 'react'; export default function Layout({ children }: { children: ReactNode }) { return ( {/* Render the inspector component */} {children} ); } ``` *** ## Features [#features] * **Interactive Hover Overlay**: Hovering over elements displays a visual border highlight showing their target area. * **CSS Property Tooltip**: Shows the active CSS rules, classes, and properties injected by Plumeria for the hovered element. * **Target Freezing**: Press the `Shift` key to freeze/lock targeting onto the currently hovered element. This allows you to move your cursor into the inspector tooltip and scroll through rules. Press `Shift` again to unlock. * **Keyboard Shortcut**: Press `Cmd + I` / `Ctrl + I` to toggle the inspector on and off. * **Floating Badge Toggle**: A minimalist, semi-transparent badge in the bottom-right corner shows the inspector status and can be clicked to toggle it. *** ## Props [#props] | Prop | Type | Default | Description | | --------- | --------- | ------- | ------------------------------------------------------------------------------ | | `initial` | `boolean` | `false` | If `true`, the inspector starts toggled ON. If `false`, it starts toggled OFF. | *** ## Production Mode [#production-mode] By default, the `Inspector` imported from `@plumeria/inspector` is stripped from production builds entirely. The main entry point resolves through the `production` export condition to a no-op module, so your bundler emits no client chunk for it — costing 0KB in production. If you want the inspector accessible in production (for staging environments, demos, or public showcases), import from the `@plumeria/inspector/production` subpath instead: ```tsx import { Inspector } from '@plumeria/inspector/production'; export default function Layout({ children }: { children: ReactNode }) { return ( {children} ); } ``` *** ## Live Demo [#live-demo] The inspector is active right here on this documentation site! To try it out: 1. Click the **Inspector: ON** badge in the bottom-right corner, or press `Cmd + I` / `Ctrl + I`. 2. Hover over any text, heading, or container on this page to see the outline and compiled rules. 3. Press `Shift` to freeze the selection and explore the details in the tooltip. --- # css.create Source: https://plumeria.dev/docs/api-reference/javascript/create ```ts export type create = >(rule: T)=> CreateReturnType; export const create: create; ``` `create` defines css styles using plain JavaScript style objects.\ type-safe・autocomplete・lintable Only the styles you use in `classStyle` will be ondemand compiled. ## Example [#example] ```tsx title="TypeScript" import * as css from '@plumeria/core' const styles = css.create({ container: { display: 'flex', justifyContent: 'space-between', }, text: { fontSize: '14px', textDecoration: 'none', }, }) export default function App() { return (

); } ``` The call is cleaned up by the bundler. **Compiled:** ```tsx

``` **Generated CSS:** ```css .xxp6epoh { display: flex; } .xwbwwha1 { justify-content: space-between; } .xbief8v4:not(#\#) { font-size: 14px; } .xzllkng3 { text-decoration: none; } ``` Compiles each style CSS property into a unique, **atomic**, and **hashed** class name. This prevents style collisions and maximizes reusability. ## Dynamic values [#dynamic-values] You can use functions to define dynamic styles. These are processed as dynamic values at build time. ```tsx const styles = css.create({ palette: (color: string) => ({ backgroundColor: color, }), }); export const Color = ({ color }) => { return ( Dynamic Color ) } ``` ## Variants bracket notation [#variants-bracket-notation] You can resolve dynamic variant styles using standard bracket notation (e.g., `variantStyles[size]`). Plumeria's compiler automatically extracts these variants and creates static lookup tables at build time. ```tsx import * as css from '@plumeria/core'; const styles = css.create({ base: { display: 'inline-flex', borderRadius: '4px', backgroundColor: 'blue', color: 'white', } }); const sizeStyles = css.create({ small: { fontSize: '12px', padding: '4px 8px', }, large: { fontSize: '18px', padding: '12px 24px', } }); type Size = 'small' | 'large'; // can also use the type exhaustively via typeof sizeStyles export const Button = ({ size }: { size: Size }) => { return ( ); }; ``` Function keys (dynamic styles) within the style object are ignored during bracket notation lookup table compilation. ### The last source wins [#the-last-source-wins] An element takes a list, and a property set by more than one entry keeps the value from the one written last. That is what lets a variant override the base above. The rule holds whatever the entries are — a plain style, a condition, a bracket group. Swapping two of them swaps which one applies: ```tsx const styles = css.create({ base: { color: 'white' }, muted: { color: 'slategray' }, }); const toneStyles = css.create({ brand: { color: 'royalblue' }, danger: { color: 'crimson' }, }); // muted wins — it is written last