@terpjs/react-core 0.9.0 → 0.10.0

package/src/theme.test.tsx

@@ -83,6 +83,35 @@ describe("ThemeProvider + ThemeToggle", () => {
     expect(document.documentElement.getAttribute("data-theme")).toBe("light");
   });
 
+  it("restores a persisted SYSTEM choice over the app default", () => {
+    // The one stored choice a declared default used to beat. `"system"` is a menu entry a
+    // person can pick, and it is stored like any other — so reading it as "nothing stored"
+    // put them back on the app's palette on the next load, while the menu reported that
+    // palette as active. An app declaring a palette must not be able to overrule a person
+    // who asked to follow their own platform.
+    window.localStorage.setItem(THEME_STORAGE_KEY, "system");
+    render(
+      <ThemeProvider defaultTheme="midnight">
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.hasAttribute("data-theme")).toBe(false);
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    expect(screen.getByRole("menuitemradio", { name: "System" })).toBeChecked();
+  });
+
+  it("treats a stored theme this build does not ship as no choice at all", () => {
+    // A theme removed by an upgrade must not leave a viewer pinned to a `data-theme` value
+    // nothing styles — which is what the app's default is for.
+    window.localStorage.setItem(THEME_STORAGE_KEY, "sepia");
+    render(
+      <ThemeProvider defaultTheme="contrast">
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.getAttribute("data-theme")).toBe("contrast");
+  });
+
   it("switching back to system removes the attribute (OS preference wins)", () => {
     render(
       <ThemeProvider defaultTheme="dark">

package/src/theme.themes.test.ts

@@ -6,9 +6,9 @@ import { DEFAULT_STRINGS } from "./uiText";
 
 // react-core's theme list against the contract's published one.
 //
-// `Theme` in `theme.tsx` is a hand-written union of the stylesheet's theme names, and
-// `THEME_ICONS` and the label map are records over it. That is a restatement of a published
-// contract, so it can drift from it — and both directions fail quietly:
+// `Theme` in `themes.ts` is a hand-written union of the stylesheet's theme names, and
+// `THEME_ICONS` and the label map in `theme.tsx` are records over it. That is a restatement of a
+// published contract, so it can drift from it — and both directions fail quietly:
 //
 //   * A theme the sheet ships that this union omits is a palette no app can ever select. It
 //     is compiled, gated for contrast and completeness, published in the manifest, and
@@ -33,19 +33,25 @@ const manifest: {
 
 // Read as source rather than imported, because the union is a type: it does not survive to
 // runtime, and `THEMES` alone would not prove the type and the array agree.
+//
+// Two files, because the names and the records over them are two files: the names are a leaf
+// module the layout-declaration resolver also reads (it must refuse a palette a checked-in
+// declaration asks for), and the icon and label records belong with the control that renders
+// them. Each regex below names the file it is asserting about.
+const namesSource = readFileSync(new URL("./themes.ts", import.meta.url), "utf-8");
 const themeSource = readFileSync(new URL("./theme.tsx", import.meta.url), "utf-8");
 
 /** The names in `export type Theme = "a" | "b" | …`. */
 function unionMembers(): string[] {
-  const match = /export type Theme =([^;]+);/.exec(themeSource);
-  if (!match) throw new Error("theme.tsx: could not find `export type Theme`");
+  const match = /export type Theme =([^;]+);/.exec(namesSource);
+  if (!match) throw new Error("themes.ts: could not find `export type Theme`");
   return [...match[1]!.matchAll(/"([a-z-]+)"/g)].map((entry) => entry[1]!);
 }
 
 /** The names in the `THEMES` array literal. */
 function themesArray(): string[] {
-  const match = /const THEMES: readonly Theme\[\] = \[([^\]]+)\]/.exec(themeSource);
-  if (!match) throw new Error("theme.tsx: could not find the `THEMES` array");
+  const match = /const THEMES: readonly Theme\[\] = \[([^\]]+)\]/.exec(namesSource);
+  if (!match) throw new Error("themes.ts: could not find the `THEMES` array");
   return [...match[1]!.matchAll(/"([a-z-]+)"/g)].map((entry) => entry[1]!);
 }
 

package/src/theme.tsx

@@ -1,38 +1,22 @@
+import type { IconName } from "@terpjs/contract";
 import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";
 import type { ReactNode } from "react";
 
 import { Icon } from "./icons";
+import { THEMES } from "./themes";
+import type { Theme } from "./themes";
 import { Menu, MenuItem } from "./ui/Menu";
 import { useStrings } from "./uiText";
 
 /**
- * The visual theme: an explicit choice, or "system" to follow the OS preference.
- *
- * The token stylesheet (`@terpjs/contract/tokens.css`) carries every palette: it applies
- * each named theme's colours under `<html data-theme="<name>">` and — with no attribute —
- * applies the dark palette under `@media (prefers-color-scheme: dark)`, so "system" simply
- * removes the attribute.
- *
- * The names are the stylesheet's, so this union is a restatement of a published contract
- * and could drift from it silently — a theme the sheet ships that no app can select, or one
- * this offers that resolves to nothing. `theme.themes.test.ts` holds it against the token
- * manifest. The union is written out rather than derived from the manifest at runtime because
- * react-core publishes unbuilt source and imports nothing but React: resolving a JSON module
- * from a sibling package would add a requirement to every consumer's bundler and tsconfig,
- * which is the consumption-model change the framework spends real effort avoiding.
+ * The theme names and the runtime list of them live in `themes.ts`, a leaf module with no
+ * React and no DOM, because the layout-declaration resolver needs the same list to refuse a
+ * palette an app's checked-in file names — and it must not import this file to get it.
+ * Re-exported here so `ThemeProvider`'s own type stays where its props are documented.
  */
-export type Theme = "light" | "dark" | "midnight" | "twilight" | "contrast" | "system";
+export type { Theme } from "./themes";
 
-const THEMES: readonly Theme[] = [
-  "light",
-  "dark",
-  "midnight",
-  "twilight",
-  "contrast",
-  "system",
-];
-
-const THEME_ICONS: Record<Theme, string> = {
+const THEME_ICONS: Record<Theme, IconName> = {
   light: "sun",
   dark: "moon",
   midnight: "moon-stars",
@@ -51,12 +35,26 @@ interface ThemeContextValue {
 
 const ThemeContext = createContext<ThemeContextValue | null>(null);
 
-function readStoredTheme(): Theme {
+/**
+ * The theme this viewer chose, or `null` if they have not chosen one.
+ *
+ * `null` rather than `"system"` for the absent case, and the distinction is load-bearing.
+ * `"system"` is a choice a person can make from the menu — it means "follow my platform" —
+ * and it is stored like any other. Collapsing it into the absent case made a declared
+ * `defaultTheme` beat it on every reload: the person picked System, the session honoured it,
+ * and the next load silently put them back on the app's palette while the menu reported that
+ * palette as active. The key documents itself as applying "until a person chooses another",
+ * and this was the one choice it could not survive.
+ *
+ * A stored value this build does not ship also reads as no choice — a theme removed by an
+ * upgrade must not leave a viewer pinned to a `data-theme` nothing styles.
+ */
+function readStoredTheme(): Theme | null {
   try {
     const stored = window.localStorage.getItem(THEME_STORAGE_KEY);
-    return THEMES.includes(stored as Theme) ? (stored as Theme) : "system";
+    return THEMES.includes(stored as Theme) ? (stored as Theme) : null;
   } catch {
-    return "system";
+    return null;
   }
 }
 
@@ -73,13 +71,12 @@ export interface ThemeProviderProps {
  * {@link UserMenu} already includes it).
  *
  * `defaultTheme` is how an app ships on a named theme — `defaultTheme="midnight"` and
- * nothing else — since it applies until the user chooses otherwise.
+ * nothing else — since it applies until the user chooses otherwise, INCLUDING when what they
+ * choose is "system". Prefer declaring it in the app's own `frontend/layout-contract.json`,
+ * which is the form a tool can read and rewrite.
  */
 export function ThemeProvider({ defaultTheme = "system", children }: ThemeProviderProps) {
-  const [theme, setThemeState] = useState<Theme>(() => {
-    const stored = readStoredTheme();
-    return stored === "system" ? defaultTheme : stored;
-  });
+  const [theme, setThemeState] = useState<Theme>(() => readStoredTheme() ?? defaultTheme);
 
   useEffect(() => {
     const root = document.documentElement;

package/src/themes.ts

@@ -0,0 +1,54 @@
+/**
+ * The theme names, as a leaf module: no React, no DOM, two literals and nothing else.
+ *
+ * They live here rather than beside `ThemeProvider` because two consumers need them and only
+ * one of them is a component. The provider needs the list to decide whether a stored choice is
+ * still a theme this build ships; {@link ./layoutDeclaration.resolveLayoutDeclaration} needs it
+ * to refuse a palette an app's checked-in declaration names and this release cannot honour.
+ * Importing `theme.tsx` from that resolver would have pulled React, the icon set and the
+ * component stylesheet's module-scope injection into a module whose entire job is to validate a
+ * JSON file — and into the node-environment test that covers it, where the stylesheet's
+ * `document` guard is the only thing standing between it and a crash.
+ *
+ * The union is a restatement of a published contract — `@terpjs/contract`'s compiled stylesheet
+ * and its token manifest — so it can drift from it, in both directions and quietly:
+ *
+ *   * A theme the sheet ships that this union omits is a palette no app can ever select. It is
+ *     compiled, gated for contrast and completeness, published in the manifest, unreachable.
+ *   * A theme this union offers that the sheet has no block for sets `data-theme` to a value
+ *     nothing matches, so the app renders the base palette while the control reports the choice
+ *     took.
+ *
+ * `theme.themes.test.ts` holds this file against the manifest for exactly that. The names are
+ * written out rather than derived from the manifest at runtime because react-core publishes
+ * unbuilt source and imports nothing but React: resolving a sibling package's JSON module would
+ * add a bundler and tsconfig requirement to every consumer, which is the consumption-model
+ * change the framework spends real effort avoiding. The copy stays a copy, and the copy is
+ * checked.
+ */
+
+/**
+ * The visual theme: an explicit choice, or `"system"` to follow the OS preference.
+ *
+ * The token stylesheet (`@terpjs/contract/tokens.css`) carries every palette: it applies each
+ * named theme's colours under `<html data-theme="<name>">` and — with no attribute — applies the
+ * dark palette under `@media (prefers-color-scheme: dark)`, so `"system"` simply removes the
+ * attribute.
+ */
+export type Theme = "light" | "dark" | "midnight" | "twilight" | "contrast" | "system";
+
+/**
+ * Every value {@link Theme} admits, in the order the theme control offers them: the shipped
+ * palettes in registry order, then the OS-preference sentinel last.
+ *
+ * This is the runtime half of the union — the type does not survive to runtime, and a stored
+ * string, a JSON file and a bootstrap option are all `string` until something checks them.
+ */
+export const THEMES: readonly Theme[] = [
+  "light",
+  "dark",
+  "midnight",
+  "twilight",
+  "contrast",
+  "system",
+];

package/src/toast.tsx

@@ -1,3 +1,4 @@
+import type { IconName } from "@terpjs/contract";
 import { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 
@@ -39,7 +40,7 @@ const ToastContext = createContext<ToastApi | null>(null);
 
 const DEFAULT_DURATION_MS = 5000;
 
-const iconName: Record<ToastVariant, string> = {
+const iconName: Record<ToastVariant, IconName> = {
   success: "check",
   error: "x",
   warning: "bell",

package/src/tokens.guard.test.ts

@@ -1,6 +1,9 @@
 import { readFileSync } from "node:fs";
 import { describe, expect, it } from "vitest";
 
+import { NARROW_VIEWPORT, WIDE_VIEWPORT_QUERY } from "./breakpoints";
+import { TERP_STYLES_CSS } from "./styles";
+
 // Vitest stubs .css imports to empty modules, so the sheet is read from disk.
 const tokensCss = readFileSync(
   new URL("../../contract/src/tokens.css", import.meta.url),
@@ -21,6 +24,119 @@ const declared = new Set(
   [...tokensCss.matchAll(/(--[a-z0-9-]+)\s*:/g)].map((match) => match[1]!),
 );
 
+/** The framework sheet with its comments removed — prose naming a token is not a reader. */
+const sheet = TERP_STYLES_CSS.replace(/\/\*[\s\S]*?\*\//g, "");
+
+/**
+ * Published motion tokens no rule in the sheet reads, as an exact list.
+ *
+ * The other three are wired: every `transition` in the sheet names
+ * `--motion-duration-fast` / `--motion-duration-instant` with
+ * `--motion-easing-standard`, which was inert by construction because those tokens'
+ * values ARE the `150ms` / `100ms` / `ease` literals they replaced.
+ *
+ * These four are not, and leaving them that way is a position rather than an omission.
+ * They map onto no literal this sheet contains, so there is nothing to convert. The two
+ * ways out are both worse than naming them here: deleting them is a **contract change**,
+ * since `tokens.manifest.json` publishes them and a consumer may already read one; and
+ * giving them readers means inventing overlay entrance/exit animations, which is a
+ * behaviour change wearing a token wiring's clothes — and one the screenshot lane cannot
+ * see either way, because it runs with `animations: "disabled"`.
+ *
+ * Exact equality in both directions, which is what makes it a decision instead of drift:
+ * wiring one has to shrink this list, and publishing an eighth motion token has to
+ * either name a reader or land here with a reason.
+ */
+const UNREAD_TOKENS: Record<string, string[]> = {
+  "--motion-": [
+    "--motion-duration-base",
+    "--motion-duration-slow",
+    "--motion-easing-entrance",
+    "--motion-easing-exit",
+  ],
+  // The published type scale, wired in 4b by the prose components — and the reason it took a
+  // new component rather than a conversion is the interesting part. Every motion literal
+  // mapped exactly onto a token, so wiring those was inert. Here the sheet writes line heights
+  // of 1.2, 1.25, 1.3, 1.4 and 1.5 while the scale offers 1.2, 1.35, 1.5 and 1.7: only 8 of 32
+  // literals map. Converting those eight and leaving thirteen is a half-migration, and
+  // converting the rest CHANGES rendered line heights across a dozen components — a typography
+  // pass with its own baselines, not a token wiring done in passing. New components have
+  // nothing depending on their metrics, so they take the scale as published.
+  "--font-line-height-": [],
+  // EMPTY, and `wide` is what emptied it. It sat here reading "for the uppercase-label
+  // treatment nothing in the package uses" — a token waiting for a component. The navigation
+  // group label is that treatment, and it takes 0.08em from the scale rather than adding a
+  // third bare literal beside the sheet's 0.04em and 0.06em. Which is the whole point of
+  // keeping this list: it named the reader before the reader existed, so the new rule had one
+  // obvious right answer instead of a plausible wrong one.
+  "--font-letter-spacing-": [],
+  // The shell's published geometry, tracked from the day it shipped rather than after
+  // something rots. All four have readers — two sidebar widths, the header's floor and the
+  // content measure — so the list is empty, and empty is the assertion: a fifth shell token
+  // added without a rule to read it lands here and has to justify itself. That is the exact
+  // offence `--color-fg-on-brand` was deleted for, and the reason it went unnoticed for a
+  // release is that only three families were tracked at all. (Still only four: `--color-`,
+  // `--space-`, `--radius-` and the rest publish unread tokens with nothing to say so. The
+  // sidebar colour family WAS in that state for four releases — five tokens declared in every
+  // theme and read by nothing — which is the offence `--color-fg-on-brand` was deleted for. The
+  // difference there is that the vocabulary was wrong; here it was right and the readers were
+  // missing, so the fix was to wire them. Tracked from now on.)
+  "--shell-": [],
+  "--color-sidebar-": [],
+  // The whole semantic colour layer, which the comment above admitted was untracked and then
+  // left untracked. Seventeen of the forty-eight published `--color-` tokens have no `var()`
+  // reader anywhere in the sheet, and until now nothing said so — the exact `--color-fg-on-brand`
+  // shape that comment describes, seventeen times over.
+  //
+  // Booked as one family rather than four narrower ones on purpose. `--color-bg-`,
+  // `--color-border-`, `--color-interactive-` and `--color-chart-` are each read by NOTHING, and
+  // the assertion below requires a tracked family to publish more than it books — a deliberate
+  // "is the prefix right?" check that a wholly-unread family would trip. The broader prefix
+  // subsumes them and still catches the eighteenth. `--color-sidebar-` stays above because it
+  // makes a narrower claim worth keeping: that family is read in full.
+  //
+  // None of these seventeen is a defect on its own. They are a published vocabulary that shipped
+  // ahead of its consumers — four surface tokens, three borders, three interactive states, a
+  // five-step chart ramp and two neutrals — and the point of booking them is that the list can
+  // only shrink from here, so wiring one is visible and adding an eighteenth has to argue.
+  "--color-": [
+    "--color-bg-canvas",
+    "--color-bg-inset",
+    "--color-bg-raised",
+    "--color-bg-surface",
+    "--color-border-default",
+    "--color-border-strong",
+    "--color-border-subtle",
+    "--color-chart-1",
+    "--color-chart-2",
+    "--color-chart-3",
+    "--color-chart-4",
+    "--color-chart-5",
+    "--color-interactive-active",
+    "--color-interactive-hover",
+    "--color-interactive-selected",
+    "--color-neutral-500",
+    "--color-neutral-800",
+  ],
+};
+
+/**
+ * Bare `line-height` / `letter-spacing` values still in the sheet, as an exact multiset.
+ *
+ * The reconciliation debt, made a number so it cannot grow quietly. The scale above is now
+ * read, but these 32 declarations predate it and most map onto nothing in it — so a new rule
+ * that adds a 27th bare line height has to either use a token or come here and say why, and
+ * whoever does the typography pass has a target rather than a grep.
+ *
+ * Two entries are permanent rather than pending: `line-height: 0` and `line-height: 1` are
+ * icon and avatar boxes, where the line box is being removed rather than set to a step on a
+ * prose scale.
+ */
+const BARE_TYPE_LITERALS: Record<string, Record<string, number>> = {
+  "line-height": { "0": 2, "1": 4, "1.2": 4, "1.25": 7, "1.3": 2, "1.4": 3, "1.5": 4 },
+  "letter-spacing": { "0": 4, "0.04em": 1, "0.06em": 1 },
+};
+
 describe("design tokens", () => {
   it("only references custom properties the contract token sheet declares", () => {
     // A fallback-less var() against an undeclared token silently computes to the
@@ -49,4 +165,80 @@ describe("design tokens", () => {
     expect(tokensCss).toContain("color-scheme: light");
     expect(tokensCss.match(/color-scheme: dark/g)?.length ?? 0).toBeGreaterThanOrEqual(2);
   });
+
+  it("spells the one viewport cutover from the published token, in one place", () => {
+    // The breakpoint is the other token family nothing can `var()`: CSS forbids a custom
+    // property in a media-query condition, and `matchMedia` takes a string, so neither
+    // consumer can read `--breakpoint-md` the way a colour is read. The literal is therefore
+    // unavoidable — and unguarded it was already written twice, verbatim, in `AppShell` and
+    // `DataView`, which is the duplication the diagnosis named.
+    //
+    // So this holds three things together that CANNOT agree by construction: the token the
+    // contract publishes, the string the components hand to `matchMedia`, and the query the
+    // stylesheet uses. The third one at least is the complement of the second by construction
+    // rather than by a second literal.
+    const declaredMd = /--breakpoint-md:\s*([^;]+);/.exec(tokensCss)?.[1]?.trim();
+    expect(declaredMd, "the contract should publish --breakpoint-md").toBe("768px");
+    expect(NARROW_VIEWPORT).toBe(`(max-width: ${declaredMd})`);
+    expect(WIDE_VIEWPORT_QUERY).toBe(`not all and ${NARROW_VIEWPORT}`);
+    expect(sheet).toContain(`@media ${WIDE_VIEWPORT_QUERY}`);
+
+    // And nobody re-spells it. The two components import the constant now; a third copy is
+    // exactly how the first two came to disagree with nothing noticing.
+    const offenders = Object.entries(sources)
+      .filter(([file]) => !file.includes(".test.") && file !== "./breakpoints.ts")
+      .filter(([, text]) => text.includes("max-width: 768px"))
+      .map(([file]) => file);
+    expect(offenders, "the breakpoint belongs in ./breakpoints.ts and nowhere else").toEqual([]);
+  });
+
+  it("names every published token in a tracked family that the sheet does not read", () => {
+    // The other direction of this file's join. The test above catches a `var()` naming a
+    // token the contract never declared; this one catches a token the contract publishes
+    // that nothing consumes — the `--color-fg-on-brand` shape, which was deleted for
+    // being declared in five themes and read by none. A Studio editor built from the
+    // manifest offers a control per published token, so an unread one is a knob that
+    // does nothing.
+    for (const [family, unread] of Object.entries(UNREAD_TOKENS)) {
+      const published = [
+        ...new Set(
+          // `[a-z0-9-]`, not `[a-z-]`. The narrower class could not match a token name with a
+          // DIGIT in it, which is every step of every scale the contract publishes — all nine
+          // neutrals, the five chart colours, every `--space-N` and `--font-size-N`. So a family
+          // containing them reported only its wordy members as published, and an unread numbered
+          // token was invisible to a test whose entire job is to name unread tokens. Found when
+          // the semantic colour layer was booked and the guard could see ten of its seventeen.
+          [...tokensCss.matchAll(new RegExp(`(${family}[a-z0-9-]+)\\s*:`, "g"))].map(
+            (match) => match[1]!,
+          ),
+        ),
+      ];
+      expect(published.length, `${family} publishes nothing — is the prefix right?`).toBeGreaterThan(
+        unread.length,
+      );
+      expect(
+        published.filter((token) => !sheet.includes(`var(${token})`)).sort(),
+        `a published ${family} token gained or lost a reader — wire it, or record it with a reason`,
+      ).toEqual(unread);
+    }
+  });
+
+  it("holds the bare type literals at their recorded count", () => {
+    // The debt the type scale's arrival did not clear, as a ratchet. See BARE_TYPE_LITERALS:
+    // most of these map onto no step in the published scale, so converting them changes
+    // rendered line heights and belongs in a typography pass. What this stops is the count
+    // growing in the meantime.
+    for (const [property, expected] of Object.entries(BARE_TYPE_LITERALS)) {
+      const counts: Record<string, number> = {};
+      for (const match of sheet.matchAll(new RegExp(`\\b${property}:\\s*([^;]+);`, "g"))) {
+        const value = match[1]!.trim();
+        if (value.includes("var(")) continue;
+        counts[value] = (counts[value] ?? 0) + 1;
+      }
+      expect(
+        counts,
+        `${property}: use the published scale, or record the new literal here`,
+      ).toEqual(expected);
+    }
+  });
 });