@eifi1/ui-kit 0.49.0 → 0.50.0

package/src/i18n/locales/fr.ts

@@ -632,6 +632,19 @@ export function uiKitLabelsFr(numberLocale = "fr-FR"): UiKitLabels {
       awaitClickHint: "Cliquez sur l’élément mis en évidence pour continuer",
       awaitInputHint: "Saisissez une valeur dans le champ mis en évidence pour continuer", // 0.46: TourStep.awaitInput (keksdose live #436).
       step: (current, total) => `${n(current)} / ${n(total)}`,
+      // 0.50: guided form tours (docs/tours-harmonization.md §11).
+      leaveEmpty: "Laisser vide",
+      optional: "Facultatif",
+      gateHint: "Remplissez le champ mis en évidence pour continuer",
+      gateReady: "Prêt. Appuyez sur Suivant ou sur Entrée pour continuer.",
+      awaitGateHint: "Enregistrez pour continuer",
+      awaitGateRefused: "Ce n’est pas encore enregistré. Vérifiez le formulaire et réessayez.",
+      backToStep: (title) => `Retour à «\u202f${title}\u202f»`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "Me guider",
+      description: "Vous guide dans ce formulaire, champ par champ",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page. keksdose's reviewed words.
     tourCatalogue: {

package/src/i18n/locales/hu.ts

@@ -619,6 +619,19 @@ export function uiKitLabelsHu(numberLocale = "hu-HU"): UiKitLabels {
       awaitClickHint: "A folytatáshoz kattintson a kiemelt elemre",
       awaitInputHint: "A folytatáshoz adjon meg egy értéket a kiemelt mezőben", // 0.46: TourStep.awaitInput (keksdose live #436).
       step: (current, total) => `${n(current)} / ${n(total)}`,
+      // 0.50: guided form tours (docs/tours-harmonization.md §11).
+      leaveEmpty: "Hagyja üresen",
+      optional: "Nem kötelező",
+      gateHint: "A folytatáshoz töltse ki a kiemelt mezőt",
+      gateReady: "Kész. A folytatáshoz nyomja meg a Tovább gombot vagy az Entert.",
+      awaitGateHint: "A folytatáshoz mentsen",
+      awaitGateRefused: "Ez még nincs mentve. Ellenőrizze az űrlapot, és próbálja újra.",
+      backToStep: (title) => `Vissza ide: „${title}”`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "Vezessen végig",
+      description: "Mezőről mezőre végigvezeti az űrlapon",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page.
     tourCatalogue: {

package/src/i18n/locales/it.ts

@@ -621,6 +621,19 @@ export function uiKitLabelsIt(numberLocale = "it-IT"): UiKitLabels {
       awaitClickHint: "Faccia clic sull’elemento evidenziato per continuare",
       awaitInputHint: "Inserisca un valore nel campo evidenziato per continuare", // 0.46: TourStep.awaitInput (keksdose live #436).
       step: (current, total) => `${n(current)} / ${n(total)}`,
+      // 0.50: guided form tours (docs/tours-harmonization.md §11).
+      leaveEmpty: "Lascia vuoto",
+      optional: "Facoltativo",
+      gateHint: "Compili il campo evidenziato per continuare",
+      gateReady: "Pronto. Prema Avanti o Invio per continuare.",
+      awaitGateHint: "Salvi per continuare",
+      awaitGateRefused: "Non è ancora stato salvato. Controlli il modulo e riprovi.",
+      backToStep: (title) => `Torna a «${title}»`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "Guidami",
+      description: "La guida in questo modulo, campo per campo",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page. keksdose's reviewed words.
     tourCatalogue: {

package/src/i18n/locales/zh.ts

@@ -600,6 +600,19 @@ export function uiKitLabelsZh(numberLocale = "zh-CN"): UiKitLabels {
       awaitClickHint: "点击高亮的元素以继续",
       awaitInputHint: "在高亮的字段中输入一个值以继续", // 0.46: TourStep.awaitInput (keksdose live #436).
       step: (current, total) => `${n(current)} / ${n(total)}`,
+      // 0.50: guided form tours (docs/tours-harmonization.md §11).
+      leaveEmpty: "留空",
+      optional: "可选",
+      gateHint: "填写高亮的字段以继续",
+      gateReady: "已就绪。按“下一步”或回车键继续。",
+      awaitGateHint: "保存以继续",
+      awaitGateRefused: "尚未保存。请检查表单后重试。",
+      backToStep: (title) => `返回“${title}”`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "引导我",
+      description: "逐个字段引导您填写此表单",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page.
     tourCatalogue: {

package/src/i18n/review.ts

@@ -157,6 +157,7 @@ export const KIT_LABEL_SAMPLES: Readonly<Record<string, readonly (readonly unkno
   "file.size": [[2_500_000]],
   "wizard.step": [[2, 4]],
   "tour.step": [[2, 4]],
+  "tour.backToStep": [["{{title}}"]],
   "globalSearch.shortcut": [["{{keys}}"]],
   "pieChart.slice": [["{{label}}", "{{value}}", "{{percent}}"]],
   "sparkline.rising": [["{{first}}", "{{last}}"]],

package/src/lib/data-attributes.ts

@@ -0,0 +1,14 @@
+/**
+ * A component's `data-*` props, for its root element (0.50, keksdose): `data-tour`,
+ * `data-testid` and the like reach the DOM even when the props are not spread there
+ * whole. TypeScript does not check hyphenated JSX attributes, so without this a
+ * `data-tour` on such a component vanished without an error.
+ */
+export type DataAttributes = { [attribute: `data-${string}`]: string | number | boolean | undefined };
+
+/** Only the `data-*` entries of `props`. */
+export function dataAttributes(props: object): DataAttributes {
+  const out: DataAttributes = {};
+  for (const [k, v] of Object.entries(props)) if (k.startsWith("data-")) out[k as `data-${string}`] = v;
+  return out;
+}

package/src/lib/format.ts

@@ -5,6 +5,8 @@ import { formatWithMinus, type MinusStyle } from "./minus";
 import { roundHalfAway } from "./round";
 
 export type { MinusStyle } from "./minus";
+// 0.50 (KIT-1 follow-up): the kit's minus for an app's OWN `Intl.NumberFormat` wrapper.
+export { formatWithMinus } from "./minus";
 
 /**
  * Number, money, percentage, date and relative-time formatting — `Intl`, in one place,

package/src/lib/minus.ts

@@ -24,6 +24,16 @@ const MINUS_PARTS: ReadonlySet<string> = new Set(["minusSign", "exponentMinusSig
  * `Intl` marks as a minus are touched — a hyphen inside a currency's name
  * ("Bosnia-Herzegovina convertible marks") stays — and only when the text holds the
  * other sign at all, so a positive figure costs no `formatToParts`.
+ *
+ * Public since 0.50 (the KIT-1 follow-up): an app that keeps its OWN `Intl.NumberFormat`
+ * wrapper (a currency with app-specific digits, a quantity) calls it in place of
+ * `formatter.format(value)`, so its negatives match the kit's "−". Where the wrapper only
+ * re-states `formatMoney` / `formatNumber`, route it through those instead.
+ *
+ * @example
+ *   const eur = new Intl.NumberFormat("en", { style: "currency", currency: "EUR" });
+ *   formatWithMinus(eur, -150);          // "−€150.00"
+ *   formatWithMinus(eur, -150, "ascii"); // "-€150.00", for a CSV
  */
 export function formatWithMinus(
   formatter: Intl.NumberFormat,

package/src/testing/react.ts

@@ -0,0 +1,59 @@
+import { fireEvent, screen, within } from "@testing-library/react";
+
+// `@eifi1/ui-kit/testing/react` (0.50) — helpers that drive the kit's components through
+// Testing Library, from an app's own test suite.
+//
+// A sibling of `@eifi1/ui-kit/testing`, not part of it: that entry is pure (it reaches no
+// package, so it runs under node or jsdom alike), and this one needs
+// `@testing-library/react`, an optional peer only a test suite installs. Neither is part of
+// the barrel, so an app's production bundle never carries either.
+
+/** The words of the row's "⋯" button, when the app's tests render translated kit labels. */
+export interface RowMenuLabels {
+  /** The button's name on a row with no `name`. Default "Actions". */
+  actions?: string;
+  /** The button's name given the row's. Default `Actions for ${name}`. */
+  actionsFor?: (name: string) => string;
+}
+
+// The kit's English defaults (DEFAULT_ROW_ACTIONS_LABELS, and the user roster's), written
+// out rather than imported: the label module's type import would walk this entry into the
+// components. src/testing/__tests__/react.test.tsx holds them equal.
+const ACTIONS = "Actions";
+const ACTIONS_FOR = (name: string) => `Actions for ${name}`;
+
+/**
+ * Open a row's "⋯" menu and find one of its actions — the entry, unclicked, so a test can
+ * check it (locked, described) before it clicks it.
+ *
+ * `row` is the row's name as the app gave it to `RowActions` / `rowActionsColumn` /
+ * `UserRoster` ("Actions for <row>"); `undefined` takes the FIRST "⋯" on the page, named
+ * or not. Since 0.49 (KIT-12) a `tone: "danger"` action lives in that menu rather than as
+ * an icon in the row, and at Large text every action does.
+ *
+ * The entries are BUTTONS in a dialog popover named like the "⋯" button — not `menuitem`s:
+ * `getByRole("menuitem")` finds nothing there. A danger action asks for confirmation once
+ * clicked (an `alertdialog`), unless the app turned that off.
+ *
+ * @example
+ *   fireEvent.click(await rowMenuAction("Ada Example", "Delete"));
+ *   fireEvent.click(await screen.findByRole("button", { name: "Confirm" }));
+ */
+export async function rowMenuAction(
+  row: string | undefined,
+  action: string | RegExp,
+  labels: RowMenuLabels = {},
+): Promise<HTMLElement> {
+  const actions = labels.actions ?? ACTIONS;
+  const actionsFor = labels.actionsFor ?? ACTIONS_FOR;
+  // Any row's name: the words around the name, whatever the language puts first.
+  const [before, after] = actionsFor("\u0000").split("\u0000");
+  const anyRow = (name: string) =>
+    name === actions ||
+    (name.length > before.length + after.length && name.startsWith(before) && name.endsWith(after));
+  const trigger = (await screen.findAllByRole("button", { name: row === undefined ? anyRow : actionsFor(row) }))[0];
+  fireEvent.click(trigger);
+  const title = trigger.getAttribute("aria-label") ?? trigger.textContent ?? "";
+  const menu = await screen.findByRole("dialog", { name: title });
+  return within(menu).getByRole("button", { name: action });
+}

package/src/tour/tour-dock.ts

@@ -0,0 +1,132 @@
+import type { CSSProperties } from "react";
+import { readKeyboardInset } from "../hooks/use-anchored-panel";
+
+/*
+ * # The docked card (docs/tours-harmonization.md §11.7, contract round 054 §6)
+ *
+ * On a phone a field step's card is pinned full-width to the top or bottom edge of the
+ * USABLE BAND — the visual viewport less the keyboard, raised above the highest
+ * `[data-tour-obstruction]` (the number pad, a picker sheet) — on the edge away from the
+ * spotlighted field, so it covers neither the field nor the keyboard nor the pad.
+ */
+
+export type DockEdge = "top" | "bottom";
+
+export interface DockRect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/** The band, in layout-viewport px (what `position: fixed` measures from). */
+export interface Band {
+  top: number;
+  bottom: number;
+}
+
+/** Below this the docked layout applies (Tailwind's `sm`). */
+export const DOCK_MAX_WIDTH = 640;
+/** The gutter between the card and the band's edge, and between the card and the field. */
+const GUTTER = 8;
+/** An obstruction whose top is within this of the band's top covers the screen. */
+const FULL_SCREEN_SLACK = 64;
+/** Under this much free space on its edge the card flips (the hysteresis floor). */
+const MIN_DOCK = 140;
+
+/**
+ * The usable band now: the visual viewport while a keyboard is up (`readKeyboardInset`'s
+ * rules — pinch zoom is not a keyboard, 100 px minimum), else the layout viewport; its
+ * bottom raised to the top of the highest visible obstruction that holds neither the field
+ * nor the card. An obstruction that starts at the band's top (a full-screen picker, opened
+ * over everything) is not a bottom layer and is ignored; a tall one (the number pad at
+ * Large text is over half a phone) still counts.
+ */
+export function readBand(target: Element | null, card: Element | null): Band {
+  const vh = window.innerHeight;
+  let top = 0;
+  let bottom = vh;
+  const vv = window.visualViewport;
+  if (vv && readKeyboardInset() > 0) {
+    top = vv.offsetTop;
+    bottom = vv.offsetTop + vv.height;
+  }
+  for (const el of Array.from(document.querySelectorAll("[data-tour-obstruction]"))) {
+    if ((target && el.contains(target)) || (card && el.contains(card))) continue;
+    const r = el.getBoundingClientRect();
+    if (r.width <= 0 || r.height <= 0 || r.top <= top + FULL_SCREEN_SLACK) continue;
+    if (r.top < bottom) bottom = r.top;
+  }
+  return { top, bottom };
+}
+
+/** The card's free space on `edge`, between the band's edge and the spotlight. */
+function room(edge: DockEdge, spot: DockRect, band: Band): number {
+  return edge === "bottom" ? band.bottom - (spot.top + spot.height) - GUTTER * 2 : spot.top - band.top - GUTTER * 2;
+}
+
+/**
+ * The edge away from the field: the bottom when the spotlight's centre is in the band's
+ * upper half, else the top. With a `previous` edge, it stays unless the card would have to
+ * cover the spotlight there (no flip on every keyboard animation frame).
+ */
+export function dockEdge(spot: DockRect, band: Band, previous: DockEdge | null, cardHeight: number): DockEdge {
+  const preferred: DockEdge = spot.top + spot.height / 2 < band.top + (band.bottom - band.top) / 2 ? "bottom" : "top";
+  if (!previous || previous === preferred) return preferred;
+  return room(previous, spot, band) >= Math.min(MIN_DOCK, cardHeight) ? previous : preferred;
+}
+
+/** The docked card's position: full-width with 8 px (safe-area aware) gutters, its height
+ *  capped to the free space so its body scrolls and its title and buttons show. */
+export function dockStyle(edge: DockEdge, spot: DockRect | null, band: Band): CSSProperties {
+  const vh = window.innerHeight;
+  const cap = spot ? Math.max(MIN_DOCK / 2, room(edge, spot, band)) : band.bottom - band.top - GUTTER * 2;
+  const base: CSSProperties = {
+    left: `max(${GUTTER}px, env(safe-area-inset-left))`,
+    right: `max(${GUTTER}px, env(safe-area-inset-right))`,
+    width: "auto",
+    maxWidth: "none",
+    maxHeight: cap,
+  };
+  if (edge === "top") {
+    return { ...base, top: band.top <= 0 ? `max(${GUTTER}px, env(safe-area-inset-top))` : band.top + GUTTER, bottom: "auto" };
+  }
+  const fromBottom = vh - band.bottom;
+  return {
+    ...base,
+    top: "auto",
+    bottom: fromBottom <= 0 ? `max(${GUTTER}px, env(safe-area-inset-bottom))` : fromBottom + GUTTER,
+  };
+}
+
+/** The target's nearest ancestor that scrolls vertically now (a sheet's body), or null. */
+export function scrollParent(el: Element): HTMLElement | null {
+  for (let node = el.parentElement; node && node !== document.body; node = node.parentElement) {
+    const { overflowY } = getComputedStyle(node);
+    if ((overflowY === "auto" || overflowY === "scroll") && node.scrollHeight > node.clientHeight) return node;
+  }
+  return null;
+}
+
+/**
+ * Scroll the field into the half of the band away from the card, through its nearest
+ * scrollable ancestor (the window only when there is none — the page behind a sheet never
+ * moves). A field already inside that half is left where it is. Returns the edge the card
+ * takes.
+ */
+export function scrollIntoFreeHalf(el: Element, card: Element | null, previous: DockEdge | null): DockEdge {
+  const r = el.getBoundingClientRect();
+  const band = readBand(el, card);
+  const edge = dockEdge(r, band, previous, card instanceof HTMLElement ? card.offsetHeight : MIN_DOCK);
+  const mid = band.top + (band.bottom - band.top) / 2;
+  const half = edge === "bottom" ? { top: band.top + GUTTER, bottom: mid } : { top: mid, bottom: band.bottom - GUTTER };
+  if (r.top >= half.top && r.top + r.height <= half.bottom) return edge;
+  // Centred in the half, or its top at the half's top when it is taller than the half.
+  const delta =
+    r.height > half.bottom - half.top ? r.top - half.top : r.top + r.height / 2 - (half.top + half.bottom) / 2;
+  const scroller = scrollParent(el);
+  if (scroller) scroller.scrollTop += delta;
+  // A field in a kit layer with nothing to scroll: the page behind it stays put.
+  else if (!el.closest("[data-kit-layer]")) window.scrollBy?.(0, delta);
+  return edge;
+}

package/src/tour/tour-gates.ts

@@ -0,0 +1,195 @@
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
+
+/*
+ * # 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);
+    },
+  };
+}
+
+/** 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

@@ -0,0 +1,64 @@
+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

@@ -0,0 +1,15 @@
+// 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-labels.ts

@@ -12,4 +12,12 @@ export const DEFAULT_TOUR_LABELS: TourLabels = {
   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}”`,
 };