@praxisjs/css 0.1.0

package/src/extract.ts

@@ -0,0 +1,133 @@
+import { Stylesheet, ReactiveStylesheet } from "./base/stylesheet.js";
+import { isCSSBuilder, createCSSBuilder, type CSSProperties } from "./builder/css-builder.js";
+import { hashCSS } from "./internal/hash.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type EmitFn = (css: string, prepend?: boolean) => void;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+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;
+  } catch {
+    return 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"));
+  } catch { /* skip sheets that can't be instantiated at build time */ }
+}
+
+// ─── Module factory ───────────────────────────────────────────────────────────
+
+/**
+ * Creates the `@praxisjs/css` module API surface for build-time CSS extraction.
+ *
+ * All CSS-generating calls route through `emit` instead of the DOM.
+ * Pass the returned object as the `@praxisjs/css` entry in a vm sandbox's
+ * `require()` handler.
+ *
+ * @example
+ * const mod = extractionModule((css, prepend) => { ... })
+ * sandbox.require = id => id === '@praxisjs/css' ? mod : {}
+ */
+export function extractionModule(emit: EmitFn): Record<string, unknown> {
+  const seen = new Set<string>();
+
+  const dedupEmit: EmitFn = (css, prepend) => {
+    const key = hashCSS(css);
+    if (seen.has(key)) return;
+    seen.add(key);
+    emit(css, prepend);
+  };
+
+  class ExtractionThemeInstance {
+    constructor(DefaultTheme: Ctor) {
+      const css = themeToRootCSS(DefaultTheme);
+      if (css) dedupEmit(css, true);
+    }
+    get current() { return {}; }
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    switch(_T: Ctor) {}
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    destroy() {}
+  }
+
+  return {
+    __esModule: true,
+
+    // Base classes — real implementations, used by user's `extends Stylesheet`
+    Stylesheet,
+    ReactiveStylesheet,
+    createCSSBuilder,
+
+    // Token system — extraction stubs
+    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+    TokenSheet: class TokenSheet {},
+    tokenVars: (cls: unknown) => cls,
+    ThemeInstance: ExtractionThemeInstance,
+    // eslint-disable-next-line @typescript-eslint/no-extraneous-class
+    theme: () => new ExtractionThemeInstance(class {}),
+    createThemeInstance: (T: Ctor) => new ExtractionThemeInstance(T),
+    Themed: (_skeleton: unknown, DefaultTheme: Ctor) => {
+      const css = themeToRootCSS(DefaultTheme);
+      if (css) dedupEmit(css, true);
+      return (cls: unknown) => cls;
+    },
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    Theme: () => () => {},
+
+    // CSS API — collect instead of inject
+    Styled: (SheetClass: Ctor) => {
+      collectSheetCSS(SheetClass, dedupEmit);
+      // eslint-disable-next-line @typescript-eslint/no-empty-function
+      return () => {};
+    },
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    Param:  () => () => {},
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    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;
+    },
+    globalStyle: (factory: (css: typeof createCSSBuilder) => unknown) => {
+      dedupEmit(String(factory(createCSSBuilder)));
+    },
+  };
+}

package/src/global.ts

@@ -0,0 +1,60 @@
+import { createCSSBuilder, type CSSProperties, type CSSBuilder } from "./builder/css-builder.js";
+import { getCollector } from "./internal/collector.js";
+import { hashCSS } from "./internal/hash.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** Factory function that receives `css` (= `createCSSBuilder`) and returns a `CSSBuilder` or raw CSS string. */
+export type GlobalStyleFactory = (css: (props: CSSProperties) => CSSBuilder) => CSSBuilder | string;
+
+// ─── 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>();
+
+// ─── globalStyle ─────────────────────────────────────────────────────────────
+
+/**
+ * Injects unscoped CSS into `<head>` exactly once.
+ *
+ * Receives a factory function that is passed `css` — the same builder
+ * function as `this.css()` in a `Stylesheet` class — and returns either a
+ * {@link CSSBuilder} or a raw CSS string.
+ *
+ * Use `.on(selector, props)` to attach rules to specific elements.
+ * Chain multiple `.on()` calls to produce multiple selectors in one injection.
+ *
+ * Idempotent — duplicate content is ignored (content-hashed).
+ * Safe to call at module level. With the `praxisjsCSS()` Vite plugin the
+ * CSS is extracted at build time.
+ *
+ * @example
+ * globalStyle(css =>
+ *   css({})
+ *     .on('*, *::before, *::after', { boxSizing: 'border-box', margin: 0, padding: 0 })
+ *     .on('body', { fontFamily: 'system-ui', lineHeight: 1.5 })
+ *     .on('img, video', { display: 'block', maxWidth: '100%' })
+ * )
+ */
+export function globalStyle(factory: GlobalStyleFactory): void {
+  const css = String(factory(createCSSBuilder));
+
+  const key = hashCSS(css);
+  if (injected.has(key)) return;
+  injected.add(key);
+
+  if (STATIC_MODE) return;
+
+  const col = getCollector();
+  if (col) { col.inject(key, css); return; }
+
+  if (typeof document === "undefined") return;
+
+  const el = document.createElement("style");
+  el.setAttribute("data-praxis-global", key);
+  el.textContent = css;
+  document.head.appendChild(el);
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { cx, type ClassValue } from "./cx.js";
+export { preflight } from "./preflight.js";
+export { globalStyle, type GlobalStyleFactory } from "./global.js";
+export { type CSSBuilder, type CSSProperties } from "./builder/css-builder.js";
+export { keyframes } from "./builder/keyframes.js";
+export { Param } from "./decorators/param.js";
+export { ReactiveStylesheet, Stylesheet } from "./base/stylesheet.js";
+export { Styled } from "./decorators/styled.js";
+export { Style } from "./decorators/style.js";
+export { TokenSheet, tokenVars, ThemeInstance, theme, Themed, Theme, type ThemedConfig } from "./tokens/index.js";

package/src/internal/collector.ts

@@ -0,0 +1,38 @@
+/**
+ * CSS collector — used by the Vite CSS plugin during build-time extraction.
+ * When a collector is active, `injectStyle` and `keyframes` push CSS to it
+ * instead of injecting `<style>` elements into the DOM.
+ */
+
+export interface CSSCollector {
+  inject(key: string, css: string): void;
+  addKeyframes(name: string, css: string): void;
+  getCSS(): string;
+  clear(): void;
+}
+
+let _active: CSSCollector | null = null;
+
+export function setCollector(c: CSSCollector | null): void {
+  _active = c;
+}
+
+export function getCollector(): CSSCollector | null {
+  return _active;
+}
+
+export function createCollector(): CSSCollector {
+  const seen = new Set<string>();
+  const blocks: string[] = [];
+
+  return {
+    inject(key, css) {
+      if (!seen.has(key)) { seen.add(key); blocks.push(css); }
+    },
+    addKeyframes(name, css) {
+      if (!seen.has(name)) { seen.add(name); blocks.push(css); }
+    },
+    getCSS() { return blocks.join("\n"); },
+    clear() { seen.clear(); blocks.length = 0; },
+  };
+}

package/src/internal/hash.ts

@@ -0,0 +1,10 @@
+/**
+ * djb2-variant hash of a string, returning a 6-char base-36 identifier.
+ */
+export function hashCSS(str: string): string {
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 33) ^ str.charCodeAt(i);
+  }
+  return (h >>> 0).toString(36).slice(0, 6);
+}

package/src/internal/registry.ts

@@ -0,0 +1,51 @@
+import { getCollector } from "./collector.js";
+
+// ─── Static mode ──────────────────────────────────────────────────────────────
+
+// Defined by the Vite CSS plugin via `define: { __PRAXIS_CSS_STATIC__: true }`.
+// When true, CSS is already bundled via virtual:praxisjs/styles — skip DOM injection.
+declare const __PRAXIS_CSS_STATIC__: boolean | undefined;
+
+const STATIC_MODE: boolean =
+  typeof __PRAXIS_CSS_STATIC__ !== "undefined" && __PRAXIS_CSS_STATIC__;
+
+// ─── DOM registry ─────────────────────────────────────────────────────────────
+
+// WeakRef lets the GC reclaim style elements that were removed externally
+// without going through releaseStyle (e.g. framework teardown, test cleanup).
+const cssRegistry = new Map<string, { ref: WeakRef<HTMLStyleElement>; count: number }>();
+
+export function injectStyle(key: string, css: string): void {
+  if (STATIC_MODE) return;
+
+  const col = getCollector();
+  if (col) { col.inject(key, css); return; }
+
+  if (typeof document === "undefined") return;
+
+  const existing = cssRegistry.get(key);
+  const existingEl = existing?.ref.deref();
+
+  if (existing && existingEl && document.head.contains(existingEl)) {
+    existing.count++;
+    return;
+  }
+
+  const el = document.createElement("style");
+  el.setAttribute("data-praxis-hash", key);
+  el.textContent = css;
+  document.head.appendChild(el);
+  cssRegistry.set(key, { ref: new WeakRef(el), count: 1 });
+}
+
+export function releaseStyle(key: string): void {
+  if (STATIC_MODE) return;
+
+  const entry = cssRegistry.get(key);
+  if (!entry) return;
+  entry.count--;
+  if (entry.count <= 0) {
+    entry.ref.deref()?.remove();
+    cssRegistry.delete(key);
+  }
+}

package/src/preflight.ts

@@ -0,0 +1,192 @@
+import { globalStyle } from "./global.js";
+
+// Tailwind CSS preflight — https://github.com/tailwindlabs/tailwindcss/blob/main/packages/tailwindcss/preflight.css
+// --theme() references stripped and replaced with their fallback values.
+const PREFLIGHT = `
+*,
+::after,
+::before,
+::backdrop,
+::file-selector-button {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+  border: 0 solid;
+}
+
+html,
+:host {
+  line-height: 1.5;
+  -webkit-text-size-adjust: 100%;
+  tab-size: 4;
+  font-family: ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+  font-feature-settings: normal;
+  font-variation-settings: normal;
+  -webkit-tap-highlight-color: transparent;
+}
+
+hr {
+  height: 0;
+  color: inherit;
+  border-top-width: 1px;
+}
+
+abbr:where([title]) {
+  -webkit-text-decoration: underline dotted;
+  text-decoration: underline dotted;
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-size: inherit;
+  font-weight: inherit;
+}
+
+a {
+  color: inherit;
+  -webkit-text-decoration: inherit;
+  text-decoration: inherit;
+}
+
+b, strong {
+  font-weight: bolder;
+}
+
+code, kbd, samp, pre {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace;
+  font-feature-settings: normal;
+  font-variation-settings: normal;
+  font-size: 1em;
+}
+
+small {
+  font-size: 80%;
+}
+
+sub, sup {
+  font-size: 75%;
+  line-height: 0;
+  position: relative;
+  vertical-align: baseline;
+}
+
+sub { bottom: -0.25em; }
+sup { top: -0.5em; }
+
+table {
+  text-indent: 0;
+  border-color: inherit;
+  border-collapse: collapse;
+}
+
+:-moz-focusring { outline: auto; }
+
+progress { vertical-align: baseline; }
+
+summary { display: list-item; }
+
+ol, ul, menu { list-style: none; }
+
+img, svg, video, canvas, audio, iframe, embed, object {
+  display: block;
+  vertical-align: middle;
+}
+
+img, video {
+  max-width: 100%;
+  height: auto;
+}
+
+button,
+input,
+select,
+optgroup,
+textarea,
+::file-selector-button {
+  font: inherit;
+  font-feature-settings: inherit;
+  font-variation-settings: inherit;
+  letter-spacing: inherit;
+  color: inherit;
+  border-radius: 0;
+  background-color: transparent;
+  opacity: 1;
+}
+
+:where(select:is([multiple], [size])) optgroup { font-weight: bolder; }
+
+:where(select:is([multiple], [size])) optgroup option { padding-inline-start: 20px; }
+
+::file-selector-button { margin-inline-end: 4px; }
+
+::placeholder { opacity: 1; }
+
+@supports (not (-webkit-appearance: -apple-pay-button)) or (contain-intrinsic-size: 1px) {
+  ::placeholder {
+    color: color-mix(in oklab, currentcolor 50%, transparent);
+  }
+}
+
+textarea { resize: vertical; }
+
+::-webkit-search-decoration { -webkit-appearance: none; }
+
+::-webkit-date-and-time-value {
+  min-height: 1lh;
+  text-align: inherit;
+}
+
+::-webkit-datetime-edit { display: inline-flex; }
+
+::-webkit-datetime-edit-fields-wrapper { padding: 0; }
+
+::-webkit-datetime-edit,
+::-webkit-datetime-edit-year-field,
+::-webkit-datetime-edit-month-field,
+::-webkit-datetime-edit-day-field,
+::-webkit-datetime-edit-hour-field,
+::-webkit-datetime-edit-minute-field,
+::-webkit-datetime-edit-second-field,
+::-webkit-datetime-edit-millisecond-field,
+::-webkit-datetime-edit-meridiem-field {
+  padding-block: 0;
+}
+
+::-webkit-calendar-picker-indicator { line-height: 1; }
+
+:-moz-ui-invalid { box-shadow: none; }
+
+button,
+input:where([type='button'], [type='reset'], [type='submit']),
+::file-selector-button {
+  appearance: button;
+}
+
+::-webkit-inner-spin-button,
+::-webkit-outer-spin-button {
+  height: auto;
+}
+
+[hidden]:where(:not([hidden='until-found'])) {
+  display: none !important;
+}
+`;
+
+/**
+ * Injects an opinionated browser reset into `document.head` exactly once.
+ *
+ * Inspired by the Tailwind CSS preflight reset — normalises browser defaults,
+ * removes margins and padding, resets borders, and makes replaced elements
+ * block-level. Tailwind-specific `--theme()` references are not included;
+ * font stacks use standard system defaults instead.
+ *
+ * Safe to call at module level. Idempotent — multiple calls inject the CSS
+ * only once. Works with the `praxisjsCSS()` Vite plugin for static extraction.
+ *
+ * @example
+ * // src/main.ts
+ * import { preflight } from '@praxisjs/css'
+ * preflight()
+ */
+export function preflight(): void {
+  globalStyle(_css => PREFLIGHT);
+}

package/src/server.ts

@@ -0,0 +1,12 @@
+/**
+ * Server-side / build-time API for the `@praxisjs/vite-plugin` CSS extractor.
+ *
+ * Import this at `@praxisjs/css/server` — it is NOT part of the browser bundle.
+ * Using it in browser code has no effect and the tree-shaker will remove it.
+ */
+export {
+  setCollector,
+  getCollector,
+  createCollector,
+  type CSSCollector,
+} from "./internal/collector.js";

package/src/tokens/decorators.ts

@@ -0,0 +1,108 @@
+import type { RootComponent } from "@praxisjs/core/internal";
+import {
+  createClassDecorator,
+  ClassBehavior,
+  type ClassEnhancement,
+  createFieldDecorator,
+  type FieldBinding,
+} from "@praxisjs/decorators";
+
+import {
+  createThemeInstance,
+  theme,
+  ThemeInstance,
+  type ThemedConfig,
+} from "./theme-instance.js";
+
+// ─── @Themed ─────────────────────────────────────────────────────────────────
+
+class ThemedBehavior extends ClassBehavior {
+  constructor(
+    private readonly DefaultTheme: new () => unknown,
+    private readonly config: Partial<ThemedConfig>,
+  ) {
+    super();
+  }
+
+  create(_instance: RootComponent): ClassEnhancement {
+    createThemeInstance(this.DefaultTheme, this.config);
+    return {};
+  }
+
+  initialize(
+    _Enhanced: new (...args: unknown[]) => unknown,
+    _original: new (...args: unknown[]) => unknown,
+  ): void {
+    createThemeInstance(this.DefaultTheme, this.config);
+  }
+}
+
+/**
+ * Class decorator that installs the design token system on the root component.
+ *
+ * - `skeleton` — `TokenSheet` subclass that declares token names. Its static
+ *   properties (`AppTokens.colorPrimary`) return CSS var references.
+ * - `DefaultTheme` — concrete class (extends skeleton) that provides the
+ *   initial CSS custom property values injected on `:root`.
+ * - `config.persist`  — save the active theme to `localStorage` and restore it
+ *   on the next page load.
+ * - `config.syncTabs` — broadcast theme changes to other browser tabs via
+ *   `BroadcastChannel`.
+ *
+ * Must appear above `@Component()` in the decorator stack.
+ *
+ * @example
+ * @Themed(AppTokens, LightTheme, { persist: true, syncTabs: true })
+ * @Component()
+ * class App extends StatefulComponent { ... }
+ */
+export function Themed(
+  _skeleton: abstract new (...args: unknown[]) => unknown,
+  DefaultTheme: new () => unknown,
+  config?: Partial<ThemedConfig>,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any {
+  return createClassDecorator(
+    new ThemedBehavior(DefaultTheme, config ?? {}),
+  ) as unknown as (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    cls: new (...args: any[]) => any,
+    ctx: ClassDecoratorContext,
+  ) => void;
+}
+
+// ─── @Theme ───────────────────────────────────────────────────────────────────
+
+/**
+ * Field decorator that injects the active {@link ThemeInstance} into a
+ * component field. Use `.switch(ThemeClass)` to change the theme.
+ *
+ * Equivalent to the programmatic {@link theme} function — choose whichever
+ * fits the component's style.
+ *
+ * @example
+ * @Component()
+ * class Header extends StatefulComponent {
+ *   @Theme() theme!: ThemeInstance
+ *
+ *   render() {
+ *     return <button onClick={() => this.theme.switch(DarkTheme)}>Dark</button>
+ *   }
+ * }
+ */
+export function Theme() {
+  return createFieldDecorator({
+    bind(_instance, _name, _initialValue): FieldBinding {
+      return {
+        descriptor: {
+          get(): ThemeInstance { return theme(); },
+          // eslint-disable-next-line @typescript-eslint/no-empty-function
+          set(): void {},
+        },
+      };
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  }) as unknown as (_value: undefined, context: ClassFieldDecoratorContext<any>) => void;
+}
+
+export { theme, ThemeInstance, type ThemedConfig };

package/src/tokens/index.ts

@@ -0,0 +1,3 @@
+export { TokenSheet, tokenVars } from "./token-sheet.js";
+export { ThemeInstance, theme, type ThemedConfig } from "./theme-instance.js";
+export { Themed, Theme } from "./decorators.js";