@eifi1/ui-kit 0.4.0

package/dist/theme/palette-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/theme/palette-store.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { create } from \"zustand\";\nimport { persist } from \"zustand/middleware\";\nimport type { StoreApi, UseBoundStore } from \"zustand\";\nimport { logger } from \"../lib/logger\";\nimport type { HeatStops } from \"./chart-palette\";\nimport { applyTokenSet, DEFAULT_PRESET, presetById, type TokenSet } from \"./palette-presets\";\nimport type { ThemeState, ThemeMode } from \"./theme-store\";\n\n/**\n * Pre-hydration counterpart to `applyPersistedTheme`: read the palette id\n * persisted under `storageKey` straight from localStorage and apply that preset's\n * tokens for the given resolved `mode` to <html>, BEFORE React mounts (no flash of\n * the default palette). Falls back to the default preset for missing/malformed\n * state, so an app entrypoint never re-types the persist envelope.\n */\nexport function applyPersistedPalette(storageKey: string, mode: ThemeMode): void {\n  let id = DEFAULT_PRESET.id;\n  try {\n    const blob = JSON.parse(localStorage.getItem(storageKey) ?? \"{}\") as {\n      state?: { id?: string };\n    };\n    if (blob.state?.id) id = blob.state.id;\n  } catch {\n    /* malformed storage → default preset */\n  }\n  applyTokenSet(document.documentElement, presetById(id)[mode]);\n}\n\n// The palette layer flips the whole app between candidate appearance presets at\n// runtime (feedback #307), re-skinning every token-driven surface and chart.\n// Persisted like the theme so a reload keeps the selection.\ninterface PaletteState {\n  id: string;\n  setId: (id: string) => void;\n}\n\n/**\n * Build a palette store bound to a consumer-supplied localStorage key, wired to\n * that app's theme store (for the active light/dark mode). Returns the palette\n * hook plus the effect + selector hooks that read the active preset's tokens.\n */\nexport function createPaletteStore(\n  storageKey: string,\n  useTheme: UseBoundStore<StoreApi<ThemeState>>,\n) {\n  const usePalette = create<PaletteState>()(\n    logger(\n      persist(\n        (set) => ({\n          id: DEFAULT_PRESET.id,\n          setId: (id) => set({ id }),\n        }),\n        { name: storageKey, version: 1 },\n      ),\n      \"palette\",\n    ),\n  );\n\n  /** Apply the active preset's tokens to <html> as inline CSS custom properties,\n   *  re-applying when the preset or the light/dark theme changes. Tailwind v4\n   *  strips a bare root token block from the bundle, so this inline write from\n   *  the TS source of truth is what actually drives the colours. */\n  function useApplyPalette(): void {\n    const id = usePalette((s) => s.id);\n    const mode = useTheme((s) => s.mode);\n    useEffect(() => {\n      applyTokenSet(document.documentElement, presetById(id)[mode]);\n    }, [id, mode]);\n  }\n\n  /** The active preset's token set for the current theme — the source for the\n   *  JS-interpolated charts (treemap fills, heatmap stops) that can't read CSS\n   *  vars. */\n  function useActiveTokenSet(): TokenSet {\n    const id = usePalette((s) => s.id);\n    const mode = useTheme((s) => s.mode);\n    return presetById(id)[mode];\n  }\n\n  /** The 9 categorical chart hues for the active preset/theme (treemap cells). */\n  function useChartHex(): string[] {\n    return useActiveTokenSet().chart;\n  }\n\n  /** The active preset/theme heatmap interpolation stops. */\n  function useHeatStops(): HeatStops {\n    return useActiveTokenSet().heat;\n  }\n\n  return { usePalette, useApplyPalette, useActiveTokenSet, useChartHex, useHeatStops };\n}\n\nexport type PaletteStore = ReturnType<typeof createPaletteStore>;\n"],"mappings":"AAAA,SAAS,iBAAiB;AAC1B,SAAS,cAAc;AACvB,SAAS,eAAe;AAExB,SAAS,cAAc;AAEvB,SAAS,eAAe,gBAAgB,kBAAiC;AAUlE,SAAS,sBAAsB,YAAoB,MAAuB;AAC/E,MAAI,KAAK,eAAe;AACxB,MAAI;AACF,UAAM,OAAO,KAAK,MAAM,aAAa,QAAQ,UAAU,KAAK,IAAI;AAGhE,QAAI,KAAK,OAAO,GAAI,MAAK,KAAK,MAAM;AAAA,EACtC,QAAQ;AAAA,EAER;AACA,gBAAc,SAAS,iBAAiB,WAAW,EAAE,EAAE,IAAI,CAAC;AAC9D;AAeO,SAAS,mBACd,YACA,UACA;AACA,QAAM,aAAa,OAAqB;AAAA,IACtC;AAAA,MACE;AAAA,QACE,CAAC,SAAS;AAAA,UACR,IAAI,eAAe;AAAA,UACnB,OAAO,CAAC,OAAO,IAAI,EAAE,GAAG,CAAC;AAAA,QAC3B;AAAA,QACA,EAAE,MAAM,YAAY,SAAS,EAAE;AAAA,MACjC;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAMA,WAAS,kBAAwB;AAC/B,UAAM,KAAK,WAAW,CAAC,MAAM,EAAE,EAAE;AACjC,UAAM,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI;AACnC,cAAU,MAAM;AACd,oBAAc,SAAS,iBAAiB,WAAW,EAAE,EAAE,IAAI,CAAC;AAAA,IAC9D,GAAG,CAAC,IAAI,IAAI,CAAC;AAAA,EACf;AAKA,WAAS,oBAA8B;AACrC,UAAM,KAAK,WAAW,CAAC,MAAM,EAAE,EAAE;AACjC,UAAM,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI;AACnC,WAAO,WAAW,EAAE,EAAE,IAAI;AAAA,EAC5B;AAGA,WAAS,cAAwB;AAC/B,WAAO,kBAAkB,EAAE;AAAA,EAC7B;AAGA,WAAS,eAA0B;AACjC,WAAO,kBAAkB,EAAE;AAAA,EAC7B;AAEA,SAAO,EAAE,YAAY,iBAAiB,mBAAmB,aAAa,aAAa;AACrF;","names":[]}

package/dist/theme/theme-store.d.ts

@@ -0,0 +1,57 @@
+import * as zustand_middleware from 'zustand/middleware';
+import * as zustand from 'zustand';
+
+type ThemeMode = "light" | "dark";
+/** What the user chose; "system" tracks the OS `prefers-color-scheme`. */
+type ThemePreference = "light" | "dark" | "system";
+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;
+}
+/**
+ * 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 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.
+ */
+declare function applyPersistedTheme(storageKey: string): ThemeMode;
+/**
+ * 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.
+ */
+declare function createThemeStore(storageKey: string): {
+    useTheme: zustand.UseBoundStore<Omit<zustand.StoreApi<ThemeState>, "setState" | "persist"> & {
+        setState(partial: ThemeState | Partial<ThemeState> | ((state: ThemeState) => ThemeState | Partial<ThemeState>), replace?: false | undefined): unknown;
+        setState(state: ThemeState | ((state: ThemeState) => ThemeState), replace: true): unknown;
+        persist: {
+            setOptions: (options: Partial<zustand_middleware.PersistOptions<ThemeState, {
+                preference: ThemePreference;
+            }, unknown>>) => void;
+            clearStorage: () => void;
+            rehydrate: () => Promise<void> | void;
+            hasHydrated: () => boolean;
+            onHydrate: (fn: (state: ThemeState) => void) => () => void;
+            onFinishHydration: (fn: (state: ThemeState) => void) => () => void;
+            getOptions: () => Partial<zustand_middleware.PersistOptions<ThemeState, {
+                preference: ThemePreference;
+            }, unknown>>;
+        };
+    }>;
+    useApplyTheme: () => void;
+};
+type ThemeStore = ReturnType<typeof createThemeStore>;
+
+export { type ThemeMode, type ThemePreference, type ThemeState, type ThemeStore, applyPersistedTheme, createThemeStore };

package/dist/theme/theme-store.js

@@ -0,0 +1,96 @@
+import { useEffect } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger.js";
+function systemPreference() {
+  try {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  } catch {
+    return "light";
+  }
+}
+function resolve(preference) {
+  return preference === "system" ? systemPreference() : preference;
+}
+function preferenceFromState(s) {
+  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";
+}
+function applyThemeClass(mode) {
+  const root = document.documentElement;
+  if (mode === "dark") root.classList.add("dark");
+  else root.classList.remove("dark");
+}
+function applyPersistedTheme(storageKey) {
+  let preference = "system";
+  try {
+    const blob = JSON.parse(localStorage.getItem(storageKey) ?? "{}");
+    preference = preferenceFromState(blob.state);
+  } catch {
+  }
+  const mode = resolve(preference);
+  applyThemeClass(mode);
+  return mode;
+}
+function createThemeStore(storageKey) {
+  const useTheme = create()(
+    logger(
+      persist(
+        (set, get) => ({
+          preference: "system",
+          mode: systemPreference(),
+          setPreference: (preference) => set({ preference, mode: resolve(preference) }),
+          setMode: (mode) => set({ preference: mode, mode }),
+          toggle: () => {
+            const next = 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: preferenceFromState(
+              persistedState
+            )
+          }),
+          onRehydrateStorage: () => (state) => {
+            if (state) state.mode = resolve(state.preference);
+          }
+        }
+      ),
+      "theme"
+    )
+  );
+  function useApplyTheme() {
+    const mode = useTheme((s) => s.mode);
+    const preference = useTheme((s) => s.preference);
+    useEffect(() => {
+      applyThemeClass(mode);
+    }, [mode]);
+    useEffect(() => {
+      if (preference !== "system") return;
+      let mq;
+      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 {
+  applyPersistedTheme,
+  createThemeStore
+};
+//# sourceMappingURL=theme-store.js.map

package/dist/theme/theme-store.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/theme/theme-store.ts"],"sourcesContent":["import { useEffect } from \"react\";\nimport { create } from \"zustand\";\nimport { persist } from \"zustand/middleware\";\nimport { logger } from \"../lib/logger\";\n\nexport type ThemeMode = \"light\" | \"dark\";\n/** What the user chose; \"system\" tracks the OS `prefers-color-scheme`. */\nexport type ThemePreference = \"light\" | \"dark\" | \"system\";\n\nexport interface ThemeState {\n  /** The user's choice (persisted). */\n  preference: ThemePreference;\n  /** The RESOLVED light/dark actually in effect (system → OS). Read this for\n   *  anything that needs the concrete theme (e.g. token selection, toasts). */\n  mode: ThemeMode;\n  setPreference: (preference: ThemePreference) => void;\n  /** Set an explicit light/dark choice (preference follows). */\n  setMode: (mode: ThemeMode) => void;\n  /** Flip the effective theme to the opposite explicit choice. */\n  toggle: () => void;\n}\n\nfunction systemPreference(): ThemeMode {\n  try {\n    return window.matchMedia(\"(prefers-color-scheme: dark)\").matches ? \"dark\" : \"light\";\n  } catch {\n    return \"light\";\n  }\n}\n\nfunction resolve(preference: ThemePreference): ThemeMode {\n  return preference === \"system\" ? systemPreference() : preference;\n}\n\n/** Normalize a persisted theme-state blob to a valid preference. Older blobs\n *  persisted the concrete `mode` (light/dark); carry that over as an explicit\n *  preference so the choice survives. Shared by the store's `migrate` and the\n *  pre-hydration {@link applyPersistedTheme}. */\nfunction preferenceFromState(\n  s: { mode?: string; preference?: string } | null | undefined,\n): ThemePreference {\n  if (s?.preference === \"light\" || s?.preference === \"dark\" || s?.preference === \"system\") {\n    return s.preference;\n  }\n  if (s?.mode === \"light\" || s?.mode === \"dark\") return s.mode;\n  return \"system\";\n}\n\n/** Toggle the `.dark` class on <html> for a resolved light/dark mode. */\nfunction applyThemeClass(mode: ThemeMode): void {\n  const root = document.documentElement;\n  if (mode === \"dark\") root.classList.add(\"dark\");\n  else root.classList.remove(\"dark\");\n}\n\n/**\n * Pre-hydration: read the theme PREFERENCE persisted under `storageKey` straight\n * from localStorage, resolve it to a concrete light/dark mode, and toggle the\n * `.dark` class on <html> — BEFORE React and the store mount, so the first paint\n * already has the right theme (no flash). Returns the resolved mode so the caller\n * can chain {@link applyPersistedPalette}. Encapsulates the zustand-persist\n * envelope + the legacy `mode`→`preference` fallback so apps never re-type the\n * storage shape in their entrypoint.\n */\nexport function applyPersistedTheme(storageKey: string): ThemeMode {\n  let preference: ThemePreference = \"system\";\n  try {\n    const blob = JSON.parse(localStorage.getItem(storageKey) ?? \"{}\") as {\n      state?: { mode?: string; preference?: string };\n    };\n    preference = preferenceFromState(blob.state);\n  } catch {\n    /* malformed storage → system */\n  }\n  const mode = resolve(preference);\n  applyThemeClass(mode);\n  return mode;\n}\n\n/**\n * Build a theme store bound to a consumer-supplied localStorage key. Tracks a\n * light/dark/system PREFERENCE (feedback #330) and exposes the resolved `mode`.\n * Returns the `useTheme` hook plus a `useApplyTheme` effect that toggles the\n * `.dark` class on <html> and, while on \"system\", follows OS theme changes live.\n */\nexport function createThemeStore(storageKey: string) {\n  const useTheme = create<ThemeState>()(\n    logger(\n      persist(\n        (set, get) => ({\n          preference: \"system\" as ThemePreference,\n          mode: systemPreference(),\n          setPreference: (preference) => set({ preference, mode: resolve(preference) }),\n          setMode: (mode) => set({ preference: mode, mode }),\n          toggle: () => {\n            const next: ThemeMode = get().mode === \"dark\" ? \"light\" : \"dark\";\n            set({ preference: next, mode: next });\n          },\n        }),\n        {\n          name: storageKey,\n          version: 2,\n          // Only the preference is persisted; `mode` is derived on load.\n          partialize: (s) => ({ preference: s.preference }),\n          migrate: (persistedState): { preference: ThemePreference } => ({\n            preference: preferenceFromState(\n              persistedState as { mode?: string; preference?: string } | null,\n            ),\n          }),\n          onRehydrateStorage: () => (state) => {\n            // The persisted preference decides the concrete mode at load.\n            if (state) state.mode = resolve(state.preference);\n          },\n        },\n      ),\n      \"theme\",\n    ),\n  );\n\n  function useApplyTheme(): void {\n    const mode = useTheme((s) => s.mode);\n    const preference = useTheme((s) => s.preference);\n    useEffect(() => {\n      applyThemeClass(mode);\n    }, [mode]);\n    // While tracking the system, follow OS theme changes live.\n    useEffect(() => {\n      if (preference !== \"system\") return;\n      let mq: MediaQueryList;\n      try {\n        mq = window.matchMedia(\"(prefers-color-scheme: dark)\");\n      } catch {\n        return;\n      }\n      const onChange = () => useTheme.setState({ mode: mq.matches ? \"dark\" : \"light\" });\n      onChange();\n      mq.addEventListener?.(\"change\", onChange);\n      return () => mq.removeEventListener?.(\"change\", onChange);\n    }, [preference]);\n  }\n\n  return { useTheme, useApplyTheme };\n}\n\nexport type ThemeStore = ReturnType<typeof createThemeStore>;\n"],"mappings":"AAAA,SAAS,iBAAiB;AAC1B,SAAS,cAAc;AACvB,SAAS,eAAe;AACxB,SAAS,cAAc;AAmBvB,SAAS,mBAA8B;AACrC,MAAI;AACF,WAAO,OAAO,WAAW,8BAA8B,EAAE,UAAU,SAAS;AAAA,EAC9E,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEA,SAAS,QAAQ,YAAwC;AACvD,SAAO,eAAe,WAAW,iBAAiB,IAAI;AACxD;AAMA,SAAS,oBACP,GACiB;AACjB,MAAI,GAAG,eAAe,WAAW,GAAG,eAAe,UAAU,GAAG,eAAe,UAAU;AACvF,WAAO,EAAE;AAAA,EACX;AACA,MAAI,GAAG,SAAS,WAAW,GAAG,SAAS,OAAQ,QAAO,EAAE;AACxD,SAAO;AACT;AAGA,SAAS,gBAAgB,MAAuB;AAC9C,QAAM,OAAO,SAAS;AACtB,MAAI,SAAS,OAAQ,MAAK,UAAU,IAAI,MAAM;AAAA,MACzC,MAAK,UAAU,OAAO,MAAM;AACnC;AAWO,SAAS,oBAAoB,YAA+B;AACjE,MAAI,aAA8B;AAClC,MAAI;AACF,UAAM,OAAO,KAAK,MAAM,aAAa,QAAQ,UAAU,KAAK,IAAI;AAGhE,iBAAa,oBAAoB,KAAK,KAAK;AAAA,EAC7C,QAAQ;AAAA,EAER;AACA,QAAM,OAAO,QAAQ,UAAU;AAC/B,kBAAgB,IAAI;AACpB,SAAO;AACT;AAQO,SAAS,iBAAiB,YAAoB;AACnD,QAAM,WAAW,OAAmB;AAAA,IAClC;AAAA,MACE;AAAA,QACE,CAAC,KAAK,SAAS;AAAA,UACb,YAAY;AAAA,UACZ,MAAM,iBAAiB;AAAA,UACvB,eAAe,CAAC,eAAe,IAAI,EAAE,YAAY,MAAM,QAAQ,UAAU,EAAE,CAAC;AAAA,UAC5E,SAAS,CAAC,SAAS,IAAI,EAAE,YAAY,MAAM,KAAK,CAAC;AAAA,UACjD,QAAQ,MAAM;AACZ,kBAAM,OAAkB,IAAI,EAAE,SAAS,SAAS,UAAU;AAC1D,gBAAI,EAAE,YAAY,MAAM,MAAM,KAAK,CAAC;AAAA,UACtC;AAAA,QACF;AAAA,QACA;AAAA,UACE,MAAM;AAAA,UACN,SAAS;AAAA;AAAA,UAET,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW;AAAA,UAC/C,SAAS,CAAC,oBAAqD;AAAA,YAC7D,YAAY;AAAA,cACV;AAAA,YACF;AAAA,UACF;AAAA,UACA,oBAAoB,MAAM,CAAC,UAAU;AAEnC,gBAAI,MAAO,OAAM,OAAO,QAAQ,MAAM,UAAU;AAAA,UAClD;AAAA,QACF;AAAA,MACF;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,WAAS,gBAAsB;AAC7B,UAAM,OAAO,SAAS,CAAC,MAAM,EAAE,IAAI;AACnC,UAAM,aAAa,SAAS,CAAC,MAAM,EAAE,UAAU;AAC/C,cAAU,MAAM;AACd,sBAAgB,IAAI;AAAA,IACtB,GAAG,CAAC,IAAI,CAAC;AAET,cAAU,MAAM;AACd,UAAI,eAAe,SAAU;AAC7B,UAAI;AACJ,UAAI;AACF,aAAK,OAAO,WAAW,8BAA8B;AAAA,MACvD,QAAQ;AACN;AAAA,MACF;AACA,YAAM,WAAW,MAAM,SAAS,SAAS,EAAE,MAAM,GAAG,UAAU,SAAS,QAAQ,CAAC;AAChF,eAAS;AACT,SAAG,mBAAmB,UAAU,QAAQ;AACxC,aAAO,MAAM,GAAG,sBAAsB,UAAU,QAAQ;AAAA,IAC1D,GAAG,CAAC,UAAU,CAAC;AAAA,EACjB;AAEA,SAAO,EAAE,UAAU,cAAc;AACnC;","names":[]}

package/dist/tour/tour.d.ts

@@ -0,0 +1,104 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+type TourPlacement = "top" | "right" | "bottom" | "left" | "center";
+interface TourStep {
+    /** CSS selector for the element to spotlight. Omit for a centered step
+     *  (welcome/finish). If the target isn't found/visible, the step centers. */
+    target?: string;
+    title: string;
+    body: ReactNode;
+    /** Extra footer content, e.g. a "load sample data" shortcut. */
+    action?: ReactNode;
+    /** Spotlight padding around the target, px (default 8). */
+    padding?: number;
+    /** Where the card sits relative to the target. Omit for auto placement
+     *  (below → above → centered). "center" ignores the target and centers on
+     *  screen. An explicit side flips to the opposite side if it would overflow,
+     *  then clamps into the viewport. */
+    placement?: TourPlacement;
+    /** Advance only when the user clicks the spotlighted target itself (not the
+     *  card's Next button). Requires `target`: the real control's own handler runs
+     *  first, then the tour steps forward on a microtask. The overlay stays
+     *  click-through to the target. */
+    awaitClick?: boolean;
+    /** Runs before the step is shown — e.g. navigate to a route, open a panel.
+     *  May be async; the step waits for it, then locates the target. */
+    beforeStep?: () => void | Promise<void>;
+}
+interface TourLabels {
+    next: string;
+    back: string;
+    skip: string;
+    done: string;
+    /** Shown in place of the Next button on an `awaitClick` step. */
+    awaitClickHint: string;
+    /** Step counter, e.g. (2, 7) => "2 / 7". */
+    step: (current: number, total: number) => string;
+}
+interface StartOptions {
+    /** Stable id of the tour, surfaced as `activeId` so the app can mirror it to
+     *  the URL (deep-link / evaluation tracking) and record completion. */
+    id?: string;
+    /** Start at this step index instead of 0 (clamped) — for URL/deep-link resume. */
+    startIndex?: number;
+    /** Fires synchronously when the tour starts (e.g. enable a mock interceptor). */
+    onStart?: () => void;
+    onFinish?: () => void;
+    onSkip?: () => void;
+}
+interface TourContextValue {
+    active: boolean;
+    /** Id of the running tour (from {@link StartOptions.id}), else null. */
+    activeId: string | null;
+    /** Start a tour with the given steps. */
+    start: (steps: TourStep[], opts?: StartOptions) => void;
+    /** End the current tour (no callbacks fire). */
+    stop: () => void;
+    /** Advance one step; past the last step it finishes the tour (fires onFinish). */
+    next: () => void;
+    /** Go back one step (no-op on the first). */
+    prev: () => void;
+    /** Jump to a step by index, clamped to range — e.g. for URL/deep-link resume. */
+    goToStep: (index: number) => void;
+    /** Current step (0-based; 0 while inactive). */
+    index: number;
+    /** Total steps (0 while inactive). */
+    total: number;
+}
+declare function useTour(): TourContextValue;
+/**
+ * The tour engine if it is there, `null` if it is not — for a control that is a
+ * DECORATION rather than a participant.
+ *
+ * {@link useTour}'s throw is correct and stays: a component that runs a tour cannot do
+ * its job without the provider, and failing loudly is how that gets fixed. But the
+ * throw's blast radius is whatever error boundary is above it, and for a launcher in
+ * the app shell that is the whole app.
+ *
+ * Keksdose feedback dev#524 is what that costs: an `@hb/ui` module was edited while a
+ * dev server was running, vite re-evaluated it, and the module's freshly created
+ * context object was no longer the one the mounted provider was providing. React's
+ * `useContext` then answers `null` for a provider that is, structurally, right there —
+ * and the top bar's tour menu took the entire shell down with it. **Build-time module
+ * graphs cannot produce that**, so it is a development-only failure; a menu that
+ * disappears for a second is the proportionate response to it either way.
+ *
+ * Only for controls that can honestly render nothing. If a component would show a
+ * broken half of itself without the tour, it wants {@link useTour}.
+ */
+declare function useTourOptional(): TourContextValue | null;
+/**
+ * Provides the guided-tour engine: a dimmed spotlight overlay + step card driven
+ * by a list of {@link TourStep}s. Domain-free — the app supplies the steps (copy,
+ * selectors, per-step navigation, placement) and the translated {@link TourLabels}.
+ * Mount once inside the router; start a tour from anywhere via {@link useTour},
+ * which also exposes step control (`next`/`prev`/`goToStep`) and the current
+ * `index`/`total` for URL mirroring, `awaitClick` and deep-link resume.
+ */
+declare function TourProvider({ children, labels, }: {
+    children: ReactNode;
+    labels?: Partial<TourLabels>;
+}): react.JSX.Element;
+
+export { type TourLabels, type TourPlacement, TourProvider, type TourStep, useTour, useTourOptional };

package/dist/tour/tour.js

@@ -0,0 +1,351 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState
+} from "react";
+import { createPortal } from "react-dom";
+import { cn } from "../lib/cn.js";
+import { Button } from "../components/ui.js";
+const DEFAULT_LABELS = {
+  next: "Next",
+  back: "Back",
+  skip: "Skip",
+  done: "Done",
+  awaitClickHint: "Click the highlighted element to continue",
+  step: (c, t) => `${c} / ${t}`
+};
+const TourContext = createContext(null);
+function useTour() {
+  const ctx = useContext(TourContext);
+  if (!ctx) throw new Error("useTour must be used within <TourProvider>");
+  return ctx;
+}
+function useTourOptional() {
+  return useContext(TourContext);
+}
+function TourProvider({
+  children,
+  labels
+}) {
+  const merged = { ...DEFAULT_LABELS, ...labels };
+  const [steps, setSteps] = useState(null);
+  const [index, setIndex] = useState(0);
+  const [activeId, setActiveId] = useState(null);
+  const optsRef = useRef({});
+  const stepsRef = useRef(null);
+  stepsRef.current = steps;
+  const indexRef = useRef(0);
+  indexRef.current = index;
+  const active = !!steps && steps.length > 0;
+  const total = steps?.length ?? 0;
+  const start = useCallback((s, opts) => {
+    optsRef.current = opts ?? {};
+    optsRef.current.onStart?.();
+    setIndex(Math.min(Math.max(0, opts?.startIndex ?? 0), Math.max(0, s.length - 1)));
+    setActiveId(opts?.id ?? null);
+    setSteps(s);
+  }, []);
+  const stop = useCallback(() => {
+    setSteps(null);
+    setActiveId(null);
+  }, []);
+  const finish = useCallback(() => {
+    optsRef.current.onFinish?.();
+    setSteps(null);
+    setActiveId(null);
+  }, []);
+  const skip = useCallback(() => {
+    optsRef.current.onSkip?.();
+    setSteps(null);
+    setActiveId(null);
+  }, []);
+  const goToStep = useCallback((i) => {
+    const len = stepsRef.current?.length ?? 0;
+    if (len === 0) return;
+    setIndex(Math.min(Math.max(0, i), len - 1));
+  }, []);
+  const next = useCallback(() => {
+    const len = stepsRef.current?.length ?? 0;
+    if (len === 0) return;
+    if (indexRef.current >= len - 1) finish();
+    else setIndex(indexRef.current + 1);
+  }, [finish]);
+  const prev = useCallback(() => {
+    if (indexRef.current > 0) setIndex(indexRef.current - 1);
+  }, []);
+  return /* @__PURE__ */ jsxs(TourContext.Provider, { value: { active, activeId, start, stop, next, prev, goToStep, index, total }, children: [
+    children,
+    active && /* @__PURE__ */ jsx(
+      TourOverlay,
+      {
+        steps,
+        index,
+        labels: merged,
+        onNext: next,
+        onPrev: prev,
+        onSkip: skip
+      }
+    )
+  ] });
+}
+function isVisible(el) {
+  const r = el.getBoundingClientRect();
+  if (r.width <= 0 || r.height <= 0) return false;
+  const style = getComputedStyle(el);
+  return style.visibility !== "hidden" && style.display !== "none";
+}
+function queryVisibleTarget(selector) {
+  const els = document.querySelectorAll(selector);
+  for (const el of els) {
+    if (isVisible(el)) return el;
+  }
+  return null;
+}
+function sameRect(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+}
+function TourOverlay({
+  steps,
+  index,
+  labels,
+  onNext,
+  onPrev,
+  onSkip
+}) {
+  const step = steps[index];
+  const isFirst = index === 0;
+  const isLast = index === steps.length - 1;
+  const [rect, setRect] = useState(null);
+  const [ready, setReady] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    let raf = 0;
+    setReady(false);
+    setRect(null);
+    void (async () => {
+      await step.beforeStep?.();
+      if (cancelled) return;
+      if (!step.target) {
+        setReady(true);
+        return;
+      }
+      let tries = 0;
+      const find = () => {
+        if (cancelled) return;
+        const el = queryVisibleTarget(step.target);
+        if (el) {
+          el.scrollIntoView({ block: "center", behavior: "smooth" });
+          const r = el.getBoundingClientRect();
+          setRect({ top: r.top, left: r.left, width: r.width, height: r.height });
+          setReady(true);
+          return;
+        }
+        if (tries++ < 45) raf = requestAnimationFrame(find);
+        else setReady(true);
+      };
+      find();
+    })();
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(raf);
+    };
+  }, [index, step]);
+  useEffect(() => {
+    if (!step.target) return;
+    const update = () => {
+      const el = queryVisibleTarget(step.target);
+      if (el) {
+        const r = el.getBoundingClientRect();
+        const next = { top: r.top, left: r.left, width: r.width, height: r.height };
+        setRect((prev) => sameRect(prev, next) ? prev : next);
+      }
+    };
+    window.addEventListener("scroll", update, true);
+    window.addEventListener("resize", update);
+    const id = window.setInterval(update, 250);
+    return () => {
+      window.removeEventListener("scroll", update, true);
+      window.removeEventListener("resize", update);
+      clearInterval(id);
+    };
+  }, [index, step]);
+  useEffect(() => {
+    if (!ready || !step.awaitClick || !step.target) return;
+    const el = queryVisibleTarget(step.target);
+    if (!el) return;
+    const onClick = () => window.setTimeout(() => onNext(), 0);
+    el.addEventListener("click", onClick, { once: true });
+    return () => el.removeEventListener("click", onClick);
+  }, [ready, index, step, onNext]);
+  useEffect(() => {
+    const onKey = (e) => {
+      if (e.key === "Escape") {
+        onSkip();
+      } else if (e.key === "ArrowRight") {
+        e.preventDefault();
+        onNext();
+      } else if (e.key === "Enter") {
+        if (step.awaitClick) return;
+        e.preventDefault();
+        onNext();
+      } else if (e.key === "ArrowLeft") {
+        if (!isFirst) onPrev();
+      }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [isFirst, step, onNext, onPrev, onSkip]);
+  if (!ready) return null;
+  const pad = step.padding ?? 8;
+  const spot = rect ? { top: rect.top - pad, left: rect.left - pad, width: rect.width + pad * 2, height: rect.height + pad * 2 } : null;
+  return createPortal(
+    /* @__PURE__ */ jsxs("div", { className: "pointer-events-none fixed inset-0 z-[60]", role: "dialog", "aria-modal": "true", "aria-label": step.title, children: [
+      spot ? /* @__PURE__ */ jsx(
+        "div",
+        {
+          className: "pointer-events-none fixed rounded-lg transition-all duration-200 ease-out",
+          style: {
+            top: spot.top,
+            left: spot.left,
+            width: spot.width,
+            height: spot.height,
+            // A two-tone frame, not a single translucent ring.
+            //
+            // The old treatment was `ring-2 ring-white/80` over a 55% scrim, and it
+            // "was barely visible" on the app's blue-tinted surfaces. Two reasons,
+            // and a single ring can't fix either: at 55% the surround stays bright
+            // enough that the un-dimmed hole barely reads AS a hole, and a 80%-white
+            // ring sitting on the edge of a light card is white-on-near-white.
+            //
+            // So: an opaque white band immediately around the target, a dark keyline
+            // outside it, then the scrim. Whatever the target's own colour is, one of
+            // the two bands is always in contrast with it and the other is always in
+            // contrast with the dimmed surround — there is no background that can
+            // swallow both. The blurred layer between them softens the step so the
+            // frame reads as lighting rather than as a pasted-on rectangle.
+            boxShadow: [
+              "0 0 0 3px rgba(255,255,255,0.98)",
+              "0 0 0 5px rgba(15,23,42,0.92)",
+              "0 0 18px 6px rgba(15,23,42,0.45)",
+              "0 0 0 9999px rgba(15,23,42,0.70)"
+            ].join(", ")
+          }
+        }
+      ) : /* @__PURE__ */ jsx("div", { className: "pointer-events-auto fixed inset-0 bg-slate-900/70" }),
+      /* @__PURE__ */ jsx(
+        TourCard,
+        {
+          step,
+          index,
+          total: steps.length,
+          labels,
+          isFirst,
+          isLast,
+          rect: spot,
+          onBack: onPrev,
+          onNext,
+          onSkip
+        }
+      )
+    ] }),
+    document.body
+  );
+}
+function placeCard(rect, cw, ch, vw, vh, m, placement) {
+  if (!rect || placement === "center") {
+    return { top: Math.max(m, (vh - ch) / 2), left: Math.max(m, (vw - cw) / 2) };
+  }
+  const clampX = (x) => Math.min(Math.max(m, x), Math.max(m, vw - cw - m));
+  const clampY = (y) => Math.min(Math.max(m, y), Math.max(m, vh - ch - m));
+  const centerX = clampX(rect.left + rect.width / 2 - cw / 2);
+  const centerY = clampY(rect.top + rect.height / 2 - ch / 2);
+  const belowTop = rect.top + rect.height + m;
+  const aboveTop = rect.top - ch - m;
+  const rightLeft = rect.left + rect.width + m;
+  const leftLeft = rect.left - cw - m;
+  const fitsBelow = belowTop + ch <= vh;
+  const fitsAbove = aboveTop >= 0;
+  const fitsRight = rightLeft + cw <= vw;
+  const fitsLeft = leftLeft >= 0;
+  switch (placement) {
+    case "top":
+      return { top: fitsAbove ? aboveTop : fitsBelow ? belowTop : clampY(aboveTop), left: centerX };
+    case "bottom":
+      return { top: fitsBelow ? belowTop : fitsAbove ? aboveTop : clampY(belowTop), left: centerX };
+    case "right":
+      return { top: centerY, left: fitsRight ? rightLeft : fitsLeft ? leftLeft : clampX(rightLeft) };
+    case "left":
+      return { top: centerY, left: fitsLeft ? leftLeft : fitsRight ? rightLeft : clampX(leftLeft) };
+    default:
+      if (fitsBelow) return { top: belowTop, left: centerX };
+      if (fitsAbove) return { top: aboveTop, left: centerX };
+      return { top: Math.max(m, (vh - ch) / 2), left: centerX };
+  }
+}
+function TourCard({
+  step,
+  index,
+  total,
+  labels,
+  isFirst,
+  isLast,
+  rect,
+  onBack,
+  onNext,
+  onSkip
+}) {
+  const ref = useRef(null);
+  const [style, setStyle] = useState({ opacity: 0 });
+  useLayoutEffect(() => {
+    const card = ref.current;
+    if (!card) return;
+    setStyle(
+      placeCard(rect, card.offsetWidth, card.offsetHeight, window.innerWidth, window.innerHeight, 12, step.placement)
+    );
+  }, [rect, index, step.placement]);
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      ref,
+      style,
+      className: "pointer-events-auto fixed z-[61] w-80 max-w-[calc(100vw-1.5rem)] rounded-lg border border-slate-200 bg-white p-4 shadow-xl transition-all duration-200 ease-out dark:border-slate-700 dark:bg-slate-900",
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "text-sm font-semibold text-slate-900 dark:text-slate-100", children: step.title }),
+        /* @__PURE__ */ jsx("div", { className: "mt-1 text-sm leading-relaxed text-slate-600 dark:text-slate-300", children: step.body }),
+        step.action && /* @__PURE__ */ jsx("div", { className: "mt-3", children: step.action }),
+        /* @__PURE__ */ jsxs("div", { className: "mt-4 space-y-2", children: [
+          /* @__PURE__ */ jsxs("div", { className: "flex items-center justify-between gap-2", children: [
+            /* @__PURE__ */ jsx(
+              "button",
+              {
+                type: "button",
+                onClick: onSkip,
+                className: "text-xs text-slate-400 hover:text-slate-600 dark:text-slate-500 dark:hover:text-slate-300",
+                children: labels.skip
+              }
+            ),
+            /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2", children: [
+              /* @__PURE__ */ jsx("span", { className: "whitespace-nowrap text-xs tabular-nums text-slate-400 dark:text-slate-500", children: labels.step(index + 1, total) }),
+              !isFirst && /* @__PURE__ */ jsx(Button, { variant: "secondary", onClick: onBack, className: "px-2.5 py-1 text-xs", children: labels.back }),
+              !(step.awaitClick && step.target && rect) && /* @__PURE__ */ jsx(Button, { variant: "brand", onClick: onNext, className: cn("px-2.5 py-1 text-xs"), children: isLast ? labels.done : labels.next })
+            ] })
+          ] }),
+          step.awaitClick && step.target && rect && /* @__PURE__ */ jsx("div", { className: "text-center text-xs italic text-slate-400 dark:text-slate-500", children: labels.awaitClickHint })
+        ] })
+      ]
+    }
+  );
+}
+export {
+  TourProvider,
+  useTour,
+  useTourOptional
+};
+//# sourceMappingURL=tour.js.map