@eifi1/ui-kit 0.22.0 → 0.23.0

package/src/rhf/fields.tsx

@@ -13,6 +13,8 @@
  *   <RhfTimeInput name="meetingTime" label="Time" />
  *   <RhfDateRangePicker fromName="periodFrom" toName="periodTo" label="Period" />
  *   <RhfToggleGroup name="interval" label="Interval" options={INTERVALS} />
+ *   <RhfCountrySelect name="country" label="Country" preferred={["CH", "DE"]} />
+ *   <RhfMonthPicker name="fiscalYear" label="Fiscal year" mode="year" valueAsNumber />
  * </Form>
  * ```
  *
@@ -66,6 +68,8 @@ import {
 import { TimeInput, type TimeInputProps } from "../components/time-input";
 import { IbanInput, type IbanInputProps } from "../components/iban-input";
 import { PhoneInput, type PhoneInputProps } from "../components/phone-input";
+import { CountrySelect, type CountrySelectProps } from "../components/country-select";
+import { MonthPicker, type MonthPickerProps } from "../components/month-picker";
 import {
   ToggleGroup,
   type ToggleGroupBaseProps,
@@ -571,6 +575,10 @@ export type RhfMoneyFieldProps<
    *  with `rules` as well if a clamp needs explaining. */
   min?: number;
   max?: number;
+  /** Classes for the `<input>` — `className` is the item's box. {@link RhfTextField},
+   *  {@link RhfTextarea} and {@link RhfNumberField} take it; since 0.23 AmountInput
+   *  does too (keksdose G7: `text-end` for a money column). */
+  inputClassName?: string;
 };
 
 /** The amount a text reads as, or `undefined` for a draft that is not one yet. */
@@ -1197,6 +1205,252 @@ export function RhfPhoneInput<
   );
 }
 
+// ── country and month (0.23) ─────────────────────────────────────────────────
+
+type OwnCountrySelectProps = Omit<
+  CountrySelectProps<boolean>,
+  | "value"
+  | "onChange"
+  | "onBlur"
+  | "label"
+  | "hint"
+  | "error"
+  | "invalid"
+  | "disabled"
+  | "className"
+  | "id"
+  | "ref"
+  | "clearable"
+>;
+
+export type RhfCountrySelectProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> &
+  OwnCountrySelectProps & {
+    /** Offer the picker's clear "×" (and Delete on the trigger) while a country is
+     *  chosen. A clear stores `clearValue`. */
+    clearable?: boolean;
+    /** What a clear stores. Default `null`; `""` for a schema that spells "no
+     *  country" as an empty string (a zod `z.string().max(2)`, kastlan's). The picker
+     *  reads either back as empty. */
+    clearValue?: ComboClearValue;
+    /** Classes for the picker — `className` is the item's box. */
+    selectClassName?: string;
+  };
+
+/**
+ * {@link CountrySelect} bound to one field, which stores the ISO 3166-1 alpha-2 code
+ * ("CH", always upper-case), or `clearValue` once cleared (`clearable`). kastlan asked
+ * for it (0.22 adoption): its address form wired a `CountrySelect` through
+ * {@link RhfField}'s render, and with no ref on the picker react-hook-form's
+ * focus-on-error had nothing to focus — the one field on the form a failed submit
+ * could not take you to.
+ *
+ * Bound the way {@link RhfIbanInput} and {@link RhfPhoneInput} are: `field.ref` reaches
+ * the trigger (the picker's `ref`, 0.23), the form's error paints the trigger and is
+ * the shell's message under it, the hint is the shell's description — so neither is
+ * ever handed to the picker, and its box never changes when one comes or goes. The
+ * form's label names the trigger together with the chosen country, and is the phone
+ * sheet's title. `commit` and `disabledReason` are the picker's own: a country that
+ * saves itself stays focusable under a lock and says why.
+ *
+ * ```tsx
+ * <RhfCountrySelect name="country" label="Country" required
+ *   preferred={["CH", "LI", "DE", "AT", "FR", "IT"]} rules={{ required: "Choose a country" }} />
+ * ```
+ */
+export function RhfCountrySelect<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  label,
+  hint,
+  required,
+  disabled,
+  excludeWhenDisabled,
+  className,
+  clearable,
+  clearValue = null,
+  selectClassName,
+  labels,
+  ...countryProps
+}: RhfCountrySelectProps<TFieldValues, TName, TTransformed>) {
+  const labelled = hasContent(label);
+  // A string label is also what the field IS — the picker's `country` word, which
+  // titles the phone sheet. A caller's own `labels.country` still wins.
+  const ownLabels = typeof label === "string" ? { country: label, ...labels } : labels;
+  return (
+    <RhfField
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
+      render={({ field, invalid, labelId }) => {
+        const value: unknown = field.value;
+        return (
+          // FormControl clones this element with `id` / `aria-describedby` /
+          // `aria-invalid`, which the picker routes to its trigger.
+          <CountrySelect<boolean>
+            aria-required={required || undefined}
+            // The form's label, then the country (see the picker's `aria-labelledby`).
+            aria-labelledby={labelled ? labelId : undefined}
+            {...countryProps}
+            labels={ownLabels}
+            className={selectClassName}
+            ref={field.ref}
+            value={typeof value === "string" ? value : null}
+            clearable={clearable}
+            onChange={(code) => field.onChange(code ?? clearValue)}
+            // Focus leaving the picker (the wrapper's focusout) marks the field touched.
+            onBlur={field.onBlur}
+            disabled={field.disabled}
+            invalid={invalid}
+          />
+        );
+      }}
+    />
+  );
+}
+
+type OwnMonthPickerProps = Omit<
+  MonthPickerProps,
+  "value" | "onChange" | "onBlur" | "label" | "hint" | "error" | "invalid" | "disabled" | "className" | "id" | "mode"
+>;
+
+/** `mode` picks what the form stores, and `valueAsNumber` is only offered for a year. */
+type RhfMonthPickerMode =
+  | {
+      /** A month, stored as `"YYYY-MM"` (the default). */
+      mode?: "month";
+      valueAsNumber?: undefined;
+    }
+  | {
+      /** A year, stored as `"YYYY"` — or as a number with `valueAsNumber`. */
+      mode: "year";
+      /** Store the year as a number (`2026`) rather than `"2026"` — kastlan's budget
+       *  `fiscal_year` is an integer column. A number in the form reads back as its
+       *  year. */
+      valueAsNumber?: boolean;
+    };
+
+export type RhfMonthPickerProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+> = RhfFieldBaseProps<TFieldValues, TName, TTransformed> &
+  OwnMonthPickerProps & {
+    /** Classes for the picker — `className` is the item's box. As {@link RhfDateField}'s. */
+    inputClassName?: string;
+  } & RhfMonthPickerMode;
+
+function MonthControl({
+  field,
+  invalid,
+  id,
+  valueAsNumber,
+  mode,
+  inputClassName,
+  pickerProps,
+  required,
+  ...aria
+}: {
+  field: ControllerRenderProps;
+  invalid: boolean;
+  id: string;
+  valueAsNumber?: boolean;
+  mode?: "month" | "year";
+  inputClassName?: string;
+  pickerProps: OwnMonthPickerProps;
+  required?: boolean;
+  "aria-describedby"?: string;
+  "aria-invalid"?: MonthPickerProps["aria-invalid"];
+}) {
+  // MonthPicker forwards no ref; it routes `id` to its trigger, where the handle finds
+  // it — RhfDateField's way.
+  useFocusHandle(field.ref, () => document.getElementById(id));
+  const value: unknown = field.value;
+  return (
+    <MonthPicker
+      {...pickerProps}
+      {...aria}
+      // MonthPicker routes `aria-required` to its trigger since 0.23.0.
+      aria-required={required || undefined}
+      id={id}
+      mode={mode}
+      value={value === null || value === undefined ? "" : String(value)}
+      onChange={(key) => {
+        field.onChange(mode === "year" && valueAsNumber ? Number(key) : key);
+        // A pick is the whole interaction — there is no text to leave — so it touches.
+        field.onBlur();
+      }}
+      disabled={field.disabled}
+      invalid={invalid}
+      className={inputClassName}
+    />
+  );
+}
+
+/**
+ * {@link MonthPicker} bound to one field: a month as `"YYYY-MM"`, or with `mode="year"` a
+ * year as `"YYYY"` (`valueAsNumber` stores `2026`). kastlan asked for it with
+ * {@link RhfCountrySelect}: its budget wizard's fiscal year was a `MonthPicker
+ * mode="year"` inside {@link RhfField}'s render — the `String()` in, the `Number()`
+ * out, `invalid` by hand — and a failed submit could not focus it, because the picker
+ * forwards no ref.
+ *
+ * Bound as {@link RhfDateField} is: a focus handle finds the trigger by its id, so
+ * focus-on-error lands there; the form's error paints the trigger and is the shell's
+ * message; the hint is the shell's description; neither is handed to the picker, so
+ * its box never changes. Picking marks the field touched.
+ *
+ * ```tsx
+ * <RhfMonthPicker name="fiscalYear" label="Fiscal year" mode="year" valueAsNumber
+ *   min="2020" max="2029" rules={{ required: "Choose a year" }} />
+ * ```
+ */
+export function RhfMonthPicker<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+  TTransformed = TFieldValues,
+>({
+  name,
+  control,
+  rules,
+  label,
+  hint,
+  required,
+  disabled,
+  excludeWhenDisabled,
+  className,
+  inputClassName,
+  mode,
+  valueAsNumber,
+  ...pickerProps
+}: RhfMonthPickerProps<TFieldValues, TName, TTransformed>) {
+  return (
+    <RhfField
+      {...{ name, control, rules, label, hint, required, disabled, excludeWhenDisabled, className }}
+      render={({ field, invalid, id }) => (
+        // FormControl clones this element with `aria-describedby` / `aria-invalid`,
+        // which MonthControl hands on to the picker's trigger.
+        <MonthControl
+          field={field as unknown as ControllerRenderProps}
+          invalid={invalid}
+          id={id}
+          mode={mode}
+          valueAsNumber={valueAsNumber}
+          inputClassName={inputClassName}
+          pickerProps={pickerProps}
+          required={required}
+        />
+      )}
+    />
+  );
+}
+
 // ── select ───────────────────────────────────────────────────────────────────
 
 export interface RhfSelectOption {

package/src/rhf.ts

@@ -11,7 +11,8 @@ export * from "./rhf/form";
 export * from "./rhf/use-rhf-wizard-step";
 // Bound fields — one line per field (RhfTextField, RhfNumberField, RhfIntegerField, RhfMoneyField,
 // RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox; 0.22: RhfTimeInput,
-// RhfDateRangePicker, RhfToggleGroup, RhfIbanInput, RhfPhoneInput)
+// RhfDateRangePicker, RhfToggleGroup, RhfIbanInput, RhfPhoneInput; 0.23: RhfCountrySelect,
+// RhfMonthPicker)
 // and RhfField, the shell they are built on.
 export * from "./rhf/fields";
 // LineItems over useFieldArray.

package/src/shell/topbar-action-menu.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef } from "react";
+import { useId, useLayoutEffect, useRef } from "react";
 import type { KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
 import { Link } from "react-router";
 import { cn } from "../lib/cn";
@@ -11,9 +11,9 @@ import { TOPBAR_TRIGGER_CLASS } from "./topbar-controls";
 
 /**
  * One row of a {@link TopBarActionMenu}. An `action` (default) runs `onSelect`, a
- * `link` navigates via react-router, and a `divider` draws a rule. Non-divider
- * rows close the menu automatically when chosen. `kind` may be omitted for
- * actions, keeping the common case terse.
+ * `link` navigates via react-router, a `divider` draws a rule, and a `heading` names
+ * the rows after it. Action and link rows close the menu automatically when chosen.
+ * `kind` may be omitted for actions, keeping the common case terse.
  *
  * The rows are {@link MenuItem}s, so they take its options: `tone: "danger"` for the
  * log-out row, `checked` (+ `checkable`) for a choice, `current` for the link to the
@@ -46,7 +46,67 @@ export type TopBarMenuEntry =
       current?: boolean;
       disabled?: boolean;
     }
-  | { kind: "divider"; key: string };
+  | { kind: "divider"; key: string }
+  | {
+      /**
+       * A group heading (0.23, keksdose's guided-tours menu): the rows after it, up to
+       * the next heading, the next `divider` or the end of `entries`, are ONE group
+       * named by `label`. keksdose files its tours by topic and separated the blocks
+       * with bare dividers — "the kit's menu has no heading row to name them with"
+       * (tour-menu.tsx) — so a sighted reader had to guess what each block was and a
+       * screen reader was told nothing at all.
+       *
+       * Not a row: it takes no focus, the arrow keys (and Home/End) pass over it, and it
+       * never closes the menu. It is announced the way the kit's other grouped lists
+       * announce theirs (`CommandPalette`): the group's rows sit in a `role="group"`
+       * whose `aria-labelledby` is this heading, so a reader says "On this page, group"
+       * when the focus enters the first row, and nothing between rows.
+       *
+       * A divider ENDS the group, so a closing row such as "All tours…" behind a rule
+       * belongs to no topic. A heading with no rows under it is not drawn — an empty
+       * group names nothing; build the list from data and it may well be empty.
+       *
+       * The menu-wide `heading` prop is the panel's title, drawn once above everything;
+       * with group headings it is usually redundant (two stacked caps lines read as one),
+       * and the trigger's `ariaLabel` already names the menu.
+       */
+      kind: "heading";
+      key: string;
+      /** The group's name, shown above its rows and announced as the group's name. Keep
+       *  it short: it is set in small caps and wraps on a narrow panel. */
+      label: ReactNode;
+    };
+
+type HeadingEntry = Extract<TopBarMenuEntry, { kind: "heading" }>;
+type DividerEntry = Extract<TopBarMenuEntry, { kind: "divider" }>;
+type RowEntry = Exclude<TopBarMenuEntry, HeadingEntry | DividerEntry>;
+
+/** What the panel draws from `entries`: loose rows and rules, and headed groups. */
+type Block = { kind: "loose"; entry: RowEntry | DividerEntry } | { kind: "group"; heading: HeadingEntry; rows: RowEntry[] };
+
+/**
+ * Cut `entries` into blocks: a heading opens a group that takes the rows after it until
+ * the next heading or divider; everything else stands alone, as it always has.
+ */
+function toBlocks(entries: readonly TopBarMenuEntry[]): Block[] {
+  const blocks: Block[] = [];
+  let group: Extract<Block, { kind: "group" }> | null = null;
+  for (const entry of entries) {
+    if (entry.kind === "heading") {
+      group = { kind: "group", heading: entry, rows: [] };
+      blocks.push(group);
+    } else if (entry.kind === "divider") {
+      group = null;
+      blocks.push({ kind: "loose", entry });
+    } else if (group) {
+      group.rows.push(entry);
+    } else {
+      blocks.push({ kind: "loose", entry });
+    }
+  }
+  // A heading with nothing under it names nothing: not drawn (see the `heading` kind).
+  return blocks.filter((block) => block.kind === "loose" || block.rows.length > 0);
+}
 
 /**
  * The non-interactive identity block at the top of an account menu — kastlan's name +
@@ -130,6 +190,11 @@ function keepTabInsidePanel(e: ReactKeyboardEvent<HTMLUListElement>) {
  * It is also the ACCOUNT menu kastlan and keksdose each hand-build on `HoverMenu`: a
  * custom `trigger` (the avatar), a `header` (name + role / email), the rows, and a
  * free-content `footer` (the legal links).
+ *
+ * A long menu is grouped by topic with `{ kind: "heading" }` entries (0.23) — see
+ * {@link TopBarMenuEntry}. There is no separate phone layout: the panel is the same
+ * hover panel at 390px, kept inside the viewport by `HoverMenu`, and a heading wraps
+ * rather than widening it.
  */
 export function TopBarActionMenu({
   icon,
@@ -206,6 +271,10 @@ export function TopBarActionMenu({
   align?: "start" | "end" | "left" | "right";
   panelClassName?: string;
 }) {
+  // Names the groups' headings for `aria-labelledby`. Positional rather than from the
+  // entry's `key`, which is the caller's text and may hold a space — and a space in
+  // `aria-labelledby` is a list separator.
+  const uid = useId();
   return (
     <HoverMenu
       ariaLabel={ariaLabel}
@@ -258,6 +327,40 @@ export function TopBarActionMenu({
         const headerExtra = typeof header?.extra === "function" ? header.extra(close) : header?.extra;
         const footerClass =
           "flex flex-wrap gap-x-3 gap-y-1 text-xs text-[var(--text-muted)] [&_a:hover]:text-[var(--text-primary)] [&_a]:rounded-sm [&_a:focus-visible]:outline-none [&_a:focus-visible]:ring-2 [&_a:focus-visible]:ring-[var(--brand)]";
+        /** One action or link row — loose, or inside a heading's group. */
+        const row = (entry: RowEntry) => (
+          <li key={entry.key}>
+            {entry.kind === "link" ? (
+              <MenuItem
+                href={entry.to}
+                renderLink={({ href, ...p }) => <Link to={href} {...p} />}
+                onClick={close}
+                leading={entry.icon}
+                trailing={entry.trailing}
+                tone={entry.tone}
+                current={entry.current}
+                disabled={entry.disabled}
+              >
+                {entry.label}
+              </MenuItem>
+            ) : (
+              <MenuItem
+                onClick={() => {
+                  entry.onSelect();
+                  close();
+                }}
+                leading={entry.icon}
+                trailing={entry.trailing}
+                tone={entry.tone}
+                checked={entry.checked}
+                checkable={entry.checkable}
+                disabled={entry.disabled}
+              >
+                {entry.label}
+              </MenuItem>
+            )}
+          </li>
+        );
         return (
           // eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions -- a Tab bubbling up from a row or footer link, see keepTabInsidePanel
           <ul className={cn("py-1", panelClassName)} onKeyDown={keepTabInsidePanel}>
@@ -275,41 +378,34 @@ export function TopBarActionMenu({
                 {heading}
               </li>
             )}
-            {entries.map((entry) => {
-              if (entry.kind === "divider") {
-                return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+            {toBlocks(entries).map((block, i, blocks) => {
+              if (block.kind === "loose") {
+                const entry = block.entry;
+                if (entry.kind === "divider") {
+                  return <li key={entry.key} className="my-1 border-t border-[var(--border)]" />;
+                }
+                return row(entry);
               }
+              const headingId = `${uid}-group-${i}`;
+              const before = blocks[i - 1];
+              // Under a rule (or at the top of the rows) the rule's margin is the gap;
+              // straight under another group's last row the heading makes its own.
+              const tight = !before || (before.kind === "loose" && before.entry.kind === "divider");
               return (
-                <li key={entry.key}>
-                  {entry.kind === "link" ? (
-                    <MenuItem
-                      href={entry.to}
-                      renderLink={({ href, ...p }) => <Link to={href} {...p} />}
-                      onClick={close}
-                      leading={entry.icon}
-                      trailing={entry.trailing}
-                      tone={entry.tone}
-                      current={entry.current}
-                      disabled={entry.disabled}
-                    >
-                      {entry.label}
-                    </MenuItem>
-                  ) : (
-                    <MenuItem
-                      onClick={() => {
-                        entry.onSelect();
-                        close();
-                      }}
-                      leading={entry.icon}
-                      trailing={entry.trailing}
-                      tone={entry.tone}
-                      checked={entry.checked}
-                      checkable={entry.checkable}
-                      disabled={entry.disabled}
-                    >
-                      {entry.label}
-                    </MenuItem>
-                  )}
+                <li key={block.heading.key} role="none">
+                  <div
+                    id={headingId}
+                    role="presentation"
+                    className={cn(
+                      "px-3 pb-0.5 text-[11px] font-semibold uppercase tracking-wide text-[var(--text-muted)] [overflow-wrap:anywhere]",
+                      tight ? "pt-1" : "pt-2.5",
+                    )}
+                  >
+                    {block.heading.label}
+                  </div>
+                  <ul role="group" aria-labelledby={headingId}>
+                    {block.rows.map(row)}
+                  </ul>
                 </li>
               );
             })}

package/src/wizard/stepper-nav.tsx

@@ -31,7 +31,7 @@ import type { UseWizardReturn, WizardLabels } from "./types";
  * `isCommitStep`), so the policy options — `cancellable`, `onExit`, `commits`,
  * `onDone` — are all set on `useWizard`. What is set HERE is how the Finish button
  * looks and what wraps it, because that is presentation and usually depends on
- * state the app holds (a "replace everything" toggle, a write lock).
+ * state the app holds (a "replace everything" toggle, a write lock — `finishCommit`).
  */
 export function StepperNav<TData extends Record<string, unknown>>({
   wizard,
@@ -42,6 +42,8 @@ export function StepperNav<TData extends Record<string, unknown>>({
   labels,
   finishVariant = "brand",
   finishDisabled = false,
+  finishCommit,
+  finishDisabledReason,
   doneDisabled = false,
   renderFinish,
 }: {
@@ -57,6 +59,30 @@ export function StepperNav<TData extends Record<string, unknown>>({
   /** Disable Finish for a reason of the app's own, on top of the kit's gates
    *  (`canFinish`, submitting, validating). */
   finishDisabled?: boolean;
+  /**
+   * Finish COMMITS — {@link Button}'s `commit`, handed to the Finish button. Under a
+   * locked {@link WriteLockProvider} it is `aria-disabled` but focusable, with the lock's
+   * reason in the kit Tooltip, and a click (or Enter) does not run `wizard.finish`.
+   * Every other button of the bar stays live: the steps before the commit write nothing,
+   * so the whole wizard can still be walked through on a read-only page.
+   *
+   * keksdose G1: its YNAB import runs the mapping wizard on the read-only demo (dev#497)
+   * and locks only the confirm step's Finish — by cloning `commit` into the element
+   * `renderFinish` hands it, because StepperNav took no `commit` of its own. That clone
+   * still works; this is the same thing without one. Named `finishCommit` beside
+   * `finishVariant` / `finishDisabled` rather than a bare `commit`, which on a component
+   * with five buttons would not say which one saves — and would read like `useWizard`'s
+   * `commits`, which is a step's policy, not a lock.
+   */
+  finishCommit?: boolean;
+  /**
+   * Why Finish is not available — {@link Button}'s `disabledReason` on the Finish button:
+   * `aria-disabled` and focusable, the reason in the kit Tooltip and on the button's
+   * `aria-describedby`, `wizard.finish` not run. The explained form of `finishDisabled`
+   * (a native `disabled` takes the button out of the tab order, so its reason never
+   * reaches a keyboard). Under a lock with `finishCommit`, the lock's reason wins.
+   */
+  finishDisabledReason?: ReactNode;
   /**
    * Disable Done — the button of the last step after a commit — while the step still
    * has work of its own running. keksdose's YNAB import ends on a recurring step whose
@@ -82,6 +108,10 @@ export function StepperNav<TData extends Record<string, unknown>>({
    * re-derive (the problem this component exists to end); `onBeforeFinish` can veto
    * a click but cannot explain a disabled button. The element is a plain `<Button>`,
    * so a wrapper that clones it with `disabled` works as expected.
+   *
+   * For the write lock itself there is no need to wrap any more: `finishCommit` (and
+   * `finishDisabledReason`) put the kit Button's own Tooltip on Finish. An element
+   * cloned with `commit` here keeps working the same way.
    */
   renderFinish?: (button: ReactElement) => ReactNode;
 }) {
@@ -134,6 +164,10 @@ export function StepperNav<TData extends Record<string, unknown>>({
         variant={finishVariant}
         data-tour="wizard-finish"
         onClick={wizard.finish}
+        // The kit Button's lock: a reason (its own or, with `commit`, the provider's)
+        // wins over `disabled` and keeps the button reachable, saying why.
+        commit={finishCommit}
+        disabledReason={finishDisabledReason}
         disabled={wizard.isSubmitting || pending || !canFinish || finishDisabled}
         aria-busy={wizard.isSubmitting || pending || undefined}
       >

package/dist/components/field-anatomy.d.ts

@@ -1,95 +0,0 @@
-import * as react from 'react';
-import { ReactNode } from 'react';
-
-/** `undefined`, `null`, `false` and `""` are what a caller's `cond && "…"` evaluates to
- *  when there is nothing to say; none of them is content. A numeric `0` is. */
-declare function hasContent(node: ReactNode): boolean;
-/**
- * A `hint` that is plain TEXT is a caption under the field; anything else (a
- * `FieldHint` "?") rides the label line — the rule `Select` set in 0.15: the label
- * line is 11px of strip shared with the label, and a sentence placed there was set on
- * top of both the label and the value.
- */
-declare function isTextHint(hint: ReactNode): boolean;
-interface FieldMessages {
-    /** `invalid`, a message, or an `aria-invalid` from outside (a form library). */
-    isInvalid: boolean;
-    /** The caller's description, then the caption, then the error — the standing
-     *  advice before the news, as `useFieldError` in ui.tsx orders them. */
-    describedBy: string | undefined;
-    /** The caption and the error, for under the field; `null` when there is neither. */
-    below: ReactNode;
-    /** The hint for the LABEL line (a `FieldHint`), or `undefined` when the hint is a
-     *  caption or there is none. */
-    labelHint: ReactNode;
-}
-/** `hint` / `error` / `invalid` resolved the way `Select` resolves them. */
-declare function useFieldMessages({ hint, error, invalid, describedBy, ariaInvalid, }: {
-    hint?: ReactNode;
-    error?: ReactNode;
-    invalid?: boolean;
-    describedBy?: string;
-    ariaInvalid?: unknown;
-}): FieldMessages;
-/**
- * The field and what is under it, as one box — `FieldGroup` in ui.tsx, for the same
- * reasons written there. Nothing of its own while there is nothing under the field and
- * the caller passed no `error` key (the DOM is exactly what it was before these props);
- * once `error` is passed the box is kept even with no message, so the trigger is never
- * reparented — and remounted, losing focus — as the message comes and goes.
- */
-declare function FieldBox({ below, reserve, children, }: {
-    below: ReactNode;
-    reserve: boolean;
-    children: ReactNode;
-}): react.JSX.Element;
-/**
- * The static label in a trigger field's top strip — a {@link FieldLabel}, or, with a
- * `FieldHint`, the label and its "?" laid out on ONE flex row (dev#468: two absolute
- * offsets guessing at the same baseline put the "?" three pixels above its word).
- * `FloatingField`'s static-label row, except that it stops at `end-9`: the date and
- * month triggers keep that column (`pe-9`) for the calendar glyph or the clear ×, and a
- * long label truncates before it rather than putting the "?" on top of it.
- */
-declare function FieldLabelLine({ label, hint }: {
-    label: ReactNode;
-    hint?: ReactNode;
-}): react.JSX.Element;
-/**
- * How tall the strip over a bare group is.
- *
- *  - `"toggle"` — 16px. keksdose's `ClearedStatusPicker` (live #288 rework, #431,
- *    measured): *"16px of label strip plus a 26px group is exactly a labelled Input"*,
- *    so a status group in a row of 42px fields ends where they end. The label's line
- *    box runs into the group's top hairline, but the ACTIVE fill — the thing feedback
- *    #117 was about — starts at 19px, below the label's 17.75px.
- *  - `"tiles"` — 20px, keksdose's `FlagPicker` and location field (`pt-5`). A tile has
- *    no inset fill: its selection IS its frame, a 2px dark border-and-ring from the
- *    tile's top edge, so the tile has to start below the whole label line.
- */
-declare const LABEL_STRIP_PAD: {
-    readonly toggle: "pt-4";
-    readonly tiles: "pt-5";
-};
-/**
- * The 11px label (and its `FieldHint`) over a group that is NOT a field — keksdose K2:
- * a segmented control or a row of swatches standing in a form row beside labelled
- * inputs, whose label must sit on the same line as theirs (`top-1`, `inset-x-3`, the
- * type of a field's static label) without the group growing a field's border round
- * it. `id` goes on the label so the group can be `aria-labelledby` it.
- *
- * `relative` is load-bearing twice over: the row is positioned against it, and a
- * caller's `sr-only` label cannot escape it (sr-only-containment).
- */
-declare function LabelStrip({ labelId, label, hint, disabled, pad, className, children, }: {
-    labelId: string;
-    label: ReactNode;
-    hint?: ReactNode;
-    /** Dim the label with its group, as `peer-disabled:` dims a field's own. */
-    disabled?: boolean;
-    pad: keyof typeof LABEL_STRIP_PAD;
-    className?: string;
-    children: ReactNode;
-}): react.JSX.Element;
-
-export { FieldBox, FieldLabelLine, type FieldMessages, LABEL_STRIP_PAD, LabelStrip, hasContent, isTextHint, useFieldMessages };