@krizaka/ui 2.0.0 → 2.1.0

package/dist/theme.d.ts

@@ -3,14 +3,21 @@ import { a as ButtonVariants } from './button-Cgfkg_3y.js';
 import 'tailwind-variants';
 
 type Mode = "dark" | "light" | "system";
-/**
- * In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.
- * `nonce` for a strict Content-Security-Policy.
- */
-declare function ThemeScript({ nonce, }: {
+type ThemeScriptProps = {
     /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */
     nonce?: string;
-}): React.JSX.Element;
+    /**
+     * The mode before the visitor chooses one — pass the same value as `ThemeProvider`'s `defaultMode`. A persisted
+     * choice (`kz-theme`) always wins.
+     * @default "system"
+     */
+    defaultMode?: Mode;
+};
+/**
+ * In <head>, before anything renders: applies the persisted mode (else `defaultMode`) and named theme, so the page
+ * never flashes. `nonce` for a strict Content-Security-Policy.
+ */
+declare function ThemeScript({ nonce, defaultMode }: ThemeScriptProps): React.JSX.Element;
 type ThemeContextValue = {
     /** The chosen mode: dark, light or follow the system. */
     mode: Mode;
@@ -21,7 +28,10 @@ type ThemeContextValue = {
 };
 type ThemeProviderProps = {
     children: React.ReactNode;
-    /** The mode before anything is persisted. */
+    /**
+     * The mode before the visitor chooses one (nothing persisted as `kz-theme`) — pass the same value to `ThemeScript`.
+     * @default "system"
+     */
     defaultMode?: Mode;
 };
 declare function ThemeProvider({ children, defaultMode }: ThemeProviderProps): React.JSX.Element;
@@ -43,4 +53,4 @@ type ThemeToggleProps = Omit<React.ComponentProps<"button">, "onClick" | "childr
  */
 declare function ThemeToggle({ label, variant, shape, className, ...props }: ThemeToggleProps): React.JSX.Element;
 
-export { type Mode, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, ThemeScript, ThemeToggle, type ThemeToggleProps, useTheme };
+export { type Mode, type ThemeContextValue, ThemeProvider, type ThemeProviderProps, ThemeScript, type ThemeScriptProps, ThemeToggle, type ThemeToggleProps, useTheme };

package/dist/theme.js

@@ -47,10 +47,9 @@ function applyName(previous, next) {
   if (previous) classes.remove(`theme-${previous}`);
   if (next) classes.add(`theme-${next}`);
 }
-function ThemeScript({
-  nonce
-}) {
-  const js = `(function(){try{var m=localStorage.getItem("${MODE_KEY}")||"system";var n=localStorage.getItem("${NAME_KEY}");var d=matchMedia("${DARK_QUERY}").matches;var c=document.documentElement.classList;c.toggle("light",m==="light"||(m==="system"&&!d));if(n)c.add("theme-"+n)}catch(e){}})()`;
+function ThemeScript({ nonce, defaultMode = "system" }) {
+  const fallback = isMode(defaultMode) ? defaultMode : "system";
+  const js = `(function(){try{var m=localStorage.getItem("${MODE_KEY}");if(m!=="dark"&&m!=="light"&&m!=="system")m="${fallback}";var n=localStorage.getItem("${NAME_KEY}");var d=matchMedia("${DARK_QUERY}").matches;var c=document.documentElement.classList;c.toggle("light",m==="light"||(m==="system"&&!d));if(n)c.add("theme-"+n)}catch(e){}})()`;
   return /* @__PURE__ */ jsx("script", { nonce, dangerouslySetInnerHTML: { __html: js } });
 }
 var ThemeContext = React.createContext(null);
@@ -58,6 +57,10 @@ function ThemeProvider({ children, defaultMode = "system" }) {
   const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);
   const mode = isMode(stored) ? stored : defaultMode;
   const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);
+  React.useEffect(() => {
+    const persisted = read(MODE_KEY);
+    applyMode(isMode(persisted) ? persisted : defaultMode);
+  }, [defaultMode]);
   React.useEffect(() => {
     if (mode !== "system") return;
     const query = window.matchMedia(DARK_QUERY);

package/dist/theme.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/theme/theme.tsx"],"sourcesContent":["// Client. ONE mechanism for the whole organisation: dark by default, `html.light` for light, `html.theme-<name>` for a\n// named theme, persisted in localStorage (`kz-theme` for the mode, `kz-theme-name` for the named theme).\nimport * as React from \"react\";\n\nimport { type ButtonVariants, buttonVariants } from \"../button/button\";\n\nexport type Mode = \"dark\" | \"light\" | \"system\";\n\nconst MODE_KEY = \"kz-theme\";\nconst NAME_KEY = \"kz-theme-name\";\nconst MODES: readonly Mode[] = [\"dark\", \"light\", \"system\"];\nconst DARK_QUERY = \"(prefers-color-scheme: dark)\";\n\nconst isMode = (value: unknown): value is Mode => MODES.includes(value as Mode);\n\n// Storage blocked (private mode, sandbox): the choice lives in memory for the page.\nconst memory = new Map<string, string>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    return memory.get(key) ?? null;\n  }\n}\n\nfunction write(key: string, value: string | null) {\n  if (value === null) memory.delete(key);\n  else memory.set(key, value);\n  try {\n    if (value === null) localStorage.removeItem(key);\n    else localStorage.setItem(key, value);\n  } catch {\n    // storage blocked: memory holds it\n  }\n}\n\n// The persisted choice is an external store: every provider and tab reads the same value, the server reads none.\nconst listeners = new Set<() => void>();\nconst notify = () => listeners.forEach((listener) => listener());\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  window.addEventListener(\"storage\", listener);\n  return () => {\n    listeners.delete(listener);\n    window.removeEventListener(\"storage\", listener);\n  };\n}\n\nfunction applyMode(mode: Mode) {\n  const dark = window.matchMedia(DARK_QUERY).matches;\n  document.documentElement.classList.toggle(\"light\", mode === \"light\" || (mode === \"system\" && !dark));\n}\n\nfunction applyName(previous: string | null, next: string | null) {\n  const classes = document.documentElement.classList;\n  if (previous) classes.remove(`theme-${previous}`);\n  if (next) classes.add(`theme-${next}`);\n}\n\n/**\n * In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n * `nonce` for a strict Content-Security-Policy.\n */\nexport function ThemeScript({\n  nonce,\n}: {\n  /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */\n  nonce?: string;\n}) {\n  const js =\n    `(function(){try{var m=localStorage.getItem(\"${MODE_KEY}\")||\"system\";var n=localStorage.getItem(\"${NAME_KEY}\");` +\n    `var d=matchMedia(\"${DARK_QUERY}\").matches;var c=document.documentElement.classList;` +\n    `c.toggle(\"light\",m===\"light\"||(m===\"system\"&&!d));if(n)c.add(\"theme-\"+n)}catch(e){}})()`;\n  return <script nonce={nonce} dangerouslySetInnerHTML={{ __html: js }} />;\n}\n\nexport type ThemeContextValue = {\n  /** The chosen mode: dark, light or follow the system. */\n  mode: Mode;\n  setMode: (mode: Mode) => void;\n  /** The named theme (`html.theme-<name>`), or null. */\n  theme: string | null;\n  setTheme: (theme: string | null) => void;\n};\n\nconst ThemeContext = React.createContext<ThemeContextValue | null>(null);\n\nexport type ThemeProviderProps = {\n  children: React.ReactNode;\n  /** The mode before anything is persisted. */\n  defaultMode?: Mode;\n};\n\nexport function ThemeProvider({ children, defaultMode = \"system\" }: ThemeProviderProps) {\n  // Before hydration the server knows nothing persisted (ThemeScript has already applied it to <html>).\n  const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);\n  const mode: Mode = isMode(stored) ? stored : defaultMode;\n  const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);\n\n  // \"system\" follows the operating system while the page is open.\n  React.useEffect(() => {\n    if (mode !== \"system\") return;\n    const query = window.matchMedia(DARK_QUERY);\n    const onChange = () => applyMode(\"system\");\n    query.addEventListener?.(\"change\", onChange);\n    return () => query.removeEventListener?.(\"change\", onChange);\n  }, [mode]);\n\n  const setMode = React.useCallback((next: Mode) => {\n    write(MODE_KEY, next);\n    applyMode(next);\n    notify();\n  }, []);\n\n  const setTheme = React.useCallback((next: string | null) => {\n    applyName(read(NAME_KEY), next);\n    write(NAME_KEY, next);\n    notify();\n  }, []);\n\n  const value = React.useMemo(() => ({ mode, setMode, theme, setTheme }), [mode, setMode, theme, setTheme]);\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n\nexport function useTheme(): ThemeContextValue {\n  const context = React.useContext(ThemeContext);\n  if (!context) throw new Error(\"useTheme: wrap the app in <ThemeProvider>\");\n  return context;\n}\n\nconst ICONS: Record<Mode, React.ReactNode> = {\n  dark: <path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" />,\n  light: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"4\" />\n      <path d=\"M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4\" />\n    </>\n  ),\n  system: (\n    <>\n      <rect x=\"3\" y=\"4\" width=\"18\" height=\"12\" rx=\"2\" />\n      <path d=\"M8 20h8M12 16v4\" />\n    </>\n  ),\n};\n\nexport type ThemeToggleProps = Omit<React.ComponentProps<\"button\">, \"onClick\" | \"children\"> &\n  Pick<ButtonVariants, \"variant\" | \"shape\"> & {\n    /** Any `Button` variant. */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`). */\n    label: string | ((mode: Mode) => string);\n  };\n\n/**\n * An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n * <ThemeProvider> above it. State: `data-mode`.\n */\nexport function ThemeToggle({ label, variant = \"ghost\", shape, className, ...props }: ThemeToggleProps) {\n  const { mode, setMode } = useTheme();\n  const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;\n  const name = typeof label === \"function\" ? label(mode) : label;\n  return (\n    <button\n      type=\"button\"\n      aria-label={name}\n      title={name}\n      data-mode={mode}\n      onClick={() => setMode(next)}\n      className={buttonVariants({ variant, shape, size: \"icon\", className })}\n      {...props}\n    >\n      <svg viewBox=\"0 0 24 24\" className=\"h-5 w-5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden>\n        {ICONS[mode]}\n      </svg>\n    </button>\n  );\n}\n"],"mappings":";;;;;;AAEA,YAAY,WAAW;AAwEd,SA4DL,UA5DK,KA4DL,YA5DK;AAlET,IAAM,WAAW;AACjB,IAAM,WAAW;AACjB,IAAM,QAAyB,CAAC,QAAQ,SAAS,QAAQ;AACzD,IAAM,aAAa;AAEnB,IAAM,SAAS,CAAC,UAAkC,MAAM,SAAS,KAAa;AAG9E,IAAM,SAAS,oBAAI,IAAoB;AAEvC,SAAS,KAAK,KAA4B;AACxC,MAAI;AACF,WAAO,aAAa,QAAQ,GAAG;AAAA,EACjC,QAAQ;AACN,WAAO,OAAO,IAAI,GAAG,KAAK;AAAA,EAC5B;AACF;AAEA,SAAS,MAAM,KAAa,OAAsB;AAChD,MAAI,UAAU,KAAM,QAAO,OAAO,GAAG;AAAA,MAChC,QAAO,IAAI,KAAK,KAAK;AAC1B,MAAI;AACF,QAAI,UAAU,KAAM,cAAa,WAAW,GAAG;AAAA,QAC1C,cAAa,QAAQ,KAAK,KAAK;AAAA,EACtC,QAAQ;AAAA,EAER;AACF;AAGA,IAAM,YAAY,oBAAI,IAAgB;AACtC,IAAM,SAAS,MAAM,UAAU,QAAQ,CAAC,aAAa,SAAS,CAAC;AAC/D,SAAS,UAAU,UAAsB;AACvC,YAAU,IAAI,QAAQ;AACtB,SAAO,iBAAiB,WAAW,QAAQ;AAC3C,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AACzB,WAAO,oBAAoB,WAAW,QAAQ;AAAA,EAChD;AACF;AAEA,SAAS,UAAU,MAAY;AAC7B,QAAM,OAAO,OAAO,WAAW,UAAU,EAAE;AAC3C,WAAS,gBAAgB,UAAU,OAAO,SAAS,SAAS,WAAY,SAAS,YAAY,CAAC,IAAK;AACrG;AAEA,SAAS,UAAU,UAAyB,MAAqB;AAC/D,QAAM,UAAU,SAAS,gBAAgB;AACzC,MAAI,SAAU,SAAQ,OAAO,SAAS,QAAQ,EAAE;AAChD,MAAI,KAAM,SAAQ,IAAI,SAAS,IAAI,EAAE;AACvC;AAMO,SAAS,YAAY;AAAA,EAC1B;AACF,GAGG;AACD,QAAM,KACJ,+CAA+C,QAAQ,4CAA4C,QAAQ,wBACtF,UAAU;AAEjC,SAAO,oBAAC,YAAO,OAAc,yBAAyB,EAAE,QAAQ,GAAG,GAAG;AACxE;AAWA,IAAM,eAAqB,oBAAwC,IAAI;AAQhE,SAAS,cAAc,EAAE,UAAU,cAAc,SAAS,GAAuB;AAEtF,QAAM,SAAe,2BAAqB,WAAW,MAAM,KAAK,QAAQ,GAAG,MAAM,IAAI;AACrF,QAAM,OAAa,OAAO,MAAM,IAAI,SAAS;AAC7C,QAAM,QAAc,2BAAqB,WAAW,MAAM,KAAK,QAAQ,GAAG,MAAM,IAAI;AAGpF,EAAM,gBAAU,MAAM;AACpB,QAAI,SAAS,SAAU;AACvB,UAAM,QAAQ,OAAO,WAAW,UAAU;AAC1C,UAAM,WAAW,MAAM,UAAU,QAAQ;AACzC,UAAM,mBAAmB,UAAU,QAAQ;AAC3C,WAAO,MAAM,MAAM,sBAAsB,UAAU,QAAQ;AAAA,EAC7D,GAAG,CAAC,IAAI,CAAC;AAET,QAAM,UAAgB,kBAAY,CAAC,SAAe;AAChD,UAAM,UAAU,IAAI;AACpB,cAAU,IAAI;AACd,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEL,QAAM,WAAiB,kBAAY,CAAC,SAAwB;AAC1D,cAAU,KAAK,QAAQ,GAAG,IAAI;AAC9B,UAAM,UAAU,IAAI;AACpB,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEL,QAAM,QAAc,cAAQ,OAAO,EAAE,MAAM,SAAS,OAAO,SAAS,IAAI,CAAC,MAAM,SAAS,OAAO,QAAQ,CAAC;AACxG,SAAO,oBAAC,aAAa,UAAb,EAAsB,OAAe,UAAS;AACxD;AAEO,SAAS,WAA8B;AAC5C,QAAM,UAAgB,iBAAW,YAAY;AAC7C,MAAI,CAAC,QAAS,OAAM,IAAI,MAAM,2CAA2C;AACzE,SAAO;AACT;AAEA,IAAM,QAAuC;AAAA,EAC3C,MAAM,oBAAC,UAAK,GAAE,iDAAgD;AAAA,EAC9D,OACE,iCACE;AAAA,wBAAC,YAAO,IAAG,MAAK,IAAG,MAAK,GAAE,KAAI;AAAA,IAC9B,oBAAC,UAAK,GAAE,sGAAqG;AAAA,KAC/G;AAAA,EAEF,QACE,iCACE;AAAA,wBAAC,UAAK,GAAE,KAAI,GAAE,KAAI,OAAM,MAAK,QAAO,MAAK,IAAG,KAAI;AAAA,IAChD,oBAAC,UAAK,GAAE,mBAAkB;AAAA,KAC5B;AAEJ;AAmBO,SAAS,YAAY,EAAE,OAAO,UAAU,SAAS,OAAO,WAAW,GAAG,MAAM,GAAqB;AACtG,QAAM,EAAE,MAAM,QAAQ,IAAI,SAAS;AACnC,QAAM,OAAO,OAAO,MAAM,QAAQ,IAAI,IAAI,KAAK,MAAM,MAAM;AAC3D,QAAM,OAAO,OAAO,UAAU,aAAa,MAAM,IAAI,IAAI;AACzD,SACE;AAAA,IAAC;AAAA;AAAA,MACC,MAAK;AAAA,MACL,cAAY;AAAA,MACZ,OAAO;AAAA,MACP,aAAW;AAAA,MACX,SAAS,MAAM,QAAQ,IAAI;AAAA,MAC3B,WAAW,eAAe,EAAE,SAAS,OAAO,MAAM,QAAQ,UAAU,CAAC;AAAA,MACpE,GAAG;AAAA,MAEJ,8BAAC,SAAI,SAAQ,aAAY,WAAU,WAAU,MAAK,QAAO,QAAO,gBAAe,aAAY,KAAI,eAAc,SAAQ,gBAAe,SAAQ,eAAW,MACpJ,gBAAM,IAAI,GACb;AAAA;AAAA,EACF;AAEJ;","names":[]}
+{"version":3,"sources":["../src/theme/theme.tsx"],"sourcesContent":["// Client. ONE mechanism for the whole organisation: dark by default, `html.light` for light, `html.theme-<name>` for a\n// named theme, persisted in localStorage (`kz-theme` for the mode, `kz-theme-name` for the named theme).\nimport * as React from \"react\";\n\nimport { type ButtonVariants, buttonVariants } from \"../button/button\";\n\nexport type Mode = \"dark\" | \"light\" | \"system\";\n\nconst MODE_KEY = \"kz-theme\";\nconst NAME_KEY = \"kz-theme-name\";\nconst MODES: readonly Mode[] = [\"dark\", \"light\", \"system\"];\nconst DARK_QUERY = \"(prefers-color-scheme: dark)\";\n\nconst isMode = (value: unknown): value is Mode => MODES.includes(value as Mode);\n\n// Storage blocked (private mode, sandbox): the choice lives in memory for the page.\nconst memory = new Map<string, string>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    return memory.get(key) ?? null;\n  }\n}\n\nfunction write(key: string, value: string | null) {\n  if (value === null) memory.delete(key);\n  else memory.set(key, value);\n  try {\n    if (value === null) localStorage.removeItem(key);\n    else localStorage.setItem(key, value);\n  } catch {\n    // storage blocked: memory holds it\n  }\n}\n\n// The persisted choice is an external store: every provider and tab reads the same value, the server reads none.\nconst listeners = new Set<() => void>();\nconst notify = () => listeners.forEach((listener) => listener());\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  window.addEventListener(\"storage\", listener);\n  return () => {\n    listeners.delete(listener);\n    window.removeEventListener(\"storage\", listener);\n  };\n}\n\nfunction applyMode(mode: Mode) {\n  const dark = window.matchMedia(DARK_QUERY).matches;\n  document.documentElement.classList.toggle(\"light\", mode === \"light\" || (mode === \"system\" && !dark));\n}\n\nfunction applyName(previous: string | null, next: string | null) {\n  const classes = document.documentElement.classList;\n  if (previous) classes.remove(`theme-${previous}`);\n  if (next) classes.add(`theme-${next}`);\n}\n\nexport type ThemeScriptProps = {\n  /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */\n  nonce?: string;\n  /**\n   * The mode before the visitor chooses one — pass the same value as `ThemeProvider`'s `defaultMode`. A persisted\n   * choice (`kz-theme`) always wins.\n   * @default \"system\"\n   */\n  defaultMode?: Mode;\n};\n\n/**\n * In <head>, before anything renders: applies the persisted mode (else `defaultMode`) and named theme, so the page\n * never flashes. `nonce` for a strict Content-Security-Policy.\n */\nexport function ThemeScript({ nonce, defaultMode = \"system\" }: ThemeScriptProps) {\n  const fallback = isMode(defaultMode) ? defaultMode : \"system\";\n  const js =\n    `(function(){try{var m=localStorage.getItem(\"${MODE_KEY}\");if(m!==\"dark\"&&m!==\"light\"&&m!==\"system\")m=\"${fallback}\";` +\n    `var n=localStorage.getItem(\"${NAME_KEY}\");var d=matchMedia(\"${DARK_QUERY}\").matches;var c=document.documentElement.classList;` +\n    `c.toggle(\"light\",m===\"light\"||(m===\"system\"&&!d));if(n)c.add(\"theme-\"+n)}catch(e){}})()`;\n  return <script nonce={nonce} dangerouslySetInnerHTML={{ __html: js }} />;\n}\n\nexport type ThemeContextValue = {\n  /** The chosen mode: dark, light or follow the system. */\n  mode: Mode;\n  setMode: (mode: Mode) => void;\n  /** The named theme (`html.theme-<name>`), or null. */\n  theme: string | null;\n  setTheme: (theme: string | null) => void;\n};\n\nconst ThemeContext = React.createContext<ThemeContextValue | null>(null);\n\nexport type ThemeProviderProps = {\n  children: React.ReactNode;\n  /**\n   * The mode before the visitor chooses one (nothing persisted as `kz-theme`) — pass the same value to `ThemeScript`.\n   * @default \"system\"\n   */\n  defaultMode?: Mode;\n};\n\nexport function ThemeProvider({ children, defaultMode = \"system\" }: ThemeProviderProps) {\n  // Before hydration the server knows nothing persisted (ThemeScript has already applied it to <html>).\n  const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);\n  const mode: Mode = isMode(stored) ? stored : defaultMode;\n  const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);\n\n  // The same resolution as ThemeScript (a no-op after it), for an app that renders the provider without the script.\n  React.useEffect(() => {\n    const persisted = read(MODE_KEY);\n    applyMode(isMode(persisted) ? persisted : defaultMode);\n  }, [defaultMode]);\n\n  // \"system\" follows the operating system while the page is open.\n  React.useEffect(() => {\n    if (mode !== \"system\") return;\n    const query = window.matchMedia(DARK_QUERY);\n    const onChange = () => applyMode(\"system\");\n    query.addEventListener?.(\"change\", onChange);\n    return () => query.removeEventListener?.(\"change\", onChange);\n  }, [mode]);\n\n  const setMode = React.useCallback((next: Mode) => {\n    write(MODE_KEY, next);\n    applyMode(next);\n    notify();\n  }, []);\n\n  const setTheme = React.useCallback((next: string | null) => {\n    applyName(read(NAME_KEY), next);\n    write(NAME_KEY, next);\n    notify();\n  }, []);\n\n  const value = React.useMemo(() => ({ mode, setMode, theme, setTheme }), [mode, setMode, theme, setTheme]);\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n\nexport function useTheme(): ThemeContextValue {\n  const context = React.useContext(ThemeContext);\n  if (!context) throw new Error(\"useTheme: wrap the app in <ThemeProvider>\");\n  return context;\n}\n\nconst ICONS: Record<Mode, React.ReactNode> = {\n  dark: <path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" />,\n  light: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"4\" />\n      <path d=\"M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4\" />\n    </>\n  ),\n  system: (\n    <>\n      <rect x=\"3\" y=\"4\" width=\"18\" height=\"12\" rx=\"2\" />\n      <path d=\"M8 20h8M12 16v4\" />\n    </>\n  ),\n};\n\nexport type ThemeToggleProps = Omit<React.ComponentProps<\"button\">, \"onClick\" | \"children\"> &\n  Pick<ButtonVariants, \"variant\" | \"shape\"> & {\n    /** Any `Button` variant. */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`). */\n    label: string | ((mode: Mode) => string);\n  };\n\n/**\n * An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n * <ThemeProvider> above it. State: `data-mode`.\n */\nexport function ThemeToggle({ label, variant = \"ghost\", shape, className, ...props }: ThemeToggleProps) {\n  const { mode, setMode } = useTheme();\n  const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;\n  const name = typeof label === \"function\" ? label(mode) : label;\n  return (\n    <button\n      type=\"button\"\n      aria-label={name}\n      title={name}\n      data-mode={mode}\n      onClick={() => setMode(next)}\n      className={buttonVariants({ variant, shape, size: \"icon\", className })}\n      {...props}\n    >\n      <svg viewBox=\"0 0 24 24\" className=\"h-5 w-5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden>\n        {ICONS[mode]}\n      </svg>\n    </button>\n  );\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/ui",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "The Krizaka front-end platform's components: the primitives (button, card, dialog, toast, menu, field, tabs, chip, switch, slider, command palette, theme, countdown…) on the semantic --kz-* tokens, the animated marks (Krizaka, Orazaka, Orochia) and the motion signature — web and /native.",
   "keywords": [
     "krizaka",
@@ -194,7 +194,7 @@
     "*.css"
   ],
   "peerDependencies": {
-    "@krizaka/tailwind": ">=2.0.0",
+    "@krizaka/tailwind": ">=2.1.0",
     "react": ">=18",
     "react-dom": ">=18",
     "react-native": ">=0.76",
@@ -238,7 +238,7 @@
     "typescript": "^5.9.0",
     "vitest": "^4.1.11",
     "@krizaka/config": "0.1.0",
-    "@krizaka/tokens": "2.0.0"
+    "@krizaka/tokens": "2.1.0"
   },
   "engines": {
     "node": ">=20"

package/registry/index.json

@@ -1,6 +1,6 @@
 {
   "name": "@krizaka/ui",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "items": [
     {
       "name": "alert",

package/registry/theme.json

@@ -22,6 +22,7 @@
   ],
   "bestPractices": [
     "Put `<ThemeScript />` in `<head>` and `suppressHydrationWarning` on `<html>`: the right theme is applied before the first paint.",
+    "A product that is dark (or light) first passes the same `defaultMode` to `ThemeScript` and `ThemeProvider`; the visitor's choice still wins.",
     "The choice is persisted as `kz-theme` and applied as `html.light`: every Krizaka app reads the same switch.",
     "Check every screen in both themes."
   ],
@@ -53,15 +54,22 @@
             "name": "defaultMode",
             "type": "Mode",
             "default": "system",
-            "description": "The mode before anything is persisted.",
+            "description": "The mode before the visitor chooses one (nothing persisted as `kz-theme`) — pass the same value to `ThemeScript`.",
             "required": false
           }
         ]
       },
       {
         "component": "ThemeScript",
-        "description": "In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n`nonce` for a strict Content-Security-Policy.",
+        "description": "In <head>, before anything renders: applies the persisted mode (else `defaultMode`) and named theme, so the page\nnever flashes. `nonce` for a strict Content-Security-Policy.",
         "props": [
+          {
+            "name": "defaultMode",
+            "type": "Mode",
+            "default": "system",
+            "description": "The mode before the visitor chooses one — pass the same value as `ThemeProvider`'s `defaultMode`. A persisted\nchoice (`kz-theme`) always wins.",
+            "required": false
+          },
           {
             "name": "nonce",
             "type": "string",
@@ -187,15 +195,15 @@
     },
     {
       "path": "theme/index.ts",
-      "content": "/** @krizaka/ui/theme — `ThemeScript`, `ThemeProvider`, `useTheme`, `ThemeToggle`. Client (\"use client\"). */\nexport {\n  type Mode,\n  type ThemeContextValue,\n  ThemeProvider,\n  type ThemeProviderProps,\n  ThemeScript,\n  ThemeToggle,\n  type ThemeToggleProps,\n  useTheme,\n} from \"./theme\";\n"
+      "content": "/** @krizaka/ui/theme — `ThemeScript`, `ThemeProvider`, `useTheme`, `ThemeToggle`. Client (\"use client\"). */\nexport {\n  type Mode,\n  type ThemeContextValue,\n  ThemeProvider,\n  type ThemeProviderProps,\n  ThemeScript,\n  type ThemeScriptProps,\n  ThemeToggle,\n  type ThemeToggleProps,\n  useTheme,\n} from \"./theme\";\n"
     },
     {
       "path": "theme/meta.ts",
-      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Theme\",\n  summary: \"Dark, light or the system's: `ThemeProvider`, `ThemeScript` against the flash, and `ThemeToggle`.\",\n  status: \"stable\",\n  category: \"foundations\",\n  platforms: \"both\",\n  whenToUse: [\n    \"Once per app, in the root layout: `ThemeScript` in `<head>`, `ThemeProvider` around the app.\",\n    \"`ThemeToggle` in the header or the settings, to cycle dark → light → system.\",\n    \"`useTheme()` to read or set the mode from your own control.\",\n  ],\n  whenNotToUse: [\n    { when: \"To theme one area differently: put `.theme-light` or `.theme-dark` on the subtree instead.\" },\n    { when: \"To change a product's colours: override the `--kz-*` tokens in its design system.\" },\n  ],\n  bestPractices: [\n    \"Put `<ThemeScript />` in `<head>` and `suppressHydrationWarning` on `<html>`: the right theme is applied before the first paint.\",\n    \"The choice is persisted as `kz-theme` and applied as `html.light`: every Krizaka app reads the same switch.\",\n    \"Check every screen in both themes.\",\n  ],\n  accessibility: {\n    keyboard: [{ keys: \"Enter / Space\", action: \"The toggle cycles to the next mode.\" }],\n    notes: [\"`ThemeToggle` is a button named by `label` (translated); its icon shows the current mode.\", \"`color-scheme` follows the theme, so native controls and scrollbars match.\"],\n  },\n  related: [\"button\", \"cn\"],\n  web: {\n    imports: [\"ThemeProvider\", \"ThemeScript\", \"ThemeToggle\", \"useTheme\"],\n    examples: [\n      { name: \"toggle\", title: \"Toggle\", description: \"A ghost icon button in its provider.\" },\n      { name: \"secondary\", title: \"Another look\", description: \"Any button variant and shape.\" },\n    ],\n  },\n  native: {\n    imports: [\"ThemeProvider\", \"useTheme\"],\n    differences: [\n      \"`ThemeProvider` takes the product's colour roles (`overrides`) and fonts; there is no `ThemeScript` and no toggle.\",\n      \"`useTheme()` returns the resolved `theme` (colour roles), `scheme`, `radius` and `motion` for `StyleSheet`.\",\n      \"The mode is not persisted: the app stores it from `onModeChange`.\",\n    ],\n    examples: [{ name: \"provider\", title: \"Provider\", description: \"Once at the root; `useTheme()` reads the roles in any component.\" }],\n  },\n} satisfies ComponentMeta;\n"
+      "content": "import type { ComponentMeta } from \"../meta\";\n\nexport const meta = {\n  title: \"Theme\",\n  summary: \"Dark, light or the system's: `ThemeProvider`, `ThemeScript` against the flash, and `ThemeToggle`.\",\n  status: \"stable\",\n  category: \"foundations\",\n  platforms: \"both\",\n  whenToUse: [\n    \"Once per app, in the root layout: `ThemeScript` in `<head>`, `ThemeProvider` around the app.\",\n    \"`ThemeToggle` in the header or the settings, to cycle dark → light → system.\",\n    \"`useTheme()` to read or set the mode from your own control.\",\n  ],\n  whenNotToUse: [\n    { when: \"To theme one area differently: put `.theme-light` or `.theme-dark` on the subtree instead.\" },\n    { when: \"To change a product's colours: override the `--kz-*` tokens in its design system.\" },\n  ],\n  bestPractices: [\n    \"Put `<ThemeScript />` in `<head>` and `suppressHydrationWarning` on `<html>`: the right theme is applied before the first paint.\",\n    \"A product that is dark (or light) first passes the same `defaultMode` to `ThemeScript` and `ThemeProvider`; the visitor's choice still wins.\",\n    \"The choice is persisted as `kz-theme` and applied as `html.light`: every Krizaka app reads the same switch.\",\n    \"Check every screen in both themes.\",\n  ],\n  accessibility: {\n    keyboard: [{ keys: \"Enter / Space\", action: \"The toggle cycles to the next mode.\" }],\n    notes: [\"`ThemeToggle` is a button named by `label` (translated); its icon shows the current mode.\", \"`color-scheme` follows the theme, so native controls and scrollbars match.\"],\n  },\n  related: [\"button\", \"cn\"],\n  web: {\n    imports: [\"ThemeProvider\", \"ThemeScript\", \"ThemeToggle\", \"useTheme\"],\n    examples: [\n      { name: \"toggle\", title: \"Toggle\", description: \"A ghost icon button in its provider.\" },\n      { name: \"secondary\", title: \"Another look\", description: \"Any button variant and shape.\" },\n    ],\n  },\n  native: {\n    imports: [\"ThemeProvider\", \"useTheme\"],\n    differences: [\n      \"`ThemeProvider` takes the product's colour roles (`overrides`) and fonts; there is no `ThemeScript` and no toggle.\",\n      \"`useTheme()` returns the resolved `theme` (colour roles), `scheme`, `radius` and `motion` for `StyleSheet`.\",\n      \"The mode is not persisted: the app stores it from `onModeChange`.\",\n    ],\n    examples: [{ name: \"provider\", title: \"Provider\", description: \"Once at the root; `useTheme()` reads the roles in any component.\" }],\n  },\n} satisfies ComponentMeta;\n"
     },
     {
       "path": "theme/theme.tsx",
-      "content": "// Client. ONE mechanism for the whole organisation: dark by default, `html.light` for light, `html.theme-<name>` for a\n// named theme, persisted in localStorage (`kz-theme` for the mode, `kz-theme-name` for the named theme).\nimport * as React from \"react\";\n\nimport { type ButtonVariants, buttonVariants } from \"../button/button\";\n\nexport type Mode = \"dark\" | \"light\" | \"system\";\n\nconst MODE_KEY = \"kz-theme\";\nconst NAME_KEY = \"kz-theme-name\";\nconst MODES: readonly Mode[] = [\"dark\", \"light\", \"system\"];\nconst DARK_QUERY = \"(prefers-color-scheme: dark)\";\n\nconst isMode = (value: unknown): value is Mode => MODES.includes(value as Mode);\n\n// Storage blocked (private mode, sandbox): the choice lives in memory for the page.\nconst memory = new Map<string, string>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    return memory.get(key) ?? null;\n  }\n}\n\nfunction write(key: string, value: string | null) {\n  if (value === null) memory.delete(key);\n  else memory.set(key, value);\n  try {\n    if (value === null) localStorage.removeItem(key);\n    else localStorage.setItem(key, value);\n  } catch {\n    // storage blocked: memory holds it\n  }\n}\n\n// The persisted choice is an external store: every provider and tab reads the same value, the server reads none.\nconst listeners = new Set<() => void>();\nconst notify = () => listeners.forEach((listener) => listener());\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  window.addEventListener(\"storage\", listener);\n  return () => {\n    listeners.delete(listener);\n    window.removeEventListener(\"storage\", listener);\n  };\n}\n\nfunction applyMode(mode: Mode) {\n  const dark = window.matchMedia(DARK_QUERY).matches;\n  document.documentElement.classList.toggle(\"light\", mode === \"light\" || (mode === \"system\" && !dark));\n}\n\nfunction applyName(previous: string | null, next: string | null) {\n  const classes = document.documentElement.classList;\n  if (previous) classes.remove(`theme-${previous}`);\n  if (next) classes.add(`theme-${next}`);\n}\n\n/**\n * In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n * `nonce` for a strict Content-Security-Policy.\n */\nexport function ThemeScript({\n  nonce,\n}: {\n  /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */\n  nonce?: string;\n}) {\n  const js =\n    `(function(){try{var m=localStorage.getItem(\"${MODE_KEY}\")||\"system\";var n=localStorage.getItem(\"${NAME_KEY}\");` +\n    `var d=matchMedia(\"${DARK_QUERY}\").matches;var c=document.documentElement.classList;` +\n    `c.toggle(\"light\",m===\"light\"||(m===\"system\"&&!d));if(n)c.add(\"theme-\"+n)}catch(e){}})()`;\n  return <script nonce={nonce} dangerouslySetInnerHTML={{ __html: js }} />;\n}\n\nexport type ThemeContextValue = {\n  /** The chosen mode: dark, light or follow the system. */\n  mode: Mode;\n  setMode: (mode: Mode) => void;\n  /** The named theme (`html.theme-<name>`), or null. */\n  theme: string | null;\n  setTheme: (theme: string | null) => void;\n};\n\nconst ThemeContext = React.createContext<ThemeContextValue | null>(null);\n\nexport type ThemeProviderProps = {\n  children: React.ReactNode;\n  /** The mode before anything is persisted. */\n  defaultMode?: Mode;\n};\n\nexport function ThemeProvider({ children, defaultMode = \"system\" }: ThemeProviderProps) {\n  // Before hydration the server knows nothing persisted (ThemeScript has already applied it to <html>).\n  const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);\n  const mode: Mode = isMode(stored) ? stored : defaultMode;\n  const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);\n\n  // \"system\" follows the operating system while the page is open.\n  React.useEffect(() => {\n    if (mode !== \"system\") return;\n    const query = window.matchMedia(DARK_QUERY);\n    const onChange = () => applyMode(\"system\");\n    query.addEventListener?.(\"change\", onChange);\n    return () => query.removeEventListener?.(\"change\", onChange);\n  }, [mode]);\n\n  const setMode = React.useCallback((next: Mode) => {\n    write(MODE_KEY, next);\n    applyMode(next);\n    notify();\n  }, []);\n\n  const setTheme = React.useCallback((next: string | null) => {\n    applyName(read(NAME_KEY), next);\n    write(NAME_KEY, next);\n    notify();\n  }, []);\n\n  const value = React.useMemo(() => ({ mode, setMode, theme, setTheme }), [mode, setMode, theme, setTheme]);\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n\nexport function useTheme(): ThemeContextValue {\n  const context = React.useContext(ThemeContext);\n  if (!context) throw new Error(\"useTheme: wrap the app in <ThemeProvider>\");\n  return context;\n}\n\nconst ICONS: Record<Mode, React.ReactNode> = {\n  dark: <path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" />,\n  light: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"4\" />\n      <path d=\"M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4\" />\n    </>\n  ),\n  system: (\n    <>\n      <rect x=\"3\" y=\"4\" width=\"18\" height=\"12\" rx=\"2\" />\n      <path d=\"M8 20h8M12 16v4\" />\n    </>\n  ),\n};\n\nexport type ThemeToggleProps = Omit<React.ComponentProps<\"button\">, \"onClick\" | \"children\"> &\n  Pick<ButtonVariants, \"variant\" | \"shape\"> & {\n    /** Any `Button` variant. */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`). */\n    label: string | ((mode: Mode) => string);\n  };\n\n/**\n * An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n * <ThemeProvider> above it. State: `data-mode`.\n */\nexport function ThemeToggle({ label, variant = \"ghost\", shape, className, ...props }: ThemeToggleProps) {\n  const { mode, setMode } = useTheme();\n  const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;\n  const name = typeof label === \"function\" ? label(mode) : label;\n  return (\n    <button\n      type=\"button\"\n      aria-label={name}\n      title={name}\n      data-mode={mode}\n      onClick={() => setMode(next)}\n      className={buttonVariants({ variant, shape, size: \"icon\", className })}\n      {...props}\n    >\n      <svg viewBox=\"0 0 24 24\" className=\"h-5 w-5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden>\n        {ICONS[mode]}\n      </svg>\n    </button>\n  );\n}\n"
+      "content": "// Client. ONE mechanism for the whole organisation: dark by default, `html.light` for light, `html.theme-<name>` for a\n// named theme, persisted in localStorage (`kz-theme` for the mode, `kz-theme-name` for the named theme).\nimport * as React from \"react\";\n\nimport { type ButtonVariants, buttonVariants } from \"../button/button\";\n\nexport type Mode = \"dark\" | \"light\" | \"system\";\n\nconst MODE_KEY = \"kz-theme\";\nconst NAME_KEY = \"kz-theme-name\";\nconst MODES: readonly Mode[] = [\"dark\", \"light\", \"system\"];\nconst DARK_QUERY = \"(prefers-color-scheme: dark)\";\n\nconst isMode = (value: unknown): value is Mode => MODES.includes(value as Mode);\n\n// Storage blocked (private mode, sandbox): the choice lives in memory for the page.\nconst memory = new Map<string, string>();\n\nfunction read(key: string): string | null {\n  try {\n    return localStorage.getItem(key);\n  } catch {\n    return memory.get(key) ?? null;\n  }\n}\n\nfunction write(key: string, value: string | null) {\n  if (value === null) memory.delete(key);\n  else memory.set(key, value);\n  try {\n    if (value === null) localStorage.removeItem(key);\n    else localStorage.setItem(key, value);\n  } catch {\n    // storage blocked: memory holds it\n  }\n}\n\n// The persisted choice is an external store: every provider and tab reads the same value, the server reads none.\nconst listeners = new Set<() => void>();\nconst notify = () => listeners.forEach((listener) => listener());\nfunction subscribe(listener: () => void) {\n  listeners.add(listener);\n  window.addEventListener(\"storage\", listener);\n  return () => {\n    listeners.delete(listener);\n    window.removeEventListener(\"storage\", listener);\n  };\n}\n\nfunction applyMode(mode: Mode) {\n  const dark = window.matchMedia(DARK_QUERY).matches;\n  document.documentElement.classList.toggle(\"light\", mode === \"light\" || (mode === \"system\" && !dark));\n}\n\nfunction applyName(previous: string | null, next: string | null) {\n  const classes = document.documentElement.classList;\n  if (previous) classes.remove(`theme-${previous}`);\n  if (next) classes.add(`theme-${next}`);\n}\n\nexport type ThemeScriptProps = {\n  /** The nonce of a strict Content-Security-Policy (`script-src 'nonce-…'`). */\n  nonce?: string;\n  /**\n   * The mode before the visitor chooses one — pass the same value as `ThemeProvider`'s `defaultMode`. A persisted\n   * choice (`kz-theme`) always wins.\n   * @default \"system\"\n   */\n  defaultMode?: Mode;\n};\n\n/**\n * In <head>, before anything renders: applies the persisted mode (else `defaultMode`) and named theme, so the page\n * never flashes. `nonce` for a strict Content-Security-Policy.\n */\nexport function ThemeScript({ nonce, defaultMode = \"system\" }: ThemeScriptProps) {\n  const fallback = isMode(defaultMode) ? defaultMode : \"system\";\n  const js =\n    `(function(){try{var m=localStorage.getItem(\"${MODE_KEY}\");if(m!==\"dark\"&&m!==\"light\"&&m!==\"system\")m=\"${fallback}\";` +\n    `var n=localStorage.getItem(\"${NAME_KEY}\");var d=matchMedia(\"${DARK_QUERY}\").matches;var c=document.documentElement.classList;` +\n    `c.toggle(\"light\",m===\"light\"||(m===\"system\"&&!d));if(n)c.add(\"theme-\"+n)}catch(e){}})()`;\n  return <script nonce={nonce} dangerouslySetInnerHTML={{ __html: js }} />;\n}\n\nexport type ThemeContextValue = {\n  /** The chosen mode: dark, light or follow the system. */\n  mode: Mode;\n  setMode: (mode: Mode) => void;\n  /** The named theme (`html.theme-<name>`), or null. */\n  theme: string | null;\n  setTheme: (theme: string | null) => void;\n};\n\nconst ThemeContext = React.createContext<ThemeContextValue | null>(null);\n\nexport type ThemeProviderProps = {\n  children: React.ReactNode;\n  /**\n   * The mode before the visitor chooses one (nothing persisted as `kz-theme`) — pass the same value to `ThemeScript`.\n   * @default \"system\"\n   */\n  defaultMode?: Mode;\n};\n\nexport function ThemeProvider({ children, defaultMode = \"system\" }: ThemeProviderProps) {\n  // Before hydration the server knows nothing persisted (ThemeScript has already applied it to <html>).\n  const stored = React.useSyncExternalStore(subscribe, () => read(MODE_KEY), () => null);\n  const mode: Mode = isMode(stored) ? stored : defaultMode;\n  const theme = React.useSyncExternalStore(subscribe, () => read(NAME_KEY), () => null);\n\n  // The same resolution as ThemeScript (a no-op after it), for an app that renders the provider without the script.\n  React.useEffect(() => {\n    const persisted = read(MODE_KEY);\n    applyMode(isMode(persisted) ? persisted : defaultMode);\n  }, [defaultMode]);\n\n  // \"system\" follows the operating system while the page is open.\n  React.useEffect(() => {\n    if (mode !== \"system\") return;\n    const query = window.matchMedia(DARK_QUERY);\n    const onChange = () => applyMode(\"system\");\n    query.addEventListener?.(\"change\", onChange);\n    return () => query.removeEventListener?.(\"change\", onChange);\n  }, [mode]);\n\n  const setMode = React.useCallback((next: Mode) => {\n    write(MODE_KEY, next);\n    applyMode(next);\n    notify();\n  }, []);\n\n  const setTheme = React.useCallback((next: string | null) => {\n    applyName(read(NAME_KEY), next);\n    write(NAME_KEY, next);\n    notify();\n  }, []);\n\n  const value = React.useMemo(() => ({ mode, setMode, theme, setTheme }), [mode, setMode, theme, setTheme]);\n  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;\n}\n\nexport function useTheme(): ThemeContextValue {\n  const context = React.useContext(ThemeContext);\n  if (!context) throw new Error(\"useTheme: wrap the app in <ThemeProvider>\");\n  return context;\n}\n\nconst ICONS: Record<Mode, React.ReactNode> = {\n  dark: <path d=\"M20 14.5A8 8 0 0 1 9.5 4a8 8 0 1 0 10.5 10.5Z\" />,\n  light: (\n    <>\n      <circle cx=\"12\" cy=\"12\" r=\"4\" />\n      <path d=\"M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4\" />\n    </>\n  ),\n  system: (\n    <>\n      <rect x=\"3\" y=\"4\" width=\"18\" height=\"12\" rx=\"2\" />\n      <path d=\"M8 20h8M12 16v4\" />\n    </>\n  ),\n};\n\nexport type ThemeToggleProps = Omit<React.ComponentProps<\"button\">, \"onClick\" | \"children\"> &\n  Pick<ButtonVariants, \"variant\" | \"shape\"> & {\n    /** Any `Button` variant. */\n    variant?: ButtonVariants[\"variant\"];\n    /**\n     * rounded · pill.\n     * @default \"rounded\"\n     */\n    shape?: ButtonVariants[\"shape\"];\n    /** The accessible name — a string, or one per current mode (e.g. `(mode) => t(\"theme.\" + mode)`). */\n    label: string | ((mode: Mode) => string);\n  };\n\n/**\n * An icon button (styled as `IconButton`, without its Slot) that cycles dark → light → system. Needs a\n * <ThemeProvider> above it. State: `data-mode`.\n */\nexport function ThemeToggle({ label, variant = \"ghost\", shape, className, ...props }: ThemeToggleProps) {\n  const { mode, setMode } = useTheme();\n  const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length] as Mode;\n  const name = typeof label === \"function\" ? label(mode) : label;\n  return (\n    <button\n      type=\"button\"\n      aria-label={name}\n      title={name}\n      data-mode={mode}\n      onClick={() => setMode(next)}\n      className={buttonVariants({ variant, shape, size: \"icon\", className })}\n      {...props}\n    >\n      <svg viewBox=\"0 0 24 24\" className=\"h-5 w-5\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"2\" strokeLinecap=\"round\" strokeLinejoin=\"round\" aria-hidden>\n        {ICONS[mode]}\n      </svg>\n    </button>\n  );\n}\n"
     }
   ],
   "dependencies": [],
@@ -215,15 +223,22 @@
           "name": "defaultMode",
           "type": "Mode",
           "default": "system",
-          "description": "The mode before anything is persisted.",
+          "description": "The mode before the visitor chooses one (nothing persisted as `kz-theme`) — pass the same value to `ThemeScript`.",
           "required": false
         }
       ]
     },
     {
       "component": "ThemeScript",
-      "description": "In <head>, before anything renders: applies the persisted mode and named theme, so the page never flashes.\n`nonce` for a strict Content-Security-Policy.",
+      "description": "In <head>, before anything renders: applies the persisted mode (else `defaultMode`) and named theme, so the page\nnever flashes. `nonce` for a strict Content-Security-Policy.",
       "props": [
+        {
+          "name": "defaultMode",
+          "type": "Mode",
+          "default": "system",
+          "description": "The mode before the visitor chooses one — pass the same value as `ThemeProvider`'s `defaultMode`. A persisted\nchoice (`kz-theme`) always wins.",
+          "required": false
+        },
         {
           "name": "nonce",
           "type": "string",