@nanisoft/prism-ui 0.5.1 → 0.7.0

package/dist/theming/index.d.ts

@@ -14,6 +14,57 @@ export declare const MODES: readonly ["light", "dark"];
 export type Mode = (typeof MODES)[number];
 export declare const PACK_ATTRIBUTE = "data-pack";
 export declare const DEFAULT_STORAGE_KEY = "prism-theme";
+/**
+ * The root attribute that records where the active pack and mode came from.
+ *
+ * This is a contract, not markup. The boot script is its only writer, and the
+ * provider never touches it, because two writers would make the recorded origin
+ * a race rather than a record. The value is always one of `THEME_ORIGINS` and is
+ * written on every path the script reaches, including a stored value that could
+ * not be parsed: an absent attribute cannot be told from an unread one, and a
+ * theme that fell through to the default is exactly the case a reader needs to
+ * see named.
+ *
+ * It is not `data-theme`, which `MIGRATION.md` retires. It carries the
+ * provenance of a resolution, never a pack.
+ */
+export declare const THEME_ORIGIN_ATTRIBUTE = "data-theme-origin";
+/**
+ * The closed set the boot script may write to `THEME_ORIGIN_ATTRIBUTE`.
+ *
+ *   - `stored`   a valid `{ pack, mode }` pair was in the key this line writes.
+ *   - `legacy`   the key was empty and a key this line no longer writes held a
+ *                recoverable mode, so that decision was taken and carried over.
+ *   - `unparsed` the key held a value that is not a pair. The theme fell
+ *                through whole, and the value was left in place, because it is
+ *                the only record that this reader ever chose anything.
+ *   - `document` the key was empty and the root element's own attributes
+ *                supplied the theme.
+ *   - `default`  neither did, so the consumer's own defaults apply.
+ *
+ * `legacy` and `unparsed` are why the set is five and not three: a
+ * three-value set records that the theme came from somewhere but cannot
+ * distinguish "never chose" from "chose, and the value no longer parses", which
+ * is the one distinction a storage migration has to be retired against.
+ */
+export declare const THEME_ORIGINS: readonly ["stored", "legacy", "document", "default", "unparsed"];
+export type ThemeOrigin = (typeof THEME_ORIGINS)[number];
+/**
+ * Keys earlier lines of this package wrote and this line does not.
+ *
+ * `prism-theme-mode` was the shared chrome key: the mode setter wrote it, and
+ * only the mode setter, as a bare `'light'` or `'dark'` string, because the pack
+ * was fixed per site and the mode was the one choice that travelled across
+ * sites. The value is not a `{ pack, mode }` pair and can never collide with one
+ * this line writes, so reading it costs nothing and recovers a real decision.
+ *
+ * The list is the migration's own expiry. Every key in it is a clause the boot
+ * script carries and prices, and the migration is retired by deleting the last
+ * entry: the clause's live population is then empty, the gate reports it, and
+ * the byte ceiling's generation allowance falls to zero with it. Nothing here
+ * is bounded by a date or a version number.
+ */
+export declare const LEGACY_MODE_STORAGE_KEYS: readonly ["prism-theme-mode"];
 /**
  * Reads a persisted `{ pack, mode }` object.
  *
@@ -27,15 +78,94 @@ export declare function parseStoredTheme(raw: string | null): {
     mode: Mode;
 } | null;
 /**
- * Turns a pack and mode into the two markup attributes that express them.
+ * What `resolveTheme` was given, and nothing else.
+ *
+ * The three readers are all the same question asked of different state: what
+ * does this reader believe, what has the server rendered, and what is the
+ * consumer's own default. `stored` and `legacy` are raw strings exactly as the
+ * store holds them, so a corrupt value is visible to the rule rather than
+ * normalised away by a caller.
+ */
+export type ThemeResolutionInput = {
+    /** Raw contents of the key this line writes, or `null` when it is absent. */
+    stored: string | null;
+    /** Raw contents of one key this line no longer writes, or `null`. */
+    legacy: string | null;
+    /** `data-pack` on the root element as rendered, valid or not. */
+    documentPack: string | null;
+    /** Whether the root element carries `.dark` as rendered. */
+    documentDark: boolean;
+    defaultPack: PackId;
+    defaultMode: Mode;
+};
+export type ThemeResolution = {
+    pack: PackId;
+    mode: Mode;
+    /** Which source named the pair, for `THEME_ORIGIN_ATTRIBUTE`. */
+    origin: ThemeOrigin;
+};
+/**
+ * The one resolution rule. `PrismProvider` calls it, and the boot script
+ * implements it as a string, and the equivalence gate runs both over one table
+ * because the string cannot import it.
+ *
+ * A serialised function is not a way to share it. The build minifies, a renamed
+ * identifier inside the script's own `try` would throw there and the catch
+ * would fail open, leaving a silent no-op on every page; so the honest shape is
+ * one implementation plus a gate that can fail, not two copies that look
+ * aligned.
+ *
+ * The order, and why each step is where it is:
+ *
+ *   1. A valid pair in the key this line writes wins outright. A decision
+ *      recorded as a pair is a decision, and it is the only source that names
+ *      both axes at once.
+ *   2. A value that is present but is not a pair falls through WHOLE. It is not
+ *      repaired field by field, because a half-applied pair is a theme neither
+ *      the reader nor the server chose, and because repairing it would make the
+ *      two readers disagree about what "a valid mode" means. The value is also
+ *      not cleared: it is the only record that this reader ever chose, and the
+ *      origin is `unparsed` so a reader can see that it is there and unusable.
+ *   3. Only an absent key reaches the keys this line no longer writes. A present
+ *      but unusable value is a record of an intent and outranks an older one.
+ *   4. The root element's own attributes, which is what a server rendered and
+ *      what must survive hydration rather than flash to the default.
+ *   5. The consumer's defaults, which is the site's decision, not the reader's.
+ *
+ * Every step names its own source, so the pack and the mode always come from
+ * the same one. That is the whole-vs-half property, and it is structural rather
+ * than a check.
+ */
+export declare function resolveTheme({ stored, legacy, documentPack, documentDark, defaultPack, defaultMode, }: ThemeResolutionInput): ThemeResolution;
+/**
+ * The first key in `LEGACY_MODE_STORAGE_KEYS` that holds a recoverable mode.
+ *
+ * Returned with the key that held it, because the recovery has to retire that
+ * key and no other. Order is the list's order, and the list is short enough
+ * that the loop is not worth a comment about its cost.
+ */
+export declare function readLegacyMode(read: (key: string) => string | null): {
+    key: string;
+    mode: Mode;
+} | null;
+/**
+ * Turns a pack and a mode into the markup attributes that express them.
  *
  * Returns attributes, never CSS values: a Server Component spreads the result
  * onto `<html>` and gets the declarative form with no client runtime. `default`
  * is expressed by omitting `data-pack`; light is expressed by omitting `dark`.
+ *
+ * `mode` is optional because a server cannot know the reader's mode, and a
+ * required one is that impossibility written into the type: the only way to ask
+ * for a boundary with no mode class of its own would be to pass `'light'` as a
+ * guess, and the guess is wrong for half of them. Omitting it is the honest
+ * spelling of "wear the mode of the element carrying `.dark`", which is what the
+ * token build's descendant selector implements. `pack` stays required, because an
+ * element carrying neither axis is not a theme boundary.
  */
 export declare function themeAttributes({ pack, mode, }: {
     pack: PackId;
-    mode: Mode;
+    mode?: Mode;
 }): {
     'data-pack'?: string;
     className?: string;

package/dist/theming/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theming/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,KAAK,mEAAoE,CAAA;AACtF,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3C,eAAO,MAAM,KAAK,4BAA6B,CAAA;AAC/C,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzC,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,mBAAmB,gBAAgB,CAAA;AAUhD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAgBxF;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,IAAI,GACL,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;CACX,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAK/C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/theming/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,eAAO,MAAM,KAAK,mEAAoE,CAAA;AACtF,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAE3C,eAAO,MAAM,KAAK,4BAA6B,CAAA;AAC/C,MAAM,MAAM,IAAI,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAA;AAEzC,eAAO,MAAM,cAAc,cAAc,CAAA;AACzC,eAAO,MAAM,mBAAmB,gBAAgB,CAAA;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,sBAAsB,CAAA;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,kEAAmE,CAAA;AAC7F,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,wBAAwB,+BAAgC,CAAA;AAUrE;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAgBxF;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,iEAAiE;IACjE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,IAAI,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,IAAI,CAAA;IACV,iEAAiE;IACjE,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,EAC3B,MAAM,EACN,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,GACZ,EAAE,oBAAoB,GAAG,eAAe,CAoBxC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GACnC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAMpC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,IAAI,GACL,EAAE;IACD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,IAAI,CAAA;CACZ,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAK/C"}

package/dist/theming/index.js

@@ -12,6 +12,56 @@ export const PACKS = ['default', 'blush', 'mint', 'lavender', 'sky', 'peach'];
 export const MODES = ['light', 'dark'];
 export const PACK_ATTRIBUTE = 'data-pack';
 export const DEFAULT_STORAGE_KEY = 'prism-theme';
+/**
+ * The root attribute that records where the active pack and mode came from.
+ *
+ * This is a contract, not markup. The boot script is its only writer, and the
+ * provider never touches it, because two writers would make the recorded origin
+ * a race rather than a record. The value is always one of `THEME_ORIGINS` and is
+ * written on every path the script reaches, including a stored value that could
+ * not be parsed: an absent attribute cannot be told from an unread one, and a
+ * theme that fell through to the default is exactly the case a reader needs to
+ * see named.
+ *
+ * It is not `data-theme`, which `MIGRATION.md` retires. It carries the
+ * provenance of a resolution, never a pack.
+ */
+export const THEME_ORIGIN_ATTRIBUTE = 'data-theme-origin';
+/**
+ * The closed set the boot script may write to `THEME_ORIGIN_ATTRIBUTE`.
+ *
+ *   - `stored`   a valid `{ pack, mode }` pair was in the key this line writes.
+ *   - `legacy`   the key was empty and a key this line no longer writes held a
+ *                recoverable mode, so that decision was taken and carried over.
+ *   - `unparsed` the key held a value that is not a pair. The theme fell
+ *                through whole, and the value was left in place, because it is
+ *                the only record that this reader ever chose anything.
+ *   - `document` the key was empty and the root element's own attributes
+ *                supplied the theme.
+ *   - `default`  neither did, so the consumer's own defaults apply.
+ *
+ * `legacy` and `unparsed` are why the set is five and not three: a
+ * three-value set records that the theme came from somewhere but cannot
+ * distinguish "never chose" from "chose, and the value no longer parses", which
+ * is the one distinction a storage migration has to be retired against.
+ */
+export const THEME_ORIGINS = ['stored', 'legacy', 'document', 'default', 'unparsed'];
+/**
+ * Keys earlier lines of this package wrote and this line does not.
+ *
+ * `prism-theme-mode` was the shared chrome key: the mode setter wrote it, and
+ * only the mode setter, as a bare `'light'` or `'dark'` string, because the pack
+ * was fixed per site and the mode was the one choice that travelled across
+ * sites. The value is not a `{ pack, mode }` pair and can never collide with one
+ * this line writes, so reading it costs nothing and recovers a real decision.
+ *
+ * The list is the migration's own expiry. Every key in it is a clause the boot
+ * script carries and prices, and the migration is retired by deleting the last
+ * entry: the clause's live population is then empty, the gate reports it, and
+ * the byte ceiling's generation allowance falls to zero with it. Nothing here
+ * is bounded by a date or a version number.
+ */
+export const LEGACY_MODE_STORAGE_KEYS = ['prism-theme-mode'];
 function isPack(value) {
     return typeof value === 'string' && PACKS.includes(value);
 }
@@ -44,11 +94,87 @@ export function parseStoredTheme(raw) {
     return { pack, mode };
 }
 /**
- * Turns a pack and mode into the two markup attributes that express them.
+ * The one resolution rule. `PrismProvider` calls it, and the boot script
+ * implements it as a string, and the equivalence gate runs both over one table
+ * because the string cannot import it.
+ *
+ * A serialised function is not a way to share it. The build minifies, a renamed
+ * identifier inside the script's own `try` would throw there and the catch
+ * would fail open, leaving a silent no-op on every page; so the honest shape is
+ * one implementation plus a gate that can fail, not two copies that look
+ * aligned.
+ *
+ * The order, and why each step is where it is:
+ *
+ *   1. A valid pair in the key this line writes wins outright. A decision
+ *      recorded as a pair is a decision, and it is the only source that names
+ *      both axes at once.
+ *   2. A value that is present but is not a pair falls through WHOLE. It is not
+ *      repaired field by field, because a half-applied pair is a theme neither
+ *      the reader nor the server chose, and because repairing it would make the
+ *      two readers disagree about what "a valid mode" means. The value is also
+ *      not cleared: it is the only record that this reader ever chose, and the
+ *      origin is `unparsed` so a reader can see that it is there and unusable.
+ *   3. Only an absent key reaches the keys this line no longer writes. A present
+ *      but unusable value is a record of an intent and outranks an older one.
+ *   4. The root element's own attributes, which is what a server rendered and
+ *      what must survive hydration rather than flash to the default.
+ *   5. The consumer's defaults, which is the site's decision, not the reader's.
+ *
+ * Every step names its own source, so the pack and the mode always come from
+ * the same one. That is the whole-vs-half property, and it is structural rather
+ * than a check.
+ */
+export function resolveTheme({ stored, legacy, documentPack, documentDark, defaultPack, defaultMode, }) {
+    const pair = parseStoredTheme(stored);
+    if (pair)
+        return { pack: pair.pack, mode: pair.mode, origin: 'stored' };
+    const renderedPack = isPack(documentPack) ? documentPack : null;
+    const renderedMode = documentDark ? 'dark' : null;
+    const fromDocument = () => ({
+        pack: renderedPack ?? defaultPack,
+        mode: renderedMode ?? defaultMode,
+        origin: 'document',
+    });
+    // A value the store holds with content, and `parseStoredTheme` did not accept.
+    const held = stored !== null && stored !== '';
+    if (held)
+        return { ...fromDocument(), origin: 'unparsed' };
+    if (isMode(legacy))
+        return { pack: defaultPack, mode: legacy, origin: 'legacy' };
+    if (renderedPack !== null || renderedMode !== null)
+        return fromDocument();
+    return { pack: defaultPack, mode: defaultMode, origin: 'default' };
+}
+/**
+ * The first key in `LEGACY_MODE_STORAGE_KEYS` that holds a recoverable mode.
+ *
+ * Returned with the key that held it, because the recovery has to retire that
+ * key and no other. Order is the list's order, and the list is short enough
+ * that the loop is not worth a comment about its cost.
+ */
+export function readLegacyMode(read) {
+    for (const key of LEGACY_MODE_STORAGE_KEYS) {
+        const value = read(key);
+        if (isMode(value))
+            return { key, mode: value };
+    }
+    return null;
+}
+/**
+ * Turns a pack and a mode into the markup attributes that express them.
  *
  * Returns attributes, never CSS values: a Server Component spreads the result
  * onto `<html>` and gets the declarative form with no client runtime. `default`
  * is expressed by omitting `data-pack`; light is expressed by omitting `dark`.
+ *
+ * `mode` is optional because a server cannot know the reader's mode, and a
+ * required one is that impossibility written into the type: the only way to ask
+ * for a boundary with no mode class of its own would be to pass `'light'` as a
+ * guess, and the guess is wrong for half of them. Omitting it is the honest
+ * spelling of "wear the mode of the element carrying `.dark`", which is what the
+ * token build's descendant selector implements. `pack` stays required, because an
+ * element carrying neither axis is not a theme boundary.
  */
 export function themeAttributes({ pack, mode, }) {
     const attributes = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanisoft/prism-ui",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Prism's React component, block and page library.",
   "license": "MIT",
@@ -75,7 +75,7 @@
     "clsx": "^2.1.1",
     "lucide-react": "^0.545.0",
     "tailwind-merge": "^3.3.1",
-    "@nanisoft/prism-tokens": "0.5.1"
+    "@nanisoft/prism-tokens": "0.6.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.3.3",
@@ -100,9 +100,19 @@
   "scripts": {
     "sync": "node scripts/sync-registry.mjs",
     "validate": "node scripts/validate-registry.mjs",
-    "build": "node scripts/build.mjs && pnpm sync && pnpm validate && shadcn build && node scripts/check-surface.mjs",
-    "check": "node scripts/validate-registry.mjs && node scripts/check-surface.mjs && node scripts/check-client-budget.mjs",
+    "build": "node scripts/build.mjs && pnpm sync && pnpm validate && node scripts/check-catalogue.mjs && shadcn build && node scripts/check-surface.mjs && node scripts/check-focus-indicators.mjs && node scripts/check-item-docs.mjs && node scripts/check-block-copy.mjs && node scripts/check-item-category.mjs && node scripts/check-block-imports.mjs",
+    "check": "node scripts/validate-registry.mjs && node scripts/check-catalogue.mjs && node scripts/check-surface.mjs && node scripts/check-focus-indicators.mjs && node scripts/check-pack-boundary.mjs && node scripts/check-vector-ink.mjs && node scripts/check-client-budget.mjs && node scripts/check-theme-resolution.mjs && node scripts/check-boot-budget.mjs && node scripts/check-item-docs.mjs && node scripts/check-block-copy.mjs && node scripts/check-item-category.mjs && node scripts/check-block-imports.mjs",
+    "check:vector-ink": "node scripts/check-vector-ink.mjs",
     "check:client-budget": "node scripts/check-client-budget.mjs",
+    "check:pack-boundary": "node scripts/check-pack-boundary.mjs",
+    "check:theme-resolution": "node scripts/check-theme-resolution.mjs",
+    "check:boot-budget": "node scripts/check-boot-budget.mjs",
+    "check:catalogue": "node scripts/check-catalogue.mjs",
+    "check:focus-indicators": "node scripts/check-focus-indicators.mjs",
+    "check:item-docs": "node scripts/check-item-docs.mjs",
+    "check:block-copy": "node scripts/check-block-copy.mjs",
+    "check:item-category": "node scripts/check-item-category.mjs",
+    "check:block-imports": "node scripts/check-block-imports.mjs",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }