@plumeria/core 0.9.7 → 0.9.9

package/README.md

@@ -1,38 +1,38 @@
 # @plumeria/core
 
-**Zero-runtime CSS in JS library in TypeScript.**
+**Zero-runtime, expressive CSS-in-JS library for TypeScript.**
 
-## Installation
+## 🌱 Installation
 
-To start using Plumeria, Install the following two packages:
+To get started with Plumeria, install the core package:
 
 ```sh
 npm install @plumeria/core
 ```
 
-### Compiler
+### 🛠 Compiler (for static extraction)
 
-To compile `@plumeria/core`, for example, to use `npx css`, install  
-[`@plumeria/compiler`](https://www.npmjs.com/package/@plumeria/compiler) for static extraction through the build process.
+If you want to extract styles at build time using commands like `npx css`, install:
 
 ```sh
 npm install --save-dev @plumeria/compiler
 ```
 
-### StyleSheet
+More at: [@plumeria/compiler on npm](https://www.npmjs.com/package/@plumeria/compiler)
 
-Import stylesheet in your application's entry point.  
-Applies the static stylesheet for production environments.
+### 🎨 Stylesheet Import
+
+In your app entry point, import the compiled CSS file:
 
 ```ts
 import '@plumeria/core/stylesheet.css';
 ```
 
-## API
+## 📘 API Reference
 
-### css.create()
+### `css.create()`
 
-Styles are defined as a map of CSS rules using css.create(). In the example below, there are 2 different CSS className. The className `styles.box` and `styles.text` are arbitrary names given to the rules.
+Define a set of styles:
 
 ```ts
 import { css } from '@plumeria/core';
@@ -48,16 +48,13 @@ const styles = css.create({
 });
 ```
 
-Pseudo and media queries can be wrapped in property style definitions:  
-Also, any properties that are not wrapped will conform to that className.
+Supports pseudo/media queries inline:
 
 ```ts
 const styles = css.create({
   box: {
-    // 900px
     [css.media.maxWidth(900)]: {
       width: '100%',
-      color: 'rgb(60,60,60)',
     },
   },
   text: {
@@ -70,9 +67,45 @@ const styles = css.create({
 });
 ```
 
-### css.global()
+### `css.createComposite()`
+
+Creates modifier classes for a base style:
+
+```ts
+const styles = css.create({
+  flexBox: {
+    display: 'flex',
+    flexDirection: 'column',
+    justifyContent: 'center',
+  },
+});
+
+const composed = css.createComposite(styles.flexBox, {
+  hover: {
+    [css.pseudo.hover]: {
+      scale: 1.5,
+    },
+  },
+  active: {
+    [css.pseudo.active]: {
+      color: css.color.gray,
+    },
+  },
+});
+```
+
+This produces named modifier classes based on the base style.  
+You can use them like this:
+
+```jsx
+<div className={composed.hover} />
+```
+
+Automatically generates all modifier variants while keeping the base style clean.
+
+### `css.global()`
 
-This API lets you define global CSS.
+Define global styles:
 
 ```ts
 css.global({
@@ -92,9 +125,9 @@ css.global({
 });
 ```
 
-### css.keyframes()
+### `css.keyframes()`
 
-Define @keyframes and set the return value directly to animationName.
+Create keyframes for animation:
 
 ```ts
 const fade = css.keyframes({
@@ -114,25 +147,55 @@ const styles = css.create({
 });
 ```
 
-### css.defineVars()
+### `css.defineConsts()`
 
-Defines custom CSS variables (custom properties) at the `:root` level.  
-This API allows you to declare design tokens such as spacing, sizes, or other constants, which can be referenced throughout your styles using the tokens.sm to `var(--sm)` syntax.
+Define reusable constant values with type safety:
+
+```ts
+const breakpoints = css.defineConsts({
+  xs: css.media.maxWidth(480),
+  sm: css.media.maxWidth(640),
+  md: css.media.maxWidth(768),
+  lg: css.media.maxWidth(1024),
+  xl: css.media.maxWidth(1280),
+});
+```
+
+Use them in your style definitions:
+
+```ts
+const styles = css.create({
+  container: {
+    [breakpoints.sm]: {
+      padding: 16,
+    },
+    [breakpoints.lg]: {
+      padding: 32,
+    },
+  },
+});
+```
+
+Constants are fully type-safe and readonly.
+
+### `css.defineVars()`
+
+Define design tokens with CSS variables:
 
 ```ts
 const tokens = css.defineVars({
-  xs: 240,
-  sm: 360,
-  md: 480,
-  lg: 600,
-  xl: 720,
+  white: 'white',
+  black: 'black',
+  textPrimary: '#eaeaea',
+  textSecondary: '#333',
+  link: 'lightblue',
+  accent: 'purple',
 });
 ```
 
-### css.defineTheme()
+### `css.defineTheme()`
 
-Define data-theme as objects.  
-A default compile to :root, and the rest as a string compile to data-theme, You can also use media and container here.
+Define theme values with responsive and conditional support:
 
 ```ts
 const themes = css.defineTheme({
@@ -149,12 +212,9 @@ const themes = css.defineTheme({
 });
 ```
 
-### css.color
-
-Mixes #000 or #FFF into the color.  
-The first argument takes the color and the second argument takes the same value as opacity (string % or number).
+### `css.color`
 
-You can also retrieve the complement of the color property from an color object.
+Color utilities:
 
 ```ts
 color: css.color.darken('skyblue', 0.12),
@@ -162,35 +222,35 @@ color: css.color.lighten('navy', 0.6),
 
 color: css.color.skyblue,
 color: css.color.aqua,
-// ...many more colors
-color: css.color.*...,
-
+// and many more
 ```
 
-### cx
+### `cx`
 
-Merges strings such as class names and pseudo.
+Classname merging helper:
 
 ```tsx
-// ":hover::after"
 cx(css.pseudo.hover, css.pseudo.after);
-// "text_hash box_hash"
-cx(styles.text, styles, box);
+// => ":hover::after"
+cx(styles.text, styles.box);
+// => "text_hash box_hash"
 ```
 
-## ESLint
+## 🧹 ESLint Support
 
-[@plumeria/eslint-plugin](https://www.npmjs.com/package/@plumeria/eslint-plugin)
+Use [@plumeria/eslint-plugin](https://www.npmjs.com/package/@plumeria/eslint-plugin) for recommended rules:
 
 ### Rules: recommended
 
-\- no-inner-call:(error)  
-\- no-unused-keys:(warn)  
-\- sort-properties:(warn)  
-\- validate-values:(warn)
+```
+- no-inner-call: error
+- no-unused-keys: warn
+- sort-properties: warn
+- validate-values: warn
+```
 
-It is recommended to use it in conjunction with TypeScript completion, which is one of the big advantages of using plumeria.
+Plumeria is best used alongside TypeScript for excellent autocomplete and validation support.
 
-## License
+## 📄 License
 
-plumeria is [MIT licensed](https://github.com/refirst11/rscute/blob/main/LICENSE).
+Plumeria is [MIT licensed](https://github.com/zss-in-js/plumeria/blob/main/LICENSE).

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { CSSHTML, CSSProperties, CreateKeyframes, CreateStyle, CreateStyleType, CreateTheme, CreateVars, ReturnType } from "zss-engine";
+import { CSSHTML, CSSProperties, CreateKeyframes, CreateStyle, CreateStyleType, CreateTheme, CreateValues, ReturnType } from "zss-engine";
 
 //#region src/css.d.ts
 declare class css {
-  static create<T extends Record<string, CSSProperties>>(object: CreateStyleType<T>): ReturnType<T>;
+  static create<const T extends Record<string, CSSProperties>>(object: CreateStyleType<T>): ReturnType<T>;
+  static createComposite<const T extends Record<string, CSSProperties>>(className: string, object: T): ReturnType<T>;
   static global(object: CSSHTML): void;
-  static defineVars<const T extends CreateVars>(object: T): { [K in keyof T]: `var(--${string})` };
-  static defineTheme<const T extends CreateTheme>(object: T): { [K in keyof T]: `var(--${string})` };
   static keyframes(object: CreateKeyframes): string;
+  static defineConsts<const T extends CreateValues>(object: T): T;
+  static defineVars<const T extends CreateValues>(object: T): { [K in keyof T]: `var(--${string})` };
+  static defineTheme<const T extends CreateTheme>(object: T): { [K in keyof T]: `var(--${string})` };
   static media: {
     dark: "@media (prefers-color-scheme: dark)";
     light: "@media (prefers-color-scheme: light)";

package/dist/index.js

@@ -19,6 +19,12 @@ function create(object) {
 	});
 	return Object.freeze(object);
 }
+function createComposite(className, object) {
+	const composed = create(object);
+	const result = {};
+	for (const key in composed) result[key] = `${className} ${composed[key]}`;
+	return result;
+}
 function global(object) {
 	const base36Hash = (0, zss_engine.genBase36Hash)(object, 8);
 	const { styleSheet } = (0, zss_engine.transpiler)(object, void 0, "--global");
@@ -26,6 +32,14 @@ function global(object) {
 	require_css.resolvePromise_2(styleSheet);
 	if (zss_engine.isDevAndTest) zss_engine.isServer ? (0, zss_engine.injectServerCSS)(base36Hash, styleSheet) : (0, zss_engine.injectClientGlobalCSS)(styleSheet);
 }
+const keyframes = (object) => {
+	const prefix = (0, zss_engine.genBase36Hash)(object, 8);
+	global({ [`@keyframes ${prefix}`]: object });
+	return prefix;
+};
+const defineConsts = (constants) => {
+	return constants;
+};
 const defineVars = (object) => {
 	const styles = { ":root": {} };
 	const result = {};
@@ -58,27 +72,28 @@ const defineTheme = (object) => {
 	global(styles);
 	return result;
 };
-const keyframes = (object) => {
-	const prefix = (0, zss_engine.genBase36Hash)(object, 8);
-	global({ [`@keyframes ${prefix}`]: object });
-	return prefix;
-};
 var css = class {
 	static create(object) {
 		return create(object);
 	}
+	static createComposite(className, object) {
+		return createComposite(className, object);
+	}
 	static global(object) {
 		return global(object);
 	}
+	static keyframes(object) {
+		return keyframes(object);
+	}
+	static defineConsts(object) {
+		return defineConsts(object);
+	}
 	static defineVars(object) {
 		return defineVars(object);
 	}
 	static defineTheme(object) {
 		return defineTheme(object);
 	}
-	static keyframes(object) {
-		return keyframes(object);
-	}
 	static media = zss_utils.media;
 	static container = zss_utils.container;
 	static pseudo = zss_utils.pseudo;

package/dist/index.mjs

@@ -18,6 +18,12 @@ function create(object) {
 	});
 	return Object.freeze(object);
 }
+function createComposite(className, object) {
+	const composed = create(object);
+	const result = {};
+	for (const key in composed) result[key] = `${className} ${composed[key]}`;
+	return result;
+}
 function global(object) {
 	const base36Hash = genBase36Hash(object, 8);
 	const { styleSheet } = transpiler(object, void 0, "--global");
@@ -25,6 +31,14 @@ function global(object) {
 	resolvePromise_2(styleSheet);
 	if (isDevAndTest) isServer ? injectServerCSS(base36Hash, styleSheet) : injectClientGlobalCSS(styleSheet);
 }
+const keyframes = (object) => {
+	const prefix = genBase36Hash(object, 8);
+	global({ [`@keyframes ${prefix}`]: object });
+	return prefix;
+};
+const defineConsts = (constants) => {
+	return constants;
+};
 const defineVars = (object) => {
 	const styles = { ":root": {} };
 	const result = {};
@@ -57,27 +71,28 @@ const defineTheme = (object) => {
 	global(styles);
 	return result;
 };
-const keyframes = (object) => {
-	const prefix = genBase36Hash(object, 8);
-	global({ [`@keyframes ${prefix}`]: object });
-	return prefix;
-};
 var css = class {
 	static create(object) {
 		return create(object);
 	}
+	static createComposite(className, object) {
+		return createComposite(className, object);
+	}
 	static global(object) {
 		return global(object);
 	}
+	static keyframes(object) {
+		return keyframes(object);
+	}
+	static defineConsts(object) {
+		return defineConsts(object);
+	}
 	static defineVars(object) {
 		return defineVars(object);
 	}
 	static defineTheme(object) {
 		return defineTheme(object);
 	}
-	static keyframes(object) {
-		return keyframes(object);
-	}
 	static media = media;
 	static container = container;
 	static pseudo = pseudo;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plumeria/core",
-  "version": "0.9.7",
-  "description": "Zero-runtime CSS in JS - Compile at build-time. No runtime overhead.",
+  "version": "0.9.9",
+  "description": "Zero-runtime, expressive CSS-in-JS library for TypeScript.",
   "keywords": [
     "css",
     "css-in-js",
@@ -39,7 +39,7 @@
     "stylesheet.css"
   ],
   "dependencies": {
-    "zss-engine": "0.2.39",
+    "zss-engine": "0.2.40",
     "zss-utils": "0.2.3"
   },
   "publishConfig": {