@plumeria/core 16.5.0 → 17.0.1

package/README.md

@@ -11,7 +11,7 @@
 
 ## Installation
 
-`@plumeria/core` contains type definitions only — importing it augments React's JSX types so that styleName is accepted on host elements. Styles are compiled away at build time by a bundler integration — [`@plumeria/next-plugin`](https://www.npmjs.com/package/@plumeria/next-plugin) for Next.js, or [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) for Vite, Webpack, and others.
+`@plumeria/core` contains type definitions only. Which JSX prop carries styles is declared in your project — one line for the default `styleName`, see [Declaring the styling prop](#declaring-the-styling-prop). Styles are compiled away at build time by a bundler integration — [`@plumeria/next-plugin`](https://www.npmjs.com/package/@plumeria/next-plugin) for Next.js, or [`@plumeria/unplugin`](https://www.npmjs.com/package/@plumeria/unplugin) for Vite, Webpack, and others.
 
 ```sh
 pnpm add -D @plumeria/core
@@ -75,6 +75,41 @@ export default function App({ cond }) {
 }
 ```
 
+## Declaring the styling prop
+
+The prop name is a build-time setting — `styleProp` on the bundler plugin — so `@plumeria/core` declares no prop of its own. Baking one in would let the types and the compiler disagree. Add one file to your project naming the prop you compile with.
+
+For the default, `styleName`, reference the declaration that ships with the package:
+
+```ts
+// plumeria.d.ts
+/// <reference types="@plumeria/core/style-name" />
+```
+
+If you renamed the prop, declare that name on React's attribute interfaces instead. `Style` is the type of anything the prop accepts — a style, a conditional, or an array of them:
+
+```ts
+// plumeria.d.ts
+import type { Style } from '@plumeria/core';
+
+declare global {
+  namespace React {
+    interface HTMLAttributes<T> {
+      sx?: Style
+    }
+    interface SVGAttributes<T> {
+      sx?: Style
+    }
+  }
+}
+```
+
+```tsx
+<div sx={[styles.text, cond && styles.cond]} />
+```
+
+Declaration merging is additive, so several names can coexist during a migration. Whichever you declare has to match what the bundler plugin was given — if they disagree the prop type-checks but is never compiled away.
+
 Explore the [documentation](https://plumeria.dev/) for the core principles, full API reference, and integrations.
 
 ## License

package/lib/css.d.ts

@@ -9,13 +9,13 @@
  * type viewTransition = <const T extends ViewTransition>(rule: T) => string;
  * type marker = (id: string, pseudo: string) => Marker;
  * type extended = <I extends string, P extends string>(id: I, pseudo: P) => Extended<I, P>;
- * type use = (...rules: StyleName[]) => string;
+ * type use = (...rules: Style) => string;
  * ```
  */
 declare module '@plumeria/core' {
   import type {
     AtomicClassNameFor,
-    StyleName,
+    Style,
     CSSProperties,
     CreateStyleValue,
     CreateReturnType,
@@ -29,18 +29,7 @@ declare module '@plumeria/core' {
     Extended,
   } from '#types';
 
-  global {
-    namespace React {
-      interface HTMLAttributes<T> {
-        styleName?: StyleName;
-      }
-      interface SVGAttributes<T> {
-        styleName?: StyleName;
-      }
-    }
-  }
-
-  export type { AtomicClassNameFor, StyleName, CSSProperties };
+  export type { AtomicClassNameFor, Style, CSSProperties };
 
   export const create: create;
   export type create = <const T extends Record<string, CreateStyleValue>>(
@@ -74,5 +63,5 @@ declare module '@plumeria/core' {
   ) => Extended<I, P>;
 
   export const use: use;
-  export type use = (...rules: StyleName) => string;
+  export type use = (...rules: Style) => string;
 }

package/lib/csstypes.d.ts

@@ -295,7 +295,16 @@ type columns = columnWidth | columnCount;
 type columnSpan = 'none' | 'all';
 type columnWidth = 'auto' | number | StableString;
 type compositeOperator = 'add' | 'subtract' | 'intersect' | 'exclude';
-type contain = 'none' | 'strict' | 'content' | StableString;
+type contain =
+  | 'none'
+  | 'strict'
+  | 'content'
+  | 'size'
+  | 'inline-size'
+  | 'layout'
+  | 'style'
+  | 'paint'
+  | StableString;
 type container = number | StableString;
 type containerName = number | StableString;
 type containerType = 'size' | 'inline-size' | 'normal';

package/lib/style-name.d.ts

@@ -0,0 +1,12 @@
+import type { Style } from '#types';
+
+global {
+  namespace React {
+    interface HTMLAttributes<T> {
+      styleName?: Style;
+    }
+    interface SVGAttributes<T> {
+      styleName?: Style;
+    }
+  }
+}

package/lib/types.d.ts

@@ -73,7 +73,7 @@ type CreateReturnType<T> = Readonly<{
     : MapNamespace<T[K]>;
 }>;
 type Conditional = false | CSSProperties | null | undefined;
-type StyleName = Conditional | StyleName[];
+type Style = Conditional | Style[];
 
 type CreateStatic = Record<string, string | number>;
 
@@ -110,7 +110,7 @@ type Extended<
 
 export type {
   AtomicClassNameFor,
-  StyleName,
+  Style,
   CSSProperties,
   CreateStyleValue,
   CreateReturnType,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plumeria/core",
-  "version": "16.5.0",
+  "version": "17.0.1",
   "description": "Zero-cost abstraction layer for styling React components.",
   "author": "Refirst 11",
   "license": "MIT",
@@ -27,6 +27,9 @@
   "exports": {
     ".": {
       "types": "./lib/css.d.ts"
+    },
+    "./style-name": {
+      "types": "./lib/style-name.d.ts"
     }
   },
   "types": "./lib/css.d.ts",