@sigx/lynx-daisyui 0.4.1 → 0.4.3

package/dist/theme/ThemeProvider.d.ts

@@ -2,81 +2,141 @@
  * `<ThemeProvider>` and `useTheme()` — daisyui theme switching for
  * `@sigx/lynx-daisyui`.
  *
- * The package ships two color themes (`daisy-light`, `daisy-dark`) plus
- * style modifier themes (`daisy-rounded`, `daisy-flat`). Each is a CSS
- * class containing scoped `--color-*` / `--radius-*` / `--border-*`
- * variable definitions; descendants of an element with the class
- * inherit those variables (Lynx has `enableCSSInheritance: true` in
- * its layout-pipeline defaults), and the daisyui components are built
- * to read those vars directly.
+ * Themes are CSS classes containing scoped `--color-*` / `--radius-*`
+ * variable definitions; descendants of an element with the class inherit
+ * those variables (Lynx has `enableCSSInheritance: true` in its
+ * layout-pipeline defaults), and the daisyui components are built to read
+ * those vars directly.
+ *
+ * Six color themes ship in the box (`daisy-light`, `daisy-dark`,
+ * `daisy-cupcake`, `daisy-emerald`, `daisy-synthwave`, `daisy-dracula`)
+ * plus style modifier themes (`daisy-rounded`, `daisy-flat`). Custom themes
+ * register their light/dark variant via `registerTheme()` in
+ * `./registry.ts` so `followSystem` and `toggle()` know what to pick.
  *
  * Usage:
  *
  * ```tsx
  * import { ThemeProvider, useTheme } from '@sigx/lynx-daisyui';
  *
+ * // System-aware (default): picks daisy-light or daisy-dark from the OS,
+ * // live-flips when the user toggles dark mode.
  * defineApp(() => () => (
- *     <ThemeProvider initial="daisy-light">
+ *     <ThemeProvider>
  *         <App />
  *     </ThemeProvider>
  * ));
  *
- * // Anywhere inside:
- * const theme = useTheme();
- * theme.toggle();             // daisy-light ↔ daisy-dark
- * theme.set('daisy-dark');    // explicit
- * theme.name;                 // 'daisy-light' | 'daisy-dark' | custom string
- * ```
+ * // Pin a specific theme — ignores system appearance.
+ * <ThemeProvider initial="daisy-light">…</ThemeProvider>
  *
- * For multi-class compositions (color + modifier), set a custom string:
- * `theme.set('daisy-light daisy-rounded')`.
+ * // Custom light/dark pair under followSystem.
+ * <ThemeProvider light="daisy-cupcake" dark="daisy-synthwave">…</ThemeProvider>
+ * ```
  */
 import { type Define } from '@sigx/lynx';
+import type { DaisyColor } from '../shared/styles.js';
+/**
+ * Declaration-merge extension: add a typed `variant` prop to `<Icon>`,
+ * `<FaSolidIcon>`, `<LucideIcon>`, etc. Daisy owns the entire concept
+ * — `@sigx/lynx-icons` has no notion of variants. Without this merge
+ * being in scope (i.e. an app that doesn't depend on daisy), `<Icon
+ * variant="…">` is a compile error: the property doesn't exist.
+ *
+ * The merge fires the moment any consumer imports anything from
+ * `@sigx/lynx-daisyui`. No subpath, no extra import dance.
+ */
+declare module '@sigx/lynx-icons' {
+    interface IconPropsExtensions {
+        /**
+         * Daisy color token applied as the icon's `fill`. Resolved at
+         * runtime through `useIconColorResolver` (provided by
+         * `<ThemeProvider>`) to the current theme's hex value.
+         */
+        variant?: DaisyColor;
+    }
+}
 /**
- * Theme class applied to the provider's host view. The two built-ins
- * (`daisy-light` / `daisy-dark`) get autocomplete; arbitrary strings
- * are accepted for custom themes or multi-class compositions like
- * `'daisy-light daisy-rounded'`.
+ * Theme class applied to the provider's host view. The six color themes
+ * get autocomplete; arbitrary strings are accepted for custom themes or
+ * multi-class compositions like `'daisy-light daisy-rounded'`.
  */
-export type DaisyTheme = 'daisy-light' | 'daisy-dark' | (string & {});
+export type DaisyTheme = 'daisy-light' | 'daisy-dark' | 'daisy-cupcake' | 'daisy-emerald' | 'daisy-synthwave' | 'daisy-dracula' | (string & {});
 export interface ThemeController {
     /** Current theme class. Reactive — read inside render/effect to track. */
     readonly name: DaisyTheme;
-    /** Replace the active theme. */
+    /**
+     * Whether the theme is currently being driven by the system color
+     * scheme (true when no `initial` was passed and `set()` hasn't been
+     * called since mount). UI like a settings screen can read this to show
+     * a "Follow system" indicator.
+     */
+    readonly followingSystem: boolean;
+    /**
+     * Replace the active theme. Pins the choice — subsequent system
+     * appearance changes won't override it (until `followSystem()` is called).
+     */
     set(name: DaisyTheme): void;
     /**
-     * Flip between `daisy-light` and `daisy-dark`. When the active
-     * theme is neither (custom / multi-class), defaults to
-     * `daisy-dark` on first call.
+     * Flip to the paired theme — for built-ins, light ↔ dark; for custom
+     * themes, follows the `pair` declared in `registerTheme()`, or the
+     * first theme of the opposite variant.
      */
     toggle(): void;
+    /**
+     * Resume following system appearance. Equivalent to mounting fresh
+     * with no `initial` prop. Useful for a "Reset to system" button.
+     */
+    followSystem(): void;
 }
 /**
- * Access the enclosing daisyui theme controller. Throws when used
- * outside `<ThemeProvider>` — install a provider at your app root.
+ * Access the active daisyui theme controller. Resolves to the nearest
+ * `<ThemeProvider>`'s controller (a content sub-scope), or — at the app root
+ * and in *headless* code with no provider mounted — the global controller
+ * (`themeController`). Never throws: theme control is reachable from anywhere
+ * (issue #113). For control that must always target the app/OS theme
+ * regardless of scope (e.g. a status-bar sync), import `themeController`.
  */
 export declare const useTheme: import("@sigx/runtime-core").InjectableFunction<ThemeController>;
 export type ThemeProviderProps = 
-/** Initial theme class. Defaults to `daisy-light`. */
+/**
+ * Pin the initial theme. When set, the provider ignores system
+ * appearance until `controller.followSystem()` is called. When
+ * omitted, the provider follows the OS color scheme and live-flips
+ * with it.
+ */
 Define.Prop<'initial', DaisyTheme, false>
+/**
+ * Theme to use when the system color scheme is `'light'`. Defaults to
+ * the first registered light theme (`daisy-light`). Only consulted
+ * while `followingSystem` is true.
+ */
+ & Define.Prop<'light', DaisyTheme, false>
+/**
+ * Theme to use when the system color scheme is `'dark'`. Defaults to
+ * the first registered dark theme (`daisy-dark`). Only consulted
+ * while `followingSystem` is true.
+ */
+ & Define.Prop<'dark', DaisyTheme, false>
 /** Extra classes appended to the theme class on the host view. */
  & Define.Prop<'class', string, false>
 /** Extra inline style on the host view. Merged after the base flex-fill defaults. */
  & Define.Prop<'style', Record<string, string | number>, false> & Define.Slot<'default'>;
 /**
- * Wraps children in a `<view class={theme}>` so the daisyui CSS
- * variables defined inside `.daisy-light` / `.daisy-dark` inherit
- * down to every descendant.
+ * Wraps children in a `<view class={theme}>` so the daisyui CSS variables
+ * defined inside the theme class inherit down to every descendant.
  *
- * The host view defaults to flex-fill long-form so the wrapper doesn't
- * collapse between ancestors that flex (e.g. `<SafeAreaProvider>`) and
- * descendants that need a sized parent (`<SafeAreaView>`). Consumers
- * override the layout via `style`.
+ * Layout: defaults to flex-fill long-form so the wrapper doesn't collapse
+ * between ancestors that flex (e.g. `<SafeAreaProvider>`) and descendants
+ * that need a sized parent (`<SafeAreaView>`). Consumers override via
+ * `style`.
  *
  * Theme name is held in an *object* signal (not a primitive) so the
- * literal-union type survives — `signal<T>` widens primitive literals
- * to plain `string` via `Widen<T>`.
+ * literal-union type survives — `signal<T>` widens primitive literals to
+ * plain `string` via `Widen<T>`.
  */
 export declare const ThemeProvider: import("@sigx/runtime-core").ComponentFactory<ThemeProviderProps, void, {
     default: () => import("@sigx/runtime-core").JSXElement | import("@sigx/runtime-core").JSXElement[] | null;
 }>;
+export { listThemes, registerTheme, extendTheme, pickThemeFor, pairOf, variantOf, colorsOf, radiusOf, } from './registry.js';
+export type { Theme, ThemePalette, ThemeRadius, ThemeVariant } from './registry.js';

package/dist/theme/ThemeProvider.js

@@ -3,81 +3,199 @@ import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
  * `<ThemeProvider>` and `useTheme()` — daisyui theme switching for
  * `@sigx/lynx-daisyui`.
  *
- * The package ships two color themes (`daisy-light`, `daisy-dark`) plus
- * style modifier themes (`daisy-rounded`, `daisy-flat`). Each is a CSS
- * class containing scoped `--color-*` / `--radius-*` / `--border-*`
- * variable definitions; descendants of an element with the class
- * inherit those variables (Lynx has `enableCSSInheritance: true` in
- * its layout-pipeline defaults), and the daisyui components are built
- * to read those vars directly.
+ * Themes are CSS classes containing scoped `--color-*` / `--radius-*`
+ * variable definitions; descendants of an element with the class inherit
+ * those variables (Lynx has `enableCSSInheritance: true` in its
+ * layout-pipeline defaults), and the daisyui components are built to read
+ * those vars directly.
+ *
+ * Six color themes ship in the box (`daisy-light`, `daisy-dark`,
+ * `daisy-cupcake`, `daisy-emerald`, `daisy-synthwave`, `daisy-dracula`)
+ * plus style modifier themes (`daisy-rounded`, `daisy-flat`). Custom themes
+ * register their light/dark variant via `registerTheme()` in
+ * `./registry.ts` so `followSystem` and `toggle()` know what to pick.
  *
  * Usage:
  *
  * ```tsx
  * import { ThemeProvider, useTheme } from '@sigx/lynx-daisyui';
  *
+ * // System-aware (default): picks daisy-light or daisy-dark from the OS,
+ * // live-flips when the user toggles dark mode.
  * defineApp(() => () => (
- *     <ThemeProvider initial="daisy-light">
+ *     <ThemeProvider>
  *         <App />
  *     </ThemeProvider>
  * ));
  *
- * // Anywhere inside:
- * const theme = useTheme();
- * theme.toggle();             // daisy-light ↔ daisy-dark
- * theme.set('daisy-dark');    // explicit
- * theme.name;                 // 'daisy-light' | 'daisy-dark' | custom string
- * ```
+ * // Pin a specific theme — ignores system appearance.
+ * <ThemeProvider initial="daisy-light">…</ThemeProvider>
  *
- * For multi-class compositions (color + modifier), set a custom string:
- * `theme.set('daisy-light daisy-rounded')`.
+ * // Custom light/dark pair under followSystem.
+ * <ThemeProvider light="daisy-cupcake" dark="daisy-synthwave">…</ThemeProvider>
+ * ```
  */
-import { component, defineInjectable, defineProvide, signal, } from '@sigx/lynx';
+import { component, defineInjectable, defineProvide, effect, onMounted, onUnmounted, signal, untrack, } from '@sigx/lynx';
+import { useIconColorResolver } from '@sigx/lynx-icons';
+import { useSystemColorScheme } from '@sigx/lynx-appearance';
+import { colorsOf, pickThemeFor, radiusOf } from './registry.js';
+import { globalThemeState, makeThemeController, themeController, } from './theme-state.js';
 /**
- * Access the enclosing daisyui theme controller. Throws when used
- * outside `<ThemeProvider>` — install a provider at your app root.
+ * Access the active daisyui theme controller. Resolves to the nearest
+ * `<ThemeProvider>`'s controller (a content sub-scope), or — at the app root
+ * and in *headless* code with no provider mounted — the global controller
+ * (`themeController`). Never throws: theme control is reachable from anywhere
+ * (issue #113). For control that must always target the app/OS theme
+ * regardless of scope (e.g. a status-bar sync), import `themeController`.
  */
-export const useTheme = defineInjectable(() => {
-    throw new Error('[lynx-daisyui] useTheme() called outside <ThemeProvider>. Wrap your app root with `<ThemeProvider initial="daisy-light">…</ThemeProvider>`.');
-});
+export const useTheme = defineInjectable(() => themeController);
 /**
- * Wraps children in a `<view class={theme}>` so the daisyui CSS
- * variables defined inside `.daisy-light` / `.daisy-dark` inherit
- * down to every descendant.
+ * Nesting-depth marker. The outermost `<ThemeProvider>` sees depth 0 and binds
+ * the global singleton (so headless `themeController` mutations render and the
+ * OS bars track it); a nested provider sees >= 1 and creates its own local
+ * state — a content sub-scope that recolors its subtree without touching the
+ * global theme or the system bars.
+ */
+const useThemeDepth = defineInjectable(() => 0);
+/**
+ * Wraps children in a `<view class={theme}>` so the daisyui CSS variables
+ * defined inside the theme class inherit down to every descendant.
  *
- * The host view defaults to flex-fill long-form so the wrapper doesn't
- * collapse between ancestors that flex (e.g. `<SafeAreaProvider>`) and
- * descendants that need a sized parent (`<SafeAreaView>`). Consumers
- * override the layout via `style`.
+ * Layout: defaults to flex-fill long-form so the wrapper doesn't collapse
+ * between ancestors that flex (e.g. `<SafeAreaProvider>`) and descendants
+ * that need a sized parent (`<SafeAreaView>`). Consumers override via
+ * `style`.
  *
  * Theme name is held in an *object* signal (not a primitive) so the
- * literal-union type survives — `signal<T>` widens primitive literals
- * to plain `string` via `Widen<T>`.
+ * literal-union type survives — `signal<T>` widens primitive literals to
+ * plain `string` via `Widen<T>`.
  */
 export const ThemeProvider = component(({ props, slots }) => {
-    const state = signal({ name: props.initial ?? 'daisy-light' });
-    const controller = {
-        get name() { return state.name; },
-        set(next) { state.name = next; },
-        toggle() {
-            if (state.name === 'daisy-light')
-                state.name = 'daisy-dark';
-            else if (state.name === 'daisy-dark')
-                state.name = 'daisy-light';
-            else
-                state.name = 'daisy-dark';
-        },
-    };
+    const systemScheme = useSystemColorScheme();
+    // The underlying signal widens to PrimitiveSignal<string> via Widen<T>;
+    // cast at read sites to keep the narrow union throughout the component.
+    const readScheme = () => systemScheme.value;
+    // Root vs. nested. The outermost provider (depth 0) binds the global
+    // singleton — so headless `themeController` mutations render here and the OS
+    // bars (via StatusBarSync) follow this theme. A nested provider gets its own
+    // local state: a content sub-scope that overrides its subtree only.
+    const depth = useThemeDepth();
+    const isRoot = depth === 0;
+    defineProvide(useThemeDepth, () => depth + 1);
+    const state = isRoot
+        ? globalThemeState
+        : signal(props.initial
+            ? { name: props.initial, following: false }
+            : {
+                name: readScheme() === 'dark'
+                    ? (props.dark ?? pickThemeFor('dark'))
+                    : (props.light ?? pickThemeFor('light')),
+                following: true,
+            });
+    // Seed the root from props/system. An explicit `initial` pin is author
+    // intent and wins. With no `initial`, reflect the current system scheme into
+    // the first render — but only while `following`, so a theme a headless
+    // caller set before this mounted is respected, not clobbered. The follow
+    // effect below keeps it in sync afterwards.
+    if (isRoot) {
+        if (props.initial) {
+            state.name = props.initial;
+            state.following = false;
+        }
+        else if (state.following) {
+            state.name = readScheme() === 'dark'
+                ? (props.dark ?? pickThemeFor('dark'))
+                : (props.light ?? pickThemeFor('light'));
+        }
+    }
+    const controller = isRoot
+        ? themeController
+        : makeThemeController(state);
     defineProvide(useTheme, () => controller);
+    // Wire the daisy color resolver into `@sigx/lynx-icons`'s injectable
+    // so any `<Icon variant="primary">` rendered inside this subtree gets
+    // the daisy primary hex automatically. Reading `state.name` inside
+    // the resolver makes every icon's render re-run when the theme flips.
+    const resolver = (iconProps) => {
+        const variant = iconProps.variant;
+        if (!variant)
+            return undefined;
+        // Every theme's palette lives in the registry; fall back to daisy-light
+        // if the active theme isn't registered. SVG fills can't read CSS vars,
+        // so the resolved hex/rgb is substituted into the fill at render time.
+        const palette = colorsOf(state.name) ?? colorsOf('daisy-light');
+        return palette?.[variant];
+    };
+    defineProvide(useIconColorResolver, () => resolver);
+    // Follow the system color scheme while `following`. Reactive: re-runs when
+    // `following` flips true (e.g. `controller.followSystem()`, including the
+    // headless `themeController`) or when the OS scheme changes, and writes the
+    // matching theme. Reading `state.following` and `systemScheme.value` tracks
+    // them; the `name` write is `untrack`ed so it can't re-trigger the effect.
+    // Created on mount (the native publisher may populate the scheme between
+    // setup and mount) and torn down on unmount.
+    let follow;
+    onMounted(() => {
+        follow = effect(() => {
+            const following = state.following;
+            const scheme = readScheme();
+            if (!following)
+                return;
+            const next = scheme === 'dark'
+                ? (props.dark ?? pickThemeFor('dark'))
+                : (props.light ?? pickThemeFor('light'));
+            untrack(() => {
+                if (state.name !== next)
+                    state.name = next;
+            });
+        });
+    });
+    onUnmounted(() => {
+        follow?.stop();
+        follow = undefined;
+    });
     return () => {
-        const baseStyle = {
+        // Every theme is data. Apply its color tokens as inline CSS custom
+        // properties — Lynx inherits custom properties to descendants, so
+        // component classes resolve `var(--color-*)` against these (the same
+        // mechanism SafeAreaProvider uses for `--sat`/`--sal`). The `daisy`
+        // base class supplies theme-agnostic structural tokens (radius,
+        // sizing); a theme may override roundness via `radius`. The root
+        // background/text are painted from the palette literals (inline
+        // `var()` values don't resolve in Lynx).
+        const palette = colorsOf(state.name) ?? colorsOf('daisy-light');
+        const radius = radiusOf(state.name);
+        const style = {
             flexGrow: 1,
             flexShrink: 1,
             flexBasis: 0,
             minHeight: 0,
             display: 'flex',
             flexDirection: 'column',
+            backgroundColor: palette['base-100'],
+            color: palette['base-content'],
         };
-        return (_jsx("view", { class: `${state.name}${props.class ? ' ' + props.class : ''}`, style: props.style ? { ...baseStyle, ...props.style } : baseStyle, children: slots.default?.() }));
+        for (const key in palette) {
+            style[`--color-${key}`] = palette[key];
+        }
+        if (radius) {
+            if (radius.box)
+                style['--rounded-box'] = radius.box;
+            if (radius.btn)
+                style['--rounded-btn'] = radius.btn;
+            if (radius.badge)
+                style['--rounded-badge'] = radius.badge;
+            if (radius.tab)
+                style['--rounded-tab'] = radius.tab;
+            if (radius.selector)
+                style['--rounded-selector'] = radius.selector;
+            if (radius.toggle)
+                style['--rounded-toggle'] = radius.toggle;
+        }
+        if (props.style)
+            Object.assign(style, props.style);
+        return (_jsx("view", { class: `daisy${props.class ? ' ' + props.class : ''}`, style: style, children: slots.default?.() }));
     };
 });
+// Re-export registry helpers so consumers only need `@sigx/lynx-daisyui`.
+export { listThemes, registerTheme, extendTheme, pickThemeFor, pairOf, variantOf, colorsOf, radiusOf, } from './registry.js';

package/dist/theme/registry.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Theme registry — the single source of truth for daisy 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
+ * 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-*)`),
+ * and the icon color resolver reads the same palette for SVG fills (parsed SVG
+ * content can't read CSS vars). There is no per-theme CSS or parallel JS
+ * palette to keep in sync.
+ *
+ * The six built-ins are seeded below. 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 `.daisy` base class (`styles/themes/tokens.css`);
+ * a theme may override roundness via `radius`.
+ *
+ * Colors are engine-safe strings — hex or `rgb()`. Lynx's CSS engine does not
+ * parse `oklch()`, so convert before registering.
+ */
+import type { DaisyColor } from '../shared/styles.js';
+export type ThemeVariant = 'light' | 'dark';
+/** Full daisy color palette — every semantic token, no holes. */
+export type ThemePalette = Record<DaisyColor, string>;
+/** Roundness token overrides. Defaults live in the bundled `.daisy` base. */
+export interface ThemeRadius {
+    box?: string;
+    btn?: string;
+    badge?: string;
+    tab?: string;
+    selector?: string;
+    toggle?: string;
+}
+export interface Theme {
+    /** Unique id — also the value of `theme.name`. */
+    name: string;
+    /** Light or dark — drives follow-system selection and status-bar tint. */
+    variant: ThemeVariant;
+    /** Complete color palette (all 20 semantic tokens). */
+    colors: ThemePalette;
+    /**
+     * 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 `.daisy`. */
+    radius?: ThemeRadius;
+}
+/**
+ * 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 declare function listThemes(): readonly Theme[];
+/**
+ * Register (or replace, by `name`) a theme. Call at module-load time before
+ * mounting `<ThemeProvider>` so it shows up in `listThemes()` / `pickThemeFor()`.
+ */
+export declare function registerTheme(theme: Theme): void;
+/**
+ * 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 declare function extendTheme(base: string, patch: {
+    name: string;
+    variant?: ThemeVariant;
+    pair?: string;
+    colors?: Partial<ThemePalette>;
+    radius?: ThemeRadius;
+}): Theme;
+/** The variant of a registered theme, or `undefined` if not registered. */
+export declare function variantOf(name: string | undefined): ThemeVariant | undefined;
+/** The color palette of a registered theme, or `undefined` if not registered. */
+export declare function colorsOf(name: string | undefined): ThemePalette | undefined;
+/** The roundness overrides of a registered theme, if any. */
+export declare function radiusOf(name: string | undefined): ThemeRadius | undefined;
+/**
+ * Pick a default theme for a given system color scheme — the first registered
+ * theme of that variant (`daisy-light` / `daisy-dark` under the seeded
+ * registry). Falls back to `'daisy-light'` if none of that variant exists.
+ */
+export declare function pickThemeFor(scheme: ThemeVariant): string;
+/**
+ * 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 declare function pairOf(name: string): string;