@eifi1/ui-kit 0.53.0 → 0.55.0

package/src/tour/tour-gates.ts

@@ -1,218 +0,0 @@
-import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
-import type { TourStep, TourStepContext } from "./tour";
-
-/*
- * # Value gates (docs/tours-harmonization.md §11.1)
- *
- * A form publishes whether a field holds what a tour waits for (`useTourGate`), a step
- * names the key (`TourStep.gate`). The form knows nothing about steps, the step nothing
- * about the form's state: the registry between them is a `Map` held by the provider.
- *
- * - Each key holds a STACK of publishers in mount order; the most recently mounted one
- *   is current. When it unmounts, the one below it is current again. StrictMode's
- *   double mount is push, pop, push.
- * - Writes happen in a layout effect, only when `key` or `satisfied` changes, and never
- *   re-render the provider: only the overlay subscribes (`useSyncExternalStore`), and it
- *   is mounted only while a tour runs.
- * - The same object carries the release bus of `awaitGate` steps (§11.4): `release` and
- *   `refuse` are EVENTS, not states, and are not buffered.
- */
-
-/** One publisher of a key. */
-interface GateEntry {
-  satisfied: boolean;
-}
-
-/** `release(key)` / `refuse(key, reason)` from the app, as the provider hears them. */
-export type GateSignal = { kind: "release"; key: string } | { kind: "refuse"; key: string; reason?: string };
-
-export interface GateRegistry {
-  /** The current publisher's value; `undefined` while nobody publishes `key`. */
-  get(key: string): boolean | undefined;
-  /** Is anyone publishing `key`? */
-  has(key: string): boolean;
-  /** For `useSyncExternalStore`: bumped on every change. */
-  subscribe(listener: () => void): () => void;
-  version(): number;
-  push(key: string, entry: GateEntry): void;
-  pop(key: string, entry: GateEntry): void;
-  changed(key: string): void;
-  /** Whether a tour runs (for the two-publishers warning). */
-  setActive(active: boolean): void;
-  /** The release bus. */
-  listen(listener: (signal: GateSignal) => void): () => void;
-  emit(signal: GateSignal): void;
-}
-
-/** The kit's dev switch (as number-input's): a development build, never under vitest. */
-export function devWarnings(): boolean {
-  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
-}
-
-export function createGateRegistry(): GateRegistry {
-  let active = false;
-  const stacks = new Map<string, GateEntry[]>();
-  const listeners = new Set<() => void>();
-  const signals = new Set<(signal: GateSignal) => void>();
-  const warned = new Set<string>();
-  let version = 0;
-  const notify = (key: string) => {
-    version++;
-    const stack = stacks.get(key);
-    // Two publishers of one key that disagree while a tour runs: the most recent wins,
-    // which is right, but an app keying fields `amount` in two forms wants to hear it.
-    if (stack && stack.length > 1 && active && devWarnings() && !warned.has(key)) {
-      const values = new Set(stack.map((e) => e.satisfied));
-      if (values.size > 1) {
-        warned.add(key);
-        console.warn(
-          `[ui-kit] Two components publish the tour gate "${key}" with different values; the one mounted last ` +
-            "wins. Qualify gate keys by form (`txn.amount`, `account.name`).",
-        );
-      }
-    }
-    for (const listener of listeners) listener();
-  };
-  return {
-    get(key) {
-      const stack = stacks.get(key);
-      return stack && stack.length > 0 ? stack[stack.length - 1].satisfied : undefined;
-    },
-    has(key) {
-      return (stacks.get(key)?.length ?? 0) > 0;
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    },
-    version: () => version,
-    push(key, entry) {
-      const stack = stacks.get(key) ?? [];
-      stack.push(entry);
-      stacks.set(key, stack);
-      notify(key);
-    },
-    pop(key, entry) {
-      const stack = stacks.get(key);
-      if (!stack) return;
-      const at = stack.indexOf(entry);
-      if (at >= 0) stack.splice(at, 1);
-      if (stack.length === 0) stacks.delete(key);
-      notify(key);
-    },
-    changed: notify,
-    setActive(value) {
-      active = value;
-    },
-    listen(listener) {
-      signals.add(listener);
-      return () => {
-        signals.delete(listener);
-      };
-    },
-    emit(signal) {
-      for (const listener of signals) listener(signal);
-    },
-  };
-}
-
-/*
- * 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;
-  /** Did the provider get a `launch`? */
-  canLaunch: boolean;
-}
-
-export const TourInternalContext = createContext<TourInternals | null>(null);
-
-/**
- * Publish whether this field holds what a tour waits for (§11.1): `useTourGate("txn.amount",
- * amount !== "")` beside the field. A step with `gate: "txn.amount"` keeps its Next locked
- * until it is `true`. A key no step names as `gate` is a FACT a step's `when` can ask
- * (`ctx.gate("txn.transfer")`).
- *
- * - `key` `null`/`undefined` publishes nothing: one field component used by a create and
- *   an edit form takes part only in create (`mode === "create" ? "txn.memo" : null`).
- * - Publish the value's state. Do not invent a "touched" gate: a field already filled
- *   when the step arrives (a date prefilled with today) shows Next open at once, which is
- *   intended.
- * - Qualify keys by form (`txn.amount`, not `amount`). Two publishers of one key: the one
- *   mounted last wins.
- * - A no-op without a `TourProvider`, so a form's tests need none. It keeps publishing
- *   while no tour runs, because "Guide me" can start inside a form already filled.
- */
-export function useTourGate(key: string | null | undefined, satisfied: boolean): void {
-  const gates = useContext(TourInternalContext)?.gates ?? null;
-  const entryRef = useRef<GateEntry | null>(null);
-  const satisfiedRef = useRef(satisfied);
-  useLayoutEffect(() => {
-    satisfiedRef.current = satisfied;
-    const entry = entryRef.current;
-    if (!gates || key == null || !entry || entry.satisfied === satisfied) return;
-    entry.satisfied = satisfied;
-    gates.changed(key);
-  }, [gates, key, satisfied]);
-  useLayoutEffect(() => {
-    if (!gates || key == null) return;
-    const entry: GateEntry = { satisfied: satisfiedRef.current };
-    entryRef.current = entry;
-    gates.push(key, entry);
-    return () => {
-      entryRef.current = null;
-      gates.pop(key, entry);
-    };
-  }, [gates, key]);
-}
-
-/** What {@link useTourGateRelease} hands back. */
-export interface TourGateRelease {
-  /** The awaited thing happened (a save succeeded): the tour moves past the step that awaits `key`. */
-  release(key: string): void;
-  /** It was refused (a save failed): the step awaiting `key` stays and shows `reason`. */
-  refuse(key: string, reason?: string): void;
-}
-
-const NO_RELEASE: TourGateRelease = { release: () => {}, refuse: () => {} };
-
-/**
- * The signals of `awaitGate` steps (§11.4), usually from a mutation's `onSuccess` /
- * `onError`. Stable identities. No-ops without a provider, and while no tour runs or no
- * step of the run awaits the key: a release is an event and is never buffered.
- */
-export function useTourGateRelease(): TourGateRelease {
-  const gates = useContext(TourInternalContext)?.gates ?? null;
-  return useMemo(
-    () =>
-      gates
-        ? {
-            release: (key: string) => gates.emit({ kind: "release", key }),
-            refuse: (key: string, reason?: string) => gates.emit({ kind: "refuse", key, reason }),
-          }
-        : NO_RELEASE,
-    [gates],
-  );
-}

package/src/tour/tour-guide-button.tsx

@@ -1,64 +0,0 @@
-import { useContext, useId } from "react";
-import type { ReactElement } from "react";
-import { Compass } from "lucide-react";
-import { Button } from "../components/button";
-import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
-import { useTourOptional, type TourAt } from "./tour";
-import { TourInternalContext } from "./tour-gates";
-import { DEFAULT_TOUR_GUIDE_LABELS, type TourGuideLabels } from "./tour-guide-labels";
-
-export { DEFAULT_TOUR_GUIDE_LABELS };
-export type { TourGuideLabels };
-
-export interface TourGuideButtonProps {
-  /** The tour id handed to the provider's `launch`. */
-  tour: string;
-  /** Usually the form's first in-form anchor (`start(tour, { at })`). */
-  at?: TourAt;
-  /** Default `"ghost"`. */
-  variant?: "ghost" | "secondary";
-  /** Default `"sm"`. */
-  size?: "sm" | "md";
-  labels?: LabelOverride<TourGuideLabels>;
-  className?: string;
-}
-
-/**
- * "Guide me" inside a form (docs/tours-harmonization.md §11.5): starts the tour `tour` by id,
- * at `at`, through `TourProvider`'s `launch` — the run starts inside the open form, with no
- * intro and no Back past `at`, and counts as completing the tour (Marcel, Q2).
- *
- * A decoration: it renders nothing without a provider, without `launch`, or while a tour
- * runs. Place it in the form's header or in `FormActions`' `start` slot.
- */
-export function TourGuideButton({
-  tour,
-  at,
-  variant = "ghost",
-  size = "sm",
-  labels,
-  className,
-}: TourGuideButtonProps): ReactElement | null {
-  const engine = useTourOptional();
-  const internals = useContext(TourInternalContext);
-  const words = useKitLabels("tourGuide", DEFAULT_TOUR_GUIDE_LABELS, labels);
-  const descriptionId = useId();
-  if (!engine || !internals?.canLaunch || engine.active) return null;
-  return (
-    <>
-      <Button
-        variant={variant}
-        size={size}
-        className={className}
-        aria-describedby={descriptionId}
-        onClick={() => engine.start(tour, { at })}
-      >
-        <Compass className="size-4" aria-hidden="true" />
-        {words.label}
-      </Button>
-      <span id={descriptionId} hidden>
-        {words.description}
-      </span>
-    </>
-  );
-}

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

@@ -1,15 +0,0 @@
-// The English words of `TourGuideButton` (docs/tours-harmonization.md §11), in a module with
-// no component code, like every `*-labels.ts` (0.34, KS U8).
-
-/** The `tourGuide` namespace: the form's "Guide me". */
-export interface TourGuideLabels {
-  /** The button's text. */
-  label: string;
-  /** Its accessible description. */
-  description: string;
-}
-
-export const DEFAULT_TOUR_GUIDE_LABELS: TourGuideLabels = {
-  label: "Guide me",
-  description: "Walks you through this form, field by field",
-};

package/src/tour/tour-info.ts

@@ -1,144 +0,0 @@
-import type { ReactNode } from "react";
-
-/**
- * The tours an app offers, as data (docs/tours-harmonization.md §2.2, §6) — one list for
- * the tours page (`TourCatalogue`) and the top bar's `TourMenu`. The step lists stay the
- * app's own: the kit's engine runs them (`useTour().start`), and this describes them.
- *
- * The kit takes finished strings, never i18n keys (§6.3, kk K-1). Role- and data-gated
- * tours are filtered by the app before they come in; every count counts what it is given
- * (§6.3, kk K-2, ka F6).
- */
-export interface TourInfo {
-  /** Stable id: what `onLaunch` gets, the progress key, `?tour=`. */
-  id: string;
-  title: string;
-  /** The one-liner under the title (and what the menu could carry). */
-  description?: string;
-  /** The longer account: which screens it visits, what it explains. Shown from `sm`. */
-  about?: string;
-  /** The tour's icon, drawn at 16px in the brand colour. */
-  icon?: ReactNode;
-  /** The id of its `TourGroup`: the section it is listed under. */
-  group: string;
-  /** The page the tour starts on — `TourMenu`'s "On this page". */
-  route?: string;
-  /** The day it shipped (ISO `YYYY-MM-DD`): what makes it NEW (§6.4). Without it, never NEW. */
-  since?: string;
-  /** The last update or fix (§8): a completion from before `updated.date` no longer counts. */
-  updated?: TourUpdate;
-  /** How many steps it has. Left out, the card shows no step count. */
-  steps?: number;
-  /** The points it awards (§6.1). Left out, the card draws no chip (never "0 points"). */
-  points?: number;
-  /** About how long it takes, in minutes — worded by the kit ("About 3 min", §6.5). */
-  duration?: number;
-  /** A chip beside NEW in the app's words — kastlan's practice mode (§6.5, ka F1). */
-  badge?: ReactNode;
-}
-
-/** A tour's last update or fix (§8). One at a time: a later update replaces it. */
-export interface TourUpdate {
-  /** The day it shipped (ISO `YYYY-MM-DD`). */
-  date: string;
-  /** Why, in a short sentence in the app's words: "The import screen moved; the tour follows it now."
-   *  Only shown (the card's reset line); the reset itself reads `date` alone, so an app that
-   *  keeps a reason KEY on its tour definitions passes those to `complete(tour)` as they are. */
-  reason?: string;
-}
-
-/** A section of the tours page, in the app's words and order (§2.3). An empty one is hidden. */
-export interface TourGroup {
-  id: string;
-  title: string;
-  /** The help line under the heading. */
-  help?: string;
-  /** The heading's icon, drawn at 16px. */
-  icon?: ReactNode;
-}
-
-/**
- * Which tours are completed and when: tour id → the ISO timestamp of the completion, or
- * `null` for one recorded without a date (kastlan's old id list, §6.2; stored as `""`,
- * §9.6.6). A tour that is not a key is untaken.
- */
-export type TourCompletions = Readonly<Record<string, string | null>>;
-
-/** The calendar day of an ISO date or timestamp — `"2026-10-17T08:00:00Z"` → `"2026-10-17"`. */
-const dayOf = (iso: string) => iso.slice(0, 10);
-
-/** What a reset reads of a tour (§8): the update's day, nothing else. */
-type TourUpdated = { updated?: { date: string } | null };
-
-const BARE_DAY = /^\d{4}-\d{2}-\d{2}$/;
-
-/** The start of an ISO day (`YYYY-MM-DD`) in THIS device's time zone, as an instant. */
-function startOfLocalDay(day: string): number {
-  const [y, m, d] = dayOf(day).split("-").map(Number);
-  return new Date(y, m - 1, d).getTime();
-}
-
-/** A completion as an instant: a timestamp as written, a bare day from its local start. */
-const instantOf = (iso: string) => (BARE_DAY.test(iso) ? startOfLocalDay(iso) : Date.parse(iso));
-
-/**
- * Is this tour NEW for the person looking at it (§2.4, §6.4)? It shipped AFTER the
- * account was opened — compared by calendar day, so a tour shipped on the joining day was
- * already there to be found — and it is not taken yet. No `since`, or no `joined` date,
- * is never NEW: a pill that appears late is better than one that flickers, and a first
- * tour shipped with a feature should not flash NEW at every older account (KS, ka F7).
- *
- * `completed` is whether the tour was EVER completed — a tour reset by an update (§8) is
- * not NEW again; it carries the "Updated" pill instead, and `since` stays its first ship
- * date.
- */
-export function isTourNew({
-  since,
-  joined,
-  completed,
-}: {
-  since?: string | null;
-  /** The account's `created_at` (a date or a timestamp); unknown → never NEW. */
-  joined?: string | null;
-  completed?: boolean;
-}): boolean {
-  return !!since && !!joined && dayOf(since) > dayOf(joined) && !completed;
-}
-
-/**
- * Was this completion reset by an update (§8)? True when the tour carries `updated` and
- * the completion happened BEFORE the update day began on this device — instants compared:
- * the completion's timestamp against the start of `updated.date` in local time, so one
- * taken at 00:30 in Zurich on the update day counts (its UTC day is the day before) — or
- * has no date at all, which predates any update. A tour never completed (`completedAt`
- * undefined) is never reset: for that person there is nothing to reset. The check itself
- * deletes nothing; a new `complete(tour)` replaces the old date.
- */
-export function isTourReset(tour: TourUpdated, completedAt: string | null | undefined): boolean {
-  if (completedAt === undefined || !tour.updated) return false;
-  return completedAt === null || instantOf(completedAt) < startOfLocalDay(tour.updated.date);
-}
-
-/** Does this completion count — completed, and not reset by a later update (§8)? */
-export function isTourDone(tour: TourUpdated, completedAt: string | null | undefined): boolean {
-  return completedAt !== undefined && !isTourReset(tour, completedAt);
-}
-
-/**
- * How many of `tours` count as done (§8): the header's "x of y". A tour reset by an update
- * does not count until it is taken again, as on its card.
- */
-export function doneCount(tours: readonly ({ id: string } & TourUpdated)[], completed: TourCompletions): number {
-  return tours.filter((tour) => isTourDone(tour, completed[tour.id])).length;
-}
-
-/**
- * The points earned on `tours` (§6.1, §8): the sum of each done tour's `points`. A reset
- * tour's points are not earned until it is taken again; a tour without points adds none.
- */
-export function earnedPoints(
-  tours: readonly ({ id: string; points?: number | null } & TourUpdated)[],
-  completed: TourCompletions,
-): number {
-  return tours.reduce((sum, tour) => sum + (isTourDone(tour, completed[tour.id]) ? (tour.points ?? 0) : 0), 0);
-}

package/src/tour/tour-labels.ts

@@ -1,23 +0,0 @@
-// The English words of ./tour, in a module with no component code: the English catalogue
-// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk
-// like the other languages (0.34, KS U8). ./tour re-exports them.
-
-import type { TourLabels } from "./tour";
-
-export const DEFAULT_TOUR_LABELS: TourLabels = {
-  next: "Next",
-  back: "Back",
-  skip: "Skip",
-  done: "Done",
-  awaitClickHint: "Click the highlighted element to continue",
-  awaitInputHint: "Enter a value in the highlighted field to continue",
-  step: (c, t) => `${c} / ${t}`,
-  // 0.50: guided form tours (docs/tours-harmonization.md §11).
-  leaveEmpty: "Leave empty",
-  optional: "Optional",
-  gateHint: "Fill in the highlighted field to continue",
-  gateReady: "Ready. Press Next or Enter to continue.",
-  awaitGateHint: "Save to continue",
-  awaitGateRefused: "That wasn’t saved yet. Check the form and try again.",
-  backToStep: (title) => `Back to “${title}”`,
-};