@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/theme/text-size.ts

@@ -1,289 +0,0 @@
-import { useEffect, useMemo, useSyncExternalStore } from "react";
-import { create } from "zustand";
-import { persist } from "zustand/middleware";
-import { logger } from "../lib/logger";
-import { readStoredJson } from "../lib/safe-storage";
-import { registerDeviceSetting } from "../lib/device-settings";
-
-/**
- * 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;
-}
-
-/** The frozen format holding a size this kit knows — the shape `readStoredJson` admits. */
-const holdsTextSize = (blob: unknown): blob is { state: { size: TextSize } } =>
-  isTextSize((blob as PersistedTextSize | null)?.state?.size);
-
-/** 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 {
-  return readStoredJson(storageKey, holdsTextSize)?.state.size ?? 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",
-    ),
-  );
-  // Reset this device's settings (docs/settings-harmonization.md §11.4): no choice on
-  // this device, so `useApplyTextSize` re-resolves to the account's size, else Normal.
-  registerDeviceSetting({
-    key: storageKey,
-    kind: "appearance",
-    reset: () => useTextSizeStore.getState().setSize(null),
-  });
-
-  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/theme/theme-store.ts

@@ -1,157 +0,0 @@
-import { useEffect } from "react";
-import { create } from "zustand";
-import { persist } from "zustand/middleware";
-import { logger } from "../lib/logger";
-import { readStoredJson } from "../lib/safe-storage";
-import { registerDeviceSetting } from "../lib/device-settings";
-
-export type ThemeMode = "light" | "dark";
-/** What the user chose; "system" tracks the OS `prefers-color-scheme`. */
-export type ThemePreference = "light" | "dark" | "system";
-
-export interface ThemeState {
-  /** The user's choice (persisted). */
-  preference: ThemePreference;
-  /** The RESOLVED light/dark actually in effect (system → OS). Read this for
-   *  anything that needs the concrete theme (e.g. token selection, toasts). */
-  mode: ThemeMode;
-  setPreference: (preference: ThemePreference) => void;
-  /** Set an explicit light/dark choice (preference follows). */
-  setMode: (mode: ThemeMode) => void;
-  /** Flip the effective theme to the opposite explicit choice. */
-  toggle: () => void;
-}
-
-function systemPreference(): ThemeMode {
-  try {
-    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
-  } catch {
-    return "light";
-  }
-}
-
-function resolve(preference: ThemePreference): ThemeMode {
-  return preference === "system" ? systemPreference() : preference;
-}
-
-/** Normalize a persisted theme-state blob to a valid preference. Older blobs
- *  persisted the concrete `mode` (light/dark); carry that over as an explicit
- *  preference so the choice survives. Shared by the store's `migrate` and the
- *  pre-hydration {@link applyPersistedTheme}. */
-function preferenceFromState(s: { mode?: string; preference?: string } | null | undefined): ThemePreference {
-  if (s?.preference === "light" || s?.preference === "dark" || s?.preference === "system") {
-    return s.preference;
-  }
-  if (s?.mode === "light" || s?.mode === "dark") return s.mode;
-  return "system";
-}
-
-/**
- * Toggle the `.dark` class on <html> for a resolved light/dark mode, and say the same
- * to the BROWSER through `color-scheme` (0.47, keksdose dev #600): the class switches
- * the kit's tokens, but everything the browser paints itself — a native `<select>`'s
- * open list, a date input's popup, scrollbars, autofill — follows `color-scheme` only,
- * and stayed light on the dark theme. Inline on <html>, so it holds whatever an app's
- * stylesheet says, and it is set by the pre-paint {@link applyPersistedTheme} too.
- */
-function applyThemeClass(mode: ThemeMode): void {
-  const root = document.documentElement;
-  if (mode === "dark") root.classList.add("dark");
-  else root.classList.remove("dark");
-  root.style.colorScheme = mode;
-}
-
-/** zustand's envelope, any object; `preferenceFromState` reads only the two names it knows. */
-const isEnvelope = (blob: unknown): blob is { state?: { mode?: string; preference?: string } } =>
-  typeof blob === "object" && blob !== null;
-
-/**
- * Pre-hydration: read the theme PREFERENCE persisted under `storageKey` straight
- * from localStorage, resolve it to a concrete light/dark mode, and toggle the
- * `.dark` class (and `color-scheme`) on <html> — BEFORE React and the store mount,
- * so the first paint already has the right theme (no flash). Returns the resolved
- * mode so the caller can chain {@link applyPersistedPalette}. Encapsulates the
- * zustand-persist envelope + the legacy `mode`→`preference` fallback so apps never re-type the
- * storage shape in their entrypoint.
- */
-export function applyPersistedTheme(storageKey: string): ThemeMode {
-  // Absent, blocked or malformed storage → "system", through `preferenceFromState`.
-  const preference = preferenceFromState(readStoredJson(storageKey, isEnvelope)?.state);
-  const mode = resolve(preference);
-  applyThemeClass(mode);
-  return mode;
-}
-
-/**
- * Build a theme store bound to a consumer-supplied localStorage key. Tracks a
- * light/dark/system PREFERENCE (feedback #330) and exposes the resolved `mode`.
- * Returns the `useTheme` hook plus a `useApplyTheme` effect that toggles the
- * `.dark` class on <html> and, while on "system", follows OS theme changes live.
- */
-export function createThemeStore(storageKey: string) {
-  const useTheme = create<ThemeState>()(
-    logger(
-      persist(
-        (set, get) => ({
-          preference: "system" as ThemePreference,
-          mode: systemPreference(),
-          setPreference: (preference) => set({ preference, mode: resolve(preference) }),
-          setMode: (mode) => set({ preference: mode, mode }),
-          toggle: () => {
-            const next: ThemeMode = get().mode === "dark" ? "light" : "dark";
-            set({ preference: next, mode: next });
-          },
-        }),
-        {
-          name: storageKey,
-          version: 2,
-          // Only the preference is persisted; `mode` is derived on load.
-          partialize: (s) => ({ preference: s.preference }),
-          migrate: (persistedState): { preference: ThemePreference } => ({
-            preference: preferenceFromState(persistedState as { mode?: string; preference?: string } | null),
-          }),
-          onRehydrateStorage: () => (state) => {
-            // The persisted preference decides the concrete mode at load.
-            if (state) state.mode = resolve(state.preference);
-          },
-        },
-      ),
-      "theme",
-    ),
-  );
-  // Reset this device's settings (docs/settings-harmonization.md §11.4): back to
-  // "System" through the setter, which re-resolves `mode`; `useApplyTheme` puts the
-  // class back and follows the OS again, and the persisted blob is what the pre-paint
-  // `applyPersistedTheme` reads next load.
-  registerDeviceSetting({
-    key: storageKey,
-    kind: "appearance",
-    reset: () => useTheme.getState().setPreference("system"),
-  });
-
-  function useApplyTheme(): void {
-    const mode = useTheme((s) => s.mode);
-    const preference = useTheme((s) => s.preference);
-    useEffect(() => {
-      applyThemeClass(mode);
-    }, [mode]);
-    // While tracking the system, follow OS theme changes live.
-    useEffect(() => {
-      if (preference !== "system") return;
-      let mq: MediaQueryList;
-      try {
-        mq = window.matchMedia("(prefers-color-scheme: dark)");
-      } catch {
-        return;
-      }
-      const onChange = () => useTheme.setState({ mode: mq.matches ? "dark" : "light" });
-      onChange();
-      mq.addEventListener?.("change", onChange);
-      return () => mq.removeEventListener?.("change", onChange);
-    }, [preference]);
-  }
-
-  return { useTheme, useApplyTheme };
-}
-
-export type ThemeStore = ReturnType<typeof createThemeStore>;

package/src/tour/tour-catalogue-labels.ts

@@ -1,75 +0,0 @@
-// The English words of `TourCatalogue` and `TourCatalogueCard` (docs/tours-harmonization.md
-// §3), in a module with no component code, like every `*-labels.ts` (0.34, KS U8).
-// keksdose's reviewed words (tour.* in its en.json) where it had them.
-
-/** The `tourCatalogue` namespace. Counts arrive as numbers, dates already formatted. */
-export interface TourCatalogueLabels {
-  /** The search box's name. */
-  searchLabel: string;
-  searchPlaceholder: string;
-  /** The group select's name (keksdose: "Topic"). */
-  groupLabel: string;
-  /** The select's first option, with the count the other filters leave. */
-  groupAll: (count: number) => string;
-  /** A group's option: its title and its count. */
-  groupOption: (group: string, count: number) => string;
-  /** The all / to do / done toggle's name. */
-  stateLabel: string;
-  stateAll: (count: number) => string;
-  stateTodo: (count: number) => string;
-  stateDone: (count: number) => string;
-  /** Under the filter bar while a filter is on. */
-  showing: (shown: number, total: number) => string;
-  noMatches: string;
-  noMatchesHint: string;
-  clearFilters: string;
-  /** The NEW pill. */
-  badgeNew: string;
-  /** The pill on a tour reset by an update (§8). */
-  badgeUpdated: string;
-  /** A reset tour's line: the update's day (formatted) and its reason (§8); `reason` is
-   *  left out when the tour's update carries none. */
-  resetOn: (date: string, reason?: string) => string;
-  /** The points chip. */
-  points: (count: number) => string;
-  steps: (count: number) => string;
-  /** The duration, in minutes. */
-  duration: (minutes: number) => string;
-  /** Completed, with the day (formatted). */
-  completedOn: (date: string) => string;
-  /** Completed without a date (kastlan's old id list, §6.2). */
-  completed: string;
-  /** Not taken yet — the state icon, for a reader. */
-  notCompleted: string;
-  markUndone: string;
-  start: string;
-  replay: string;
-}
-
-export const DEFAULT_TOUR_CATALOGUE_LABELS: TourCatalogueLabels = {
-  searchLabel: "Search tours",
-  searchPlaceholder: "Search tours…",
-  groupLabel: "Topic",
-  groupAll: (count) => `All topics (${count})`,
-  groupOption: (group, count) => `${group} (${count})`,
-  stateLabel: "Filter tours",
-  stateAll: (count) => `All (${count})`,
-  stateTodo: (count) => `Not taken (${count})`,
-  stateDone: (count) => `Completed (${count})`,
-  showing: (shown, total) => `Showing ${shown} of ${total} tours`,
-  noMatches: "No tour matches",
-  noMatchesHint: "Try another word, or clear the filter.",
-  clearFilters: "Clear filters",
-  badgeNew: "New",
-  badgeUpdated: "Updated",
-  resetOn: (date, reason) => (reason ? `Reset on ${date}: ${reason}` : `Reset on ${date}`),
-  points: (count) => `+${count} pts`,
-  steps: (count) => (count === 1 ? "1 step" : `${count} steps`),
-  duration: (minutes) => `About ${minutes} min`,
-  completedOn: (date) => `Completed on ${date}`,
-  completed: "Completed",
-  notCompleted: "Not completed",
-  markUndone: "Mark as not done",
-  start: "Start",
-  replay: "Replay",
-};