@sigx/lynx-zero 0.4.9

package/src/theme/registry.ts

@@ -0,0 +1,290 @@
+/**
+ * Theme registry — the single source of truth for registered themes.
+ *
+ * A theme is *data*: a name, a light/dark variant, and a full color palette
+ * (plus an optional toggle `pair` and roundness overrides). Both rendering and
+ * any DS-specific consumers (e.g. icon tinting) read from here —
+ * `<ThemeProvider>` applies a theme's `colors` as inline CSS custom properties
+ * on its host view (Lynx inherits custom properties to descendants, so
+ * component classes resolve `var(--color-*)`). There is no per-theme CSS or
+ * parallel JS palette to keep in sync.
+ *
+ * The registry starts **empty** — design-system packages seed it at module
+ * load (e.g. `@sigx/lynx-daisyui` registers its six built-ins on import).
+ * Register more — including tenant themes fetched at runtime — with
+ * `registerTheme()`, or `extendTheme()` to derive one from a base. Order
+ * matters for `pickThemeFor()`: the first theme of a given variant is the
+ * follow-system default for that variant.
+ *
+ * Structural tokens (radius, sizing, component dimensions) are theme-agnostic
+ * and ship once in the bundled `.lynx-zero` base class (`styles/tokens.css`);
+ * a theme may override roundness via `radius` and base size units via `sizes`.
+ *
+ * Colors are engine-safe strings — hex or `rgb()`. Lynx's CSS engine does not
+ * parse `oklch()`, so convert before registering.
+ */
+import {
+  COLOR_VARIANT_LIST,
+  type ColorToken,
+  type CoreColorToken,
+  type SoftColorToken,
+} from '../contract.js';
+import { mixColors } from './color-mix.js';
+
+export type ThemeVariant = 'light' | 'dark';
+
+/**
+ * Full *registered* color palette — every semantic token including the
+ * `*-soft` tints, no holes. This is what `colorsOf()` returns.
+ */
+export type ThemePalette = Record<ColorToken, string>;
+
+/**
+ * What a theme *author* writes: every core token, with the `*-soft` tints
+ * optional — any omitted soft is computed at registration (`softMix` of the
+ * variant color into `base-100`).
+ */
+export type ThemePaletteInput =
+  & Record<CoreColorToken, string>
+  & Partial<Record<SoftColorToken, string>>;
+
+/**
+ * Roundness token overrides. Emitted as `--radius-selector` /
+ * `--radius-field` / `--radius-box`. Defaults live in the bundled
+ * `.lynx-zero` base.
+ */
+export interface ThemeRadius {
+  /** Small selectable controls — checkbox, toggle, badge. */
+  selector?: string;
+  /** Fields — button, input, select, textarea. */
+  field?: string;
+  /** Boxes — card, modal, alert. */
+  box?: string;
+}
+
+/**
+ * Base size-unit overrides. Emitted as `--size-selector` / `--size-field`;
+ * component dimensions are integer multiples of these. Defaults live in the
+ * bundled `.lynx-zero` base.
+ */
+export interface ThemeSizes {
+  /** Base unit for selector controls (checkbox, toggle, badge). */
+  selector?: string;
+  /** Base unit for fields (button, input, select). */
+  field?: string;
+}
+
+export interface ThemeInput {
+  /** Unique id — also the value of `theme.name`. */
+  name: string;
+  /** Light or dark — drives follow-system selection and status-bar tint. */
+  variant: ThemeVariant;
+  /** Color palette — core tokens required, `*-soft` tints optional. */
+  colors: ThemePaletteInput;
+  /**
+   * Which theme `toggle()` flips to. Defaults to the first registered theme of
+   * the opposite variant.
+   */
+  pair?: string;
+  /** Optional roundness overrides; unspecified tokens fall back to the base. */
+  radius?: ThemeRadius;
+  /** Optional base size-unit overrides; unspecified tokens fall back to the base. */
+  sizes?: ThemeSizes;
+  /**
+   * Whether this theme ships a build-time CSS class named after it (the DS
+   * package generates `.theme-name { --color-*: … }` at build time, e.g. via
+   * daisyui's `gen-theme-css.mjs`). Such themes paint correctly on the very
+   * first frame; themes without it apply via the runtime `setProperty` path
+   * post-mount, with their variant's static theme class as the first-frame
+   * fallback.
+   */
+  staticCss?: boolean;
+  /**
+   * How strong the computed `*-soft` tints are: the ratio of the variant
+   * color mixed into `base-100` for any soft token the palette doesn't set
+   * explicitly. Design-system flavor, carried as theme data — daisy's
+   * built-ins use `0.08` (daisyUI v5's ~8% tints), hero's use `0.2`
+   * (HeroUI's `color/20`). Default `0.16`.
+   */
+  softMix?: number;
+}
+
+/** A registered theme — same shape as the input, with the palette completed. */
+export interface Theme extends Omit<ThemeInput, 'colors'> {
+  colors: ThemePalette;
+}
+
+const DEFAULT_SOFT_MIX = 0.16;
+
+/**
+ * Complete a theme's palette: any `*-soft` token the author didn't set is
+ * computed as `softMix` of the variant color mixed into `base-100` (in JS —
+ * Lynx CSS can't alpha-compose `var()` colors, so the tints are materialized
+ * in the palette). Idempotent; explicitly provided softs are kept verbatim.
+ *
+ * DS packages run their builtin arrays through this before exporting them so
+ * build scripts (gen-theme-css) see the same palette the registry serves.
+ */
+export function completeTheme(input: ThemeInput): Theme {
+  const mix = input.softMix ?? DEFAULT_SOFT_MIX;
+  const colors = { ...input.colors } as ThemePalette;
+  for (const variant of COLOR_VARIANT_LIST) {
+    const soft: SoftColorToken = `${variant}-soft`;
+    if (colors[soft] === undefined) {
+      colors[soft] = mixColors(colors[variant], colors['base-100'], mix);
+    }
+  }
+  return { ...input, colors };
+}
+
+const registry: Theme[] = [];
+
+/**
+ * Whether `name` is a registered theme that ships a build-time CSS class —
+ * i.e. it paints correctly on the first frame. Themes registered without
+ * `staticCss` return `false`; `<ThemeProvider>` falls back to their variant's
+ * static class for first paint and swaps in the exact palette via
+ * `setProperty`.
+ */
+export function hasStaticCss(name: string | undefined): boolean {
+  return findTheme(name)?.staticCss === true;
+}
+
+/**
+ * Resolve a `theme.name` to its registered `Theme`. Supports multi-class names
+ * like `'daisy-light daisy-rounded'` by matching the first registered id found.
+ */
+function findTheme(name: string | undefined): Theme | undefined {
+  if (!name) return undefined;
+  for (const part of name.split(/\s+/)) {
+    const hit = registry.find((t) => t.name === part);
+    if (hit) return hit;
+  }
+  return undefined;
+}
+
+/**
+ * All registered themes in insertion order. Returns a shallow copy so callers
+ * can't mutate the internal registry — re-registration goes through
+ * `registerTheme()`. Each entry is a full `Theme` (name, variant, palette),
+ * so consumers can render swatches in a picker.
+ */
+export function listThemes(): readonly Theme[] {
+  return registry.slice();
+}
+
+/**
+ * Register (or replace, by `name`) a theme. Call at module-load time before
+ * mounting `<ThemeProvider>` so it shows up in `listThemes()` / `pickThemeFor()`.
+ * The palette is completed on the way in (`completeTheme`): any `*-soft`
+ * token the author didn't set is computed from `softMix`.
+ */
+export function registerTheme(theme: ThemeInput): void {
+  const complete = completeTheme(theme);
+  const i = registry.findIndex((t) => t.name === complete.name);
+  if (i >= 0) registry[i] = complete;
+  else registry.push(complete);
+}
+
+/**
+ * Derive a new theme from a registered base, overriding any colors / roundness.
+ * Ergonomic for "tenant tweaks a few tokens": the result is a full `Theme` you
+ * pass to `registerTheme()`. Throws if `base` isn't registered.
+ *
+ * ```ts
+ * registerTheme(extendTheme('daisy-dark', {
+ *   name: 'acme-dark',
+ *   colors: { primary: '#fb7185' },
+ * }));
+ * ```
+ */
+export function extendTheme(
+  base: string,
+  patch: {
+    name: string;
+    variant?: ThemeVariant;
+    pair?: string;
+    colors?: Partial<ThemePalette>;
+    radius?: ThemeRadius;
+    sizes?: ThemeSizes;
+    softMix?: number;
+  },
+): Theme {
+  const src = findTheme(base);
+  if (!src) {
+    throw new Error(
+      `[lynx-zero] extendTheme: unknown base theme "${base}". `
+      + `Register it first, or extend a theme your design system registered.`,
+    );
+  }
+  // Merge core tokens, then RECOMPUTE every soft tint the patch didn't set
+  // explicitly — patching `primary` must not leave the base's stale
+  // `primary-soft` behind. (A soft the base author set explicitly is
+  // indistinguishable from a computed one post-registration; explicit softs
+  // therefore live in the patch when extending.)
+  const merged: Record<string, string> = { ...src.colors };
+  for (const variant of COLOR_VARIANT_LIST) delete merged[`${variant}-soft`];
+  Object.assign(merged, patch.colors);
+  return completeTheme({
+    name: patch.name,
+    variant: patch.variant ?? src.variant,
+    pair: patch.pair ?? src.pair,
+    colors: merged as ThemePaletteInput,
+    radius: patch.radius ?? src.radius,
+    sizes: patch.sizes ?? src.sizes,
+    softMix: patch.softMix ?? src.softMix,
+  });
+}
+
+/** The variant of a registered theme, or `undefined` if not registered. */
+export function variantOf(name: string | undefined): ThemeVariant | undefined {
+  return findTheme(name)?.variant;
+}
+
+/** The color palette of a registered theme, or `undefined` if not registered. */
+export function colorsOf(name: string | undefined): ThemePalette | undefined {
+  return findTheme(name)?.colors;
+}
+
+/** The roundness overrides of a registered theme, if any. */
+export function radiusOf(name: string | undefined): ThemeRadius | undefined {
+  return findTheme(name)?.radius;
+}
+
+/** The base size-unit overrides of a registered theme, if any. */
+export function sizesOf(name: string | undefined): ThemeSizes | undefined {
+  return findTheme(name)?.sizes;
+}
+
+/**
+ * The first registered palette — the engine's last-resort fallback when an
+ * active theme name isn't registered. `undefined` only when no design system
+ * has seeded the registry yet.
+ * @internal
+ */
+export function fallbackPalette(): ThemePalette | undefined {
+  return registry[0]?.colors;
+}
+
+/**
+ * Pick a default theme for a given system color scheme — the first registered
+ * theme of that variant. Falls back to the first registered theme of any
+ * variant, or `''` while the registry is empty (a design-system package seeds
+ * it at module load, so this is only reachable before any DS import).
+ */
+export function pickThemeFor(scheme: ThemeVariant): string {
+  const hit = registry.find((t) => t.variant === scheme);
+  return hit?.name ?? registry[0]?.name ?? '';
+}
+
+/**
+ * Resolve the paired theme of a given name — used by `theme.toggle()`. Follows
+ * `pair` if set, otherwise the first theme of the opposite variant. Returns the
+ * input unchanged when the theme isn't registered.
+ */
+export function pairOf(name: string): string {
+  const hit = findTheme(name);
+  if (!hit) return name;
+  if (hit.pair) return hit.pair;
+  return pickThemeFor(hit.variant === 'light' ? 'dark' : 'light');
+}

package/src/theme/theme-state.ts

@@ -0,0 +1,112 @@
+/**
+ * Global theme state — the headless DI singleton behind `useTheme()`.
+ *
+ * The active selection (current theme name + follow-system flag) lives here as
+ * a module-level signal, mirroring how `./registry.ts` is already a global
+ * module singleton. This is what makes theme control reachable from *headless*
+ * code — a store, a service, app-boot logic, an effect — not just from a
+ * component mounted under `<ThemeProvider>`.
+ *
+ * The root `<ThemeProvider>` (depth 0) binds to this state: it renders its host
+ * view from it, owns the system-color-scheme follow effect that writes to it
+ * while `following`, and seeds an `initial` prop into it. Nested providers
+ * (depth >= 1) build their own local state via `makeThemeController` so a
+ * subtree can be overridden without touching the global — see
+ * `./ThemeProvider.tsx`.
+ *
+ * `followSystem()` here only flips the flag; the actual re-apply on an OS color
+ * scheme change is driven by the root provider's follow effect (which has the
+ * appearance signal in scope).
+ */
+import { signal } from '@sigx/lynx';
+import { pairOf, pickThemeFor } from './registry.js';
+import type { ThemeController, ThemeName } from './ThemeProvider.js';
+
+/** The mutable selection a `ThemeController` reads from and writes to. */
+export interface ThemeState {
+    name: ThemeName;
+    following: boolean;
+    /**
+     * Global text-scale multiplier applied on top of the theme's `--text-*`
+     * ramp. Orthogonal to `name`: a theme switch / `toggle()` leaves it
+     * untouched, so a user/accessibility scale persists across appearance
+     * changes. `1` = the default ramp.
+     */
+    fontScale: number;
+}
+
+/**
+ * Coerce a font-scale input to a valid positive, finite multiplier. Rejects
+ * `NaN`, `±Infinity`, and non-positive values — which would otherwise emit
+ * invalid CSS (`NaNpx`, negative font sizes) and break `fontScale === 1`
+ * comparisons — by returning `fallback` instead.
+ */
+export function normalizeFontScale(value: unknown, fallback = 1): number {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
+
+/**
+ * Build a `ThemeController` over a given state object. Used for both the global
+ * singleton (below) and each nested `<ThemeProvider>`'s local state — same
+ * behaviour, different backing store. `followSystem()` only flips the flag; the
+ * owning provider's follow effect performs the re-apply.
+ */
+export function makeThemeController(state: ThemeState): ThemeController {
+    return {
+        get name() {
+            return state.name;
+        },
+        get followingSystem() {
+            return state.following;
+        },
+        get fontScale() {
+            return state.fontScale;
+        },
+        set(next) {
+            state.name = next;
+            state.following = false;
+        },
+        toggle() {
+            state.name = pairOf(state.name);
+            state.following = false;
+        },
+        followSystem() {
+            state.following = true;
+        },
+        setFontScale(scale) {
+            // Ignore invalid input (keep the current scale) so state stays valid.
+            state.fontScale = normalizeFontScale(scale, state.fontScale);
+        },
+    };
+}
+
+// Object signal (not primitive) so theme-name literal unions a DS layers on
+// top survive — `signal<T>` widens primitive literals to plain `string` via
+// `Widen<T>`. Seeded from whatever is registered at first import (a DS package
+// seeds the registry at its own module load; until then the name is '') —
+// the root <ThemeProvider> re-seeds from the system color scheme + its props
+// on mount.
+const state = signal<ThemeState>({
+    name: pickThemeFor('light'),
+    following: true,
+    fontScale: 1,
+});
+
+/**
+ * The backing signal for the global theme. Read/written by the root
+ * `<ThemeProvider>` and shared with `themeController`; not part of the public
+ * API.
+ * @internal
+ */
+export const globalThemeState = state;
+
+/**
+ * The global theme controller — the headless handle. Import and call from
+ * anywhere (no `<ThemeProvider>` ancestor required); `useTheme()`'s default
+ * factory returns this same instance, and the root `<ThemeProvider>` provides
+ * it to its subtree. `StatusBarSync` binds to it so the OS bars always follow
+ * the global/screen theme, never a content sub-scope.
+ */
+export const themeController: ThemeController = makeThemeController(state);

package/src/theme/use-screen-theme.ts

@@ -0,0 +1,42 @@
+/**
+ * `useScreenTheme(name)` — pin the **global** theme while a navigation
+ * screen is focused, restoring the previous selection when it blurs.
+ *
+ * This is the right tool for *per-screen* theming — "this screen is dark, that
+ * one is light." Because it drives the global theme (not a content sub-scope),
+ * the OS status/navigation bars follow automatically via `<StatusBarSync>`, so
+ * the bar icons stay legible against each screen's background. For recoloring a
+ * *region within* a screen without touching the bars, nest a `<ThemeProvider>`
+ * instead.
+ *
+ * Built on `useFocusEffect` from `@sigx/lynx-navigation` (an optional peer
+ * dependency): it must be called from inside a component rendered as a route by
+ * `<Stack>` / `<Tabs>` — the same constraint as `useFocusEffect`/`useIsFocused`.
+ *
+ * Save/restore composes with the stack (LIFO focus/blur): pushing a themed
+ * screen saves whatever was live, applies its own theme, and restores on pop —
+ * including resuming follow-system if that's what was active.
+ *
+ * ```tsx
+ * const Gallery = component(() => {
+ *     useScreenTheme('daisy-dark'); // dark while this screen is on top
+ *     return () => <view>…</view>;
+ * });
+ * ```
+ */
+import { useFocusEffect } from '@sigx/lynx-navigation';
+import { themeController } from './theme-state.js';
+import type { ThemeName } from './ThemeProvider.js';
+
+/** Pin the global theme to `name` while this screen is focused; restore on blur. */
+export function useScreenTheme(name: ThemeName): void {
+    useFocusEffect(() => {
+        const prevName = themeController.name;
+        const prevFollowing = themeController.followingSystem;
+        themeController.set(name);
+        return () => {
+            if (prevFollowing) themeController.followSystem();
+            else themeController.set(prevName);
+        };
+    });
+}

package/src/theme/use-theme-colors.ts

@@ -0,0 +1,99 @@
+/**
+ * `useThemeColors()` — resolve the *active, scoped* theme palette to concrete
+ * color values for consumers that can't read CSS custom properties.
+ *
+ * Native widgets are the audience: platform text inputs, `<sigx-richtext>`,
+ * SVG fills — anything where `var(--color-*)` never resolves because the
+ * value is consumed outside Lynx's CSS pipeline. Components pass these
+ * resolved literals via inline `style` or native props instead.
+ *
+ * Scoped + reactive: resolves through `useTheme()` (the nearest
+ * `<ThemeProvider>`'s controller, falling back to the global one), and the
+ * getters read `theme.name` — call them inside render and a theme switch
+ * recolors the consumer.
+ *
+ * ```tsx
+ * const colors = useThemeColors();
+ * return () => (
+ *   <input style={{
+ *     color: colors.colorOf('base-content'),
+ *     '-x-placeholder-color': colors.colorOf('base-content', 0.45),
+ *   }} />
+ * );
+ * ```
+ */
+import type { ColorToken } from '../contract.js';
+import { colorsOf, fallbackPalette } from './registry.js';
+import { useTheme } from './ThemeProvider.js';
+
+export interface ThemeColors {
+  /**
+   * The active palette's value for `token`, normalized to hex — optionally
+   * with `alpha` (0–1) appended as a hex byte (`#RRGGBBAA`). Returns `''`
+   * when no theme is registered yet (pre-DS-import edge case).
+   */
+  colorOf(token: ColorToken, alpha?: number): string;
+}
+
+export function useThemeColors(): ThemeColors {
+  const theme = useTheme();
+  return {
+    colorOf(token, alpha) {
+      // Reading `theme.name` here is what makes call sites reactive.
+      const palette = colorsOf(theme.name) ?? fallbackPalette();
+      const raw = palette?.[token];
+      if (!raw) return '';
+      const hex = toHexColor(raw);
+      return alpha === undefined ? hex : withAlpha(hex, alpha);
+    },
+  };
+}
+
+/**
+ * Normalize an engine-safe palette color to full-form hex
+ * (`#RRGGBB`/`#RRGGBBAA`) — the registry allows `rgb()`/`rgba()` entries and
+ * shorthand hex, but native color parsers may accept only the full forms.
+ * Unknown notations pass through unchanged.
+ */
+export function toHexColor(color: string): string {
+  const c = color.trim();
+  if (c.startsWith('#')) {
+    const h = c.slice(1);
+    // Expand #RGB / #RGBA to the full form; leave other lengths as-is.
+    if (h.length === 3 || h.length === 4) {
+      return `#${h.split('').map((ch) => ch + ch).join('')}`;
+    }
+    return c;
+  }
+  const m = /^rgba?\(\s*(\d+)\s*[, ]\s*(\d+)\s*[, ]\s*(\d+)\s*(?:[,/]\s*([\d.]+%?)\s*)?\)$/i.exec(c);
+  if (!m) return c;
+  const byte = (v: number): string =>
+    Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
+  let hex = `#${byte(Number(m[1]))}${byte(Number(m[2]))}${byte(Number(m[3]))}`;
+  if (m[4] !== undefined) {
+    const a = m[4].endsWith('%') ? Number(m[4].slice(0, -1)) / 100 : Number(m[4]);
+    hex += byte(Math.max(0, Math.min(1, a)) * 255);
+  }
+  return hex;
+}
+
+/**
+ * Append an alpha channel (0–1) to a hex color
+ * (`#RGB`/`#RRGGBB`/`#RRGGBBAA` → `#RRGGBBAA`). Non-hex input passes
+ * through unchanged; non-finite alpha is treated as opaque.
+ */
+export function withAlpha(hex: string, alpha: number): string {
+  const input = hex.trim();
+  if (!input.startsWith('#')) return input;
+  if (!Number.isFinite(alpha)) return input;
+  let h = input.slice(1);
+  if (h.length === 3) h = h.split('').map((c) => c + c).join('');
+  if (h.length === 8) h = h.slice(0, 6);
+  // Anything that isn't #RRGGBB by now (#RGBA, bad lengths) is not a shape
+  // we can safely re-alpha — return it unchanged rather than corrupt it.
+  if (h.length !== 6) return input;
+  const byte = Math.round(Math.max(0, Math.min(1, alpha)) * 255)
+    .toString(16)
+    .padStart(2, '0');
+  return `#${h}${byte}`;
+}