@eifi1/ui-kit 0.21.0 → 0.23.0

package/src/rhf.ts

@@ -10,7 +10,9 @@ export * from "./rhf/form";
 // The react-hook-form bridge to the wizard's Next gate (useWizard lives in /wizard).
 export * from "./rhf/use-rhf-wizard-step";
 // Bound fields — one line per field (RhfTextField, RhfNumberField, RhfIntegerField, RhfMoneyField,
-// RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox)
+// RhfDateField, RhfTextarea, RhfSelect, RhfCheckbox, RhfCombobox, RhfTextCombobox; 0.22: RhfTimeInput,
+// 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/tour/tour.tsx

@@ -261,6 +261,43 @@ function sameRect(a: Rect | null, b: Rect | null): boolean {
   return a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
 }
 
+function rectOf(el: Element): Rect {
+  const r = el.getBoundingClientRect();
+  return { top: r.top, left: r.left, width: r.width, height: r.height };
+}
+
+/**
+ * What the finder established for ONE step: where its target is (`null` = no target,
+ * or not on the page), and the reading direction the card takes from it.
+ *
+ * It carries the step it was found for, and the overlay only believes it for that
+ * step — which is the whole fix for keksdose's tours audit 2026-10-02, §1.0 A ("stale
+ * spotlight on the step after a spotlighted one", 15 steps in 16 tours, desktop and
+ * phone, mouse and keyboard). When step N spotlit a target and step N+1 had none (or
+ * its anchor was missing), N+1 kept N's hole and parked its card beside it, so a
+ * centred "You're all set" read as pointing at the Import & Export link; Back→Next kept
+ * it for as long as anyone watched.
+ *
+ * The overlay used to hold `rect` and `ready` as separate states and reset them
+ * DURING RENDER when the step changed. React 19 does not keep a render-phase update
+ * while an earlier, lower-priority update to the same hook is still queued — it only
+ * writes the result to the base state "unless the queue is empty" — and the follow
+ * interval below queues exactly such an update every 250 ms (eagerly bailed out because
+ * the rect had not moved, but left in the queue for rebasing). So the click's render
+ * showed the reset, and the very next render (the finder saying "ready") re-based on
+ * the old rect. A deep link was fine because nothing had queued anything yet.
+ *
+ * Keying the result to its step does not depend on any of that ordering: a rect found
+ * for another step is not this step's rect, whatever the queue does with it, and a
+ * missing anchor reads as "no target" instead of as the last thing that was lit.
+ */
+interface Located {
+  index: number;
+  step: TourStep;
+  rect: Rect | null;
+  dir: Direction;
+}
+
 function TourOverlay({
   steps,
   index,
@@ -279,33 +316,31 @@ function TourOverlay({
   const step = steps[index];
   const isFirst = index === 0;
   const isLast = index === steps.length - 1;
-  const [rect, setRect] = useState<Rect | null>(null);
-  const [ready, setReady] = useState(false);
-  // A new step starts unlocated: reset during render when the step changes, so the
-  // previous step's spotlight never paints over the new one. The effect below then
-  // locates it.
-  const [locating, setLocating] = useState({ index, step });
-  if (locating.index !== index || locating.step !== step) {
-    setLocating({ index, step });
-    setReady(false);
-    setRect(null);
-  }
+  // A new step starts unlocated: whatever was found for another step (see `Located`)
+  // is ignored, so the overlay renders nothing until the effect below has located THIS
+  // step, and never the previous step's spotlight.
+  const [located, setLocated] = useState<Located | null>(null);
+  const current = located !== null && located.index === index && located.step === step ? located : null;
+  const ready = current !== null;
+  const rect = current?.rect ?? null;
   // The overlay is portalled to <body>, out of whatever `dir` subtree the app set, so it
   // takes the direction of the element it spotlights (the document's for a centered
   // step). Arrow keys and start/end placement read it.
-  const [dir, setDir] = useState<Direction>(() => dirOf(null));
+  const dir: Direction = current?.dir ?? "ltr";
   const rootRef = useRef<HTMLDivElement>(null);
 
   // Run beforeStep, then locate the target (retrying across route/render lag).
   useEffect(() => {
     let cancelled = false;
     let raf = 0;
+    // `null` = untargeted, or the finder gave up → the card centres, with no hole.
+    const settle = (el: Element | null) =>
+      setLocated({ index, step, rect: el ? rectOf(el) : null, dir: dirOf(el) });
     void (async () => {
       await step.beforeStep?.();
       if (cancelled) return;
       if (!step.target) {
-        setDir(dirOf(null));
-        setReady(true);
+        settle(null);
         return;
       }
       let tries = 0;
@@ -314,17 +349,11 @@ function TourOverlay({
         const el = queryVisibleTarget(step.target!);
         if (el) {
           el.scrollIntoView({ block: "center", behavior: "smooth" });
-          const r = el.getBoundingClientRect();
-          setRect({ top: r.top, left: r.left, width: r.width, height: r.height });
-          setDir(dirOf(el));
-          setReady(true);
+          settle(el);
           return;
         }
         if (tries++ < 45) raf = requestAnimationFrame(find);
-        else {
-          setDir(dirOf(null));
-          setReady(true); // give up → render centered
-        }
+        else settle(null); // give up → render centered
       };
       find();
     })();
@@ -334,15 +363,19 @@ function TourOverlay({
     };
   }, [index, step]);
 
-  // Follow the target as the page scrolls / reflows.
+  // Follow the target as the page scrolls / reflows — only once THIS step is located,
+  // and only into this step's result.
   useEffect(() => {
     if (!step.target) return;
     const update = () => {
       const el = queryVisibleTarget(step.target!);
       if (el) {
-        const r = el.getBoundingClientRect();
-        const next = { top: r.top, left: r.left, width: r.width, height: r.height };
-        setRect((prev) => (sameRect(prev, next) ? prev : next));
+        const next = rectOf(el);
+        setLocated((prev) =>
+          prev && prev.index === index && prev.step === step && !sameRect(prev.rect, next)
+            ? { ...prev, rect: next }
+            : prev,
+        );
       }
     };
     window.addEventListener("scroll", update, true);
@@ -358,14 +391,19 @@ function TourOverlay({
   // awaitClick: advance when the *real* target is clicked. The spotlight hole is
   // click-through (see the shields in the render below) so the element's own
   // handler runs first; we step forward on the next macrotask.
+  //
+  // Re-armed when the target turns up after the finder gave up (the follow effect
+  // lights it late): the card swaps Next for the "click the highlighted element" hint
+  // as soon as there is a rect, so the click must work from that moment too.
+  const spotted = rect !== null;
   useEffect(() => {
-    if (!ready || !step.awaitClick || !step.target) return;
+    if (!ready || !spotted || !step.awaitClick || !step.target) return;
     const el = queryVisibleTarget(step.target);
     if (!el) return;
     const onClick = () => window.setTimeout(() => onNext(), 0);
     el.addEventListener("click", onClick, { once: true });
     return () => el.removeEventListener("click", onClick);
-  }, [ready, index, step, onNext]);
+  }, [ready, spotted, index, step, onNext]);
 
   // Keyboard: Esc skips, Enter and the reading-direction arrow advance (→ in LTR,
   // ← in RTL), the other arrow goes back. On awaitClick steps Enter is ignored (it

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}
       >