@eifi1/ui-kit 0.31.1 → 0.32.1

package/src/theme/text-size.ts

@@ -0,0 +1,283 @@
+import { useEffect, useMemo, useSyncExternalStore } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger";
+import { readStored } from "../lib/safe-storage";
+
+/**
+ * The text size (docs/text-size-harmonization.md §2.1, §3.1, §10.3, §10.6).
+ *
+ * ONE scale on `<html>`: `data-text-size="normal|large|xlarge"`, and `tokens.css` turns
+ * it into `font-size: 100% / 125% / 150%` — percent, never px, so "Normal" keeps
+ * whatever size the person set in the browser. Tailwind's spacing and type are rem, so
+ * about 90 % of every screen grows with that one declaration; the breakpoints follow too
+ * (tokens.css redefines `sm:` … `3xl:` per size, {@link useBreakpoint} answers the same
+ * in JS).
+ *
+ * The names below are the mechanism's public vocabulary and are FROZEN: an app's
+ * storage, its `/auth/me` column (server-kit's `TEXT_SIZES`) and the inline boot snippet
+ * all spell them this way.
+ */
+
+/** The three steps, in order (§2.1, §10.6): server-kit's `TEXT_SIZES`, value for value. */
+export const TEXT_SIZES = ["normal", "large", "xlarge"] as const;
+
+export type TextSize = (typeof TEXT_SIZES)[number];
+
+/** The root font size each step sets, as a factor of the browser's own (tokens.css). For
+ *  what CSS cannot reach: a canvas or SVG chart's px constants, a windowed list's row
+ *  estimate, a popover width in px (§3.2). */
+export const TEXT_SCALE: Readonly<Record<TextSize, number>> = { normal: 1, large: 1.25, xlarge: 1.5 };
+
+/** The attribute on `<html>` that carries the size. */
+const TEXT_SIZE_ATTRIBUTE = "data-text-size";
+
+export function isTextSize(value: unknown): value is TextSize {
+  return value === "normal" || value === "large" || value === "xlarge";
+}
+
+/**
+ * The size in force: **this device's own choice → the account's → Normal** (§2.2, §2.6).
+ * Each is taken only when it is one of {@link TEXT_SIZES}; anything else (a stale value,
+ * `null` = never chosen) falls through to the next. The one order the pre-paint call, the
+ * apply hook and `useAccountAppearance` all use, so the three can never disagree.
+ */
+export function resolveTextSize(device: unknown, account?: unknown): TextSize {
+  if (isTextSize(device)) return device;
+  if (isTextSize(account)) return account;
+  return "normal";
+}
+
+/* ── <html data-text-size> and the subscribers that read it ─────────────── */
+
+const listeners = new Set<() => void>();
+let observer: MutationObserver | null = null;
+
+function notify(): void {
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  // Also catches writers that are not this module — the inline boot snippet, an app
+  // setting the attribute by hand, a test.
+  if (!observer && typeof MutationObserver !== "undefined" && typeof document !== "undefined") {
+    observer = new MutationObserver(notify);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: [TEXT_SIZE_ATTRIBUTE] });
+  }
+  return () => {
+    listeners.delete(listener);
+    if (listeners.size === 0) {
+      observer?.disconnect();
+      observer = null;
+    }
+  };
+}
+
+/** The size `<html>` carries now; Normal without one (or outside a browser). */
+export function readTextSize(): TextSize {
+  if (typeof document === "undefined") return "normal";
+  const value = document.documentElement.getAttribute(TEXT_SIZE_ATTRIBUTE);
+  return isTextSize(value) ? value : "normal";
+}
+
+/** Put `size` on `<html>`. Every {@link useTextSize} re-renders with it. */
+export function applyTextSize(size: TextSize): void {
+  if (typeof document === "undefined") return;
+  const root = document.documentElement;
+  if (root.getAttribute(TEXT_SIZE_ATTRIBUTE) === size) return;
+  root.setAttribute(TEXT_SIZE_ATTRIBUTE, size);
+  notify();
+}
+
+export interface TextSizeInfo {
+  size: TextSize;
+  /** {@link TEXT_SCALE} for `size`: 1, 1.25 or 1.5. */
+  scale: number;
+}
+
+/**
+ * The size in force on this page, and its scale (§3.1) — read from `<html>`, so it needs
+ * no store and works in every kit component: whoever applied the size (the app's store,
+ * the pre-paint call, the inline snippet), this follows it.
+ *
+ * Only for what CSS cannot do. A class that should differ at Large is a `large:`
+ * variant; a layout switch is a breakpoint, which already scales.
+ */
+export function useTextSize(): TextSizeInfo {
+  const size = useSyncExternalStore(subscribe, readTextSize, () => "normal" as const);
+  return useMemo(() => ({ size, scale: TEXT_SCALE[size] }), [size]);
+}
+
+/* ── Storage: the frozen format, the pre-paint call ─────────────────────── */
+
+/**
+ * What a text-size store persists under its key — zustand's persist envelope, and FROZEN
+ * (§10.3) because an app's inline `<head>` snippet reads it before any module loads:
+ *
+ *     {"state":{"size":"large"},"version":1}
+ *
+ * `size` is one of {@link TEXT_SIZES}, or `null` / absent when this device never chose.
+ * A future change adds a key; it never renames `state.size` or changes its values.
+ *
+ * A hand-written seed (a test, a screenshot script) must carry `"version":1`: the store
+ * drops a stored state of another version as a migration it doesn't know, silently
+ * (keksdose's 0.32 report). The inline snippet reads `state.size` whatever the version,
+ * so the two would disagree. In the kit's showcase, `?text-size=` needs no seed.
+ */
+export interface PersistedTextSize {
+  state?: { size?: TextSize | null };
+  version?: number;
+}
+
+/** This device's own choice under `storageKey`, or `null` when it never chose (or the
+ *  storage is blocked, malformed, or holds a value that is not a size). */
+export function readPersistedTextSize(storageKey: string): TextSize | null {
+  try {
+    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedTextSize | null;
+    const size = blob?.state?.size;
+    return isTextSize(size) ? size : null;
+  } catch {
+    return null;
+  }
+}
+
+export interface PersistedAppearanceOptions {
+  /**
+   * The account's last known value, for a device without a choice of its own (§10.3):
+   * what the app persisted with its user (keksdose keeps `/auth/me` in localStorage), so
+   * a cold boot paints the account's size instead of Normal and then jumping — offline
+   * too. Called once, guarded: a throw counts as "no account value".
+   */
+  account?: () => string | null | undefined;
+}
+
+function readAccount(account: PersistedAppearanceOptions["account"]): unknown {
+  if (!account) return undefined;
+  try {
+    return account();
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Pre-paint (§3.1, §10.3): read this device's choice under `storageKey` — else the
+ * account's last known value — and put it on `<html>` BEFORE `createRoot`, next to
+ * `applyPersistedTheme`, so the first paint already has the right size. Returns the size
+ * applied.
+ *
+ * ```ts
+ * applyPersistedTextSize("keksdose-text-size", {
+ *   account: () => readPersistedUser()?.text_size,
+ * });
+ * ```
+ */
+export function applyPersistedTextSize(storageKey: string, options: PersistedAppearanceOptions = {}): TextSize {
+  const size = resolveTextSize(readPersistedTextSize(storageKey), readAccount(options.account));
+  applyTextSize(size);
+  return size;
+}
+
+/**
+ * The same pre-paint as {@link applyPersistedTextSize}, as an inline `<head>` script for
+ * a boot splash painted from `index.html` before any module runs (§10.3). A function
+ * EXPRESSION: call it with the storage key and, optionally, a function returning the
+ * account's last known value.
+ *
+ * ```html
+ * <script>
+ *   (function(k,a){…})("keksdose-text-size", function () {
+ *     return JSON.parse(localStorage.getItem("keksdose-auth")).state.user.text_size;
+ *   });
+ * </script>
+ * ```
+ *
+ * Paste the constant's value in place of `(function(k,a){…})`. It reads the frozen
+ * {@link PersistedTextSize} format, never throws, and sets only `data-text-size`.
+ *
+ * The splash sizes in rem, and needs the root rules inline beside it, since the app's
+ * stylesheet is a separate request and arrives after the splash paints (0.32.1,
+ * keksdose's 0.32 report: that is every app, not an edge case):
+ *
+ * ```html
+ * <style>html[data-text-size=large]{font-size:125%}html[data-text-size=xlarge]{font-size:150%}</style>
+ * ```
+ *
+ * Under a hash-based Content Security Policy (`script-src 'sha256-…'`) this is a second
+ * inline script with its own hash: add it to the policy, and recompute it whenever the
+ * storage key or the account function in the call changes (keksdose added it to both
+ * its Caddyfiles, and its guard test hashes every inline script).
+ */
+export const TEXT_SIZE_INLINE_SCRIPT =
+  "(function(k,a){function ok(v){return v==='normal'||v==='large'||v==='xlarge'}" +
+  "var v=null;try{var s=JSON.parse(localStorage.getItem(k)||'null');v=s&&s.state&&s.state.size}catch(e){}" +
+  "if(!ok(v)){v=null;try{v=a?a():null}catch(e){}}" +
+  "try{document.documentElement.setAttribute('data-text-size',ok(v)?v:'normal')}catch(e){}})";
+
+/* ── The store ──────────────────────────────────────────────────────────── */
+
+export interface TextSizeState {
+  /** This device's own choice (persisted), or `null` when it never chose — then the
+   *  account's value applies (§2.2). */
+  size: TextSize | null;
+  /** Store this device's choice; `null` forgets it, so the account's applies again. */
+  setSize: (size: TextSize | null) => void;
+}
+
+export interface ApplyTextSizeOptions {
+  /** The account's value (`/auth/me`'s `text_size`): it applies while this device has no
+   *  choice of its own. Leave it out where there is no account. */
+  account?: string | null;
+}
+
+/**
+ * Build a text-size store bound to a consumer-supplied localStorage key, shaped like
+ * `createThemeStore` (§6). It holds the DEVICE's choice only; the account's value comes
+ * in through `useApplyTextSize({ account })` and `useAccountAppearance`, and the size in
+ * force is always {@link resolveTextSize} of the two.
+ *
+ * - `useTextSizeStore` — the zustand hook: `size` (device choice or null) and `setSize`.
+ * - `useApplyTextSize({ account })` — the effect that puts the size in force on `<html>`.
+ *   Mount it once near the root, beside `useApplyTheme`.
+ *
+ * The persisted format is {@link PersistedTextSize}, and frozen.
+ */
+export function createTextSizeStore(storageKey: string) {
+  const useTextSizeStore = create<TextSizeState>()(
+    logger(
+      persist(
+        (set) => ({
+          size: null,
+          setSize: (size) => set({ size: isTextSize(size) ? size : null }),
+        }),
+        {
+          name: storageKey,
+          version: 1,
+          partialize: (s) => ({ size: s.size }),
+          // A hand-edited or future value must not reach <html> as an unknown size.
+          merge: (persisted, current) => ({
+            ...current,
+            size: isTextSize((persisted as { size?: unknown } | null)?.size)
+              ? ((persisted as { size: TextSize }).size)
+              : null,
+          }),
+        },
+      ),
+      "text-size",
+    ),
+  );
+
+  function useApplyTextSize({ account }: ApplyTextSizeOptions = {}): TextSize {
+    const device = useTextSizeStore((s) => s.size);
+    const size = resolveTextSize(device, account);
+    useEffect(() => {
+      applyTextSize(size);
+    }, [size]);
+    return size;
+  }
+
+  return { useTextSizeStore, useApplyTextSize };
+}
+
+export type TextSizeStore = ReturnType<typeof createTextSizeStore>;

package/src/wizard/wizard-summary.tsx

@@ -40,8 +40,10 @@ export function WizardSummary({
         <Card key={sIdx}>
           {/* CardHeader is a grid, and CardAction is the top-right column it
               reserves — the edit button has to go through it or it stacks under
-              the title instead of sitting beside it. */}
-          <CardHeader className="pb-2">
+              the title instead of sitting beside it. `stackAction={false}`: the pencil
+              is named by `aria-label` and stays an icon at Large, so it keeps its
+              place beside the title there too (0.32.1). */}
+          <CardHeader className="pb-2" stackAction={false}>
             <CardTitle className="text-base">{section.label}</CardTitle>
             {section.stepIndex !== undefined && onEditStep && (
               <CardAction>

package/tokens.css

@@ -30,6 +30,148 @@
 
 @custom-variant dark (&:where(.dark, .dark *));
 
+/* ── Text size and contrast (0.32, docs/text-size-harmonization.md §3, §5, §10) ──────
+ *
+ * ONE scale on <html>: `data-text-size="normal|large|xlarge"` is 100 / 125 / 150 % of
+ * the browser's OWN font size — percent, never px, so "Normal" keeps whatever the person
+ * set in the browser. Tailwind's spacing and type are rem, so this one declaration grows
+ * about 90 % of every screen. The kit's stores put the attribute there before first
+ * paint (`applyPersistedTextSize`, or the inline `TEXT_SIZE_INLINE_SCRIPT`).
+ *
+ * `data-contrast="more"` is "More contrast", from the setting or from
+ * `prefers-contrast: more` on "System". The colour tokens are stepped in JS
+ * (`applyTokenSet`), because they are written inline on <html> and no rule here could
+ * beat them; what lives here is only what is NOT inline — the focus frame's width.
+ *
+ * These names are frozen: apps read them, and so does an app's boot splash. */
+
+@theme {
+  /* The kit's two small sizes, which were `text-[10px]` / `text-[11px]` and did not
+     grow with anything (§3.2). Font size only, no line height — exactly what the
+     arbitrary px values set — so a site moves to them without its line box changing. */
+  --text-micro: 0.625rem;
+  --text-caption: 0.6875rem;
+  /* keksdose's `min-[2400px]` as a named step (§10.4), so it scales like the others.
+     Declared here so Tailwind registers `3xl:` in the breakpoint group — the variant
+     below then replaces its query and keeps that place in the cascade order. */
+  --breakpoint-3xl: 150rem;
+}
+
+html[data-text-size="large"] {
+  font-size: 125%;
+}
+html[data-text-size="xlarge"] {
+  font-size: 150%;
+}
+
+/* One focus frame for the kit (§5): `FOCUS_RING` draws its ring this wide. Not inline,
+   so a stylesheet rule can raise it. */
+:root {
+  --focus-ring-width: 2px;
+}
+:root[data-contrast="more"] {
+  --focus-ring-width: 3px;
+}
+
+/* ── Breakpoints that follow the text size (§3.3, §10.4) ─────────────────────────────
+ *
+ * A media query's rem is the browser's default font size, never <html>'s, so Tailwind's
+ * `md:` would stay at 48rem while the text grows to 150 % — a tablet at Extra large
+ * would keep the desktop shell. Each breakpoint is therefore redefined as three media
+ * queries, one per size, each scoped to that size with an attribute selector:
+ *
+ *     md:   48rem at Normal, 60rem at Large, 72rem at Extra large   (× 1, 1.25, 1.5)
+ *
+ * The scope sits in `:where()`, so `md:flex` keeps the specificity it had (0,1,0) and
+ * the cascade between utilities is unchanged. A redefined built-in (`sm` … `2xl`, and
+ * `3xl` from @theme above) keeps its place in Tailwind's variant order — checked in the
+ * built showcase CSS — and Tailwind's own query for it is not emitted any more.
+ *
+ * The `max-*` variants are new names to Tailwind (its own `max-*` is one functional
+ * variant, which CSS cannot replace), so they sort AFTER the other variants rather than
+ * before `sm`. They are declared widest first, as Tailwind orders its own, so the
+ * narrower range still wins (`max-lg:px-4 max-sm:px-2`). A scan of the kit, the
+ * showcase and the three apps (2026-10-08) found no element where a `max-*` utility and
+ * a later variant (`md:`, `dark:`, `@container`, `pointer-*` …) set the same property
+ * in an overlapping range, so no rendering changes with that order.
+ *
+ * Not a container on <body> (§10.4): fixed overlays and a container querying itself
+ * would break. Arbitrary `min-[…]` / `max-[…]` media variants do NOT scale — use a
+ * name. `useBreakpoint` / `usePhoneLayout` answer the same questions in JS, with the
+ * same numbers (hooks/use-breakpoint.ts). */
+
+@custom-variant sm {
+  @media (width >= 40rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 50rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 60rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant md {
+  @media (width >= 48rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 60rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 72rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant lg {
+  @media (width >= 64rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 80rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 96rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant xl {
+  @media (width >= 80rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 100rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 120rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant 2xl {
+  @media (width >= 96rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 120rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 144rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant 3xl {
+  @media (width >= 150rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width >= 187.5rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width >= 225rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+
+@custom-variant max-3xl {
+  @media (width < 150rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 187.5rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 225rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant max-2xl {
+  @media (width < 96rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 120rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 144rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant max-xl {
+  @media (width < 80rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 100rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 120rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant max-lg {
+  @media (width < 64rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 80rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 96rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant max-md {
+  @media (width < 48rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 60rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 72rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+@custom-variant max-sm {
+  @media (width < 40rem) { &:where(:not([data-text-size$=large] *)) { @slot; } }
+  @media (width < 50rem) { &:where([data-text-size=large] *) { @slot; } }
+  @media (width < 60rem) { &:where([data-text-size=xlarge] *) { @slot; } }
+}
+
+/* `large:` is Large AND Extra large; `xlarge:` only Extra large; `contrast:` is More
+   contrast however it came about. Modelled on `dark:` — `:where()`, so a variant adds
+   no specificity and `large:text-base` beats `text-sm` by order alone. Declared AFTER
+   the breakpoints, so a size wins over a breakpoint: `max-sm:grid-cols-2
+   large:grid-cols-1` is one column on a phone at Large.
+   `$=large` ("ends in large") matches both "large" and "xlarge". */
+@custom-variant large (&:where([data-text-size$=large], [data-text-size$=large] *));
+@custom-variant xlarge (&:where([data-text-size=xlarge], [data-text-size=xlarge] *));
+@custom-variant contrast (&:where([data-contrast=more], [data-contrast=more] *));
+
 :root {
   --bg-page: #ede3cf;          /* warm dim sand — low-glare light page */
   --bg-surface: #f6ecd9;       /* warm off-white card/panel (not pure white) */
@@ -304,7 +446,7 @@
 /* The kit's focus ring on the toast's buttons — sonner's is a black shadow that
    vanishes on the dark theme. */
 .kit-toaster [data-sonner-toast][data-styled="true"] :is([data-button], [data-close-button]):focus-visible {
-  outline: 2px solid var(--brand);
+  outline: var(--focus-ring-width, 2px) solid var(--brand);
   outline-offset: 2px;
 }
 
@@ -551,10 +693,18 @@ body {
   .animate-drill { animation-name: overlay-fade-in; }
 }
 
-/* Scrollbars: keep light defaults; theme to slate when dark mode is active. */
+/* Scrollbars: keep light defaults; theme to the palette when dark mode is active.
+ *
+ * From the tokens, not literals (0.32.1, keksdose's 0.32 report): the thumb is a border
+ * (`--border`) on the page (`--bg-page`), so a palette preset carries through, and so
+ * does More contrast (§5), which steps `--border` until it clears 3:1 against every
+ * surface, the page among them: WCAG 1.4.11's floor for a control's visible part. At
+ * standard contrast it is as quiet as the slate-700-on-slate-900 it replaces (1.5:1
+ * against 1.7:1 in the default dark preset). Hover takes `--border-strong`, the border
+ * pulled toward the text, which grows with it. */
 .dark {
   color-scheme: dark;
-  scrollbar-color: rgb(51 65 85) rgb(15 23 42); /* slate-700 thumb on slate-900 track */
+  scrollbar-color: var(--border) var(--bg-page);
 }
 
 .dark ::-webkit-scrollbar {
@@ -563,19 +713,19 @@ body {
 }
 
 .dark ::-webkit-scrollbar-track {
-  background-color: rgb(15 23 42); /* slate-900 */
+  background-color: var(--bg-page);
 }
 
 .dark ::-webkit-scrollbar-thumb {
-  background-color: rgb(51 65 85); /* slate-700 */
+  background-color: var(--border);
   border-radius: 6px;
-  border: 2px solid rgb(15 23 42); /* slate-900 — creates inset padding */
+  border: 2px solid var(--bg-page); /* the track's colour: inset padding */
 }
 
 .dark ::-webkit-scrollbar-thumb:hover {
-  background-color: rgb(71 85 105); /* slate-600 */
+  background-color: var(--border-strong);
 }
 
 .dark ::-webkit-scrollbar-corner {
-  background-color: rgb(15 23 42); /* slate-900 */
+  background-color: var(--bg-page);
 }