@eifi1/ui-kit 0.49.0 → 0.50.0

package/src/components/amount-input.tsx

@@ -41,10 +41,11 @@ import {
 } from "./field-parts";
 import { useEndWidth, useNumericField } from "./numeric-field";
 import type { CommitScope } from "./write-lock";
+import { dataAttributes, type DataAttributes } from "../lib/data-attributes";
 
 /** {@link AmountInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
  *  wrapper typed itself off `ComponentProps<typeof AmountInput>` until then. */
-export interface AmountInputProps extends FieldHelpProps {
+export interface AmountInputProps extends FieldHelpProps, DataAttributes {
   value: string;
   onChange: (value: string) => void;
   currency?: string;
@@ -427,8 +428,8 @@ export function AmountInput(props: AmountInputProps) {
   const { lock, locked, off, isMobile, asDisplay, showCalc, showNumpad, setFocused, mark, draft, setDraft, derived } =
     numeric;
   const invalid = numeric.isInvalid;
-  // A locked chip is a read-out: picking a currency is a change too.
-  const editable = !!onCurrencyChange && !locked;
+  // A locked or disabled chip is a read-out: picking a currency is a change too.
+  const editable = !!onCurrencyChange && !locked && !off;
   // Room for the trailing controls — the calculator and the currency chip — once
   // measured, as NumberInput reserves its own (keksdose live #367, DUP-10): their
   // width, the track's `end-1` inset in the boxed shape, and NumberInput's 4px gap.
@@ -533,7 +534,7 @@ export function AmountInput(props: AmountInputProps) {
   const selected = getCurrency(currency);
 
   return (
-    <div className={cn("w-full", className)}>
+    <div {...dataAttributes(props)} className={cn("w-full", className)}>
       {/* Inner relative box holds the input + its absolutely-positioned
           trailing controls (calculator / currency), so those stay anchored to
           the INPUT even when the mobile math bar is rendered below (#334). It is

package/src/components/autocomplete.tsx

@@ -519,6 +519,8 @@ export function Autocomplete<V extends string | number = string>(props: Autocomp
             // Every press inside the list keeps focus in the field — rows, the status
             // line, the scrollbar — or the input's blur would close the list first.
             role="presentation"
+            // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+            data-kit-layer=""
             // Portalled out of the form's `dir`; the field's is put back. The list is
             // exactly the field's width, so `left` places it in either direction.
             dir={dir}

package/src/components/combobox-core.tsx

@@ -1064,6 +1064,8 @@ export function ComboboxPanel<V extends string | number>({
       // `aria-describedby` has nothing to collide with.
       {...rest}
       ref={panelRef}
+      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+      data-kit-layer=""
       dir={dir}
       onKeyDown={onKeyDown}
       // A press in a panel opened from a row is inside this list for the core's outside

package/src/components/combobox-suggestions.tsx

@@ -92,6 +92,8 @@ export function SuggestionList({
   return createPortal(
     <div
       ref={panelRef}
+      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+      data-kit-layer=""
       // z-50, not the old z-30: the list is a child of <body> now, so it is
       // competing with the app's own overlays rather than with its own siblings.
       className="fixed z-50"

package/src/components/currency-select.tsx

@@ -2,7 +2,16 @@ import { useCallback, useId } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { FieldChevron, FIELD_TRIGGER, FIELD_INVALID, FIELD_FLOATING_PAD } from "./field-base";
 import { FieldLabel } from "./field-parts";
-import { assignRef, EndHintRow, useFieldMessages, type FieldHelpProps } from "./field-parts";
+import {
+  assignRef,
+  EndHintRow,
+  LockedReason,
+  useFieldMessages,
+  useLockReason,
+  type DisabledReasonDisplay,
+  type FieldHelpProps,
+} from "./field-parts";
+import type { CommitScope } from "./write-lock";
 import { cn } from "../lib/cn";
 import { useComboboxCore } from "./combobox-core";
 import {
@@ -90,6 +99,31 @@ export interface CurrencySelectProps extends Omit<ComponentPropsWithoutRef<"div"
    * filter that only matches the hidden English name is worse than no filter.
    */
   currencyNames?: Record<string, string>;
+  /** As {@link Select}'s: no focus, no list, the settled look, no chevron. */
+  disabled?: boolean;
+  /**
+   * Why the currency cannot be changed — {@link Select}'s `disabledReason` (keksdose,
+   * 2026-10-23: a budget's currency for a guest or a viewer, and while offline, which
+   * keksdose drew as a one-option `Select` to keep the reason and lost the flag). The
+   * trigger stays focusable and `aria-disabled` (never the `disabled` attribute), keeps
+   * its flag and code, opens nothing, and `onChange` is never called; the reason is a
+   * line under the field at Large and on a touch screen, else in the kit
+   * {@link Tooltip} (`disabledReasonDisplay`), and on the trigger's `aria-describedby`
+   * (after a caption, before an error). It wears the settled look of a disabled field
+   * and drops its chevron, as a locked Select does. It wins over `disabled`.
+   */
+  disabledReason?: ReactNode;
+  /** Where the reason shows — {@link Select}'s `disabledReasonDisplay`: a line under the
+   *  field at Large and on a touch screen by default, the tooltip otherwise. */
+  disabledReasonDisplay?: DisabledReasonDisplay;
+  /**
+   * This picker COMMITS — choosing saves. Under a locked {@link WriteLockProvider} it is
+   * locked the `disabledReason` way with the lock's reason (which wins over its own).
+   * No provider, or an unlocked one: no effect. {@link Select}'s `commit`. A currency
+   * field inside a form with its own Save stays editable under the lock — leave this off
+   * there, and put `commit` on the Save.
+   */
+  commit?: CommitScope;
   /** The TRIGGER — the focusable `<button>` — as a React 19 ref prop, as on
    *  {@link MultiSelect} and {@link CountrySelect}: react-hook-form's focus-on-error
    *  calls `focus()` on it (0.34, API-3, refactor audit 2026-10). Not the wrapper. */
@@ -109,6 +143,10 @@ export function CurrencySelect({
   help,
   labels,
   currencyNames,
+  disabled,
+  disabledReason,
+  disabledReasonDisplay,
+  commit,
   "aria-label": ariaLabel,
   "aria-describedby": ariaDescribedBy,
   "aria-invalid": ariaInvalid,
@@ -137,6 +175,15 @@ export function CurrencySelect({
 
   const selected = getCurrency(value);
 
+  // The lock — Select's (`useLockReason`): the WriteLock's reason under `commit`, else
+  // the caller's own. Locked or `disabled`, nothing opens the list or picks a value.
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const inert = locked || Boolean(disabled);
+  // A lock (or `disabled`) arriving while the list is up closes it — adjusted while
+  // rendering, as CountrySelect does, so no frame shows a list that cannot be used.
+  if (inert && open) setOpen(false);
+
   const listboxId = `${useId()}-listbox`;
   // Text is a caption under the field; anything else (a FieldHint) rides the label
   // line — and a FieldHint is that caption at Large and on touch (§4). See `hint`. On
@@ -152,6 +199,8 @@ export function CurrencySelect({
     invalid,
     describedBy: ariaDescribedBy,
     ariaInvalid,
+    // A lock's reason sits between the caption and the error, as on Select.
+    reasonId: locked && lock.reasonId,
   });
   const { labelHint, describedBy, isInvalid } = field;
 
@@ -169,10 +218,21 @@ export function CurrencySelect({
       ref={setTrigger}
       type="button"
       aria-label={name}
-      onClick={() => setOpen((v) => !v)}
+      // The focusable kind of disabled while locked (Select's rule): native `disabled`
+      // would take the field out of the tab order, and the reason with it.
+      disabled={locked ? undefined : disabled}
+      aria-disabled={locked || undefined}
+      onClick={(e) => {
+        if (inert) {
+          e.preventDefault();
+          return;
+        }
+        setOpen((v) => !v);
+      }}
       // Down/Up opens the list from the closed trigger, per the APG; Enter and Space
       // already do through the button's own click.
       onKeyDown={(e) => {
+        if (inert) return;
         if (e.key === "ArrowDown" || e.key === "ArrowUp") {
           e.preventDefault();
           setOpen(true);
@@ -191,12 +251,27 @@ export function CurrencySelect({
       aria-expanded={open}
       aria-invalid={isInvalid || undefined}
       aria-describedby={describedBy}
-      className={cn(FIELD_TRIGGER, "pe-9", label !== undefined && FIELD_FLOATING_PAD, isInvalid && FIELD_INVALID)}
+      className={cn(
+        FIELD_TRIGGER,
+        "pe-9",
+        label !== undefined && FIELD_FLOATING_PAD,
+        // FIELD_BASE's `disabled:` look, for a trigger locked without being `disabled`
+        // (the `:disabled` variants cannot match it) — Select's FIELD_LOCKED. No hover:
+        // nothing here answers a press.
+        locked && "cursor-not-allowed bg-surface-2 text-muted hover:bg-surface-2",
+        isInvalid && FIELD_INVALID,
+      )}
     >
       {/* The trigger stays COMPACT — flag + code only — so it never clips in a
           narrow field; the full names live in the (wider) popup (feedback
           #308). */}
-      <span className={cn("flex items-center gap-2 min-w-0", selected ? "text-primary" : "text-placeholder")}>
+      <span
+        className={cn(
+          "flex items-center gap-2 min-w-0",
+          // The settled look reaches the code too: `text-primary` here would outweigh it.
+          !selected ? "text-placeholder" : inert ? "text-muted" : "text-primary",
+        )}
+      >
         {selected ? (
           <>
             <CurrencyFlag country={selected.country} />
@@ -206,10 +281,23 @@ export function CurrencySelect({
           placeholder ?? text.currency
         )}
       </span>
-      <FieldChevron />
+      {/* No menu to drop while disabled or locked, so no chevron — the arrow is the one
+          thing on the control that promises a choice (dev#474, as on Select). */}
+      {!inert && <FieldChevron />}
     </button>
   );
 
+  // Select's frame: the line under the trigger, or the Tooltip with a hidden copy for
+  // `aria-describedby`. The wrapper `<div>` keeps `className`, so the layout holds.
+  // `flex w-full items-stretch`: the trigger keeps the field's full width in it.
+  const control = locked ? (
+    <LockedReason lock={lock} display={disabledReasonDisplay} className="flex w-full items-stretch">
+      {trigger}
+    </LockedReason>
+  ) : (
+    trigger
+  );
+
   return (
     // The wrapper takes `rest`; the trigger takes the name. This field's label is a
     // floating <span> rather than a <label for>, so a caller who wants the control to
@@ -230,7 +318,7 @@ export function CurrencySelect({
         ))}
       {/* No label line to ride: at the field's end edge, outside the box, as an
           unlabelled Select places its FieldHint. */}
-      <EndHintRow hint={label === undefined ? labelHint : undefined}>{trigger}</EndHintRow>
+      <EndHintRow hint={label === undefined ? labelHint : undefined}>{control}</EndHintRow>
       {field.below}
       {/* Portalled to <body> and anchored to the trigger (dev#548), so where it stands
           in the flow no longer moves it. */}
@@ -246,6 +334,7 @@ export function CurrencySelect({
         // to say what it asks for (live #200).
         sheetTitle={label ?? text.currency}
         onChoose={(code) => {
+          if (inert) return;
           onChange(code);
           // Back to the trigger: the panel holding focus is about to unmount, and a
           // keyboard user who has answered the field should stand on it, ready to Tab on.

package/src/components/data-table-mobile.tsx

@@ -72,7 +72,18 @@ const CARD_NO_TRUNCATE =
  * BETWEEN facts rather than between a label and its own value. `relative` holds a
  * header's `sr-only` text (an actions column's), as every kit container must.
  */
-export function StackedFields<T>({ columns, row, compact }: { columns: DataTableColumn<T>[]; row: T; compact: boolean }) {
+export function StackedFields<T>({
+  columns,
+  row,
+  compact,
+  liftOwnClicks = false,
+}: {
+  columns: DataTableColumn<T>[];
+  row: T;
+  compact: boolean;
+  /** On a stretched card (0.50 K4): lift the own-click fields above its title link. */
+  liftOwnClicks?: boolean;
+}) {
   const fields = filledFields(columns, row);
   if (fields.length === 0) return null;
   return (
@@ -85,7 +96,7 @@ export function StackedFields<T>({ columns, row, compact }: { columns: DataTable
           <dt className="text-xs uppercase tracking-wide text-muted">{col.header}</dt>
           <dd
             {...dataAttrsOf(col.cellProps?.(row))}
-            className="mt-0.5 min-w-0 break-words text-secondary"
+            className={cn("mt-0.5 min-w-0 break-words text-secondary", liftOwnClicks && keepsOwnClicks(col) && LIFTED_FIELD)}
           >
             {value}
           </dd>
@@ -95,6 +106,21 @@ export function StackedFields<T>({ columns, row, compact }: { columns: DataTable
   );
 }
 
+/**
+ * A stretched card's own-click cell (0.50 K4): above the title control's overlay
+ * (`after:z-[1]`), so its link or buttons take their own taps. `w-fit` keeps the lifted
+ * box to the cell's content, so the field's empty rest still opens the row.
+ */
+const LIFTED_CELL = "relative z-[2]";
+const LIFTED_FIELD = cn(LIFTED_CELL, "w-fit max-w-full justify-self-start");
+
+/**
+ * The keyboard frame of a stretched card (0.50 K4): FOCUS_RING's, inside the card,
+ * while its title control (`data-card-link`) has the focus.
+ */
+const STRETCHED_RING =
+  "has-[[data-card-link]:focus-visible]:ring-inset has-[[data-card-link]:focus-visible]:ring-focus has-[[data-card-link]:focus-visible]:ring-brand";
+
 /** The most fields the default phone card shows under its title (0.49 KIT-7). */
 export const MOBILE_CARD_FIELDS = 3;
 
@@ -308,6 +334,13 @@ export interface MobileRowProps<T> {
   mobileDir: Direction;
   /** No column the card renders owns a link, so the card itself may be one. */
   mobileCardLinkable: boolean;
+  /**
+   * The card draws cells that keep their own clicks, so it cannot be one control (0.50
+   * K4): its TITLE is the row's link (`rowHref`) or button (`onRowClick`), stretched over
+   * the card, and those cells sit above it. Only for the default card, never a
+   * `mobileCard`, and never when the title itself keeps its own clicks.
+   */
+  mobileCardStretched: boolean;
   mobileCard: DataTableProps<T>["mobileCard"];
   mobilePrimaryCol: DataTableColumn<T> | null;
   /** The `role: "status"` columns, drawn as chips beside the title (0.49 KIT-7). */
@@ -349,6 +382,7 @@ export function MobileRow<T>({
   swipeActionsFor,
   mobileDir,
   mobileCardLinkable,
+  mobileCardStretched,
   mobileCard,
   mobilePrimaryCol,
   mobileStatusColumns,
@@ -389,7 +423,10 @@ export function MobileRow<T>({
   // scrolling never meet the gesture. Until 0.40 an open card silently lost it.
   // In selection mode a sideways drag would be a second meaning for a selecting touch.
   const swipeEnabled = !!swipe && !selecting;
-  const href = mobileCardLinkable ? rowHref?.(row) : undefined;
+  // The stretched card (0.50 K4): the title is the control, the card a plain box.
+  // Selection mode keeps its own card (the whole card is the toggle there).
+  const stretched = mobileCardStretched && interactive && !selecting && !mobileCard && !!mobilePrimaryCol;
+  const href = mobileCardLinkable || stretched ? rowHref?.(row) : undefined;
   const cardClass = cn(
     "w-full text-start flex items-center",
     // §4: more room per row at Large — a taller row is a bigger tap target too.
@@ -409,7 +446,13 @@ export function MobileRow<T>({
     // AppShell main's `overflow-x-clip` — so the frame went missing on one side. A press
     // keeps the fill and the squeeze above; an outline on every tap of a long list would
     // be louder than the acknowledgement it replaces.
-    (interactive || selecting) && cn("[-webkit-tap-highlight-color:transparent] focus-visible:ring-inset", FOCUS_RING),
+    (interactive || selecting) &&
+      !stretched &&
+      cn("[-webkit-tap-highlight-color:transparent] focus-visible:ring-inset", FOCUS_RING),
+    // A stretched card (0.50 K4) draws the same frame, inside the card, while its TITLE
+    // control has the keyboard: the ring outlines the whole tap target, as on every other
+    // card, not the title's line alone. The own-click cells draw their own.
+    stretched && cn("relative [-webkit-tap-highlight-color:transparent]", STRETCHED_RING),
     selecting && "cursor-pointer",
     select?.selected && selecting && "bg-brand-soft",
     // A 500 ms hold would otherwise start a text selection, and iOS's link callout —
@@ -424,6 +467,45 @@ export function MobileRow<T>({
   // exactly one anchor exists per row.
   // The default card's filled fields and status values (0.49 KIT-7): an empty one
   // gets no line. Not computed for a `mobileCard`, which draws its own.
+  // The stretched card's title control (0.50 K4): the row's link, or a real <button>
+  // when the table only has `onRowClick` — a plain control, since nothing interactive
+  // sits inside it any more. Its `::after` covers the whole card, so a tap anywhere
+  // but on an own-click cell (lifted above it) lands on it, and a long press on the
+  // card is a long press on the link ("open in new tab"). Its accessible name is the
+  // title alone; the fields read as text after it. `data-row-link` marks it as the
+  // row itself for `fromOwnControl`, so the long press still arms on it.
+  const stretchedClass =
+    "block w-full text-start focus-visible:outline-none after:absolute after:inset-0 after:z-[1] after:content-['']";
+  const titleControl = (title: ReactNode) =>
+    href ? (
+      <RowLink
+        href={href}
+        data-card-link=""
+        data-row-link=""
+        onActivate={() => onRowClick!(row)}
+        aria-expanded={opensRow ? expanded : undefined}
+        className={stretchedClass}
+        // Enter follows RowLink's own onClick; Space opens the row too, not the list's scroll.
+        onKeyDown={(e) => {
+          if (e.key !== " ") return;
+          e.preventDefault();
+          onRowClick!(row);
+        }}
+      >
+        {title}
+      </RowLink>
+    ) : (
+      <button
+        type="button"
+        data-card-link=""
+        data-row-link=""
+        aria-expanded={opensRow ? expanded : undefined}
+        onClick={() => onRowClick!(row)}
+        className={cn(stretchedClass, "font-[inherit]")}
+      >
+        {title}
+      </button>
+    );
   const fields = mobileCard ? [] : filledFields(mobileSecondaryColumns, row);
   const statuses = mobileCard ? [] : filledFields(mobileStatusColumns, row);
   const actionCells = mobileCard ? [] : filledFields(mobileActionColumns, row);
@@ -455,7 +537,7 @@ export function MobileRow<T>({
                     data-card-title=""
                     className="min-w-0 flex-1 break-words font-medium"
                   >
-                    {mobilePrimaryCol.cell(row)}
+                    {stretched ? titleControl(mobilePrimaryCol.cell(row)) : mobilePrimaryCol.cell(row)}
                   </div>
                 )}
                 {statuses.length > 0 && (
@@ -472,7 +554,7 @@ export function MobileRow<T>({
             {fields.length > 0 && large ? (
               // §4: each label ABOVE its value at Large. Side by side, a label column
               // sized to the widest label leaves a value a sliver of a 240 px card.
-              <StackedFields columns={mobileSecondaryColumns} row={row} compact={compact} />
+              <StackedFields columns={mobileSecondaryColumns} row={row} compact={compact} liftOwnClicks={stretched} />
             ) : fields.length > 0 && (
               <dl
                 className={cn(
@@ -487,7 +569,7 @@ export function MobileRow<T>({
                     </dt>
                     <dd
                       {...dataAttrsOf(col.cellProps?.(row))}
-                      className="min-w-0 text-secondary self-center"
+                      className={cn("min-w-0 text-secondary self-center", stretched && keepsOwnClicks(col) && LIFTED_FIELD)}
                     >
                       {value}
                     </dd>
@@ -500,7 +582,11 @@ export function MobileRow<T>({
             {actionCells.length > 0 && (
               <div data-card-actions="" className="flex min-w-0 flex-wrap items-center justify-end gap-2">
                 {actionCells.map(({ col, value }) => (
-                  <div key={col.key} {...dataAttrsOf(col.cellProps?.(row))} className="flex min-w-0 justify-end">
+                  <div
+                    key={col.key}
+                    {...dataAttrsOf(col.cellProps?.(row))}
+                    className={cn("flex min-w-0 justify-end", stretched && LIFTED_CELL)}
+                  >
                     {value}
                   </div>
                 ))}
@@ -592,6 +678,11 @@ export function MobileRow<T>({
       />
       {cardInner}
     </div>
+  ) : stretched ? (
+    // The stretched card (0.50 K4): a plain box; its title is the control (above).
+    <div {...press} data-card-stretched="" className={cardClass}>
+      {cardInner}
+    </div>
   ) : interactive && href ? (
       // A card with a URL of its own is a LINK, not a div wearing role="button"
       // (feedback #451): the phone's long-press "open in new tab" and a screen

package/src/components/data-table-row.tsx

@@ -404,6 +404,7 @@ export interface DataTableMobileRowProps<T>
     | "opensRow"
     | "mobileDir"
     | "mobileCardLinkable"
+    | "mobileCardStretched"
     | "mobileCard"
     | "mobilePrimaryCol"
     | "mobileStatusColumns"

package/src/components/data-table.tsx

@@ -1483,6 +1483,13 @@ export function DataTable<T>({
   // renderer is opaque to us; a link inside one is the caller's to declare by
   // marking the column it comes from.
   const mobileCardLinkable = (mobileCard ? mobileColumns : [...onCard]).every((c) => !keepsOwnClicks(c));
+  // ...except on the default card (0.50 K4, kastlan): its title becomes the row's link
+  // (or, with only `onRowClick`, a button), stretched over the card, and the own-click
+  // cells — a tel: link, the actions row — sit above it, so "tap to open" stays and no
+  // control nests in another. A `mobileCard` stays the fallback above (its controls
+  // cannot be lifted), and so does a card whose title keeps its own clicks.
+  const mobileCardStretched =
+    !mobileCard && !mobileCardLinkable && !!mobilePrimaryCol && !keepsOwnClicks(mobilePrimaryCol);
   // The card list's reading direction, for the one thing on it CSS cannot flip: which
   // physical drag a logical `start`/`end` swipe action means. Read off the DOM through
   // a ref callback (it runs at commit, like a layout effect) because `dir` is an
@@ -1646,10 +1653,11 @@ export function DataTable<T>({
         className={rowClassName?.(row)}
         attrs={rowAttributes?.(row)}
         interactive={!!onRowClick}
-        href={mobileCardLinkable ? rowHref?.(row) : undefined}
+        href={mobileCardLinkable || mobileCardStretched ? rowHref?.(row) : undefined}
         swipeActionsFor={swipeActionsFor}
         mobileDir={mobileDir}
         mobileCardLinkable={mobileCardLinkable}
+        mobileCardStretched={mobileCardStretched}
         mobileCard={mobileCard}
         mobilePrimaryCol={mobilePrimaryCol}
         mobileStatusColumns={mobileStatusColumns}

package/src/components/dropdown.tsx

@@ -432,6 +432,8 @@ export function DropdownPanel({
     <div
       {...rest}
       ref={setPanel}
+      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6).
+      data-kit-layer=""
       dir={dir}
       onKeyDown={handleKeyDown}
       onPointerDownCapture={handlePointerDownCapture}

package/src/components/full-bleed-dialog.tsx

@@ -208,6 +208,9 @@ export function FullBleedDialog({
       // `tabIndex` below by passing one of them too — this is the element the focus
       // trap holds, and each of those failures is invisible on screen.
       {...rest}
+      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6):
+      // a backdrop, so the tour measures the panel inside it to tell a full-screen sheet.
+      data-kit-layer="backdrop"
       className={cn(
         "fixed inset-0 z-50 flex items-stretch justify-center bg-black/40 outline-none",
         closing ? "animate-overlay-out" : "animate-overlay",

package/src/components/modal.tsx

@@ -394,6 +394,9 @@ function ModalPanel({
       // that page from a screen reader for 220ms. Not `inert` — that would let a tap
       // fall through the fading backdrop to the row underneath.
       aria-hidden={exiting || undefined}
+      // A kit layer, for the tour's layer order (0.50, docs/tours-harmonization.md §11.6):
+      // a backdrop, so the tour measures the panel inside it to tell a full-screen sheet.
+      data-kit-layer="backdrop"
       className={cn(
         // Live #320. The panel below rises only where it is bottom-anchored: from md up
         // it is centred, and a centred box sliding up from off-screen reads as a

package/src/components/number-input.tsx

@@ -16,10 +16,11 @@ import { useEndWidth, useNumericField } from "./numeric-field";
 import type { CommitScope } from "./write-lock";
 import { cn } from "../lib/cn";
 import { commitExpression, formatResult } from "../lib/calc";
+import { dataAttributes, type DataAttributes } from "../lib/data-attributes";
 
 /** {@link NumberInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
  *  wrapper typed itself off `ComponentProps<typeof NumberInput>` until then. */
-export interface NumberInputProps extends FieldHelpProps {
+export interface NumberInputProps extends FieldHelpProps, DataAttributes {
   /** The text, DOT-decimal ("1234.5", or a calculation being typed: "12+5"), as
    *  `onChange` reports it — so a caller's `Number(value)` reads it. The field SHOWS it
    *  in the locale's mark (see `locale`). A comma here is read as the decimal mark too,
@@ -549,12 +550,16 @@ export function NumberInput(props: NumberInputProps) {
   ) : (
     field
   );
-  if (numeric.hint.captionText === undefined && numeric.errorEl === null && !reserve) return box;
+  const data = dataAttributes(props);
+  if (numeric.hint.captionText === undefined && numeric.errorEl === null && !reserve) {
+    // Bare, unless the caller tags it: then the same plain root as below carries the tags.
+    return Object.keys(data).length > 0 ? <div {...data}>{box}</div> : box;
+  }
   // Outside the field's own `relative` box, as Select's caption is: the calculator
   // and the unit are `inset-y-0` in it and would stretch down over a second line.
   // `className` stays on the field, so adding a caption cannot change what it styles.
   return (
-    <div>
+    <div {...data}>
       {box}
       <FieldCaption parts={numeric.hint} />
       {numeric.errorEl}

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: {