@marianmeres/stuic 3.90.0 → 3.92.0

package/dist/components/ColorScheme/ColorSchemeLocal.svelte

@@ -3,13 +3,26 @@
 	export interface Props {}
 </script>
 
+<script lang="ts">
+	import { ColorScheme } from "./color-scheme.svelte.js";
+	$effect(() => {
+		// Bootstrap <script> below has run by the time this effect fires;
+		// re-seed the runtime from whatever the DOM is now showing.
+		ColorScheme.syncFromDom();
+	});
+</script>
+
 <!--
-    Similar to PrefersColorScheme, except that it never reads window.matchMedia and only
-    relies on the local userland setting
+	Similar to ColorSchemeSystemAware, except that it never reads window.matchMedia and only
+	relies on the local userland setting.
+
+	Uses the hardcoded default storage key "stuic-color-scheme". Apps that
+	override the runtime key via `ColorScheme.configure({ key })` should ship
+	their own inline bootstrap in `app.html` if FOUC-free hydration matters.
 -->
 <svelte:head>
 	<script>
-		const KEY = "stuic-color-scheme";
+		const KEY = window.__COLOR_SCHEME_KEY__ ?? "stuic-color-scheme";
 		const cls = window.document.documentElement.classList;
 		localStorage.getItem(KEY) === "dark" ? cls.add("dark") : cls.remove("dark");
 	</script>

package/dist/components/ColorScheme/ColorSchemeLocal.svelte.d.ts

@@ -1,21 +1,6 @@
 /** ColorSchemeLocal has no props - it's a pure hydration component */
 export interface Props {
 }
-interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
-        $$bindings?: Bindings;
-    } & Exports;
-    (internal: unknown, props: {
-        $$events?: Events;
-        $$slots?: Slots;
-    }): Exports & {
-        $set?: any;
-        $on?: any;
-    };
-    z_$$bindings?: Bindings;
-}
-declare const ColorSchemeLocal: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
-type ColorSchemeLocal = InstanceType<typeof ColorSchemeLocal>;
+declare const ColorSchemeLocal: import("svelte").Component<Record<string, never>, {}, "">;
+type ColorSchemeLocal = ReturnType<typeof ColorSchemeLocal>;
 export default ColorSchemeLocal;

package/dist/components/ColorScheme/ColorSchemeSystemAware.svelte

@@ -3,12 +3,25 @@
 	export interface Props {}
 </script>
 
+<script lang="ts">
+	import { ColorScheme } from "./color-scheme.svelte.js";
+	$effect(() => {
+		// Bootstrap <script> below has run by the time this effect fires;
+		// re-seed the runtime from whatever the DOM is now showing.
+		ColorScheme.syncFromDom();
+	});
+</script>
+
 <!--
-	If you do not wish to take the system preference into account use LocalColorScheme sibling
+	If you do not wish to take the system preference into account use ColorSchemeLocal sibling.
+
+	Uses the hardcoded default storage key "stuic-color-scheme". Apps that
+	override the runtime key via `ColorScheme.configure({ key })` should ship
+	their own inline bootstrap in `app.html` if FOUC-free hydration matters.
 -->
 <svelte:head>
 	<script>
-		const KEY = "stuic-color-scheme";
+		const KEY = window.__COLOR_SCHEME_KEY__ ?? "stuic-color-scheme";
 		const cls = window.document.documentElement.classList;
 		if (KEY in localStorage) {
 			localStorage.getItem(KEY) === "dark" ? cls.add("dark") : cls.remove("dark");

package/dist/components/ColorScheme/ColorSchemeSystemAware.svelte.d.ts

@@ -1,21 +1,6 @@
 /** ColorSchemeSystemAware has no props - it's a pure hydration component */
 export interface Props {
 }
-interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
-    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
-        $$bindings?: Bindings;
-    } & Exports;
-    (internal: unknown, props: {
-        $$events?: Events;
-        $$slots?: Slots;
-    }): Exports & {
-        $set?: any;
-        $on?: any;
-    };
-    z_$$bindings?: Bindings;
-}
-declare const ColorSchemeSystemAware: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
-    [evt: string]: CustomEvent<any>;
-}, {}, {}, string>;
-type ColorSchemeSystemAware = InstanceType<typeof ColorSchemeSystemAware>;
+declare const ColorSchemeSystemAware: import("svelte").Component<Record<string, never>, {}, "">;
+type ColorSchemeSystemAware = ReturnType<typeof ColorSchemeSystemAware>;
 export default ColorSchemeSystemAware;

package/dist/components/ColorScheme/color-scheme.svelte.d.ts

@@ -1,47 +1,81 @@
 type Scheme = "dark" | "light";
+declare global {
+    interface Window {
+        /**
+         * Optional global override for the localStorage key the inline bootstrap
+         * `<script>` in `<ColorSchemeLocal />` / `<ColorSchemeSystemAware />` reads
+         * from. Set this before the hydration component mounts (e.g. in
+         * `app.html` or at the very top of the root layout's `<script>`) to use a
+         * custom key with FOUC-free hydration. `ColorScheme.configure({ key })`
+         * also writes this global to keep runtime and bootstrap in sync.
+         */
+        __COLOR_SCHEME_KEY__?: string;
+    }
+}
 /**
  * A utility class for managing light/dark color scheme preferences.
  *
- * Handles system preferences, localStorage persistence, and DOM class toggling.
+ * Handles localStorage persistence and DOM class toggling.
  * Works with Tailwind CSS dark mode (class-based strategy).
  *
  * The `ColorScheme.current` getter is reactive (Svelte 5 `$state`): reading it
- * inside a `$derived`/`$effect`/template will react to toggles, cross-tab
- * `storage` events, and OS-level system-preference changes.
+ * inside a `$derived`/`$effect`/template will react to toggles and cross-tab
+ * `storage` events.
  *
  * @example
  * ```ts
  * // Reactive current value (use in templates / $derived / $effect):
  * const scheme = ColorScheme.current; // 'light' or 'dark'
  *
- * // Backward-compatible non-reactive read:
- * const v = ColorScheme.getValue();
- *
  * // Toggle between light and dark
  * ColorScheme.toggle();
  *
- * // Check system preference only
- * const systemPref = ColorScheme.getSystemValue();
- *
  * // Reset to system preference
  * ColorScheme.reset();
+ *
+ * // Use a custom localStorage key (call early in app boot):
+ * ColorScheme.configure({ key: "myapp:color-scheme" });
  * ```
  *
  * @remarks
- * - Uses localStorage key: "stuic-color-scheme"
+ * - Default localStorage key: "stuic-color-scheme" (override via `configure`)
  * - Adds/removes "dark" class on `<html>` element
  * - Works with Tailwind's `darkMode: 'class'` configuration
+ * - Pair with `<ColorSchemeLocal />` or `<ColorSchemeSystemAware />` for
+ *   FOUC-free initial paint
  */
 export declare class ColorScheme {
-    static readonly KEY: "stuic-color-scheme";
     static readonly DARK: "dark";
     static readonly LIGHT: "light";
+    /**
+     * The active localStorage key. Default is `"stuic-color-scheme"`. Override via
+     * `ColorScheme.configure({ key })` or the `key` prop on the hydration components.
+     */
+    static get KEY(): string;
+    /**
+     * Configure the runtime. Call early in app boot, before any consumer reads
+     * `ColorScheme.current`. Mutates module state; safe to call more than once
+     * (last write wins). Calling without changes is a no-op.
+     *
+     * Also writes `window.__COLOR_SCHEME_KEY__` so a subsequent hydration
+     * component mount (or any external bootstrap script that reads the global)
+     * stays in sync with the runtime.
+     */
+    static configure(opts: {
+        key?: string;
+    }): void;
     /**
      * Reactive current value. Read inside `$derived`, `$effect`, or a Svelte
-     * template to react to scheme changes (including cross-tab `storage`
-     * events and OS-level system-preference changes).
+     * template to react to scheme changes (including cross-tab `storage` events).
      */
     static get current(): Scheme;
+    /**
+     * Re-seed `current` from the actual `<html>` class state. Used by the
+     * hydration components after their inline bootstrap `<script>` has run, so
+     * the runtime matches whichever strategy actually painted the DOM. Does NOT
+     * write to the DOM.
+     */
+    static syncFromDom(): void;
     /**
      * Reads the `prefers-color-scheme` system setting
      */
@@ -51,15 +85,16 @@ export declare class ColorScheme {
      */
     static getLocalValue(fallback?: Scheme): Scheme;
     /**
-     * Tries local first, fallbacks to system. Backward-compatible alias for `current`.
+     * Backward-compatible alias for `current`.
      */
     static getValue(): Scheme;
     /**
-     * Sets and saves the opposite of current.
+     * Toggles between light and dark, persists to localStorage, and updates the DOM.
      */
     static toggle(): void;
     /**
-     * Resets color scheme to system preference by removing localStorage value and classes.
+     * Resets color scheme to system preference by removing the localStorage value
+     * and re-applying the resolved scheme.
      */
     static reset(): void;
 }

package/dist/components/ColorScheme/color-scheme.svelte.js

@@ -1,57 +1,103 @@
+const DEFAULT_KEY = "stuic-color-scheme";
+let _key = DEFAULT_KEY;
 let _current = $state("light");
 function _compute() {
-    return ColorScheme.getLocalValue(ColorScheme.getSystemValue());
+    const local = globalThis.localStorage?.getItem(_key);
+    if (local === "dark" || local === "light")
+        return local;
+    return ColorScheme.getSystemValue();
+}
+function _applyDom(scheme) {
+    globalThis?.document?.documentElement.classList.toggle(ColorScheme.DARK, scheme === ColorScheme.DARK);
 }
 function _sync() {
     const next = _compute();
-    if (next !== _current)
+    if (next !== _current) {
         _current = next;
+        _applyDom(next);
+    }
 }
 /**
  * A utility class for managing light/dark color scheme preferences.
  *
- * Handles system preferences, localStorage persistence, and DOM class toggling.
+ * Handles localStorage persistence and DOM class toggling.
  * Works with Tailwind CSS dark mode (class-based strategy).
  *
  * The `ColorScheme.current` getter is reactive (Svelte 5 `$state`): reading it
- * inside a `$derived`/`$effect`/template will react to toggles, cross-tab
- * `storage` events, and OS-level system-preference changes.
+ * inside a `$derived`/`$effect`/template will react to toggles and cross-tab
+ * `storage` events.
  *
  * @example
  * ```ts
  * // Reactive current value (use in templates / $derived / $effect):
  * const scheme = ColorScheme.current; // 'light' or 'dark'
  *
- * // Backward-compatible non-reactive read:
- * const v = ColorScheme.getValue();
- *
  * // Toggle between light and dark
  * ColorScheme.toggle();
  *
- * // Check system preference only
- * const systemPref = ColorScheme.getSystemValue();
- *
  * // Reset to system preference
  * ColorScheme.reset();
+ *
+ * // Use a custom localStorage key (call early in app boot):
+ * ColorScheme.configure({ key: "myapp:color-scheme" });
  * ```
  *
  * @remarks
- * - Uses localStorage key: "stuic-color-scheme"
+ * - Default localStorage key: "stuic-color-scheme" (override via `configure`)
  * - Adds/removes "dark" class on `<html>` element
  * - Works with Tailwind's `darkMode: 'class'` configuration
+ * - Pair with `<ColorSchemeLocal />` or `<ColorSchemeSystemAware />` for
+ *   FOUC-free initial paint
  */
 export class ColorScheme {
-    static KEY = "stuic-color-scheme";
     static DARK = "dark";
     static LIGHT = "light";
+    /**
+     * The active localStorage key. Default is `"stuic-color-scheme"`. Override via
+     * `ColorScheme.configure({ key })` or the `key` prop on the hydration components.
+     */
+    static get KEY() {
+        return _key;
+    }
+    /**
+     * Configure the runtime. Call early in app boot, before any consumer reads
+     * `ColorScheme.current`. Mutates module state; safe to call more than once
+     * (last write wins). Calling without changes is a no-op.
+     *
+     * Also writes `window.__COLOR_SCHEME_KEY__` so a subsequent hydration
+     * component mount (or any external bootstrap script that reads the global)
+     * stays in sync with the runtime.
+     */
+    static configure(opts) {
+        if (opts?.key && opts.key !== _key) {
+            _key = opts.key;
+            if (typeof window !== "undefined")
+                window.__COLOR_SCHEME_KEY__ = opts.key;
+            _sync();
+        }
+    }
     /**
      * Reactive current value. Read inside `$derived`, `$effect`, or a Svelte
-     * template to react to scheme changes (including cross-tab `storage`
-     * events and OS-level system-preference changes).
+     * template to react to scheme changes (including cross-tab `storage` events).
      */
     static get current() {
         return _current;
     }
+    /**
+     * Re-seed `current` from the actual `<html>` class state. Used by the
+     * hydration components after their inline bootstrap `<script>` has run, so
+     * the runtime matches whichever strategy actually painted the DOM. Does NOT
+     * write to the DOM.
+     */
+    static syncFromDom() {
+        if (typeof document === "undefined")
+            return;
+        const next = document.documentElement.classList.contains(ColorScheme.DARK)
+            ? ColorScheme.DARK
+            : ColorScheme.LIGHT;
+        if (next !== _current)
+            _current = next;
+    }
     /**
      * Reads the `prefers-color-scheme` system setting
      */
@@ -64,39 +110,44 @@ export class ColorScheme {
      * Reads locally (localStorage) saved value
      */
     static getLocalValue(fallback = "light") {
-        return (globalThis.localStorage?.getItem(ColorScheme.KEY) || fallback);
+        return globalThis.localStorage?.getItem(_key) || fallback;
     }
     /**
-     * Tries local first, fallbacks to system. Backward-compatible alias for `current`.
+     * Backward-compatible alias for `current`.
      */
     static getValue() {
-        return ColorScheme.current;
+        return _current;
     }
     /**
-     * Sets and saves the opposite of current.
+     * Toggles between light and dark, persists to localStorage, and updates the DOM.
      */
     static toggle() {
-        // returns bool, indicating whether token is in the list after the call or not.
-        const isDark = globalThis?.document?.documentElement.classList.toggle(ColorScheme.DARK);
-        globalThis.localStorage?.setItem(ColorScheme.KEY, isDark ? ColorScheme.DARK : ColorScheme.LIGHT);
-        _sync();
+        const next = _current === ColorScheme.DARK ? ColorScheme.LIGHT : ColorScheme.DARK;
+        globalThis.localStorage?.setItem(_key, next);
+        _applyDom(next);
+        _current = next;
     }
     /**
-     * Resets color scheme to system preference by removing localStorage value and classes.
+     * Resets color scheme to system preference by removing the localStorage value
+     * and re-applying the resolved scheme.
      */
     static reset() {
-        globalThis.localStorage?.removeItem(ColorScheme.KEY);
-        globalThis?.document?.documentElement.classList.remove(ColorScheme.DARK, ColorScheme.LIGHT);
+        globalThis.localStorage?.removeItem(_key);
         _sync();
     }
 }
 if (typeof window !== "undefined") {
+    // If the app declared a custom key via the global (typical place: app.html,
+    // before the bootstrap <script> runs), adopt it so the runtime reads/writes
+    // the same key the bootstrap painted from.
+    if (window.__COLOR_SCHEME_KEY__)
+        _key = window.__COLOR_SCHEME_KEY__;
+    // Seed from localStorage (with system-pref fallback). Reading from the DOM
+    // here is unreliable: module init runs before the hydration component's
+    // inline <script> is appended to <head>, so the dark class isn't there yet.
     _current = _compute();
     window.addEventListener("storage", (e) => {
-        if (e.key === ColorScheme.KEY)
+        if (e.key === _key)
             _sync();
     });
-    window
-        .matchMedia?.(`(prefers-color-scheme: ${ColorScheme.DARK})`)
-        .addEventListener("change", () => _sync());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.90.0",
+	"version": "3.92.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && pnpm run prepack",