nuclo 0.2.19 → 0.2.21

package/dist/style/css.d.ts

@@ -2,14 +2,21 @@ import type { ClassInput, CssInstance, FlatStyle, KeyframeFrames, Style, StyleRe
 export type { ClassInput, CssInstance, CSSProperties, FlatStyle, KeyframeFrames, KeyframeStop, Pseudo, Size, Style, StyleResult, ThemeConfig, VariantDefinitions, VariantProps, VariantsConfig, VariantsFn, } from "../../types/style";
 /**
  * Compose class lists with exact conflict resolution: when two inputs style
- * the same (query, selector, property), the last one wins. Works because the
- * engine knows what every class it generated means. Nested arrays are flattened,
- * so `cx([a, cond && b], c)` composes the same as `cx(a, cond && b, c)`.
+ * the same (query, selector-suffix) context, their declaration blocks merge
+ * with the later input winning per property — the merged block gets its own
+ * content-addressed class, so `cx(base, active)` keeps every base property
+ * the active style doesn't override. Works because the engine remembers what
+ * every class it minted means. Unknown external classes pass through as-is.
+ * Nested arrays are flattened, so `cx([a, cond && b], c)` composes the same
+ * as `cx(a, cond && b, c)`.
  */
 export declare function cx(...inputs: ClassInput[]): StyleResult;
 export declare function createCss<const T extends ThemeConfig>(theme?: T): CssInstance<T>;
 /** Themeless css() — full property/variant typing, no tokens or screens. */
-export declare const css: (style: Style<object>) => StyleResult;
+export declare const css: {
+    (style: Style<object>): StyleResult;
+    (name: string, style: Style<object>): StyleResult;
+};
 /** Themeless variants() recipe helper. */
 export declare const variants: <const V extends VariantDefinitions<object>>(config: VariantsConfig<object, V>) => VariantsFn<V>;
 /** Themeless keyframes() helper. */

package/dist/style/css.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/style/css.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,cAAc,EAEd,KAAK,EACL,WAAW,EACX,WAAW,EACX,kBAAkB,EAElB,cAAc,EACd,UAAU,EACV,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,UAAU,GACV,MAAM,mBAAmB,CAAC;AAiJ3B;;;;;GAKG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,WAAW,CAMvD;AAKD,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,GAAE,CAAW,GAAG,WAAW,CAAC,CAAC,CAAC,CA2NzF;AAgBD,4EAA4E;AAC5E,eAAO,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,WAAwD,CAAC;AACrG,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,EACjE,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,KAC7B,UAAU,CAAC,CAAC,CAAqD,CAAC;AACvE,oCAAoC;AACpC,eAAO,MAAM,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,MAA2D,CAAC;AACxH,sCAAsC;AACtC,eAAO,MAAM,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,IACxB,CAAC"}
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../../src/style/css.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACX,UAAU,EACV,WAAW,EACX,SAAS,EACT,cAAc,EAEd,KAAK,EACL,WAAW,EACX,WAAW,EACX,kBAAkB,EAElB,cAAc,EACd,UAAU,EACV,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EACX,UAAU,EACV,WAAW,EACX,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,MAAM,EACN,IAAI,EACJ,KAAK,EACL,WAAW,EACX,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,cAAc,EACd,UAAU,GACV,MAAM,mBAAmB,CAAC;AA+L3B;;;;;;;;;GASG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,GAAG,WAAW,CAMvD;AAKD,wBAAgB,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,WAAW,EAAE,KAAK,GAAE,CAAW,GAAG,WAAW,CAAC,CAAC,CAAC,CA8QzF;AAgBD,4EAA4E;AAC5E,eAAO,MAAM,GAAG,EAAE;IACjB,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC;IACpC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC;CAIV,CAAC;AAC1C,0CAA0C;AAC1C,eAAO,MAAM,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,EACjE,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC,KAC7B,UAAU,CAAC,CAAC,CAAqD,CAAC;AACvE,oCAAoC;AACpC,eAAO,MAAM,SAAS,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,MAA2D,CAAC;AACxH,sCAAsC;AACtC,eAAO,MAAM,WAAW,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,KAAK,IACxB,CAAC"}

package/dist/style/engine.d.ts

@@ -1,5 +1,5 @@
 /**
- * Shared atomic-CSS engine state.
+ * Shared generated-CSS engine state.
  *
  * One stylesheet, one rule registry, shared by every `createCss` instance so
  * identical declarations dedupe globally and cascade order stays deterministic:
@@ -11,19 +11,44 @@
  */
 type SSRCollector = (rule: string) => void;
 export declare function setSSRCollector(fn: SSRCollector | null): void;
+export interface BlockMeta {
+    readonly query: string | undefined;
+    readonly suffix: string;
+    readonly decls: ReadonlyArray<readonly [string, string]>;
+    /** Author-supplied identity from `css(name, …)`; inherited by cx() merges. */
+    readonly name: string | undefined;
+}
 /** Pre-register at-rule queries so their cascade order follows theme order. */
 export declare function registerQueries(queries: Iterable<string>): void;
 /**
- * Order-independent 53-bit content hash (two interleaved FNV-1a style passes).
- * Class names must match between server and client for SSR hydration, so a
- * counter is not an option; 53 bits keeps collision odds negligible (~1e-5 at
- * 10k unique declarations).
+ * Content-addressed ~42-bit hash (two interleaved FNV-1a style passes). Class
+ * names must match between server and client for SSR hydration, so a counter
+ * is not an option; 42 bits keeps collision odds low (~1e-5 at 10k
+ * unique declaration blocks).
  */
 export declare function hash(input: string): string;
-/** One class per (query, selector-suffix, declaration) — the atomic core. */
-export declare function atom(query: string | undefined, suffix: string, property: string, value: string): string;
-/** Conflict key for a generated class — lets cx() resolve overrides exactly. */
+export declare function expandAmpersands(input: string, replacement: string): string;
+/**
+ * One class per (query, selector-suffix) — every declaration that shares that
+ * context compiles into a single rule under a single generated class name,
+ * rather than one class per individual property. Pass `name` to give the
+ * style a stable, readable identity (see mintBlock).
+ */
+export declare function atomBlock(query: string | undefined, suffix: string, decls: ReadonlyArray<readonly [string, string]>, name?: string, exactName?: boolean): string;
+/**
+ * Merge two same-context generated classes into one: `second`'s declarations
+ * override `first`'s per exact property (shorthand/longhand interplay is left
+ * to CSS order), and the combined block mints its own content-addressed class
+ * — so cx(base, override) keeps base's untouched properties instead of
+ * dropping the whole base class. Deterministic: the same pair always yields
+ * the same class name, on server and client alike. A named base passes its
+ * name down as a prefix, so `cx(appRoot, active)` reads as `app-root-1a2b3c`.
+ */
+export declare function mergeBlocks(first: string, second: string): string;
+/** Conflict key (query|suffix) for a generated class — lets cx() group classes by selector context. */
 export declare function conflictKeyOf(className: string): string | undefined;
+/** Current registry generation, used to invalidate per-instance WeakMap hits after resetStyles(). */
+export declare function getStyleEpoch(): number;
 /** Register a non-atomic rule (keyframes, global styles) once per dedupe key. */
 export declare function addRawRule(dedupeKey: string, rule: string): void;
 /** All generated CSS — base rules first, then at-rule groups in registration order. */

package/dist/style/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/style/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAG3C,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAE7D;AAwBD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAI/D;AA0FD;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1C;AAED,6EAA6E;AAC7E,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAavG;AAED,gFAAgF;AAChF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEnE;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOhE;AAED,uFAAuF;AACvF,wBAAgB,UAAU,IAAI,MAAM,CAQnC;AAED,gFAAgF;AAChF,wBAAgB,WAAW,IAAI,IAAI,CAclC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/style/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,KAAK,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAG3C,wBAAgB,eAAe,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,GAAG,IAAI,CAE7D;AAQD,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzD,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AA4BD,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,CAI/D;AAsND;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAS1C;AAWD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAsB3E;AA+FD;;;;;GAKG;AACH,wBAAgB,SAAS,CACxB,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC/C,IAAI,CAAC,EAAE,MAAM,EACb,SAAS,UAAQ,GACf,MAAM,CAER;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAWjE;AAED,uGAAuG;AACvG,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE;AAED,qGAAqG;AACrG,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAOhE;AAED,uFAAuF;AACvF,wBAAgB,UAAU,IAAI,MAAM,CAQnC;AAED,gFAAgF;AAChF,wBAAgB,WAAW,IAAI,IAAI,CAiBlC"}

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "nuclo",
 	"private": false,
-	"version": "0.2.19",
-	"description": "Lightweight, type-safe DOM library with plain mutable state and explicit updates — global tag builders, SSR, hydration, and atomic CSS, no virtual DOM, no compiler.",
+	"version": "0.2.21",
+	"description": "Lightweight, type-safe DOM library with plain mutable state and explicit updates — global tag builders, SSR, hydration, and typed CSS, no virtual DOM, no compiler.",
 	"license": "MIT",
 	"author": "Danilo Celestino de Castro (https://github.com/dan2dev)",
 	"keywords": [
@@ -56,6 +56,7 @@
 		"test": "npm run typecheck && vitest run --coverage",
 		"test:watch": "vitest --watch --coverage",
 		"bench": "bun bench/ssr.bench.ts && bun bench/hydrate.bench.ts",
+		"bench:style": "bun bench/style.bench.ts",
 		"bench:jfb": "bun bench/js-framework.bench.ts",
 		"lint": "eslint . --ext .ts,.js,.json,.jsonc,.json5,.md,.css",
 		"lint:fix": "eslint . --ext .ts,.js,.json,.jsonc,.json5,.md,.css --fix"

package/types/features/style.d.ts

@@ -62,6 +62,8 @@ declare global {
 
 	/** Themeless css() — full property/variant typing, no tokens or screens. */
 	function css(style: Style<object>): StyleResult;
+	/** Themeless css() under a readable, stable class name: `css("app-root", { … })` → `.app-root`. */
+	function css(name: string, style: Style<object>): StyleResult;
 	/** Compose class lists with last-wins conflict resolution. */
 	function cx(...inputs: ClassInput[]): StyleResult;
 	/** Themeless variants() recipe helper. */

package/types/index.d.ts

@@ -107,6 +107,7 @@ export const isBrowser: boolean;
 // Styling (themeless default instance + themed factory)
 export function createCss<const T extends ThemeConfig>(theme?: T): CssInstance<T>;
 export function css(style: Style<object>): StyleResult;
+export function css(name: string, style: Style<object>): StyleResult;
 export function cx(...inputs: ClassInput[]): StyleResult;
 export function variants<const V extends VariantDefinitions<object>>(
   config: VariantsConfig<object, V>,

package/types/ssr.d.ts

@@ -41,5 +41,5 @@ export function renderToStringWithContainer(
  */
 export function setSSRCollector(fn: ((rule: string) => void) | null): void;
 
-/** Serialize every registered atomic CSS rule (for a <style> tag in SSR output). */
+/** Serialize every registered generated CSS rule (for a <style> tag in SSR output). */
 export function getCssText(): string;

package/types/style.d.ts

@@ -1,5 +1,5 @@
 /**
- * nuclo styling type definitions — atomic, theme-aware, typed CSS-in-TS.
+ * nuclo styling type definitions — block-based, theme-aware, typed CSS-in-TS.
  *
  * This module is the single source of truth for the styling types. It lives in
  * `types/` (shipped in the npm package alongside `dist/`) so that both the
@@ -334,7 +334,7 @@ export type StyleResult = {
 };
 
 // ---------------------------------------------------------------------------
-// Variants — typed, atomic style recipes (base + named variant groups +
+// Variants — typed style recipes (base + named variant groups +
 // defaults + compound variants). One recipe in, a call-with-props function out.
 // ---------------------------------------------------------------------------
 
@@ -379,10 +379,19 @@ export type ClassInput = StyleResult | string | false | null | undefined | reado
 /** A themed styling instance returned by createCss(). */
 export interface CssInstance<T extends ThemeConfig = ThemeConfig> {
 	/**
-	 * Compile a style object into atomic CSS classes.
+	 * Compile a style object into CSS classes — one per selector context
+	 * (base, each pseudo-selector, each media query) it touches.
 	 * Returns `{ className }` — usable directly as a nuclo attributes object.
 	 */
 	css(style: Style<T>): StyleResult;
+	/**
+	 * Compile a style object under a readable, stable class name:
+	 * `css("app-root", { minHeight: "100vh" })` → `.app-root`.
+	 * The base context takes the name verbatim; the style's other contexts
+	 * take it as a prefix (`app-root-1a2b3c`). Named styles are keyed by name
+	 * as well as content, so they never share a class with an unrelated style.
+	 */
+	css(name: string, style: Style<T>): StyleResult;
 	/**
 	 * Compose class lists with exact conflict resolution: when two inputs
 	 * style the same (query, selector, property), the last one wins.