@eifi1/ui-kit 0.51.6 → 0.52.0

package/src/theme/contrast.ts

@@ -2,7 +2,7 @@ import { useEffect } from "react";
 import { create } from "zustand";
 import { persist } from "zustand/middleware";
 import { logger } from "../lib/logger";
-import { readStored } from "../lib/safe-storage";
+import { readStoredJson } from "../lib/safe-storage";
 import { registerDeviceSetting } from "../lib/device-settings";
 import { useMediaQuery } from "../hooks/use-media-query";
 import { CONTRAST_STEPPED_VARS, contrastStep, rememberedTokenSet } from "./contrast-tokens";
@@ -134,15 +134,14 @@ export interface PersistedContrast {
   version?: number;
 }
 
-/** This device's own choice under `storageKey`, or `null` when it never chose. */
+/** The frozen format holding a mode this kit knows — the shape `readStoredJson` admits. */
+const holdsContrast = (blob: unknown): blob is { state: { contrast: ContrastMode } } =>
+  isContrastMode((blob as PersistedContrast | null)?.state?.contrast);
+
+/** 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 mode). */
 export function readPersistedContrast(storageKey: string): ContrastMode | null {
-  try {
-    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedContrast | null;
-    const mode = blob?.state?.contrast;
-    return isContrastMode(mode) ? mode : null;
-  } catch {
-    return null;
-  }
+  return readStoredJson(storageKey, holdsContrast)?.state.contrast ?? null;
 }
 
 /**

package/src/theme/palette-store.ts

@@ -3,11 +3,19 @@ import { create } from "zustand";
 import { persist } from "zustand/middleware";
 import type { StoreApi, UseBoundStore } from "zustand";
 import { logger } from "../lib/logger";
+import { readStoredJson } from "../lib/safe-storage";
 import { registerDeviceSetting } from "../lib/device-settings";
 import type { HeatStops } from "./chart-palette";
 import { applyTokenSet, DEFAULT_PRESET, presetById, type TokenSet } from "./palette-presets";
 import type { ThemeState, ThemeMode } from "./theme-store";
 
+/** zustand's envelope with a preset id in it; anything else (absent, blocked, malformed)
+ *  is the default preset. An unknown id is too — `presetById`'s fallback. */
+const holdsPaletteId = (blob: unknown): blob is { state: { id: string } } => {
+  const id = (blob as { state?: { id?: unknown } } | null)?.state?.id;
+  return typeof id === "string" && id !== "";
+};
+
 /**
  * Pre-hydration counterpart to `applyPersistedTheme`: read the palette id
  * persisted under `storageKey` straight from localStorage and apply that preset's
@@ -16,15 +24,7 @@ import type { ThemeState, ThemeMode } from "./theme-store";
  * state, so an app entrypoint never re-types the persist envelope.
  */
 export function applyPersistedPalette(storageKey: string, mode: ThemeMode): void {
-  let id = DEFAULT_PRESET.id;
-  try {
-    const blob = JSON.parse(localStorage.getItem(storageKey) ?? "{}") as {
-      state?: { id?: string };
-    };
-    if (blob.state?.id) id = blob.state.id;
-  } catch {
-    /* malformed storage → default preset */
-  }
+  const id = readStoredJson(storageKey, holdsPaletteId)?.state.id ?? DEFAULT_PRESET.id;
   applyTokenSet(document.documentElement, presetById(id)[mode]);
 }
 

package/src/theme/text-size.ts

@@ -2,7 +2,7 @@ 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";
+import { readStoredJson } from "../lib/safe-storage";
 import { registerDeviceSetting } from "../lib/device-settings";
 
 /**
@@ -131,16 +131,14 @@ export interface PersistedTextSize {
   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 {
-  try {
-    const blob = JSON.parse(readStored(storageKey) ?? "null") as PersistedTextSize | null;
-    const size = blob?.state?.size;
-    return isTextSize(size) ? size : null;
-  } catch {
-    return null;
-  }
+  return readStoredJson(storageKey, holdsTextSize)?.state.size ?? null;
 }
 
 export interface PersistedAppearanceOptions {

package/src/theme/theme-store.ts

@@ -2,6 +2,7 @@ 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";
@@ -60,6 +61,10 @@ function applyThemeClass(mode: ThemeMode): void {
   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
@@ -70,15 +75,8 @@ function applyThemeClass(mode: ThemeMode): void {
  * storage shape in their entrypoint.
  */
 export function applyPersistedTheme(storageKey: string): ThemeMode {
-  let preference: ThemePreference = "system";
-  try {
-    const blob = JSON.parse(localStorage.getItem(storageKey) ?? "{}") as {
-      state?: { mode?: string; preference?: string };
-    };
-    preference = preferenceFromState(blob.state);
-  } catch {
-    /* malformed storage → system */
-  }
+  // Absent, blocked or malformed storage → "system", through `preferenceFromState`.
+  const preference = preferenceFromState(readStoredJson(storageKey, isEnvelope)?.state);
   const mode = resolve(preference);
   applyThemeClass(mode);
   return mode;

package/src/tour/tour-catalogue.tsx

@@ -1,9 +1,9 @@
 import { useId, type ReactNode } from "react";
 import { Circle, CircleCheck, Clock, Play } from "lucide-react";
 import { cn } from "../lib/cn";
-import { useKitFormat } from "../lib/format";
-import { foldForSearch } from "../lib/text-match";
-import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
+import { useDayFormatter } from "../lib/day-format";
+import { matchesSearch, searchWords } from "../lib/text-match";
+import { useKitLabels, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { Button } from "../components/button";
 import { Card } from "../components/card";
 import { Chip } from "../components/chip";
@@ -31,10 +31,13 @@ export interface TourCatalogueCardProps {
   /** "Mark as not done". Without it, the link is not drawn. */
   onReset?: (id: string) => void;
   /**
-   * Formats the completion and update days. Default: the kit's medium date in the provider's locale.
-   * It gets the completion's ISO instant and the update's bare `"YYYY-MM-DD"` (`updated.date`): read
-   * the bare day on its calendar (the kit's `formatDate`, `parseIsoDate`), never `new Date(day)`,
-   * which is UTC midnight and the day before west of UTC (round 0.45, N9).
+   * Formats the completion and update days. Default (0.52): the `<UiKitProvider formatDate>`
+   * when the app set one — its date preference, no weekday: the day sits in a sentence —
+   * else the kit's medium date in the provider's locale and `timeZone`. It gets the
+   * completion's ISO instant and the update's bare `"YYYY-MM-DD"` (`updated.date`): read the
+   * bare day on its calendar (the kit's `formatDate`, `parseIsoDate`), never `new Date(day)`,
+   * which is UTC midnight and the day before west of UTC (round 0.45, N9). An empty answer
+   * falls back to the kit's.
    */
   formatDate?: (iso: string) => string;
   labels?: LabelOverride<TourCatalogueLabels>;
@@ -61,8 +64,7 @@ export function TourCatalogueCard({
   className,
 }: TourCatalogueCardProps) {
   const words = useKitLabels("tourCatalogue", DEFAULT_TOUR_CATALOGUE_LABELS, labelsProp);
-  const { formatDate } = useKitFormat();
-  const day = formatDateProp ?? ((iso: string) => formatDate(iso, "medium"));
+  const day = useDayFormatter(formatDateProp);
   const titleId = useId();
   const done = isTourDone(tour, completedAt);
   const reset = isTourReset(tour, completedAt);
@@ -210,18 +212,27 @@ export function TourCatalogue({
 }: TourCatalogueProps) {
   const words = useKitLabels("tourCatalogue", DEFAULT_TOUR_CATALOGUE_LABELS, labelsProp);
   const uid = useId();
-  const { locale: kitLocale } = useKitFormat();
-  const locale = localeProp ?? kitLocale;
+  const locale = useKitLocale(localeProp);
   // A group or state the list does not have is no filter at all (an old link).
   const group = groups.some((g) => g.id === groupProp) ? groupProp : null;
   const state = STATE_FILTERS.includes(stateProp) ? stateProp : "all";
 
   const listed = tours.filter((t) => groups.some((g) => g.id === t.group));
   const done = (tour: TourInfo) => isTourDone(tour, completed[tour.id]);
-  const needle = foldForSearch(query.trim(), locale);
+  // Every word somewhere in the title, the one-liner or the about — "budget visits" finds
+  // "Your budget" whose about says "Visits the budget page" — as every kit list searches
+  // since 0.51.4 (refactor audit 2026-10-30, DUP-4: the whole query had to be one
+  // substring of one text).
+  // `|| undefined`: an app's JSON says `null` where TourInfo says absent, and
+  // `matchesSearch` leaves out only `undefined` — `"about": null` threw on the first letter
+  // typed, as the old matcher's `!!text` never did (0.52 code review, tour-catalogue.tsx).
+  const queryWords = searchWords(query, locale);
   const matchesQuery = (tour: TourInfo) =>
-    !needle ||
-    [tour.title, tour.description, tour.about].some((text) => !!text && foldForSearch(text, locale).includes(needle));
+    matchesSearch(
+      queryWords,
+      [tour.title || undefined, tour.description || undefined, tour.about || undefined],
+      locale,
+    );
   const inState = (tour: TourInfo) => (state === "all" ? true : state === "done" ? done(tour) : !done(tour));
   const inGroup = (tour: TourInfo, id: string | null = group) => id === null || tour.group === id;
 
@@ -230,7 +241,7 @@ export function TourCatalogue({
   const visible = found.filter(inState);
   const groupCount = (id: string | null) =>
     listed.filter((t) => matchesQuery(t) && inState(t) && inGroup(t, id)).length;
-  const filtering = needle.length > 0 || state !== "all" || group !== null;
+  const filtering = queryWords.length > 0 || state !== "all" || group !== null;
   const sections = groups
     .map((g) => ({ ...g, tours: visible.filter((t) => t.group === g.id) }))
     .filter((g) => g.tours.length > 0);

package/src/tour/tour-dock.ts

@@ -25,8 +25,6 @@ export interface Band {
   bottom: number;
 }
 
-/** Below this the docked layout applies (Tailwind's `sm`). */
-export const DOCK_MAX_WIDTH = 640;
 /** The gutter between the card and the band's edge, and between the card and the field. */
 const GUTTER = 8;
 /** An obstruction whose top is within this of the band's top covers the screen. */

package/src/tour/tour-gates.ts

@@ -1,4 +1,5 @@
 import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
+import type { TourStep, TourStepContext } from "./tour";
 
 /*
  * # Value gates (docs/tours-harmonization.md §11.1)
@@ -117,6 +118,28 @@ export function createGateRegistry(): GateRegistry {
   };
 }
 
+/*
+ * The step context and `when` (§11.3), asked by the provider on each arrival and by the
+ * overlay (a `beforeStep`, the "Back to …" link). Here rather than in tour.tsx, whose
+ * names reach the barrel through `export *`, and rather than in the overlay, which loads
+ * only once a tour starts (refactor audit 2026-10-30, MOD-1).
+ */
+
+export function stepContext(gates: GateRegistry, via: TourStepContext["via"]): TourStepContext {
+  return { gate: (key) => gates.get(key), via };
+}
+
+/** A step's `when`, asked now; a throw is a skip, and the error goes to the console. */
+export function isShown(step: TourStep, ctx: TourStepContext): boolean {
+  if (!step.when) return true;
+  try {
+    return step.when(ctx) === true;
+  } catch (error) {
+    console.error(error);
+    return false;
+  }
+}
+
 /** What the provider shares with the gate hooks and `TourGuideButton` — internal. */
 export interface TourInternals {
   gates: GateRegistry;