@praxisjs/css 0.3.4 → 0.3.5

package/src/cx.ts

@@ -8,19 +8,26 @@ export type ClassValue =
   | Record<string, unknown>;
 
 export function cx(...args: ClassValue[]): string {
-  const classes: string[] = [];
-  for (const arg of args) {
-    if (!arg && arg !== 0) continue;
-    if (typeof arg === "string" || typeof arg === "number") {
-      classes.push(String(arg));
-    } else if (Array.isArray(arg)) {
-      const inner = cx(...(arg as ClassValue[]));
-      if (inner) classes.push(inner);
-    } else if (typeof arg === "object") {
-      for (const [key, val] of Object.entries(arg)) {
-        if (val) classes.push(key);
-      }
+  let out = "";
+  for (const arg of args) out = append(out, arg);
+  return out;
+}
+
+// Builds the string directly instead of collecting parts in an array: cx() runs on every render of
+// every styled component.
+function append(out: string, arg: ClassValue): string {
+  if (!arg && arg !== 0) return out;
+  if (typeof arg === "string" || typeof arg === "number") {
+    return out === "" ? String(arg) : `${out} ${String(arg)}`;
+  }
+  if (Array.isArray(arg)) {
+    for (const item of arg) out = append(out, item);
+    return out;
+  }
+  if (typeof arg === "object") {
+    for (const key in arg) {
+      if (Object.hasOwn(arg, key) && arg[key]) out = out === "" ? key : `${out} ${key}`;
     }
   }
-  return classes.join(" ");
+  return out;
 }

package/src/decorators/param.ts

@@ -1,13 +1,7 @@
-import { createFieldDecorator } from "@praxisjs/decorators";
+import { addParamName } from "../internal/sheet.js";
 
 import type { ReactiveStylesheet } from "../base/stylesheet.js";
 
-const PARAM_META = new WeakMap<object, Set<string>>();
-
-export function getParamNames(ctor: object): Set<string> {
-  return PARAM_META.get(ctor) ?? new Set();
-}
-
 /**
  * Marks a field in a {@link ReactiveStylesheet} subclass as a reactive CSS custom property.
  * The field name becomes `--fieldName` on the component's container element.
@@ -28,13 +22,15 @@ export function getParamNames(ctor: object): Set<string> {
  * this.$card.color = '#ef4444'  // updates --color reactively
  */
 export function Param() {
-  return createFieldDecorator<ReactiveStylesheet>({
-    bind(instance, name) {
-      const ctor = (instance as object).constructor as object;
-      let meta = PARAM_META.get(ctor);
-      if (!meta) { meta = new Set(); PARAM_META.set(ctor, meta); }
-      meta.add(name);
-      return {};
-    },
-  });
+  // Only records the field name: a stylesheet is instantiated once per class, as the template
+  // `@Styled` compiles, and every component instance then gets its own signals from there.
+  return function <This extends ReactiveStylesheet, Value>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<This, Value>,
+  ): void {
+    const name = context.name as string;
+    context.addInitializer(function (this: This) {
+      addParamName(this.constructor, name);
+    });
+  };
 }

package/src/decorators/style.ts

@@ -1,5 +1,26 @@
-import { effect, getComponentAnchor, signal } from "@praxisjs/core/internal";
-import { createFieldDecorator } from "@praxisjs/decorators";
+import {
+  createEffect,
+  disposeEffect,
+  getComponentAnchor,
+  readSignal,
+  SignalNode,
+  writeSignal,
+  type EffectNode,
+} from "@praxisjs/core/internal";
+import { addClaimableInitializer, assertFieldContext } from "@praxisjs/decorators";
+
+import { HookedField, type LifecycleHost } from "../internal/lifecycle.js";
+
+class StyleField extends HookedField {
+  readonly node: SignalNode<string | number>;
+  effect: EffectNode | undefined = undefined;
+  el: HTMLElement | undefined = undefined;
+
+  constructor(instance: LifecycleHost, value: string | number) {
+    super(instance);
+    this.node = new SignalNode(value);
+  }
+}
 
 /**
  * Reactive field decorator that binds a signal value to a CSS custom property
@@ -15,37 +36,60 @@ import { createFieldDecorator } from "@praxisjs/decorators";
  * }
  */
 export function Style(property: `--${string}`) {
-  return createFieldDecorator<object>({
-    bind(instance, _name, initialValue) {
-      const sig = signal(initialValue as string | number);
-      let stopEffect: (() => void) | null = null;
-
-      return {
-        descriptor: {
-          get() {
-            return sig();
-          },
-          set(v: string | number) {
-            sig.set(v);
-          },
-        },
-
-        onMount() {
-          const el = getComponentAnchor(instance)?.parentElement ?? null;
-          if (!el) return;
-
-          stopEffect = effect(() => {
-            el.style.setProperty(property, String(sig()));
-          });
-        },
-
-        onUnmount() {
-          stopEffect?.();
-          stopEffect = null;
-          const el = getComponentAnchor(instance)?.parentElement ?? null;
-          if (el) el.style.removeProperty(property);
-        },
-      };
-    },
-  });
+  return function <This extends object, Value = unknown>(
+    _value: undefined,
+    context: ClassFieldDecoratorContext<This, Value>,
+  ): void {
+    assertFieldContext(context);
+    const name = context.name;
+    // Accessors and hooks are shared by every instance of the decorated field; the instance's
+    // own state lives in this slot.
+    const slot = Symbol(`praxis.style.${String(name)}`);
+    type Host = LifecycleHost & Record<typeof slot, StyleField>;
+
+    const descriptor: PropertyDescriptor = {
+      enumerable: true,
+      configurable: true,
+      get(this: Host) {
+        return readSignal(this[slot].node);
+      },
+      set(this: Host, value: string | number) {
+        writeSignal(this[slot].node, value);
+      },
+    };
+
+    function onMount(this: Host): void {
+      const field = this[slot];
+      field.prevMount?.call(this);
+      const el = getComponentAnchor(this)?.parentElement;
+      if (!el) return;
+      const node = field.node;
+      field.el = el;
+      field.effect = createEffect(() => {
+        el.style.setProperty(property, String(readSignal(node)));
+      });
+    }
+
+    function onUnmount(this: Host): void {
+      const field = this[slot];
+      field.prevUnmount?.call(this);
+      if (field.effect) {
+        disposeEffect(field.effect);
+        field.effect = undefined;
+      }
+      // The element it was set on, even if the anchor has been detached by now.
+      if (field.el) {
+        field.el.style.removeProperty(property);
+        field.el = undefined;
+      }
+    }
+
+    addClaimableInitializer(context, function (value) {
+      const host = this as unknown as Host & Record<PropertyKey, unknown>;
+      host[slot] = new StyleField(host, value as string | number);
+      Object.defineProperty(host, name, descriptor);
+      host.onMount = onMount;
+      host.onUnmount = onUnmount;
+    });
+  };
 }

package/src/decorators/styled.ts

@@ -1,63 +1,72 @@
 import type { StatefulComponent } from "@praxisjs/core";
-import { effect, getComponentAnchor, signal } from "@praxisjs/core/internal";
-import { createFieldDecorator } from "@praxisjs/decorators";
-
-import { getParamNames } from "./param.js";
-import { isCSSBuilder } from "../builder/css-builder.js";
-import { hashCSS } from "../internal/hash.js";
-import { injectStyle, releaseStyle } from "../internal/registry.js";
+import {
+  createEffect,
+  disposeEffect,
+  getComponentAnchor,
+  readSignal,
+  SignalNode,
+  writeSignal,
+  type EffectNode,
+} from "@praxisjs/core/internal";
+import { assertFieldContext } from "@praxisjs/decorators";
+
+import { HookedField, type LifecycleHost } from "../internal/lifecycle.js";
+import { injectStyle } from "../internal/registry.js";
+import { compileSheet, type CompiledSheet } from "../internal/sheet.js";
 
 import type { ReactiveStylesheet, Stylesheet } from "../base/stylesheet.js";
 
-// ─── Class data cache ─────────────────────────────────────────────────────────
+type ParamValue = string | number;
+
+const PARAMS = Symbol("praxis.styled.params");
 
-interface StyleClassData {
-  classMap: Readonly<Record<string, string>>;
-  rawCSS: string;
-  registryKey: string;
-  paramDefaults: Readonly<Record<string, string | number>>;
+interface ParamSheet {
+  readonly [PARAMS]: Array<SignalNode<ParamValue>>;
 }
 
-const styleClassCache = new Map<new () => Stylesheet, StyleClassData>();
-
-function getStyleClassData(StyleClass: new () => Stylesheet): StyleClassData {
-  const cached = styleClassCache.get(StyleClass);
-  if (cached) return cached;
-
-  // Constructing the template fires @Param() addInitializers, populating PARAM_META.
-  const template = new StyleClass() as unknown as Record<string, unknown>;
-  const paramNames = getParamNames(StyleClass);
-
-  const classMap: Record<string, string> = {};
-  const blocks: string[] = [];
-  const paramDefaults: Record<string, string | number> = {};
-
-  for (const [key, value] of Object.entries(template)) {
-    if (key.startsWith("$")) {
-      // Accept plain strings or fluent CSSBuilder values.
-      const css = typeof value === "string" ? value : isCSSBuilder(value) ? String(value) : null;
-      if (css !== null) {
-        const safeName = key.slice(1).replace(/[^\w-]/g, "-");
-        const className = `prx-${safeName}-${hashCSS(css)}`;
-        classMap[key] = className;
-        blocks.push(`.${className} { ${css.trim()} }`);
-      }
-    } else if (paramNames.has(key) && (typeof value === "string" || typeof value === "number")) {
-      paramDefaults[key] = value;
+// One class per stylesheet: the class names and the @Param() accessors live on its prototype,
+// so an instance is a single slot holding its signal nodes.
+function createParamSheetClass(sheet: CompiledSheet): new (nodes: Array<SignalNode<ParamValue>>) => ParamSheet {
+  class Sheet implements ParamSheet {
+    readonly [PARAMS]: Array<SignalNode<ParamValue>>;
+
+    constructor(nodes: Array<SignalNode<ParamValue>>) {
+      this[PARAMS] = nodes;
     }
   }
-
-  const data: StyleClassData = {
-    classMap: Object.freeze(classMap),
-    rawCSS: blocks.join("\n"),
-    registryKey: blocks.length ? hashCSS(blocks.join("\n")) : "",
-    paramDefaults: Object.freeze(paramDefaults),
-  };
-  styleClassCache.set(StyleClass, data);
-  return data;
+  const proto = Sheet.prototype;
+  for (const key in sheet.classMap) {
+    Object.defineProperty(proto, key, { value: sheet.classMap[key], writable: true, enumerable: true, configurable: true });
+  }
+  sheet.params.forEach((param, i) => {
+    Object.defineProperty(proto, param, {
+      enumerable: true,
+      configurable: true,
+      get(this: ParamSheet) {
+        return readSignal(this[PARAMS][i]);
+      },
+      set(this: ParamSheet, value: ParamValue) {
+        writeSignal(this[PARAMS][i], value);
+      },
+    });
+  });
+  return Sheet;
 }
 
-// ─── @Styled field decorator ──────────────────────────────────────────────────
+class ParamField extends HookedField {
+  readonly nodes: Array<SignalNode<ParamValue>>;
+  readonly sheet: ParamSheet;
+  effects: EffectNode[] | undefined = undefined;
+  el: HTMLElement | undefined = undefined;
+
+  constructor(instance: LifecycleHost, Sheet: new (nodes: Array<SignalNode<ParamValue>>) => ParamSheet, defaults: readonly ParamValue[]) {
+    super(instance);
+    const nodes = new Array<SignalNode<ParamValue>>(defaults.length);
+    for (let i = 0; i < defaults.length; i++) nodes[i] = new SignalNode(defaults[i]);
+    this.nodes = nodes;
+    this.sheet = new Sheet(nodes);
+  }
+}
 
 /**
  * Scoped CSS field decorator. Receives a {@link Stylesheet} or
@@ -97,71 +106,78 @@ export function Styled<T extends Stylesheet>(
 ): [T] extends [ReactiveStylesheet]
   ? (value: undefined, context: ClassFieldDecoratorContext<StatefulComponent, T>) => void
   : (value: undefined, context: ClassFieldDecoratorContext<object, T>) => void {
-  const data = getStyleClassData(StyleClass);
+  const sheet = compileSheet(StyleClass);
+  const { css, key } = sheet;
 
   // Eagerly inject CSS at decoration time (module load) so it is in the DOM
   // before any component mounts — avoids layout-measurement timing issues.
-  // The per-instance onMount/onUnmount still manage the ref count on top of
-  // this base reference, which intentionally stays for the page lifetime.
-  if (data.rawCSS) injectStyle(data.registryKey, data.rawCSS);
-
-  return createFieldDecorator<object>({
-    bind(instance) {
-      type ParamSig = ReturnType<typeof signal<string | number>>;
-      const paramSignals: Record<string, ParamSig> = {};
-      const hasParams = Object.keys(data.paramDefaults).length > 0;
-
-      const stylesheetObj: Record<string, unknown> = hasParams
-        ? { ...data.classMap }
-        : (data.classMap as Record<string, unknown>);
-
-      for (const [paramName, defaultVal] of Object.entries(data.paramDefaults)) {
-        const sig = signal(defaultVal);
-        paramSignals[paramName] = sig;
-        Object.defineProperty(stylesheetObj, paramName, {
-          get() { return sig(); },
-          set(v: string | number) { sig.set(v); },
-          enumerable: true,
-          configurable: true,
-        });
+  if (css) injectStyle(key, css);
+
+  // Both paths return the field's value from its initializer, which is much cheaper than redefining
+  // the field with Object.defineProperty on every new instance. Each instance also re-checks the
+  // stylesheet (cheap when present): it is collected again during a server render, and put back
+  // if its <style> was removed.
+  if (sheet.params.length === 0) {
+    // The same frozen class map for every instance: no per-instance object, signals or hooks.
+    const { classMap } = sheet;
+    return ((_value: undefined, context: ClassFieldDecoratorContext) => {
+      assertFieldContext(context);
+      return () => {
+        if (css) injectStyle(key, css);
+        return classMap;
+      };
+    }) as never;
+  }
+
+  const Sheet = createParamSheetClass(sheet);
+  const { defaults } = sheet;
+  const vars = sheet.params.map((param) => `--${param}`);
+
+  return ((_value: undefined, context: ClassFieldDecoratorContext) => {
+    assertFieldContext(context);
+    const name = context.name;
+    const slot = Symbol(`praxis.styled.${String(name)}`);
+    type Host = LifecycleHost & Record<typeof slot, ParamField>;
+
+    function onMount(this: Host): void {
+      const field = this[slot];
+      field.prevMount?.call(this);
+      const el = getComponentAnchor(this)?.parentElement;
+      if (!el) return;
+      const effects: EffectNode[] = [];
+      for (let i = 0; i < vars.length; i++) {
+        const node = field.nodes[i];
+        const prop = vars[i];
+        effects.push(createEffect(() => {
+          el.style.setProperty(prop, String(readSignal(node)));
+        }));
       }
+      field.el = el;
+      field.effects = effects;
+    }
 
-      let stopFns: Array<() => void> = [];
-
-      return {
-        descriptor: { value: stylesheetObj, writable: false },
-
-        onMount() {
-          // Increment ref-count for this instance (base ref injected at decoration time).
-          if (data.rawCSS) injectStyle(data.registryKey, data.rawCSS);
-
-          if (hasParams) {
-            const el = getComponentAnchor(instance)?.parentElement;
-            if (el) {
-              for (const [paramName, sig] of Object.entries(paramSignals)) {
-                stopFns.push(effect(() => {
-                  el.style.setProperty(`--${paramName}`, String(sig()));
-                }));
-              }
-            }
-          }
-        },
-
-        onUnmount() {
-          if (data.rawCSS) releaseStyle(data.registryKey);
-          for (const stop of stopFns) stop();
-          stopFns = [];
-
-          if (hasParams) {
-            const el = getComponentAnchor(instance)?.parentElement;
-            if (el) {
-              for (const paramName of Object.keys(paramSignals)) {
-                el.style.removeProperty(`--${paramName}`);
-              }
-            }
-          }
-        },
-      };
-    },
-  });
+    function onUnmount(this: Host): void {
+      const field = this[slot];
+      field.prevUnmount?.call(this);
+      const { effects, el } = field;
+      if (effects) {
+        for (const effect of effects) disposeEffect(effect);
+        field.effects = undefined;
+      }
+      // The element the vars were set on, even if the anchor has been detached by now.
+      if (el) {
+        for (const prop of vars) el.style.removeProperty(prop);
+        field.el = undefined;
+      }
+    }
+
+    return function (this: Host): ParamSheet {
+      if (css) injectStyle(key, css);
+      const field = new ParamField(this, Sheet, defaults);
+      this[slot] = field;
+      this.onMount = onMount;
+      this.onUnmount = onUnmount;
+      return field.sheet;
+    };
+  }) as never;
 }

package/src/extract.ts

@@ -1,6 +1,11 @@
 import { Stylesheet, ReactiveStylesheet } from "./base/stylesheet.js";
-import { isCSSBuilder, createCSSBuilder, type CSSProperties } from "./builder/css-builder.js";
+import { createCSSBuilder, type CSSProperties } from "./builder/css-builder.js";
+import { keyframesRule } from "./builder/keyframes.js";
+import { globalCSS, type GlobalStyleFactory, type GlobalStyleOptions } from "./global.js";
 import { hashCSS } from "./internal/hash.js";
+import { compileSheet } from "./internal/sheet.js";
+import { preflightCSS, type PreflightOptions } from "./preflight.js";
+import { instanceToVars, varsToCSS } from "./tokens/theme-instance.js";
 import { TokenSheet, tokenVars } from "./tokens/token-sheet.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -12,18 +17,10 @@ type Ctor = new (...args: any[]) => unknown;
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-function camelToKebab(s: string): string {
-  return s.replace(/([A-Z])/g, "-$1").toLowerCase();
-}
-
 function themeToRootCSS(ThemeClass: Ctor): string | null {
   try {
-    const inst = new ThemeClass() as Record<string, unknown>;
-    const vars = Object.entries(inst)
-      .filter(([, v]) => typeof v === "string" || typeof v === "number")
-      .map(([k, v]) => `  --${camelToKebab(k)}: ${String(v)};`)
-      .join("\n");
-    return vars ? `:root {\n${vars}\n}` : null;
+    const vars = instanceToVars(new ThemeClass() as Record<string, unknown>);
+    return Object.keys(vars).length > 0 ? varsToCSS(vars) : null;
   } catch {
     return null;
   }
@@ -31,16 +28,8 @@ function themeToRootCSS(ThemeClass: Ctor): string | null {
 
 function collectSheetCSS(SheetClass: Ctor, emit: EmitFn): void {
   try {
-    const inst = new SheetClass() as Record<string, unknown>;
-    const blocks: string[] = [];
-    for (const [k, v] of Object.entries(inst)) {
-      if (!k.startsWith("$")) continue;
-      const css = typeof v === "string" ? v : (isCSSBuilder(v) ? String(v) : null);
-      if (!css) continue;
-      const name = k.slice(1).replace(/[^\w-]/g, "-");
-      blocks.push(`.prx-${name}-${hashCSS(css)} { ${css.trim()} }`);
-    }
-    if (blocks.length) emit(blocks.join("\n"));
+    const { css } = compileSheet(SheetClass);
+    if (css) emit(css);
   } catch { /* skip sheets that can't be instantiated at build time */ }
 }
 
@@ -117,20 +106,15 @@ export function extractionModule(emit: EmitFn): Record<string, unknown> {
     Style:  () => () => {},
     cx:     () => "",
     keyframes: (name: string, stops: Record<string, CSSProperties>) => {
-      const stopToCSS = (p: CSSProperties) =>
-        Object.entries(p)
-          .filter(([, v]) => v != null)
-          .map(([k, v]) => `    ${camelToKebab(k)}: ${String(v)};`)
-          .join("\n");
-      const body = Object.entries(stops)
-        .map(([s, p]) => `  ${s} {\n${stopToCSS(p)}\n  }`)
-        .join("\n");
-      const sn = `prx-${name}-${hashCSS(body)}`;
-      dedupEmit(`@keyframes ${sn} {\n${body}\n}`);
-      return sn;
+      const rule = keyframesRule(name, stops);
+      dedupEmit(rule.css);
+      return rule.name;
+    },
+    globalStyle: (factory: GlobalStyleFactory, options?: GlobalStyleOptions) => {
+      dedupEmit(globalCSS(factory, options));
     },
-    globalStyle: (factory: (css: typeof createCSSBuilder) => unknown) => {
-      dedupEmit(String(factory(createCSSBuilder)));
+    preflight: (options?: PreflightOptions) => {
+      dedupEmit(preflightCSS(options));
     },
   };
 }

package/src/global.ts

@@ -1,6 +1,7 @@
 import { createCSSBuilder, type CSSProperties, type CSSBuilder } from "./builder/css-builder.js";
 import { getCollector } from "./internal/collector.js";
 import { hashCSS } from "./internal/hash.js";
+import { STATIC_MODE } from "./internal/static-mode.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -17,14 +18,14 @@ export interface GlobalStyleOptions {
   layer?: string | false;
 }
 
-// ─── Static mode ──────────────────────────────────────────────────────────────
-
-declare const __PRAXIS_CSS_STATIC__: boolean | undefined;
-const STATIC_MODE: boolean =
-  typeof __PRAXIS_CSS_STATIC__ !== "undefined" && __PRAXIS_CSS_STATIC__;
-
 const injected = new Set<string>();
 
+/** The CSS a `globalStyle()` call injects — shared with build-time extraction. */
+export function globalCSS(factory: GlobalStyleFactory, { layer }: GlobalStyleOptions = {}): string {
+  const rawCSS = String(factory(createCSSBuilder));
+  return layer ? `@layer ${layer} {\n${rawCSS}\n}` : rawCSS;
+}
+
 // ─── globalStyle ─────────────────────────────────────────────────────────────
 
 /**
@@ -54,10 +55,10 @@ const injected = new Set<string>();
  * globalStyle(_css => `body { font-family: system-ui; }`, { layer: 'base' })
  */
 export function globalStyle(factory: GlobalStyleFactory, options: GlobalStyleOptions = {}): void {
-  const rawCSS = String(factory(createCSSBuilder));
-  const { layer } = options;
-  const css = layer ? `@layer ${layer} {\n${rawCSS}\n}` : rawCSS;
+  injectGlobalCSS(globalCSS(factory, options));
+}
 
+export function injectGlobalCSS(css: string): void {
   const key = hashCSS(css);
   if (injected.has(key)) return;
   injected.add(key);

package/src/internal/kebab.ts

@@ -0,0 +1,23 @@
+const cache = new Map<string, string>();
+
+/** `backgroundColor` → `background-color`. Memoized: the same few hundred property and token names repeat. */
+export function toKebab(camel: string): string {
+  let kebab = cache.get(camel);
+  if (kebab === undefined) {
+    kebab = camel.replace(/([A-Z])/g, "-$1").toLowerCase();
+    cache.set(camel, kebab);
+  }
+  return kebab;
+}
+
+/** One `prop: value;` line per defined entry, each prefixed with `indent`. */
+export function declarations(props: Readonly<Record<string, string | number | null | undefined>>, indent: string): string {
+  let out = "";
+  for (const key in props) {
+    const value = props[key];
+    if (value == null) continue;
+    const line = `${indent}${toKebab(key)}: ${String(value)};`;
+    out = out === "" ? line : `${out}\n${line}`;
+  }
+  return out;
+}

package/src/internal/lifecycle.ts

@@ -0,0 +1,21 @@
+export interface LifecycleHost {
+  onMount?(): void;
+  onUnmount?(): void;
+}
+
+/**
+ * Per-instance state of a decorated field that needs mount/unmount hooks. The hooks themselves
+ * are shared per decorated field and find this state through a symbol slot, so chaining onto
+ * the instance's own `onMount`/`onUnmount` allocates no closures.
+ */
+export class HookedField {
+  readonly prevMount: (() => void) | undefined;
+  readonly prevUnmount: (() => void) | undefined;
+
+  constructor(instance: LifecycleHost) {
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- called back with `.call(instance)`
+    this.prevMount = instance.onMount;
+    // eslint-disable-next-line @typescript-eslint/unbound-method -- called back with `.call(instance)`
+    this.prevUnmount = instance.onUnmount;
+  }
+}