@eifi1/ui-kit 0.49.0 → 0.50.1

package/src/components/numpad-sheet.tsx

@@ -209,6 +209,10 @@ export function NumberPadSheet({
     <div
       role="group"
       aria-label={text.panel}
+      // A kit layer, and the bottom layer a docked tour card stays clear of (0.50,
+      // docs/tours-harmonization.md §11.6).
+      data-kit-layer=""
+      data-tour-obstruction=""
       // Keep the host input focused when tapping the pad: preventDefault on
       // pointerdown blocks the focus/blur, while the buttons' click still fires.
       onPointerDown={(e) => e.preventDefault()}

package/src/components/picker-sheet.tsx

@@ -211,6 +211,10 @@ export function PickerSheet({
       // caller has something to add.
       {...rest}
       ref={setSheet}
+      // A kit layer and a bottom layer a docked tour card stays clear of (0.50,
+      // docs/tours-harmonization.md §11.6).
+      data-kit-layer=""
+      data-tour-obstruction=""
       role="dialog"
       aria-modal="true"
       // Without it the container cannot take focus, and `useFocusTrap` has nothing to

package/src/components/popover.tsx

@@ -206,6 +206,8 @@ export function Popover({
             // to remove one of them by accident.
             {...rest}
             ref={setPanel}
+            // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+            data-kit-layer=""
             role="dialog"
             id={panelId}
             // The caller's own `aria-label` wins over {@link PopoverLabels.panel}, which

package/src/i18n/defaults.ts

@@ -14,6 +14,7 @@ import {
 import { DEFAULT_WIZARD_LABELS } from "../wizard/wizard-labels";
 import { DEFAULT_TOUR_LABELS } from "../tour/tour-labels";
 import { DEFAULT_TOUR_CATALOGUE_LABELS } from "../tour/tour-catalogue-labels";
+import { DEFAULT_TOUR_GUIDE_LABELS } from "../tour/tour-guide-labels";
 import { DEFAULT_COMMAND_PALETTE_LABELS } from "../search/command-palette-labels";
 import { DEFAULT_GLOBAL_SEARCH_LABELS } from "../search/global-search-labels";
 import { DEFAULT_SERIES_CHART_LABELS } from "../components/series-chart-labels";
@@ -173,6 +174,7 @@ export const DEFAULT_UI_KIT_LABELS: UiKitLabels = {
   wizard: DEFAULT_WIZARD_LABELS,
   tour: DEFAULT_TOUR_LABELS,
   tourCatalogue: DEFAULT_TOUR_CATALOGUE_LABELS,
+  tourGuide: DEFAULT_TOUR_GUIDE_LABELS,
   commandPalette: DEFAULT_COMMAND_PALETTE_LABELS,
   globalSearch: DEFAULT_GLOBAL_SEARCH_LABELS,
   seriesChart: DEFAULT_SERIES_CHART_LABELS,

package/src/i18n/german.ts

@@ -634,6 +634,19 @@ export function germanLabels(numberLocale: string): UiKitLabels {
       awaitClickHint: "Klicken Sie auf das hervorgehobene Element, um fortzufahren",
       awaitInputHint: "Geben Sie im hervorgehobenen Feld einen Wert ein, um fortzufahren", // 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: "Leer lassen",
+      optional: "Optional",
+      gateHint: "Füllen Sie das hervorgehobene Feld aus, um fortzufahren",
+      gateReady: "Bereit. Drücken Sie Weiter oder die Eingabetaste, um fortzufahren.",
+      awaitGateHint: "Speichern Sie, um fortzufahren",
+      awaitGateRefused: "Das ist noch nicht gespeichert. Prüfen Sie das Formular und versuchen Sie es erneut.",
+      backToStep: (title) => `Zurück zu „${title}“`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "Schritt für Schritt",
+      description: "Führt Sie Feld für Feld durch dieses Formular",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page. keksdose's reviewed words.
     tourCatalogue: {

package/src/i18n/kit-labels.tsx

@@ -26,6 +26,7 @@ import type { TabsLabels } from "../components/tabs";
 import type { WizardLabels } from "../wizard/types";
 import type { TourLabels } from "../tour/tour";
 import type { TourCatalogueLabels } from "../tour/tour-catalogue-labels";
+import type { TourGuideLabels } from "../tour/tour-guide-labels";
 import type { CommandPaletteLabels } from "../search/command-palette";
 import type { GlobalSearchLabels } from "../search/global-search";
 import type { MonthPickerLabels } from "../components/month-picker";
@@ -335,6 +336,8 @@ export interface UiKitLabels {
   tour: TourLabels;
   /** 0.43.0: the tours page — `TourCatalogue` and its card (docs/tours-harmonization.md §3). */
   tourCatalogue: TourCatalogueLabels;
+  /** 0.50: the form's "Guide me" — `TourGuideButton` (docs/tours-harmonization.md §11). */
+  tourGuide: TourGuideLabels;
   commandPalette: CommandPaletteLabels;
   globalSearch: GlobalSearchLabels;
   seriesChart: SeriesChartLabels;

package/src/i18n/locales/es.ts

@@ -617,6 +617,19 @@ export function uiKitLabelsEs(numberLocale = "es-ES"): UiKitLabels {
       awaitClickHint: "Haga clic en el elemento resaltado para continuar",
       awaitInputHint: "Introduzca un valor en el campo resaltado para continuar", // 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: "Dejar vacío",
+      optional: "Opcional",
+      gateHint: "Rellene el campo resaltado para continuar",
+      gateReady: "Listo. Pulse Siguiente o Intro para continuar.",
+      awaitGateHint: "Guarde para continuar",
+      awaitGateRefused: "Todavía no se ha guardado. Revise el formulario e inténtelo de nuevo.",
+      backToStep: (title) => `Volver a «${title}»`,
+    },
+    // 0.50: the form's "Guide me" (TourGuideButton, docs/tours-harmonization.md §11).
+    tourGuide: {
+      label: "Guíeme",
+      description: "Le guía por este formulario, campo a campo",
     },
     // 0.43.0 — docs/tours-harmonization.md §3, §8: the tours page.
     tourCatalogue: {

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/lib/quiet-focus.ts

@@ -0,0 +1,32 @@
+/**
+ * Focus that is not a request to open anything (0.50.1, keksdose B1).
+ *
+ * A guided tour focuses a field step's first control on arrival (tours §11.8). The kit's
+ * pickers that open their list on focus — Combobox (and the category pickers built on it),
+ * Autocomplete, InlineEntityCombobox — opened it then too, and the list, a later layer
+ * (§11.6), covered the tour card with its Next and "Leave empty".
+ *
+ * {@link focusQuietly} marks the element for the length of its synchronous `focus()` call;
+ * a picker's `onFocus` asks {@link isQuietFocus} and, when it is, takes the focus without
+ * opening. React dispatches `onFocus` inside the native `focusin`, which `focus()` fires
+ * synchronously, so the mark is seen by exactly that focus and by no later one. A click or
+ * Tab of the person's own opens as before; from a quiet focus, ArrowDown, typing or a click
+ * opens the list.
+ */
+let quiet: Element | null = null;
+
+/** `el.focus(options)`, telling the kit's open-on-focus pickers not to open. */
+export function focusQuietly(el: HTMLElement, options?: FocusOptions): void {
+  const before = quiet;
+  quiet = el;
+  try {
+    el.focus(options);
+  } finally {
+    quiet = before;
+  }
+}
+
+/** True while `el` is being focused by {@link focusQuietly}. */
+export function isQuietFocus(el: Element): boolean {
+  return quiet === el;
+}

package/src/testing/index.ts

@@ -24,3 +24,11 @@ export {
   type StubbedBoxSize,
   type ViewportOptions,
 } from "./viewport";
+// 0.50.1 (keksdose N4): a valid `TourStepContext` for a test that calls a step's
+// `beforeStep` or `when` itself — `beforeStep!(tourStepContext())`.
+export {
+  tourStepContext,
+  type TestTourStepContext,
+  type TourStepContextOptions,
+  type TourStepVia,
+} from "./tour";

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/testing/tour.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N4): a `TourStepContext` for a test that calls a step's `beforeStep` or
+ * `when` itself. 0.50 gave both the context, so `beforeStep!()` is a type error;
+ * `beforeStep!(tourStepContext())` is the drop-in.
+ *
+ * Spelled out here rather than imported from the tour module, so `@eifi1/ui-kit/testing`
+ * still reaches no package (the tour module reaches React); the kit's own test pins that it
+ * is assignable to `TourStepContext`.
+ */
+
+/** How a step is entered: `TourStepContext["via"]`. */
+export type TourStepVia = "start" | "at" | "next" | "back" | "goto";
+
+/** The shape of `TourStepContext` (`@eifi1/ui-kit/tour`). */
+export interface TestTourStepContext {
+  gate(key: string): boolean | undefined;
+  via: TourStepVia;
+}
+
+export interface TourStepContextOptions {
+  /** How the step is entered. Default `"start"`. */
+  via?: TourStepVia;
+  /**
+   * The published gates, as the form would publish them: `{ "txn.transfer": true }`. A key
+   * left out answers `undefined` (nobody publishes it). Default: none.
+   */
+  gates?: Readonly<Record<string, boolean | undefined>>;
+}
+
+/**
+ * A valid step context: `via: "start"` and no gates published, unless `options` say
+ * otherwise. `step.beforeStep!(tourStepContext())`, `step.when!(tourStepContext({ gates:
+ * { "txn.transfer": true } }))`, `tourStepContext({ via: "at" })` for a "Guide me" entry.
+ */
+export function tourStepContext(options: TourStepContextOptions = {}): TestTourStepContext {
+  const gates = options.gates ?? {};
+  return {
+    gate: (key) => (Object.prototype.hasOwnProperty.call(gates, key) ? gates[key] : undefined),
+    via: options.via ?? "start",
+  };
+}

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-engine.ts

@@ -0,0 +1,41 @@
+/**
+ * 0.50.1 (keksdose N1): the tour engine a launcher is handed as its fourth argument — one
+ * object for the life of the provider (or of `useTourUrlSync`) whose fields always read the
+ * engine's LATEST render: `engine.active`, `engine.index` after an `await` are current, and
+ * `engine.stop()` mid-run stops the run that is up now. Internal: the type is `TourEngine`.
+ *
+ * `set` is called from a layout effect with each render's engine; `engine` reads it.
+ */
+export function liveEngine<T extends object>(
+  keys: readonly (keyof T & string)[],
+  initial: T | null = null,
+): { engine: T; set: (current: T) => void } {
+  let current = initial;
+  const read = () => {
+    if (!current)
+      throw new Error(
+        "[ui-kit] The tour engine was read before its provider rendered.",
+      );
+    return current;
+  };
+  const engine = {} as T;
+  for (const key of keys) {
+    Object.defineProperty(engine, key, {
+      enumerable: true,
+      get: () => {
+        const value = read()[key];
+        // A method is looked up when it is CALLED, so a kept `engine.stop` is the latest too.
+        return typeof value === "function"
+          ? (...args: unknown[]) =>
+              (read()[key] as (...a: unknown[]) => unknown)(...args)
+          : value;
+      },
+    });
+  }
+  return {
+    engine,
+    set: (next) => {
+      current = next;
+    },
+  };
+}