@praxisjs/css 0.1.0

package/src/builder/css-builder.ts

@@ -0,0 +1,204 @@
+import type { Properties } from "csstype";
+
+// ─── CSSProperties ────────────────────────────────────────────────────────────
+
+/**
+ * Typed CSS property object — backed by `csstype`.
+ * All ~300 CSS properties with full value autocomplete.
+ * Used as the argument to `this.css({...})` and all nesting methods.
+ */
+export type CSSProperties = Properties<string | number> & Record<string, string | number | undefined>;
+
+// ─── CSSBuilder ───────────────────────────────────────────────────────────────
+
+/**
+ * Fluent CSS builder returned by `this.css({...})`.
+ * TypeScript sees it as `string` — works in JSX `class=`, `cx()`, computed keys.
+ * Serialises to a CSS rule block via `toString()`.
+ *
+ * @example
+ * class BtnStyles extends Stylesheet {
+ *   $base = this.css({ display: 'inline-flex', padding: '8px 16px' })
+ *     .hover({ opacity: 0.9 })
+ *     .disabled({ opacity: 0.4, pointerEvents: 'none' })
+ *     .before({ content: '""', display: 'block' })
+ *     .media('max-width: 640px', { width: '100%' })
+ * }
+ */
+export type CSSBuilder = string & {
+  // ── Pseudo-classes — interaction ──────────────────────────────────────────
+  /** `&:hover { ... }` */
+  hover(props: CSSProperties): CSSBuilder;
+  /** `&:focus { ... }` */
+  focus(props: CSSProperties): CSSBuilder;
+  /** `&:focus-within { ... }` */
+  focusWithin(props: CSSProperties): CSSBuilder;
+  /** `&:focus-visible { ... }` */
+  focusVisible(props: CSSProperties): CSSBuilder;
+  /** `&:active { ... }` */
+  active(props: CSSProperties): CSSBuilder;
+  /** `&:visited { ... }` */
+  visited(props: CSSProperties): CSSBuilder;
+  /** `&:target { ... }` */
+  target(props: CSSProperties): CSSBuilder;
+
+  // ── Pseudo-classes — form state ───────────────────────────────────────────
+  /** `&:disabled, &[disabled], &[aria-disabled="true"] { ... }` */
+  disabled(props: CSSProperties): CSSBuilder;
+  /** `&:enabled { ... }` */
+  enabled(props: CSSProperties): CSSBuilder;
+  /** `&:checked { ... }` */
+  checked(props: CSSProperties): CSSBuilder;
+  /** `&:indeterminate { ... }` */
+  indeterminate(props: CSSProperties): CSSBuilder;
+  /** `&:required { ... }` */
+  required(props: CSSProperties): CSSBuilder;
+  /** `&:optional { ... }` */
+  optional(props: CSSProperties): CSSBuilder;
+  /** `&:valid { ... }` */
+  valid(props: CSSProperties): CSSBuilder;
+  /** `&:invalid { ... }` */
+  invalid(props: CSSProperties): CSSBuilder;
+  /** `&:read-only { ... }` */
+  readOnly(props: CSSProperties): CSSBuilder;
+
+  // ── Pseudo-classes — structural ───────────────────────────────────────────
+  /** `&:first-child { ... }` */
+  first(props: CSSProperties): CSSBuilder;
+  /** `&:last-child { ... }` */
+  last(props: CSSProperties): CSSBuilder;
+  /** `&:nth-child(n) { ... }` */
+  nthChild(n: string | number, props: CSSProperties): CSSBuilder;
+  /** `&:empty { ... }` */
+  empty(props: CSSProperties): CSSBuilder;
+
+  // ── Pseudo-classes — relational (CSS Selectors Level 4) ──────────────────
+  /** `&:has(selector) { ... }` */
+  has(selector: string, props: CSSProperties): CSSBuilder;
+  /** `&:is(...) { ... }` */
+  is(selector: string, props: CSSProperties): CSSBuilder;
+  /** `&:where(...) { ... }` — zero specificity */
+  where(selector: string, props: CSSProperties): CSSBuilder;
+  /** `&:not(selector) { ... }` */
+  not(selector: string, props: CSSProperties): CSSBuilder;
+
+  // ── Pseudo-elements ───────────────────────────────────────────────────────
+  /** `&::before { ... }` */
+  before(props: CSSProperties): CSSBuilder;
+  /** `&::after { ... }` */
+  after(props: CSSProperties): CSSBuilder;
+  /** `&::placeholder { ... }` */
+  placeholder(props: CSSProperties): CSSBuilder;
+  /** `&::selection { ... }` */
+  selection(props: CSSProperties): CSSBuilder;
+  /** `&::first-line { ... }` */
+  firstLine(props: CSSProperties): CSSBuilder;
+  /** `&::first-letter { ... }` */
+  firstLetter(props: CSSProperties): CSSBuilder;
+  /** `&::marker { ... }` */
+  marker(props: CSSProperties): CSSBuilder;
+  /** `&::backdrop { ... }` */
+  backdrop(props: CSSProperties): CSSBuilder;
+
+  // ── At-rules ──────────────────────────────────────────────────────────────
+  /** `@media (query) { ... }` */
+  media(query: string, props: CSSProperties): CSSBuilder;
+  /** `@container (query) { ... }` */
+  container(query: string, props: CSSProperties): CSSBuilder;
+  /** `@supports (condition) { ... }` */
+  supports(condition: string, props: CSSProperties): CSSBuilder;
+  /** Any arbitrary nested selector or at-rule. */
+  on(selector: string, props: CSSProperties): CSSBuilder;
+};
+
+// ─── Runtime ──────────────────────────────────────────────────────────────────
+
+const CSS_BUILDER = Symbol("css-builder");
+
+export function isCSSBuilder(value: unknown): boolean {
+  return typeof value === "object" && value !== null &&
+    (value as Record<symbol, unknown>)[CSS_BUILDER] === true;
+}
+
+function toKebab(camel: string): string {
+  return camel.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+function propsToCSS(props: CSSProperties): string {
+  return Object.entries(props)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${toKebab(k)}: ${String(v)};`)
+    .join("\n");
+}
+
+export function createCSSBuilder(initialProps: CSSProperties): CSSBuilder {
+  const parts: string[] = [];
+  const rootCSS = propsToCSS(initialProps);
+  if (rootCSS) parts.push(rootCSS);
+
+  const addNested = (selector: string, props: CSSProperties): CSSBuilder => {
+    const rawCSS = propsToCSS(props);
+    if (!rawCSS) return builder;
+    const inner = rawCSS.split("\n").map((l) => `  ${l}`).join("\n");
+    parts.push(`${selector} {\n${inner}\n}`);
+    return builder;
+  };
+
+  const toCSS = (): string => parts.join("\n");
+
+  const builder = Object.assign(Object.create(null) as object, {
+    [CSS_BUILDER]:        true,
+    toString:             toCSS,
+    [Symbol.toPrimitive]: toCSS,
+
+    // Pseudo-classes — interaction
+    hover:        (p: CSSProperties) => addNested("&:hover", p),
+    focus:        (p: CSSProperties) => addNested("&:focus", p),
+    focusWithin:  (p: CSSProperties) => addNested("&:focus-within", p),
+    focusVisible: (p: CSSProperties) => addNested("&:focus-visible", p),
+    active:       (p: CSSProperties) => addNested("&:active", p),
+    visited:      (p: CSSProperties) => addNested("&:visited", p),
+    target:       (p: CSSProperties) => addNested("&:target", p),
+
+    // Pseudo-classes — form state
+    disabled:     (p: CSSProperties) => addNested('&:disabled, &[disabled], &[aria-disabled="true"]', p),
+    enabled:      (p: CSSProperties) => addNested("&:enabled", p),
+    checked:      (p: CSSProperties) => addNested("&:checked", p),
+    indeterminate:(p: CSSProperties) => addNested("&:indeterminate", p),
+    required:     (p: CSSProperties) => addNested("&:required", p),
+    optional:     (p: CSSProperties) => addNested("&:optional", p),
+    valid:        (p: CSSProperties) => addNested("&:valid", p),
+    invalid:      (p: CSSProperties) => addNested("&:invalid", p),
+    readOnly:     (p: CSSProperties) => addNested("&:read-only", p),
+
+    // Pseudo-classes — structural
+    first:        (p: CSSProperties) => addNested("&:first-child", p),
+    last:         (p: CSSProperties) => addNested("&:last-child", p),
+    nthChild:     (n: string | number, p: CSSProperties) => addNested(`&:nth-child(${String(n)})`, p),
+    empty:        (p: CSSProperties) => addNested("&:empty", p),
+
+    // Pseudo-classes — relational (Selectors Level 4)
+    has:          (sel: string, p: CSSProperties) => addNested(`&:has(${sel})`, p),
+    is:           (sel: string, p: CSSProperties) => addNested(`&:is(${sel})`, p),
+    where:        (sel: string, p: CSSProperties) => addNested(`&:where(${sel})`, p),
+    not:          (sel: string, p: CSSProperties) => addNested(`&:not(${sel})`, p),
+
+    // Pseudo-elements
+    before:       (p: CSSProperties) => addNested("&::before", p),
+    after:        (p: CSSProperties) => addNested("&::after", p),
+    placeholder:  (p: CSSProperties) => addNested("&::placeholder", p),
+    selection:    (p: CSSProperties) => addNested("&::selection", p),
+    firstLine:    (p: CSSProperties) => addNested("&::first-line", p),
+    firstLetter:  (p: CSSProperties) => addNested("&::first-letter", p),
+    marker:       (p: CSSProperties) => addNested("&::marker", p),
+    backdrop:     (p: CSSProperties) => addNested("&::backdrop", p),
+
+    // At-rules
+    media:        (q: string, p: CSSProperties) => addNested(`@media (${q})`, p),
+    container:    (q: string, p: CSSProperties) => addNested(`@container (${q})`, p),
+    supports:     (cond: string, p: CSSProperties) => addNested(`@supports (${cond})`, p),
+    on:           (sel: string, p: CSSProperties) => addNested(sel, p),
+  }) as unknown as CSSBuilder;
+
+  return builder;
+}

package/src/builder/keyframes.ts

@@ -0,0 +1,66 @@
+import { getCollector } from "../internal/collector.js";
+import { hashCSS } from "../internal/hash.js";
+
+import type { CSSProperties } from "./css-builder.js";
+
+// Defined by the Vite CSS plugin — skip DOM injection when CSS is static.
+declare const __PRAXIS_CSS_STATIC__: boolean | undefined;
+const STATIC_MODE: boolean =
+  typeof __PRAXIS_CSS_STATIC__ !== "undefined" && __PRAXIS_CSS_STATIC__;
+
+type KeyframeStops = Record<string, CSSProperties>;
+
+const injected = new Set<string>();
+
+function toKebab(camel: string): string {
+  return camel.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+function stopToCSS(props: CSSProperties): string {
+  return Object.entries(props)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `    ${toKebab(k)}: ${String(v)};`)
+    .join("\n");
+}
+
+/**
+ * Defines a scoped `@keyframes` animation and injects it into `document.head`.
+ * Returns the scoped animation name — use it in the `animation` or
+ * `animationName` property of a stylesheet field.
+ *
+ * The name is content-hashed so two identical animations share one injection.
+ * Safe to call at module level (outside components).
+ *
+ * @example
+ * const pulse = keyframes('pulse', {
+ *   from: { opacity: 1 },
+ *   to:   { opacity: 0.4 },
+ * })
+ *
+ * class LoaderStyles extends Stylesheet {
+ *   $spinner = this.css({ animation: `${pulse} 1.2s ease-in-out infinite` })
+ * }
+ */
+export function keyframes(name: string, stops: KeyframeStops): string {
+  const stopsCSS = Object.entries(stops)
+    .map(([stop, props]) => `  ${stop} {\n${stopToCSS(props)}\n  }`)
+    .join("\n");
+
+  const scopedName = `prx-${name}-${hashCSS(stopsCSS)}`;
+  const kfCSS = `@keyframes ${scopedName} {\n${stopsCSS}\n}`;
+
+  if (STATIC_MODE) return scopedName;
+
+  const col = getCollector();
+  if (col) { col.addKeyframes(scopedName, kfCSS); return scopedName; }
+
+  if (!injected.has(scopedName) && typeof document !== "undefined") {
+    const el = document.createElement("style");
+    el.setAttribute("data-praxis-keyframes", scopedName);
+    el.textContent = kfCSS;
+    document.head.appendChild(el);
+    injected.add(scopedName);
+  }
+
+  return scopedName;
+}

package/src/cx.ts

@@ -0,0 +1,26 @@
+export type ClassValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | 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);
+      }
+    }
+  }
+  return classes.join(" ");
+}

package/src/decorators/param.ts

@@ -0,0 +1,40 @@
+import { createFieldDecorator } from "@praxisjs/decorators";
+
+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.
+ * Setting the field updates the CSS var reactively — zero re-renders.
+ *
+ * Only valid inside a `ReactiveStylesheet` subclass. TypeScript enforces this at
+ * compile time via the `createFieldDecorator<ReactiveStylesheet>` constraint.
+ *
+ * @example
+ * class CardStyles extends ReactiveStylesheet {
+ *   @Param() color  = '#3b82f6'   // → --color on the element
+ *   @Param() radius = '8px'       // → --radius on the element
+ *
+ *   $root = `border-radius: var(--radius); background: var(--color);`
+ * }
+ *
+ * // In the component:
+ * 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 {};
+    },
+  });
+}

package/src/decorators/style.ts

@@ -0,0 +1,55 @@
+import { effect, signal, type RootComponent } from "@praxisjs/core/internal";
+import { createFieldDecorator } from "@praxisjs/decorators";
+
+/**
+ * Reactive field decorator that binds a signal value to a CSS custom property
+ * on the component's container element — with zero re-renders.
+ *
+ * Only CSS custom properties (variables) are supported: the property name must
+ * start with `--`.
+ *
+ * @example
+ * class ThemeCard extends StatefulComponent {
+ *   @Style('--accent') accent = '#3b82f6'
+ *   @Style('--radius') radius = '8px'
+ * }
+ */
+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() {
+          // _anchor is the "[/ComponentName]" comment node inserted by the runtime.
+          // Its parentElement is the container where the component lives.
+          const el = (instance as unknown as RootComponent)._anchor
+            ?.parentElement as HTMLElement | null;
+          if (!el) return;
+
+          stopEffect = effect(() => {
+            el.style.setProperty(property, String(sig()));
+          });
+        },
+
+        onUnmount() {
+          stopEffect?.();
+          stopEffect = null;
+          const el = (instance as unknown as RootComponent)._anchor
+            ?.parentElement as HTMLElement | null;
+          if (el) el.style.removeProperty(property);
+        },
+      };
+    },
+  });
+}

package/src/decorators/styled.ts

@@ -0,0 +1,167 @@
+import type { StatefulComponent } from "@praxisjs/core";
+import { effect, signal, type RootComponent } 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 type { ReactiveStylesheet, Stylesheet } from "../base/stylesheet.js";
+
+// ─── Class data cache ─────────────────────────────────────────────────────────
+
+interface StyleClassData {
+  classMap: Readonly<Record<string, string>>;
+  rawCSS: string;
+  registryKey: string;
+  paramDefaults: Readonly<Record<string, string | number>>;
+}
+
+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;
+    }
+  }
+
+  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;
+}
+
+// ─── @Styled field decorator ──────────────────────────────────────────────────
+
+/**
+ * Scoped CSS field decorator. Receives a {@link Stylesheet} or
+ * {@link ReactiveStylesheet} subclass and builds a stylesheet object with:
+ *
+ * - `$xxx` fields → scoped class name strings (static, cached per class)
+ * - `@Param() xxx` fields → reactive CSS custom property setters
+ *   (requires {@link ReactiveStylesheet} and a `StatefulComponent` field)
+ *
+ * **TypeScript enforcement:**
+ * - `@Styled(ReactiveStylesheetSubclass)` can only be applied to fields of
+ *   classes that extend `StatefulComponent`.
+ * - `@Styled(StylesheetSubclass)` (no `@Param()`) can be applied to any component.
+ *
+ * @example — static CSS (any component)
+ * class IconStyles extends Stylesheet {
+ *   $root = `display: inline-flex; align-items: center;`
+ * }
+ *
+ * class Icon extends StatelessComponent {
+ *   @Styled(IconStyles) $s!: IconStyles
+ * }
+ *
+ * @example — reactive CSS vars (StatefulComponent only)
+ * class CardStyles extends ReactiveStylesheet {
+ *   @Param() color = '#3b82f6'
+ *   $root = `border: 2px solid var(--color);`
+ * }
+ *
+ * @Component()
+ * class Card extends StatefulComponent {
+ *   @Styled(CardStyles) $card!: CardStyles
+ * }
+ */
+export function Styled<T extends Stylesheet>(
+  StyleClass: new () => T,
+): [T] extends [ReactiveStylesheet]
+  ? (value: undefined, context: ClassFieldDecoratorContext<StatefulComponent, T>) => void
+  : (value: undefined, context: ClassFieldDecoratorContext<object, T>) => void {
+  const data = getStyleClassData(StyleClass);
+
+  // 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,
+        });
+      }
+
+      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 = (instance as unknown as RootComponent)._anchor?.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 = (instance as unknown as RootComponent)._anchor?.parentElement;
+            if (el) {
+              for (const paramName of Object.keys(paramSignals)) {
+                el.style.removeProperty(`--${paramName}`);
+              }
+            }
+          }
+        },
+      };
+    },
+  });
+}