@nanisoft/prism-ui 0.5.1 → 0.7.0

package/dist/provider/provider.js

@@ -9,67 +9,158 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * the same two markup attributes the declarative form uses. There is no
  * override, merge, token, className or style prop: the provider's only outputs
  * are the document-element attributes and context (ticket 07).
+ *
+ * It resolves through `resolveTheme`, the one rule the boot script also
+ * implements, and it never writes `THEME_ORIGIN_ATTRIBUTE`: the script is that
+ * attribute's only writer, and two writers would turn a record of the origin
+ * into a race.
  */
-import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
-import { DEFAULT_STORAGE_KEY, MODES, PACKS, parseStoredTheme, themeAttributes, } from '../theming';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+import { DEFAULT_STORAGE_KEY, PACK_ATTRIBUTE, readLegacyMode, resolveTheme, themeAttributes, } from '../theming';
 const PrismThemeContext = createContext(null);
 function applyDocumentAttributes(pack, mode) {
     const root = document.documentElement;
     const { 'data-pack': packAttribute, className } = themeAttributes({ pack, mode });
     if (packAttribute)
-        root.setAttribute('data-pack', packAttribute);
+        root.setAttribute(PACK_ATTRIBUTE, packAttribute);
     else
-        root.removeAttribute('data-pack');
+        root.removeAttribute(PACK_ATTRIBUTE);
     if (className)
         root.classList.add('dark');
     else
         root.classList.remove('dark');
 }
-function packFromDocument(fallback) {
-    const attribute = document.documentElement.getAttribute('data-pack');
-    return attribute && PACKS.includes(attribute)
-        ? attribute
-        : fallback;
+/** One guarded read. A blocked or full store must not break the page. */
+function read(key) {
+    try {
+        return localStorage.getItem(key);
+    }
+    catch {
+        return null;
+    }
+}
+/** One guarded write. The attributes are already applied when this fails. */
+function persist(key, pack, mode) {
+    try {
+        localStorage.setItem(key, JSON.stringify({ pack, mode }));
+    }
+    catch {
+        // A blocked or full localStorage must not break theme switching. The
+        // attributes are already applied, so the visible behaviour is unchanged.
+    }
 }
-function modeFromDocument(fallback) {
-    return document.documentElement.classList.contains('dark') ? 'dark' : fallback;
+function retire(key) {
+    try {
+        localStorage.removeItem(key);
+    }
+    catch {
+        // Nothing to do: a key that cannot be removed is read again next load,
+        // recovers the same decision, and writes the same pair.
+    }
 }
 export function PrismProvider({ defaultPack = 'default', defaultMode = 'light', storageKey = DEFAULT_STORAGE_KEY, children, }) {
-    const [pack, setPackState] = useState(defaultPack);
-    const [mode, setModeState] = useState(defaultMode);
-    const [resolved, setResolved] = useState(false);
     /*
-     * Resolution order on mount: stored value, then the server-rendered attribute,
-     * then the default. A server-rendered pack therefore survives hydration
-     * instead of flashing to the default.
+     * The resolution, and whether a decision has been made. Two pieces of state
+     * for two different questions, which is why the old `resolved` flag was not
+     * enough on its own:
+     *
+     *   - `theme` is null until the store has been read. It gates APPLY, because
+     *     applying the default over a server-rendered pack before resolution is
+     *     the flash the resolution order exists to prevent. It carries the
+     *     origin, so the recovery below can read it without a second lookup.
+     *   - `decided` is a ref, not state, because it must be readable by the write
+     *     effect without causing a render, and settable synchronously by a caller
+     *     whose state update has not been committed yet. It gates WRITE.
+     *
+     * A ref also cannot be re-rendered into an extra effect pass, which is what
+     * would have made the write fire once for the flag and once for the value.
+     */
+    const [theme, setTheme] = useState(null);
+    const decided = useRef(false);
+    /*
+     * Resolution on mount, through the one shared rule: the stored value, then a
+     * key this line no longer writes, then what the server rendered, then the
+     * defaults. A server-rendered pack therefore survives hydration.
      */
     useEffect(() => {
-        const stored = parseStoredTheme(localStorage.getItem(storageKey));
-        const next = stored ?? { pack: packFromDocument(defaultPack), mode: modeFromDocument(defaultMode) };
-        setPackState(next.pack);
-        setModeState(next.mode);
-        setResolved(true);
+        const recovered = readLegacyMode(read);
+        const next = resolveTheme({
+            stored: read(storageKey),
+            legacy: recovered?.mode ?? null,
+            documentPack: document.documentElement.getAttribute(PACK_ATTRIBUTE),
+            documentDark: document.documentElement.classList.contains('dark'),
+            defaultPack,
+            defaultMode,
+        });
+        if (next.origin === 'legacy' && recovered) {
+            /*
+             * The recovery write. A decision taken from a key this line no longer
+             * writes is put in the key it does write, and the old key is retired in
+             * the same breath, which is what makes the clause self-disabling: the
+             * next load finds nothing to recover, so a reader is migrated once and
+             * the population the clause can still reach only ever shrinks.
+             */
+            persist(storageKey, next.pack, next.mode);
+            retire(recovered.key);
+        }
+        // A caller that decided in a layout effect before this ran keeps its value.
+        if (!decided.current)
+            setTheme(next);
     }, [storageKey, defaultPack, defaultMode]);
     /*
-     * Persist and apply only after resolution, so the first client commit never
-     * writes the defaults over a stored or server-rendered choice.
+     * Apply always, once there is a resolution; persist only on a decision.
+     *
+     * The first resolution from the document or the defaults writes nothing, so a
+     * visitor who never touched the toggle ends the load with an empty store and
+     * a site that changes its default reaches everyone who has not chosen.
      */
     useEffect(() => {
-        if (!resolved)
+        if (!theme)
             return;
-        applyDocumentAttributes(pack, mode);
-        try {
-            localStorage.setItem(storageKey, JSON.stringify({ pack, mode }));
-        }
-        catch {
-            // A blocked or full localStorage must not break theme switching. The
-            // attributes are already applied, so the visible behaviour is unchanged.
-        }
-    }, [resolved, pack, mode, storageKey]);
-    const setPack = useCallback((next) => setPackState(next), []);
-    const setMode = useCallback((next) => setModeState(next), []);
-    const toggleMode = useCallback(() => setModeState((current) => (current === 'dark' ? MODES[0] : MODES[1])), []);
-    const value = useMemo(() => ({ pack, mode, setPack, setMode, toggleMode }), [pack, mode, setPack, setMode, toggleMode]);
+        applyDocumentAttributes(theme.pack, theme.mode);
+        if (decided.current)
+            persist(storageKey, theme.pack, theme.mode);
+    }, [theme, storageKey]);
+    const setPack = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: next,
+            mode: current?.mode ?? defaultMode,
+            origin: 'stored',
+        }));
+    }, [defaultMode]);
+    const setMode = useCallback((next) => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: next,
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    /*
+     * The pair is a closed union of two members, so the other one is the other
+     * member. Spelling it out costs nothing and does not hide the coupling behind
+     * an index into a list this file does not otherwise need.
+     *
+     * The three setters all fall back to the consumer's own default rather than
+     * to the neutral one, so a decision taken before the store has been read
+     * pairs the chosen axis with the site's default and not with a guess.
+     */
+    const toggleMode = useCallback(() => {
+        decided.current = true;
+        setTheme((current) => ({
+            pack: current?.pack ?? defaultPack,
+            mode: current?.mode === 'dark' ? 'light' : 'dark',
+            origin: 'stored',
+        }));
+    }, [defaultPack]);
+    const value = useMemo(() => ({
+        pack: theme?.pack ?? defaultPack,
+        mode: theme?.mode ?? defaultMode,
+        setPack,
+        setMode,
+        toggleMode,
+    }), [theme, defaultPack, defaultMode, setPack, setMode, toggleMode]);
     return _jsx(PrismThemeContext.Provider, { value: value, children: children });
 }
 /**

package/dist/provider/theme-script.d.ts

@@ -3,11 +3,49 @@
  *
  * A Server Component that renders one blocking script. Placed in `<head>`, it
  * applies the stored pack and mode before React hydrates, so the first paint is
- * already correct. Precedence matches `PrismProvider`: stored value, then the
- * server-rendered attribute, then the defaults. It is safe to omit; a consumer
- * who renders the attributes on `<html>` needs no client runtime at all.
+ * already correct. It is safe to omit; a consumer who renders the attributes on
+ * `<html>` needs no client runtime at all.
+ *
+ * It is the only writer of `THEME_ORIGIN_ATTRIBUTE`, and it writes that
+ * attribute on every path it reaches, so the origin of the active theme is
+ * always readable and never merely absent.
+ *
+ * The string below is a second implementation of `resolveTheme`, not a copy of
+ * it that has been kept in step. A function cannot be shared with a string that
+ * a minifier rewrites: a renamed identifier inside the script's own `try` throws
+ * there, the catch swallows it, and the theme silently stops applying on every
+ * page. So the string implements the rule and
+ * `scripts/check-theme-resolution.mjs` runs BOTH over one table of stored
+ * values, which is the only thing that can hold them together.
+ *
+ * Its price is a separate ceiling, `scripts/check-boot-budget.mjs`, because this
+ * string runs before paint on every page and adding it to a table of component
+ * bundle sizes would corrupt the unit that table exists to measure.
  */
 import { type Mode, type PackId } from '../theming';
+/**
+ * The first half of the storage-migration clause: read one key this line no
+ * longer writes.
+ *
+ * Exported because `check-boot-budget.mjs` prices the clause rather than
+ * guessing at it. The emitted string contains this fragment verbatim, so its
+ * byte count is the clause's cost and not an estimate of it.
+ */
+export declare const THEME_MIGRATION_READ: string;
+/**
+ * The second half: the clause retires itself.
+ *
+ * The recovery is the only write this string performs, and it writes the
+ * recovered pair into the key this line does write and removes the key it came
+ * from, in one guarded step. That is the clause's expiry by rule rather than by
+ * number: it fires only while a retired key still holds a mode, it fires at
+ * most once per reader because its own write is what makes the second load find
+ * nothing, and it is retired for good by deleting the last entry of
+ * `LEGACY_MODE_STORAGE_KEYS`. There is no date and no version constant in it,
+ * and the gate reports how many keys are still live so the number is visible
+ * rather than remembered.
+ */
+export declare const THEME_MIGRATION_RETIRE = "if(G===\"legacy\"){try{localStorage.setItem(K,JSON.stringify({pack:pack,mode:m}));localStorage.removeItem(LK);}catch(e){}}";
 export type PrismThemeScriptProps = {
     storageKey?: string;
     defaultPack?: PackId;

package/dist/provider/theme-script.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../../src/provider/theme-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAqC,KAAK,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,YAAY,CAAA;AAEtF,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,IAAI,CAAA;CACnB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,UAAgC,EAChC,WAAuB,EACvB,WAAqB,GACtB,EAAE,qBAAqB,+BAkBvB"}
+{"version":3,"file":"theme-script.d.ts","sourceRoot":"","sources":["../../src/provider/theme-script.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EAOL,KAAK,IAAI,EACT,KAAK,MAAM,EACZ,MAAM,YAAY,CAAA;AAEnB;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAEvB,CAAA;AAEV;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,+HACyF,CAAA;AAE5H,MAAM,MAAM,qBAAqB,GAAG;IAClC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,IAAI,CAAA;CACnB,CAAA;AAED,wBAAgB,gBAAgB,CAAC,EAC/B,UAAgC,EAChC,WAAuB,EACvB,WAAqB,GACtB,EAAE,qBAAqB,+BA+BvB"}

package/dist/provider/theme-script.js

@@ -4,25 +4,76 @@ import { jsx as _jsx } from "react/jsx-runtime";
  *
  * A Server Component that renders one blocking script. Placed in `<head>`, it
  * applies the stored pack and mode before React hydrates, so the first paint is
- * already correct. Precedence matches `PrismProvider`: stored value, then the
- * server-rendered attribute, then the defaults. It is safe to omit; a consumer
- * who renders the attributes on `<html>` needs no client runtime at all.
+ * already correct. It is safe to omit; a consumer who renders the attributes on
+ * `<html>` needs no client runtime at all.
+ *
+ * It is the only writer of `THEME_ORIGIN_ATTRIBUTE`, and it writes that
+ * attribute on every path it reaches, so the origin of the active theme is
+ * always readable and never merely absent.
+ *
+ * The string below is a second implementation of `resolveTheme`, not a copy of
+ * it that has been kept in step. A function cannot be shared with a string that
+ * a minifier rewrites: a renamed identifier inside the script's own `try` throws
+ * there, the catch swallows it, and the theme silently stops applying on every
+ * page. So the string implements the rule and
+ * `scripts/check-theme-resolution.mjs` runs BOTH over one table of stored
+ * values, which is the only thing that can hold them together.
+ *
+ * Its price is a separate ceiling, `scripts/check-boot-budget.mjs`, because this
+ * string runs before paint on every page and adding it to a table of component
+ * bundle sizes would corrupt the unit that table exists to measure.
+ */
+import { DEFAULT_STORAGE_KEY, LEGACY_MODE_STORAGE_KEYS, MODES, PACKS, PACK_ATTRIBUTE, THEME_ORIGIN_ATTRIBUTE, } from '../theming';
+/**
+ * The first half of the storage-migration clause: read one key this line no
+ * longer writes.
+ *
+ * Exported because `check-boot-budget.mjs` prices the clause rather than
+ * guessing at it. The emitted string contains this fragment verbatim, so its
+ * byte count is the clause's cost and not an estimate of it.
+ */
+export const THEME_MIGRATION_READ = LEGACY_MODE_STORAGE_KEYS.map((key) => `try{var g=localStorage.getItem(${JSON.stringify(key)});if(M.indexOf(g)>-1){L=g;LK=${JSON.stringify(key)};}}catch(e){}`).join('');
+/**
+ * The second half: the clause retires itself.
+ *
+ * The recovery is the only write this string performs, and it writes the
+ * recovered pair into the key this line does write and removes the key it came
+ * from, in one guarded step. That is the clause's expiry by rule rather than by
+ * number: it fires only while a retired key still holds a mode, it fires at
+ * most once per reader because its own write is what makes the second load find
+ * nothing, and it is retired for good by deleting the last entry of
+ * `LEGACY_MODE_STORAGE_KEYS`. There is no date and no version constant in it,
+ * and the gate reports how many keys are still live so the number is visible
+ * rather than remembered.
  */
-import { DEFAULT_STORAGE_KEY, MODES, PACKS } from '../theming';
+export const THEME_MIGRATION_RETIRE = 'if(G==="legacy"){try{localStorage.setItem(K,JSON.stringify({pack:pack,mode:m}));localStorage.removeItem(LK);}catch(e){}}';
 export function PrismThemeScript({ storageKey = DEFAULT_STORAGE_KEY, defaultPack = 'default', defaultMode = 'light', }) {
     const script = '(function(){try{' +
-        'var root=document.documentElement;' +
-        `var packs=${JSON.stringify(PACKS)};` +
-        `var modes=${JSON.stringify(MODES)};` +
-        'var stored=null;' +
-        `try{stored=JSON.parse(localStorage.getItem(${JSON.stringify(storageKey)})||"null");}catch(ignored){}` +
-        'var pack=stored&&packs.indexOf(stored.pack)>-1?stored.pack:(root.getAttribute("data-pack")||' +
-        `${JSON.stringify(defaultPack)});` +
-        'var mode=stored&&modes.indexOf(stored.mode)>-1?stored.mode:(root.classList.contains("dark")?"dark":' +
-        `${JSON.stringify(defaultMode)});` +
-        `if(packs.indexOf(pack)<0){pack=${JSON.stringify(defaultPack)};}` +
-        'if(pack&&pack!=="default"){root.setAttribute("data-pack",pack);}else{root.removeAttribute("data-pack");}' +
-        'root.classList.toggle("dark",mode==="dark");' +
-        '}catch(ignored){}})();';
+        'var r=document.documentElement,' +
+        `P=${JSON.stringify(PACKS)},` +
+        `M=${JSON.stringify(MODES)},` +
+        `K=${JSON.stringify(storageKey)},` +
+        `A=${JSON.stringify(PACK_ATTRIBUTE)},` +
+        `O=${JSON.stringify(THEME_ORIGIN_ATTRIBUTE)},` +
+        `DP=${JSON.stringify(defaultPack)},` +
+        `DM=${JSON.stringify(defaultMode)},` +
+        'L=null,LK=null,S=null,T=null;' +
+        'try{var t=localStorage.getItem(K);if(t){T=t;S=JSON.parse(t);}}catch(e){}' +
+        THEME_MIGRATION_READ +
+        'var a=r.getAttribute(A),' +
+        'DPK=P.indexOf(a)>-1?a:null,' +
+        'DK=r.classList.contains("dark")?"dark":null,' +
+        'U=S&&typeof S=="object"&&P.indexOf(S.pack)>-1&&M.indexOf(S.mode)>-1,' +
+        'pack,m,G;' +
+        'if(U){pack=S.pack;m=S.mode;G="stored";}' +
+        'else if(T){pack=DPK||DP;m=DK||DM;G="unparsed";}' +
+        'else if(L){pack=DP;m=L;G="legacy";}' +
+        'else if(DPK||DK){pack=DPK||DP;m=DK||DM;G="document";}' +
+        'else{pack=DP;m=DM;G="default";}' +
+        THEME_MIGRATION_RETIRE +
+        'if(pack!=="default"){r.setAttribute(A,pack);}else{r.removeAttribute(A);}' +
+        'r.classList.toggle("dark",m==="dark");' +
+        'r.setAttribute(O,G);' +
+        '}catch(e){}})();';
     return _jsx("script", { dangerouslySetInnerHTML: { __html: script } });
 }