@eifi1/ui-kit 0.49.0 → 0.50.0

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;