@sigx/lynx-daisyui 0.4.2 → 0.4.3

package/README.md

@@ -83,10 +83,88 @@ layout role. For multi-class compositions (color + modifier),
 `theme.set('daisy-light daisy-rounded')` works — the class string is
 applied verbatim to the host view.
 
+### Two layers: content vs. OS chrome
+
+A theme drives two different things, and they scope differently:
+
+1. **In-app content** — the `--color-*` / radius variables and icon
+   tints. These live on a host view and inherit down a subtree, so they
+   are genuinely *scopable*.
+2. **OS chrome** — the status- and navigation-bar tint (pushed by
+   `<StatusBarSync>`). This is a global OS singleton; it can only reflect
+   one theme at a time.
+
+The rule:
+
+> `useTheme()` is the theme for the **content you render** — the nearest
+> `<ThemeProvider>`, or the app-global theme at the root / in headless
+> code. **System chrome always follows the global theme.** `StatusBarSync`
+> binds to the global controller, so a nested provider can't hijack the
+> bars.
+>
+> *Scopes recolor pixels you draw; only the global theme touches the OS.*
+
+This mirrors Flutter, where `Theme` nests freely for content while system
+chrome goes through a separate channel (`AnnotatedRegion`/`SystemChrome`).
+
+### Headless control (no provider required)
+
+The active theme lives in a module-level singleton, so you can read and
+set it from anywhere — a store, a service, app-boot logic, an effect —
+without a mounted `<ThemeProvider>` ancestor. `useTheme()` resolves to
+this same controller when no provider is in scope (it never throws).
+
+```tsx
+import { themeController } from '@sigx/lynx-daisyui';
+
+// From any non-component module:
+themeController.set('daisy-dark');
+themeController.toggle();
+themeController.followSystem();
+themeController.name;            // current selection
+```
+
+A mounted root `<ThemeProvider>` binds this singleton, so headless
+mutations render and the OS bars follow.
+
+### Per-screen themes
+
+Different screens can use different themes — and the status-bar icons
+follow the active screen so they stay legible. Because this drives the
+**global** theme, the bars update automatically:
+
+```tsx
+import { useScreenTheme } from '@sigx/lynx-daisyui';
+
+const Gallery = component(() => {
+    useScreenTheme('daisy-dark'); // dark (incl. status bar) while focused; restored on blur
+    return () => <view>…</view>;
+});
+```
+
+`useScreenTheme` is built on `@sigx/lynx-navigation`'s `useFocusEffect`
+(an optional peer) and must be called from a routed screen.
+
+### Scoped sub-overrides
+
+To recolor just a **region** without touching the OS bars, nest a
+`<ThemeProvider>`. Its subtree (content + icons) re-themes; the status
+bar stays on the global theme.
+
+```tsx
+<ThemeProvider initial="daisy-light">
+    <App />
+    {/* this card renders synthwave; the status bar stays light */}
+    <ThemeProvider initial="daisy-synthwave">
+        <PreviewCard />
+    </ThemeProvider>
+</ThemeProvider>
+```
+
 ## Navigation chrome
 
 Two daisy-themed components that pair with
-[`@sigx/lynx-navigation`](../lynx-navigation). Both read state via the
+[`@sigx/lynx-navigation`](https://github.com/signalxjs/lynx/tree/main/packages/lynx-navigation). Both read state via the
 navigation package's hooks (no internal-module imports), so swapping
 in custom designs later is a one-component change.
 
@@ -146,7 +224,7 @@ one consumer of that hook.
 ### `<SwiperIndicator>`
 
 Themed wrapper around the headless `useSwiperDot*` hooks from
-[`@sigx/lynx-gestures`](../lynx-gestures#swiper-and-headless-dot-hooks).
+[`@sigx/lynx-gestures`](https://github.com/signalxjs/lynx/tree/main/packages/lynx-gestures#swiper-and-headless-dot-hooks).
 Reads colours from the active daisy theme so the indicator follows light
 / dark mode automatically.
 

package/dist/index.d.ts

@@ -58,6 +58,8 @@ export { ThemeProvider, useTheme, listThemes, registerTheme, extendTheme, pickTh
 export type { DaisyTheme, ThemeController, ThemeProviderProps, Theme, ThemePalette, ThemeRadius, ThemeVariant, } from './theme/ThemeProvider.js';
 export { StatusBarSync } from './theme/StatusBarSync.js';
 export type { StatusBarSyncProps } from './theme/StatusBarSync.js';
+export { themeController } from './theme/theme-state.js';
+export { useScreenTheme } from './theme/use-screen-theme.js';
 export { Avatar } from './data/Avatar.js';
 export type { AvatarProps, AvatarSize } from './data/Avatar.js';
 export { Text } from './typography/Text.js';

package/dist/index.js

@@ -34,6 +34,13 @@ export { SwiperIndicator } from './navigation/SwiperIndicator.js';
 // Theme
 export { ThemeProvider, useTheme, listThemes, registerTheme, extendTheme, pickThemeFor, pairOf, variantOf, colorsOf, radiusOf, } from './theme/ThemeProvider.js';
 export { StatusBarSync } from './theme/StatusBarSync.js';
+// Headless theme handle (issue #113): import and call from anywhere — stores,
+// services, effects, app-boot — with no `<ThemeProvider>` ancestor required.
+// `useTheme()` resolves to this when no provider is in scope.
+export { themeController } from './theme/theme-state.js';
+// Per-screen theming: pin the global theme while a navigation screen is focused
+// (requires the optional `@sigx/lynx-navigation` peer).
+export { useScreenTheme } from './theme/use-screen-theme.js';
 // Data
 export { Avatar } from './data/Avatar.js';
 // Typography

package/dist/theme/StatusBarSync.js

@@ -28,10 +28,13 @@ import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
  */
 import { component, effect, onMounted, onUnmounted } from '@sigx/lynx';
 import { isAvailable, setSystemBarsStyle } from '@sigx/lynx-appearance';
-import { useTheme } from './ThemeProvider.js';
+import { themeController } from './theme-state.js';
 import { variantOf } from './registry.js';
 export const StatusBarSync = component(({ props }) => {
-    const theme = useTheme();
+    // Bind to the *global* theme — not `useTheme()` — so the OS bars always
+    // track the app/screen theme and can't be hijacked by a content sub-scope
+    // (a nested `<ThemeProvider>` recolors its subtree but leaves the bars put).
+    const theme = themeController;
     let lastApplied = null;
     let runner;
     function apply(name) {

package/dist/theme/ThemeProvider.d.ts

@@ -90,8 +90,12 @@ export interface ThemeController {
     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 = 

package/dist/theme/ThemeProvider.js

@@ -35,17 +35,28 @@ import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
  * <ThemeProvider light="daisy-cupcake" dark="daisy-synthwave">…</ThemeProvider>
  * ```
  */
-import { component, defineInjectable, defineProvide, onMounted, onUnmounted, 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, pairOf, pickThemeFor, radiusOf } from './registry.js';
+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>…</ThemeProvider>`.');
-});
+export const useTheme = defineInjectable(() => themeController);
+/**
+ * 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.
@@ -64,44 +75,42 @@ export const ThemeProvider = component(({ props, slots }) => {
     // 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;
-    // Seed: pin to `initial` if set, otherwise follow system.
-    const initialState = props.initial
-        ? { name: props.initial, following: false }
-        : {
-            name: readScheme() === 'dark'
+    // 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')),
-            following: true,
-        };
-    const state = signal(initialState);
-    // Guard against re-applying the same theme on stray re-fires.
-    let lastApplied = state.following ? readScheme() : null;
-    function applySystem(scheme, force = false) {
-        if (!state.following)
-            return;
-        if (!force && lastApplied === scheme)
-            return;
-        lastApplied = scheme;
-        state.name = scheme === 'dark'
-            ? (props.dark ?? pickThemeFor('dark'))
-            : (props.light ?? pickThemeFor('light'));
+                : (props.light ?? pickThemeFor('light'));
+        }
     }
-    const controller = {
-        get name() { return state.name; },
-        get followingSystem() { return state.following; },
-        set(next) {
-            state.name = next;
-            state.following = false;
-        },
-        toggle() {
-            state.name = pairOf(state.name);
-            state.following = false;
-        },
-        followSystem() {
-            state.following = true;
-            applySystem(readScheme(), /* force */ true);
-        },
-    };
+    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
@@ -118,23 +127,32 @@ export const ThemeProvider = component(({ props, slots }) => {
         return palette?.[variant];
     };
     defineProvide(useIconColorResolver, () => resolver);
-    // Subscribe to system color-scheme changes. Both PrimitiveSignal and
-    // Computed expose `.subscribe(fn)` returning an unsubscribe handle —
-    // we lean on the structural shape so this file doesn't pull
-    // @sigx/reactivity into its imports.
-    let unsubscribe;
+    // 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(() => {
-        // Re-seed once mounted — covers the case where the native publisher
-        // populated `__globalProps` between setup and mount.
-        applySystem(readScheme());
-        const sig = systemScheme;
-        if (typeof sig.subscribe === 'function') {
-            unsubscribe = sig.subscribe(() => applySystem(readScheme()));
-        }
+        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(() => {
-        unsubscribe?.();
-        unsubscribe = undefined;
+        follow?.stop();
+        follow = undefined;
     });
     return () => {
         // Every theme is data. Apply its color tokens as inline CSS custom

package/dist/theme/theme-state.d.ts

@@ -0,0 +1,28 @@
+import type { DaisyTheme, ThemeController } from './ThemeProvider.js';
+/** The mutable selection a `ThemeController` reads from and writes to. */
+export interface ThemeState {
+    name: DaisyTheme;
+    following: boolean;
+}
+/**
+ * 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 declare function makeThemeController(state: ThemeState): ThemeController;
+/**
+ * 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 declare const globalThemeState: import("@sigx/reactivity").Signal<ThemeState>;
+/**
+ * The global theme controller — the headless handle for issue #113. 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 declare const themeController: ThemeController;

package/dist/theme/theme-state.js

@@ -0,0 +1,72 @@
+/**
+ * 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';
+/**
+ * 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) {
+    return {
+        get name() {
+            return state.name;
+        },
+        get followingSystem() {
+            return state.following;
+        },
+        set(next) {
+            state.name = next;
+            state.following = false;
+        },
+        toggle() {
+            state.name = pairOf(state.name);
+            state.following = false;
+        },
+        followSystem() {
+            state.following = true;
+        },
+    };
+}
+// Object signal (not primitive) so the `DaisyTheme` literal union survives —
+// `signal<T>` widens primitive literals to plain `string` via `Widen<T>`.
+// Seeded to a sane default; the root <ThemeProvider> re-seeds from the system
+// color scheme + its props on mount.
+const state = signal({
+    name: pickThemeFor('light'),
+    following: true,
+});
+/**
+ * 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 for issue #113. 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 = makeThemeController(state);

package/dist/theme/use-screen-theme.d.ts

@@ -0,0 +1,3 @@
+import type { DaisyTheme } from './ThemeProvider.js';
+/** Pin the global theme to `name` while this screen is focused; restore on blur. */
+export declare function useScreenTheme(name: DaisyTheme): void;

package/dist/theme/use-screen-theme.js

@@ -0,0 +1,42 @@
+/**
+ * `useScreenTheme(name)` — pin the **global** daisy 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';
+/** Pin the global theme to `name` while this screen is focused; restore on blur. */
+export function useScreenTheme(name) {
+    useFocusEffect(() => {
+        const prevName = themeController.name;
+        const prevFollowing = themeController.followingSystem;
+        themeController.set(name);
+        return () => {
+            if (prevFollowing)
+                themeController.followSystem();
+            else
+                themeController.set(prevName);
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-daisyui",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "DaisyUI integration for sigx-lynx",
   "type": "module",
   "main": "./dist/index.js",
@@ -37,15 +37,15 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@sigx/lynx": "^0.4.2",
-    "@sigx/lynx-appearance": "^0.4.2",
-    "@sigx/lynx-icons": "^0.4.2",
-    "@sigx/lynx-motion": "^0.4.2",
-    "@sigx/lynx-gestures": "^0.4.2"
+    "@sigx/lynx": "^0.4.3",
+    "@sigx/lynx-gestures": "^0.4.3",
+    "@sigx/lynx-icons": "^0.4.3",
+    "@sigx/lynx-appearance": "^0.4.3",
+    "@sigx/lynx-motion": "^0.4.3"
   },
   "peerDependencies": {
     "tailwindcss": "^3.0.0 || ^4.0.0",
-    "@sigx/lynx-navigation": "^0.4.2"
+    "@sigx/lynx-navigation": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "@sigx/lynx-navigation": {
@@ -56,7 +56,7 @@
     "@typescript/native-preview": "7.0.0-dev.20260521.1",
     "tailwindcss": "^4.0.0",
     "typescript": "^6.0.3",
-    "@sigx/lynx-navigation": "^0.4.2"
+    "@sigx/lynx-navigation": "^0.4.3"
   },
   "publishConfig": {
     "access": "public"