@sigx/lynx-zero 0.4.9 → 0.5.0

package/src/theme/theme-state.ts

@@ -1,112 +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);
+/**
+ * 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

@@ -1,42 +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);
-        };
-    });
-}
+/**
+ * `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

@@ -1,99 +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}`;
-}
+/**
+ * `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}`;
+}