@eifi1/ui-kit 0.48.2 → 0.50.0

package/dist/tour/tour-gates.js

@@ -0,0 +1,114 @@
+"use client";
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
+function devWarnings() {
+  return Boolean(import.meta.env?.DEV) && !import.meta.env?.VITEST;
+}
+function createGateRegistry() {
+  let active = false;
+  const stacks = /* @__PURE__ */ new Map();
+  const listeners = /* @__PURE__ */ new Set();
+  const signals = /* @__PURE__ */ new Set();
+  const warned = /* @__PURE__ */ new Set();
+  let version = 0;
+  const notify = (key) => {
+    version++;
+    const stack = stacks.get(key);
+    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 : void 0;
+    },
+    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);
+    }
+  };
+}
+const TourInternalContext = createContext(null);
+function useTourGate(key, satisfied) {
+  const gates = useContext(TourInternalContext)?.gates ?? null;
+  const entryRef = useRef(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 = { satisfied: satisfiedRef.current };
+    entryRef.current = entry;
+    gates.push(key, entry);
+    return () => {
+      entryRef.current = null;
+      gates.pop(key, entry);
+    };
+  }, [gates, key]);
+}
+const NO_RELEASE = { release: () => {
+}, refuse: () => {
+} };
+function useTourGateRelease() {
+  const gates = useContext(TourInternalContext)?.gates ?? null;
+  return useMemo(
+    () => gates ? {
+      release: (key) => gates.emit({ kind: "release", key }),
+      refuse: (key, reason) => gates.emit({ kind: "refuse", key, reason })
+    } : NO_RELEASE,
+    [gates]
+  );
+}
+export {
+  TourInternalContext,
+  createGateRegistry,
+  devWarnings,
+  useTourGate,
+  useTourGateRelease
+};
+//# sourceMappingURL=tour-gates.js.map

package/dist/tour/tour-gates.js.map

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

package/dist/tour/tour-guide-button.d.ts

@@ -0,0 +1,27 @@
+import type { ReactElement } from "react";
+import { type LabelOverride } from "../i18n/kit-labels.js";
+import { type TourAt } from "./tour.js";
+import { DEFAULT_TOUR_GUIDE_LABELS, type TourGuideLabels } from "./tour-guide-labels.js";
+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 declare function TourGuideButton({ tour, at, variant, size, labels, className, }: TourGuideButtonProps): ReactElement | null;

package/dist/tour/tour-guide-button.js

@@ -0,0 +1,45 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useContext, useId } from "react";
+import { Compass } from "lucide-react";
+import { Button } from "../components/button.js";
+import { useKitLabels } from "../i18n/kit-labels.js";
+import { useTourOptional } from "./tour.js";
+import { TourInternalContext } from "./tour-gates.js";
+import { DEFAULT_TOUR_GUIDE_LABELS } from "./tour-guide-labels.js";
+function TourGuideButton({
+  tour,
+  at,
+  variant = "ghost",
+  size = "sm",
+  labels,
+  className
+}) {
+  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 /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs(
+      Button,
+      {
+        variant,
+        size,
+        className,
+        "aria-describedby": descriptionId,
+        onClick: () => engine.start(tour, { at }),
+        children: [
+          /* @__PURE__ */ jsx(Compass, { className: "size-4", "aria-hidden": "true" }),
+          words.label
+        ]
+      }
+    ),
+    /* @__PURE__ */ jsx("span", { id: descriptionId, hidden: true, children: words.description })
+  ] });
+}
+export {
+  DEFAULT_TOUR_GUIDE_LABELS,
+  TourGuideButton
+};
+//# sourceMappingURL=tour-guide-button.js.map

package/dist/tour/tour-guide-button.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/tour-guide-button.tsx"],"sourcesContent":["import { useContext, useId } from \"react\";\nimport type { ReactElement } from \"react\";\nimport { Compass } from \"lucide-react\";\nimport { Button } from \"../components/button\";\nimport { useKitLabels, type LabelOverride } from \"../i18n/kit-labels\";\nimport { useTourOptional, type TourAt } from \"./tour\";\nimport { TourInternalContext } from \"./tour-gates\";\nimport { DEFAULT_TOUR_GUIDE_LABELS, type TourGuideLabels } from \"./tour-guide-labels\";\n\nexport { DEFAULT_TOUR_GUIDE_LABELS };\nexport type { TourGuideLabels };\n\nexport interface TourGuideButtonProps {\n  /** The tour id handed to the provider's `launch`. */\n  tour: string;\n  /** Usually the form's first in-form anchor (`start(tour, { at })`). */\n  at?: TourAt;\n  /** Default `\"ghost\"`. */\n  variant?: \"ghost\" | \"secondary\";\n  /** Default `\"sm\"`. */\n  size?: \"sm\" | \"md\";\n  labels?: LabelOverride<TourGuideLabels>;\n  className?: string;\n}\n\n/**\n * \"Guide me\" inside a form (docs/tours-harmonization.md §11.5): starts the tour `tour` by id,\n * at `at`, through `TourProvider`'s `launch` — the run starts inside the open form, with no\n * intro and no Back past `at`, and counts as completing the tour (Marcel, Q2).\n *\n * A decoration: it renders nothing without a provider, without `launch`, or while a tour\n * runs. Place it in the form's header or in `FormActions`' `start` slot.\n */\nexport function TourGuideButton({\n  tour,\n  at,\n  variant = \"ghost\",\n  size = \"sm\",\n  labels,\n  className,\n}: TourGuideButtonProps): ReactElement | null {\n  const engine = useTourOptional();\n  const internals = useContext(TourInternalContext);\n  const words = useKitLabels(\"tourGuide\", DEFAULT_TOUR_GUIDE_LABELS, labels);\n  const descriptionId = useId();\n  if (!engine || !internals?.canLaunch || engine.active) return null;\n  return (\n    <>\n      <Button\n        variant={variant}\n        size={size}\n        className={className}\n        aria-describedby={descriptionId}\n        onClick={() => engine.start(tour, { at })}\n      >\n        <Compass className=\"size-4\" aria-hidden=\"true\" />\n        {words.label}\n      </Button>\n      <span id={descriptionId} hidden>\n        {words.description}\n      </span>\n    </>\n  );\n}\n"],"mappings":";AA+CI,mBAQI,KAPF,YADF;AA/CJ,SAAS,YAAY,aAAa;AAElC,SAAS,eAAe;AACxB,SAAS,cAAc;AACvB,SAAS,oBAAwC;AACjD,SAAS,uBAAoC;AAC7C,SAAS,2BAA2B;AACpC,SAAS,iCAAuD;AA0BzD,SAAS,gBAAgB;AAAA,EAC9B;AAAA,EACA;AAAA,EACA,UAAU;AAAA,EACV,OAAO;AAAA,EACP;AAAA,EACA;AACF,GAA8C;AAC5C,QAAM,SAAS,gBAAgB;AAC/B,QAAM,YAAY,WAAW,mBAAmB;AAChD,QAAM,QAAQ,aAAa,aAAa,2BAA2B,MAAM;AACzE,QAAM,gBAAgB,MAAM;AAC5B,MAAI,CAAC,UAAU,CAAC,WAAW,aAAa,OAAO,OAAQ,QAAO;AAC9D,SACE,iCACE;AAAA;AAAA,MAAC;AAAA;AAAA,QACC;AAAA,QACA;AAAA,QACA;AAAA,QACA,oBAAkB;AAAA,QAClB,SAAS,MAAM,OAAO,MAAM,MAAM,EAAE,GAAG,CAAC;AAAA,QAExC;AAAA,8BAAC,WAAQ,WAAU,UAAS,eAAY,QAAO;AAAA,UAC9C,MAAM;AAAA;AAAA;AAAA,IACT;AAAA,IACA,oBAAC,UAAK,IAAI,eAAe,QAAM,MAC5B,gBAAM,aACT;AAAA,KACF;AAEJ;","names":[]}

package/dist/tour/tour-guide-labels.d.ts

@@ -0,0 +1,8 @@
+/** The `tourGuide` namespace: the form's "Guide me". */
+export interface TourGuideLabels {
+    /** The button's text. */
+    label: string;
+    /** Its accessible description. */
+    description: string;
+}
+export declare const DEFAULT_TOUR_GUIDE_LABELS: TourGuideLabels;

package/dist/tour/tour-guide-labels.js

@@ -0,0 +1,9 @@
+"use client";
+const DEFAULT_TOUR_GUIDE_LABELS = {
+  label: "Guide me",
+  description: "Walks you through this form, field by field"
+};
+export {
+  DEFAULT_TOUR_GUIDE_LABELS
+};
+//# sourceMappingURL=tour-guide-labels.js.map

package/dist/tour/tour-guide-labels.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tour/tour-guide-labels.ts"],"sourcesContent":["// The English words of `TourGuideButton` (docs/tours-harmonization.md §11), in a module with\n// no component code, like every `*-labels.ts` (0.34, KS U8).\n\n/** The `tourGuide` namespace: the form's \"Guide me\". */\nexport interface TourGuideLabels {\n  /** The button's text. */\n  label: string;\n  /** Its accessible description. */\n  description: string;\n}\n\nexport const DEFAULT_TOUR_GUIDE_LABELS: TourGuideLabels = {\n  label: \"Guide me\",\n  description: \"Walks you through this form, field by field\",\n};\n"],"mappings":";AAWO,MAAM,4BAA6C;AAAA,EACxD,OAAO;AAAA,EACP,aAAa;AACf;","names":[]}

package/dist/tour/tour-labels.js

@@ -6,7 +6,15 @@ const DEFAULT_TOUR_LABELS = {
   done: "Done",
   awaitClickHint: "Click the highlighted element to continue",
   awaitInputHint: "Enter a value in the highlighted field to continue",
-  step: (c, t) => `${c} / ${t}`
+  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\u2019t saved yet. Check the form and try again.",
+  backToStep: (title) => `Back to \u201C${title}\u201D`
 };
 export {
   DEFAULT_TOUR_LABELS

package/dist/tour/tour-labels.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/tour/tour-labels.ts"],"sourcesContent":["// The English words of ./tour, in a module with no component code: the English catalogue\n// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk\n// like the other languages (0.34, KS U8). ./tour re-exports them.\n\nimport type { TourLabels } from \"./tour\";\n\nexport const DEFAULT_TOUR_LABELS: TourLabels = {\n  next: \"Next\",\n  back: \"Back\",\n  skip: \"Skip\",\n  done: \"Done\",\n  awaitClickHint: \"Click the highlighted element to continue\",\n  awaitInputHint: \"Enter a value in the highlighted field to continue\",\n  step: (c, t) => `${c} / ${t}`,\n};\n"],"mappings":";AAMO,MAAM,sBAAkC;AAAA,EAC7C,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC;AAC7B;","names":[]}
+{"version":3,"sources":["../../src/tour/tour-labels.ts"],"sourcesContent":["// The English words of ./tour, in a module with no component code: the English catalogue\n// (src/i18n/defaults.ts) imports them without the component, so `en` loads as one chunk\n// like the other languages (0.34, KS U8). ./tour re-exports them.\n\nimport type { TourLabels } from \"./tour\";\n\nexport const DEFAULT_TOUR_LABELS: TourLabels = {\n  next: \"Next\",\n  back: \"Back\",\n  skip: \"Skip\",\n  done: \"Done\",\n  awaitClickHint: \"Click the highlighted element to continue\",\n  awaitInputHint: \"Enter a value in the highlighted field to continue\",\n  step: (c, t) => `${c} / ${t}`,\n  // 0.50: guided form tours (docs/tours-harmonization.md §11).\n  leaveEmpty: \"Leave empty\",\n  optional: \"Optional\",\n  gateHint: \"Fill in the highlighted field to continue\",\n  gateReady: \"Ready. Press Next or Enter to continue.\",\n  awaitGateHint: \"Save to continue\",\n  awaitGateRefused: \"That wasn’t saved yet. Check the form and try again.\",\n  backToStep: (title) => `Back to “${title}”`,\n};\n"],"mappings":";AAMO,MAAM,sBAAkC;AAAA,EAC7C,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,MAAM;AAAA,EACN,gBAAgB;AAAA,EAChB,gBAAgB;AAAA,EAChB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC;AAAA;AAAA,EAE3B,YAAY;AAAA,EACZ,UAAU;AAAA,EACV,UAAU;AAAA,EACV,WAAW;AAAA,EACX,eAAe;AAAA,EACf,kBAAkB;AAAA,EAClB,YAAY,CAAC,UAAU,iBAAY,KAAK;AAC1C;","names":[]}

package/dist/tour/tour.d.ts

@@ -3,12 +3,14 @@ import { type LabelOverride } from "../i18n/kit-labels.js";
 import { DEFAULT_TOUR_LABELS } from "./tour-labels.js";
 import type { TourInfo } from "./tour-info.js";
 import { type UseTourProgressOptions } from "./use-tour-progress.js";
+export { useTourGate, useTourGateRelease } from "./tour-gates.js";
+export type { TourGateRelease } from "./tour-gates.js";
 /**
  * `start`/`end` follow the reading direction (`end` is the right side in LTR and the
  * left side in RTL) and are what a translated app wants. `left`/`right` stay physical
  * for the steps that genuinely mean a screen side.
  */
-export type TourPlacement = "top" | "right" | "bottom" | "left" | "start" | "end" | "center";
+export type TourPlacement = "top" | "right" | "bottom" | "left" | "start" | "end" | "center" | "dock";
 export 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. */
@@ -17,13 +19,22 @@ export interface TourStep {
     body: ReactNode;
     /** Extra footer content, e.g. a "load sample data" shortcut. */
     action?: ReactNode;
-    /** Spotlight padding around the target, px (default 8). */
+    /** Spotlight padding around the target, px (default 8). On a field step the spot also
+     *  takes in the lines the field's `aria-describedby` names when they sit within the
+     *  ring's reach of it (a hint or warning line under the field, keksdose S1, §11.6). */
     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. "start"/"end" are the logical sides and flip in RTL; "left"/"right"
      *  are physical. An explicit side flips to the opposite side if it would
-     *  overflow, then clamps into the viewport. */
+     *  overflow, then clamps into the viewport.
+     *
+     *  `"dock"` (0.50, §11.7): below `sm` (640 px) the card is pinned full-width to the top
+     *  or bottom edge of the usable band — the visual viewport less the keyboard and any
+     *  `[data-tour-obstruction]` (the number pad) — on the edge away from the field, and the
+     *  field's scroll container brings it into the other half. From `sm` up it is auto
+     *  placement. On a phone a field step (`interactive`, `awaitInput`, `gate`, `awaitGate`)
+     *  with a target and no `placement` docks by default (`TourProvider dockOnPhones`). */
     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
@@ -58,9 +69,58 @@ export interface TourStep {
      * button) has nothing to compare: call `useTour().next()` from its `onChange`.
      */
     awaitInput?: boolean;
+    /**
+     * 0.50 (docs/tours-harmonization.md §11.1): Next stays locked until the gate `key` is
+     * satisfied — the form publishes it with `useTourGate(key, satisfied)` beside the field.
+     * Implies `interactive`. The locked Next is `aria-disabled` with {@link gateHint} under
+     * it; pressing it focuses the field. Once satisfied the tour does NOT advance by itself:
+     * Next, Enter in the field, or focus leaving the field to nowhere or to the card (the
+     * number pad's Done) moves on. A key nobody publishes is not enforced (the form closed
+     * under the tour): Next opens. A step may have a `gate` and no `target`.
+     */
+    gate?: string;
+    /** Overrides `labels.gateHint` for this step. */
+    gateHint?: string;
+    /**
+     * 0.50 (§11.4): wait for the app to RELEASE this key — `useTourGateRelease().release(key)`
+     * from the save's `onSuccess`. Implies `interactive`; usually it targets the Save button,
+     * whose hole stays click-through. Next is replaced by {@link awaitGateHint}, and a click
+     * does not advance: only `release` does. A release that arrives on an earlier step (Enter
+     * in the last field submitted the form) jumps past the first later step awaiting the key.
+     * `refuse(key, reason)` keeps the step and shows the reason, with a "Back to …" link to the
+     * first earlier field whose gate is now unsatisfied; the kit never jumps there itself.
+     * A viewer who cannot save gets `awaitGate: undefined`, so a plain Next.
+     */
+    awaitGate?: string;
+    /** Overrides `labels.awaitGateHint` for this step. */
+    awaitGateHint?: string;
+    /**
+     * 0.50 (§11.2): the field may stay empty. While the `gate` is unsatisfied the card
+     * offers "Leave empty" beside the locked Next, which moves on without touching the field
+     * (the kit never writes app values); the title carries an "Optional" chip. Not a skip:
+     * the run continues and can complete. Without a `gate`, only the chip.
+     */
+    optional?: boolean;
+    /**
+     * 0.50 (§11.3): shown only if this returns true on ARRIVAL (evaluated before
+     * `beforeStep`, so a skipped step never navigates). Next walks forward to the first step
+     * shown, Back to the nearest earlier one shown now. Branch facts are gates:
+     * `when: (c) => c.gate("txn.transfer") === true`. Keep it pure and cheap: the counter
+     * evaluates every step's `when` on each arrival. A throw counts as skipped.
+     */
+    when?: (ctx: TourStepContext) => 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>;
+     *  May be async; the step waits for it, then locates the target. Receives the
+     *  {@link TourStepContext} (0.50); a step entered by "Guide me" sees `via: "at"` and
+     *  should leave an open form alone. */
+    beforeStep?: (ctx: TourStepContext) => void | Promise<void>;
+}
+/** What a step's `when` and `beforeStep` may ask on arrival (0.50, §11.3). */
+export interface TourStepContext {
+    /** The gate's current value: true/false, or undefined while nobody publishes it. */
+    gate(key: string): boolean | undefined;
+    /** How this step is being entered. */
+    via: "start" | "at" | "next" | "back" | "goto";
 }
 export interface TourLabels {
     next: string;
@@ -71,10 +131,42 @@ export interface TourLabels {
     awaitClickHint: string;
     /** Shown in place of the Next button on an `awaitInput` step (0.46). */
     awaitInputHint: string;
-    /** Step counter, e.g. (2, 7) => "2 / 7". */
+    /** Step counter, e.g. (2, 7) => "2 / 7". Counts the steps the run shows (0.50). */
     step: (current: number, total: number) => string;
+    /** 0.50: an `optional` gate step's button while the field is empty. */
+    leaveEmpty: string;
+    /** 0.50: the chip beside an `optional` step's title. */
+    optional: string;
+    /** 0.50: under a `gate` step's locked Next (`TourStep.gateHint` overrides it). */
+    gateHint: string;
+    /** 0.50: announced (screen readers only) when a gate step's field is filled. */
+    gateReady: string;
+    /** 0.50: in place of Next on an `awaitGate` step (`TourStep.awaitGateHint` overrides it). */
+    awaitGateHint: string;
+    /** 0.50: the warning when the app `refuse`s an `awaitGate` step without a reason. */
+    awaitGateRefused: string;
+    /** 0.50: the link to an earlier step whose field was emptied, after a refused save. */
+    backToStep: (title: string) => string;
 }
 export { DEFAULT_TOUR_LABELS };
+/** 0.50 (§11.5): a step index, or the `data-tour` value of the step's anchor. */
+export type TourAt = number | string;
+/** `useTour().start`, both forms: what `TourProvider` hands its `launch` as the third argument. */
+export type TourStart = TourContextValue["start"];
+/**
+ * 0.50 (§11.5): the app's launcher — the shape `useTourUrlSync` already takes, plus `at`.
+ * It builds the steps (`prepare()`, `build()`, `tour: tourInfo(def)`) and passes `at` on to
+ * `start(steps, { …, at })`. Give the same function to `TourProvider launch` and to
+ * `useTourUrlSync`.
+ *
+ * `start` is the provider's own `start` (keksdose N4), so the launcher needs no ref to a
+ * component below the provider and may be defined above it. `useTourUrlSync` passes it too
+ * (under a provider). A two-argument launcher that reaches `start` its own way still works.
+ */
+export type TourLauncher = (id: string, opts: {
+    startIndex?: number;
+    at?: TourAt;
+}, start: TourStart) => void | Promise<unknown>;
 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. Defaults to
@@ -86,6 +178,15 @@ interface StartOptions {
     tour?: TourInfo;
     /** Start at this step index instead of 0 (clamped) — for URL/deep-link resume. */
     startIndex?: number;
+    /**
+     * 0.50 (§11.5): start here AND make it the floor — earlier steps never run (nor their
+     * `beforeStep`), Back stops here, `position`/`count` count from here, and the finish
+     * records the completion as a full run does (Marcel, Q2). A number is a step index
+     * (clamped); a string is the first step whose `target` contains `data-tour="<at>"`
+     * verbatim (unknown: 0, with a development warning). The `at` step is entered with
+     * `via: "at"`. With `startIndex` too, `startIndex` picks the step and `at` the floor.
+     */
+    at?: TourAt;
     /** Fires synchronously when the tour starts (e.g. enable a mock interceptor). */
     onStart?: () => void;
     /** After the last step: runs after the provider's progress write and `onComplete`. */
@@ -107,8 +208,17 @@ 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;
+    /**
+     * Start a tour with the given steps — or, by id (0.50), through the provider's `launch`:
+     * `start("create-transaction", { at: "txn-entry-mode" })`. Without a `launch` the id form
+     * does nothing (a development build warns).
+     */
+    start: {
+        (id: string, opts?: {
+            at?: TourAt;
+        }): void;
+        (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). */
@@ -121,6 +231,10 @@ interface TourContextValue {
     index: number;
     /** Total steps (0 while inactive). */
     total: number;
+    /** 0.50: 1-based position among the steps this run shows, for "3 of 9"; 0 while inactive. */
+    position: number;
+    /** 0.50: how many steps this run shows, from its first (the `at` floor) to the end; 0 while inactive. */
+    count: number;
 }
 export declare function useTour(): TourContextValue;
 /**
@@ -165,11 +279,21 @@ export declare function useTourOptional(): TourContextValue | null;
  * new `storageKey` (an account switch on a shared PC) is followed on the next
  * completion, without a remount.
  */
-export declare function TourProvider({ children, labels, progress, onComplete, }: {
+export declare function TourProvider({ children, labels, progress, onComplete, launch, dockOnPhones, }: {
     children: ReactNode;
     labels?: LabelOverride<TourLabels>;
+    /**
+     * 0.50 (§11.5): lets `start(id)` and `<TourGuideButton>` start a tour by id. Usually the
+     * same function the app gives `useTourUrlSync`.
+     */
+    launch?: TourLauncher;
     /** The app's tour progress: the same options its `useTourProgress` readers use. */
     progress?: UseTourProgressOptions;
     /** A tour's last step was finished; see {@link TourCompletion}. */
     onComplete?: (tour: TourInfo | undefined, completion: TourCompletion) => void;
+    /**
+     * 0.50 (§11.7, Marcel's Q1): below `sm`, a field step with a target and no `placement`
+     * docks. Default `true`; `false` makes docking strictly opt-in (`placement: "dock"`).
+     */
+    dockOnPhones?: boolean;
 }): import("react").JSX.Element;