@eifi1/ui-kit 0.33.1 → 0.35.0

package/src/components/grouped-picker.tsx

@@ -1,9 +1,11 @@
-import { useEffect, useMemo } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import { useCallback, useId, useMemo } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from "react";
 import { ChevronDown } from "lucide-react";
 import { cn } from "../lib/cn";
-import { DropdownSearchHeader, useDropdownSearch } from "./dropdown";
-import { useKitLocale } from "../i18n/kit-labels";
+import { foldForSearch } from "../lib/text-match";
+import { ComboboxPanel, useComboboxCore, type ComboOption } from "./combobox-core";
+import { assignRef } from "./field-parts";
+import { DEFAULT_COMBOBOX_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
 
 export interface PickerGroup {
   key: string;
@@ -23,62 +25,101 @@ export interface PickerGroup {
  */
 export interface GroupedPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onSelect"> {
   groups: PickerGroup[];
-  /** Face of the closed picker button. */
+  /** Face of the closed picker button. A string also names the trigger when no
+   *  `aria-label` does. */
   buttonLabel: ReactNode;
   /** Keys of the current selection, if any. */
   selected: { group: string; item: string } | null;
   onSelect: (groupKey: string, itemKey: string) => void;
-  /**
-   * @deprecated Use `aria-label`, the DOM spelling every control in the kit now
-   * takes. Kept working — three apps pass it — and it applies only when
-   * `aria-label` is absent; it goes in a later minor.
-   */
-  ariaLabel?: string;
+  /** The filter box's prompt, and its accessible name. Default: `combobox.search` from
+   *  the {@link UiKitProvider}, else "Search". */
   filterPlaceholder?: string;
+  /** The TRIGGER — the focusable `<button>` — as on every picker of the kit (MultiSelect,
+   *  CountrySelect, CurrencySelect), not the wrapper the rest of the props go on (0.34,
+   *  API-2, refactor audit 2026-10). */
+  ref?: Ref<HTMLButtonElement>;
 }
 
+/** An item's value in the list: the group's key and the item's, which together are
+ *  unique where an item key alone is not (two groups may each have an "Other"). */
+const itemValue = (group: string, item: string) => `${group}\u0000${item}`;
+
 /** Panel picker for large grouped option sets: instead of one long flat
  * dropdown, the groups sit side by side as columns with their items listed
  * beneath (feedback #267/#276), narrowed by a filter box at the top (feedback
  * #267 rework). A query that matches a group's name keeps the whole group;
- * otherwise groups are reduced to their matching items. */
+ * otherwise groups are reduced to their matching items.
+ *
+ * On the picker family's foundation since round 0.34 (Wave 2, DUP-4 + BUG-12):
+ * `useComboboxCore` + `ComboboxPanel` in its `columns` layout. Its trigger promised a
+ * dialog that was no dialog, and the choice showed by colour alone; it is a combobox over
+ * a listbox now — one `role="group"` per column, named by its heading, the chosen item
+ * `aria-selected` and checked — with the arrow keys, Enter, a named filter box, the live
+ * result count, portal anchoring (dev#548) and, on a phone, the full-screen sheet
+ * (live #200) in one column. */
 export function GroupedPicker({
   groups,
   buttonLabel,
   selected,
   onSelect,
-  ariaLabel,
-  "aria-label": ariaLabelAttr,
+  "aria-label": ariaLabel,
   filterPlaceholder,
   className,
+  ref,
   ...rest
 }: GroupedPickerProps) {
-  const { open, setOpen, wrapperRef, query, setQuery, inputRef } = useDropdownSearch();
-
-  useEffect(() => {
-    if (!open) return;
-    const onKey = (e: KeyboardEvent) => {
-      if (e.key === "Escape") setOpen(false);
-    };
-    document.addEventListener("keydown", onKey);
-    return () => document.removeEventListener("keydown", onKey);
-  }, [open, setOpen]);
+  // `filter: false`: the filter below keeps a whole group when its name matches, so the
+  // panel is handed the rows, as CountrySelect's are. Escape is the core's layer on the
+  // kit's stack — this kept an Escape handler of its own on its panel (round 0.34 BUG-1),
+  // and the stack is the one answer to it now (DUP-1). Back closes the list, as it did on
+  // `useDropdown`.
+  const core = useComboboxCore<string>({ filter: false, backCloses: true });
+  const { open, setOpen, triggerRef, closeToTrigger, query } = core;
+  // The core anchors the panel to the trigger and hands focus back to it; the caller's
+  // `ref` wants the same element. One callback feeds both, as on MultiSelect.
+  const setTrigger = useCallback(
+    (el: HTMLButtonElement | null) => {
+      triggerRef.current = el;
+      assignRef(ref, el);
+    },
+    [ref, triggerRef],
+  );
+  const comboText = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS);
 
-  // Case folding in the provider's locale — see `rowMatches` for the Turkish "İ"
-  // that plain `toLowerCase` gets wrong.
+  // Folded as every kit list folds (DUP-5): the locale's case (the Turkish "İ" that
+  // plain `toLowerCase` gets wrong), and now the accents too — "zurich" finds Zürich.
   const locale = useKitLocale();
-  const filtered = useMemo(() => {
-    const fold = (s: string) => s.toLocaleLowerCase(locale);
-    const q = fold(query.trim());
-    if (!q) return groups;
-    return groups
-      .map((g) =>
-        fold(g.label).includes(q)
-          ? g
-          : { ...g, items: g.items.filter((i) => fold(i.label).includes(q)) },
-      )
-      .filter((g) => g.items.length > 0);
+  const results = useMemo(() => {
+    const q = foldForSearch(query.trim(), locale);
+    const has = (s: string) => foldForSearch(s, locale).includes(q);
+    const kept = q
+      ? groups
+          .map((g) => (has(g.label) ? g : { ...g, items: g.items.filter((i) => has(i.label)) }))
+          .filter((g) => g.items.length > 0)
+      : groups;
+    return kept.flatMap((g) =>
+      g.items.map(
+        (item): ComboOption<string> => ({
+          value: itemValue(g.key, item.key),
+          label: item.label,
+          icon: item.icon,
+          group: g.label,
+        }),
+      ),
+    );
   }, [groups, query, locale]);
+  // Back to keys for `onSelect`, by the value the row carries.
+  const keysOf = useMemo(() => {
+    const map = new Map<string, [string, string]>();
+    for (const g of groups) for (const item of g.items) map.set(itemValue(g.key, item.key), [g.key, item.key]);
+    return map;
+  }, [groups]);
+  const chosen = selected ? itemValue(selected.group, selected.item) : null;
+
+  const listboxId = `${useId()}-listbox`;
+  // The trigger's NAME: a combobox takes none from its content. The caller's
+  // `aria-label`, as on every picker of the kit, else the face when it is text.
+  const name = ariaLabel ?? (typeof buttonLabel === "string" ? buttonLabel : undefined);
 
   return (
     // `rest` goes on the wrapper, but the accessible NAME does not: this div is a
@@ -87,71 +128,52 @@ export function GroupedPicker({
     // makes, and the reason `aria-label` is destructured out rather than left in
     // `rest`. Spread FIRST so the attributes below, each of them a fix with an
     // incident behind it, cannot be clobbered from outside.
-    <div {...rest} ref={wrapperRef} className={cn("relative", className)}>
+    <div {...rest} className={cn("relative", className)}>
       <button
+        ref={setTrigger}
         type="button"
-        aria-haspopup="dialog"
+        // A closed choice that expands into the list below — the role every trigger
+        // picker in the kit wears. It said `aria-haspopup="dialog"` over a panel that was
+        // no dialog (BUG-12).
+        role="combobox"
+        aria-haspopup="listbox"
+        aria-controls={listboxId}
         aria-expanded={open}
-        aria-label={ariaLabelAttr ?? ariaLabel}
+        aria-label={name}
         onClick={() => setOpen((o) => !o)}
-        className="flex w-full items-center justify-between gap-2 rounded-md border border-[var(--border-strong)] bg-[var(--bg-surface)] px-2.5 py-1.5 text-sm text-[var(--text-primary)] hover:bg-[var(--bg-hover)]"
+        // Down/Up opens the list from the closed trigger, per the APG.
+        onKeyDown={(e) => {
+          if (e.key === "ArrowDown" || e.key === "ArrowUp") {
+            e.preventDefault();
+            setOpen(true);
+          }
+        }}
+        className="flex w-full items-center justify-between gap-2 rounded-md border border-strong bg-surface px-2.5 py-1.5 text-sm text-primary hover:bg-hover"
       >
-        <span className="truncate">{buttonLabel}</span>
-        <ChevronDown className="size-4 shrink-0 text-[var(--text-placeholder)]" />
+        {/* The trigger's label and each item wrap from Large up (text size §10.17,
+            round 0.34 T1: the sweep read "Choose a cat…" at 360 px / Extra large). */}
+        <span className="truncate-until-large">{buttonLabel}</span>
+        <ChevronDown className="size-4 shrink-0 text-placeholder" />
       </button>
-      {open && (
-        <div className="absolute start-0 z-30 mt-1 flex max-h-96 w-[min(56rem,85vw)] flex-col overflow-hidden rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg">
-          <DropdownSearchHeader
-            query={query}
-            onQueryChange={setQuery}
-            inputRef={inputRef}
-            placeholder={filterPlaceholder}
-          />
-          <div className="overflow-y-auto p-3">
-            {filtered.length === 0 ? (
-              <p className="text-sm text-[var(--text-muted)]">—</p>
-            ) : (
-              <div className="columns-2 gap-4 md:columns-3 xl:columns-4">
-                {filtered.map((g) => (
-                  <div key={g.key} className="mb-3 break-inside-avoid">
-                    <div className="mb-1 text-xs font-semibold uppercase tracking-wide text-[var(--text-muted)]">
-                      {g.label}
-                    </div>
-                    <ul className="space-y-0.5">
-                      {g.items.map((item) => {
-                        const isSelected =
-                          selected !== null &&
-                          g.key === selected.group &&
-                          item.key === selected.item;
-                        return (
-                          <li key={item.key}>
-                            <button
-                              type="button"
-                              onClick={() => {
-                                onSelect(g.key, item.key);
-                                setOpen(false);
-                              }}
-                              className={cn(
-                                "flex w-full items-center gap-1.5 rounded px-1.5 py-0.5 text-start text-sm",
-                                isSelected
-                                  ? "bg-[var(--brand-bg)] font-medium text-[var(--brand-muted)]"
-                                  : "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)]",
-                              )}
-                            >
-                              {item.icon && <span className="shrink-0">{item.icon}</span>}
-                              <span className="min-w-0 truncate">{item.label}</span>
-                            </button>
-                          </li>
-                        );
-                      })}
-                    </ul>
-                  </div>
-                ))}
-              </div>
-            )}
-          </div>
-        </div>
-      )}
+      <ComboboxPanel
+        core={{ ...core, results }}
+        listboxId={listboxId}
+        columns
+        // As wide as four columns want (56rem), within the glass, from the trigger's
+        // start — the panel it always was.
+        width={{ minRem: 56 }}
+        searchPlaceholder={filterPlaceholder ?? comboText.search}
+        sheetTitle={ariaLabel ?? buttonLabel}
+        isSelected={(v) => v === chosen}
+        onChoose={(o) => {
+          const keys = keysOf.get(o.value);
+          if (keys) onSelect(keys[0], keys[1]);
+          closeToTrigger();
+        }}
+        showCreate={false}
+        onCreate={() => {}}
+        createContent={null}
+      />
     </div>
   );
 }

package/src/components/help-popover.tsx

@@ -0,0 +1,115 @@
+import { useId } from "react";
+import type { ReactNode } from "react";
+import { HelpCircle } from "lucide-react";
+import { cn } from "../lib/cn";
+import type { RemLength } from "../hooks/use-breakpoint";
+import { FOCUS_RING } from "./focus-ring";
+import { Popover } from "./popover";
+
+/** {@link HelpPopover}'s props. */
+export interface HelpPopoverProps {
+  /**
+   * Names the "?" and the panel — a short question ("What do the statuses mean?") or
+   * "About <field>" ("About the settlement date"), in the reader's language. Required:
+   * a "?" named "?" tells a screen reader nothing about what it opens. Not the help
+   * itself, which is `children`.
+   */
+  label: string;
+  /** The help: a paragraph, or a few. Rendered in the panel at body size. */
+  children: ReactNode;
+  /** The panel's width — {@link Popover}'s `width`. Default `"20rem"`, a paragraph's
+   *  measure; it follows the text size and never exceeds the viewport. */
+  width?: number | RemLength;
+  /** Classes for the "?" button. */
+  className?: string;
+}
+
+/** A paragraph's measure: 320 px at Normal, in rem so it grows with the text size. */
+const HELP_WIDTH: RemLength = "20rem";
+
+/**
+ * A "?" whose HELP opens on a tap, a click or Enter — for a paragraph too long to print
+ * under a field (0.34, keksdose K3, live #400: *"Remove the long text and move it behind
+ * a clickable notice like a circle"*).
+ *
+ * **Help, not a fact** (docs/text-size-harmonization.md §10.23). {@link FieldHint} is
+ * the "?" for a FACT — a format, a limit, a consequence — and since 0.32 it turns into
+ * its own words under the field at Large and on a touch screen (`useInlineHint`, §4 "No
+ * fact only in a tooltip"), because a fact a reader cannot reach is a fact they do not
+ * have. That rule stays. This part is for HELP: why the field exists, how to choose,
+ * what the options mean — text the field is usable without. Printed inline it was the
+ * longest thing in keksdose's transaction form (four statuses, ~500 characters, on every
+ * new row on a phone). `useInlineHint` turns only a FieldHint into a caption, so this
+ * one stays on the label line at every size.
+ *
+ * **On a field.** Pass it as `hint`, as a FieldHint is passed: every kit field that
+ * puts a FieldHint on its label line puts this there too, as it does any `hint` that is
+ * not text (Input, Select, Textarea, NumberInput, AmountInput, the comboboxes and
+ * pickers, ToggleGroup, {@link FieldStrip}) — and an unlabelled one at its end edge,
+ * outside the box. The `@eifi1/ui-kit/rhf` bindings draw every `hint` under the field,
+ * this one included. It also stands on its own, beside a heading or a column title.
+ *
+ * **A popover, not a tooltip**: a tooltip bubble is for a line, and opens on hover a
+ * finger never makes. This is the kit {@link Popover}: it opens and closes on a tap or a
+ * click (and on Enter or Space, as any button does), closes on Escape and on a press
+ * outside, and takes the focus into its panel and gives it back to the "?" on close. The
+ * panel is a `dialog` named by `label` and described by the help, so a screen reader
+ * reads both on opening. The "?" says `aria-expanded` and `aria-haspopup="dialog"`.
+ *
+ * **"?" rather than "!"**: it answers a question ("what is the difference between
+ * accepted and cleared?", keksdose live #247); "!" is a warning.
+ *
+ * ```tsx
+ * <Select label="Status" hint={
+ *   <HelpPopover label="What do the statuses mean?">
+ *     Pending: … Accepted: … Cleared: … Reconciled: …
+ *   </HelpPopover>
+ * } … />
+ * ```
+ */
+export function HelpPopover({ label, children, width = HELP_WIDTH, className }: HelpPopoverProps) {
+  const panelId = useId();
+  const bodyId = useId();
+  return (
+    <Popover
+      width={width}
+      panelId={panelId}
+      // The panel is named by the question and described by the answer, so focus moving
+      // into it reads both.
+      aria-label={label}
+      aria-describedby={bodyId}
+      trigger={({ open, toggle, ref }) => (
+        <button
+          ref={ref}
+          // Never `submit`: the "?" sits on a field's label line, inside a form.
+          type="button"
+          aria-label={label}
+          aria-expanded={open}
+          aria-haspopup="dialog"
+          aria-controls={open ? panelId : undefined}
+          onClick={(e) => {
+            // The "?" sits in a label strip: the press is the "?"'s, not the field's.
+            e.preventDefault();
+            toggle();
+          }}
+          // FieldHint's look, so the two marks read as one family on a label line; the
+          // open one holds its hover colour while its panel shows.
+          className={cn(
+            "flex rounded-full text-placeholder transition-colors hover:text-secondary",
+            open && "text-secondary",
+            FOCUS_RING,
+            className,
+          )}
+        >
+          <HelpCircle aria-hidden className="size-3.5" />
+        </button>
+      )}
+    >
+      {() => (
+        <div id={bodyId} className="space-y-2 text-sm leading-snug text-primary">
+          {children}
+        </div>
+      )}
+    </Popover>
+  );
+}

package/src/components/hover-menu.tsx

@@ -1,7 +1,10 @@
-import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import type { ComponentPropsWithoutRef, KeyboardEvent as ReactKeyboardEvent, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
-import { useEscapeKey, useOutsideClick } from "../hooks/use-dismiss";
+import { mergeRefs } from "./field-parts";
+import { runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
+import { anchoredInline } from "../hooks/use-anchored-panel";
+import { dirOf } from "../lib/direction";
 
 /**
  * Exported and `<div>`-shaped: the top bar composes several of these side by side, and
@@ -17,21 +20,19 @@ export interface HoverMenuProps extends Omit<ComponentPropsWithoutRef<"div">, "c
   trigger: (state: { open: boolean; toggle: () => void; close: () => void }) => ReactNode;
   children: (close: () => void) => ReactNode;
   /**
-   * Which edge of the trigger the panel lines up with. `start`/`end` follow the
-   * reading direction (`end` is the right edge in LTR, the left in RTL); `left`/`right`
-   * are physical and kept for existing callers. Default `end` — the same right-aligned
-   * panel as before in LTR, mirrored in RTL.
+   * Which edge of the trigger the panel lines up with, by the reading direction: `end`
+   * is the right edge in LTR and the left in RTL. Default `end` — the same right-aligned
+   * panel as before in LTR, mirrored in RTL. The physical `left` / `right` went in 0.35
+   * (round 0.35 R1, refactor audit 2026-10, API-6e): `right` is `end` in a left-to-right
+   * page, `left` is `start`.
    */
-  align?: "start" | "end" | "left" | "right";
+  align?: "start" | "end";
   panelClassName?: string;
   /** Extra classes for the WRAPPER (the panel has {@link panelClassName}). */
   className?: string;
-  /**
-   * @deprecated Use the DOM spelling `aria-label`, which names the `role="menu"` panel. Kept working because keksdose, kastlan and lenkbank all pass
-   * this today and a rename to save one line of resolution is not a patch release; it
-   * loses to `aria-label` wherever both are given. Removal is a later minor.
-   */
-  ariaLabel?: string;
+  /** The WRAPPER, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —
+   *  merged with its own ref, which the outside click and the hover are measured on. */
+  ref?: Ref<HTMLDivElement>;
 }
 
 // Hovering waits briefly before opening so sweeping the cursor across a row of
@@ -42,7 +43,7 @@ const CLOSE_DELAY_MS = 120;
 
 type Phase = "closed" | "opening" | "open" | "closing";
 
-const ALIGN_CLASS = { start: "start-0", end: "end-0", left: "left-0", right: "right-0" } as const;
+const ALIGN_CLASS = { start: "start-0", end: "end-0" } as const;
 
 /** Explicit menu-item roles a caller may already have written. */
 const ITEM_ROLES = '[role="menuitem"],[role="menuitemcheckbox"],[role="menuitemradio"]';
@@ -89,11 +90,12 @@ export function HoverMenu({
   align = "end",
   panelClassName,
   className,
-  ariaLabel,
-  "aria-label": ariaLabelAttr,
+  "aria-label": ariaLabel,
+  ref,
   ...rest
 }: HoverMenuProps) {
   const wrapperRef = useRef<HTMLDivElement>(null);
+  const setWrapper = useMemo(() => mergeRefs(wrapperRef, ref), [ref]);
   const [phase, setPhase] = useState<Phase>("closed");
   const open = phase === "open" || phase === "closing";
 
@@ -174,14 +176,16 @@ export function HoverMenu({
     ) ?? null;
   const items = () => (menuRef.current ? applyMenuSemantics(menuRef.current) : []);
 
-  // Escape closes, from anywhere — it did nothing at all before. Focus goes back to the
-  // trigger only when it was inside the menu: a panel opened by hover while the user is
-  // typing elsewhere must not yank the caret over here on the way out.
-  useEscapeKey(() => {
+  // Escape closes, from anywhere — it did nothing at all before — as a layer on the kit's
+  // Escape stack, so inside a dialog it closes the menu and not the dialog (Wave 2,
+  // DUP-1). Focus goes back to the trigger only when it was inside the menu: a panel
+  // opened by hover while the user is typing elsewhere must not yank the caret over
+  // here on the way out.
+  const layer = useDismissLayer(open, () => {
     const hadFocus = wrapperRef.current?.contains(document.activeElement) ?? false;
     close();
     if (hadFocus) triggerEl()?.focus();
-  }, open);
+  });
 
   // Upgrade the markup every render while open (the caller's rows can change), then
   // honour a pending keyboard open.
@@ -248,8 +252,11 @@ export function HoverMenu({
   // Keep the panel inside the viewport (feedback #85): a wide panel anchored to a
   // trigger near a screen edge would otherwise spill off it (on mobile the guided-
   // tours menu ran off the left). Once open, measure and translate it horizontally
-  // just enough to sit within an 8px margin. Recomputed on each open; `shiftX` is
-  // subtracted first so the measurement is against the natural position.
+  // just enough to sit within an 8px margin of the GLASS — `anchoredInline` against
+  // the panel's own natural box, as every anchored panel clamps (Wave 2, DUP-7; it
+  // measured against `innerWidth`, which on a phone is the grown layout viewport).
+  // Recomputed on each open; `shiftX` is subtracted first so the measurement is
+  // against the natural position.
   const panelRef = useRef<HTMLDivElement>(null);
   const [shiftX, setShiftX] = useState(0);
   // Back to 0 on close, adjusted while rendering against the previous `open`.
@@ -264,13 +271,9 @@ export function HoverMenu({
     if (!el) return;
     const rect = el.getBoundingClientRect();
     if (rect.width === 0) return; // unmeasured (e.g. jsdom) — leave as-is
-    const margin = 8;
-    const naturalLeft = rect.left - shiftX;
-    const naturalRight = rect.right - shiftX;
-    let next = 0;
-    if (naturalRight > window.innerWidth - margin) next = window.innerWidth - margin - naturalRight;
-    if (naturalLeft + next < margin) next = margin - naturalLeft;
-    setShiftX(next);
+    const natural = { left: rect.left - shiftX, right: rect.right - shiftX };
+    const { left } = anchoredInline(natural, rect.width, { dir: dirOf(el), align: "left" });
+    setShiftX(left - natural.left);
     // eslint-disable-next-line react-hooks/exhaustive-deps -- recompute only on open/close
   }, [open]);
 
@@ -283,12 +286,18 @@ export function HoverMenu({
       // `...rest` first: the hover handlers below are the whole component, and a caller
       // passing one of its own must not silently replace them.
       {...rest}
-      ref={wrapperRef}
+      ref={setWrapper}
       className={cn("relative", className)}
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
       onKeyDown={(e) => {
-        rest.onKeyDown?.(e);
+        // The caller's handler sees Escape only while this menu is the layer on top: a
+        // tooltip on one of its rows takes that press first (round 0.35 R2, the rule
+        // the dialogs got first). Every other key, and a closed menu's, as before.
+        runOwnKeyDown(e, rest.onKeyDown, layer);
+        // Focus on the trigger or in the menu: the key stops here, so a panel around
+        // the menu does not close with it.
+        if (open) takeEscape(e);
         onKeyDown(e);
       }}
     >
@@ -306,12 +315,10 @@ export function HoverMenu({
             ref={menuRef}
             role="menu"
             // On the element with the role. It used to sit on the role-less wrapper,
-            // where no screen reader reads a name. The DOM spelling wins;
-            // {@link HoverMenuProps.ariaLabel} is the deprecated alias three apps still
-            // pass, so it stays as the fallback rather than as the answer.
-            aria-label={ariaLabelAttr ?? ariaLabel}
+            // where no screen reader reads a name.
+            aria-label={ariaLabel}
             className={cn(
-              "min-w-44 max-w-[calc(100vw-1rem)] rounded-md border border-[var(--border)] bg-[var(--bg-surface)] shadow-lg",
+              "min-w-44 max-w-[calc(100vw-1rem)] rounded-md border border-subtle bg-surface shadow-lg",
               panelClassName,
             )}
           >

package/src/components/iban-input-labels.ts

@@ -0,0 +1,15 @@
+// The English words of ./iban-input, in a module with no component code: the English
+// catalogue (src/i18n/defaults.ts) imports them without the component, so `en` loads as one
+// chunk like the other languages (0.34, KS U8). ./iban-input re-exports them.
+
+import type { IbanInputLabels } from "./iban-input";
+
+export const DEFAULT_IBAN_INPUT_LABELS: IbanInputLabels = {
+  format: "An IBAN starts with a two-letter country code and two check digits.",
+  country: (code) => `“${code}” is not the country code of an IBAN.`,
+  length: (actual, expected) =>
+    `An IBAN from this country has ${expected} characters — this one has ${actual}.`,
+  checksum: "The check digits don’t match — a character is probably mistyped.",
+  qrRequired: "This is a regular IBAN. A QR-bill needs the account’s QR-IBAN.",
+  qrNotAllowed: "This is a QR-IBAN, which only receives QR-bill payments. Enter the account’s regular IBAN.",
+};

package/src/components/iban-input.tsx

@@ -1,11 +1,13 @@
-import { forwardRef, useCallback, useLayoutEffect, useRef, useState } from "react";
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
 import type { ChangeEvent, FocusEvent, ReactNode } from "react";
-import { useKitLabels } from "../i18n/kit-labels";
+import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { cn } from "../lib/cn";
 import { IBAN_LENGTHS, compactIban, formatIban, ibanProblem } from "../lib/iban";
 import type { IbanKind, IbanProblem } from "../lib/iban";
-import { assignRef, hasMessage } from "./choice-parts";
-import { Input, type InputProps } from "./ui";
+import { hasContent } from "../lib/presence";
+import { assignRef } from "./field-parts";
+import { Input, type InputProps } from "./input";
+import { DEFAULT_IBAN_INPUT_LABELS } from "./iban-input-labels";
 
 // ── Labels ────────────────────────────────────────────────────────────────────
 
@@ -27,15 +29,8 @@ export interface IbanInputLabels {
   qrNotAllowed: string;
 }
 
-export const DEFAULT_IBAN_INPUT_LABELS: IbanInputLabels = {
-  format: "An IBAN starts with a two-letter country code and two check digits.",
-  country: (code) => `“${code}” is not the country code of an IBAN.`,
-  length: (actual, expected) =>
-    `An IBAN from this country has ${expected} characters — this one has ${actual}.`,
-  checksum: "The check digits don’t match — a character is probably mistyped.",
-  qrRequired: "This is a regular IBAN. A QR-bill needs the account’s QR-IBAN.",
-  qrNotAllowed: "This is a QR-IBAN, which only receives QR-bill payments. Enter the account’s regular IBAN.",
-};
+// Defined in ./iban-input-labels, which holds no component code (0.34, KS U8).
+export { DEFAULT_IBAN_INPUT_LABELS };
 
 /**
  * The `ibanInput` namespace: prop > `<UiKitProvider labels>` > English (0.22.0).
@@ -109,7 +104,7 @@ export interface IbanInputProps extends Omit<InputProps, "type" | "value" | "def
    *  {@link IbanKind} — and why the difference matters, {@link isQrIban}. */
   kind?: IbanKind;
   /** The messages, per field. See {@link IbanInputLabels}. */
-  labels?: Partial<IbanInputLabels>;
+  labels?: LabelOverride<IbanInputLabels>;
   /** The caller's own message, shown INSTEAD of the built-in one while it is set (a
    *  server's "this account is already on file"). `null`, `false` and `""` are no
    *  message, so `touched && errors.iban` can be passed as it is. */
@@ -146,10 +141,21 @@ export interface IbanInputProps extends Omit<InputProps, "type" | "value" | "def
  * an invalid IBAN checks {@link isValidIban} / {@link ibanProblem} itself — the field
  * shows the problem but does not own the submit.
  */
-export const IbanInput = forwardRef<HTMLInputElement, IbanInputProps>(function IbanInput(
-  { value, onValueChange, onChange, onFocus, onBlur, kind = "any", labels, error, inputClassName, ...rest },
+export function IbanInput({
+  // The `<input>` (InputProps'): a React 19 ref prop since 0.34 (MOD-4, refactor audit
+  // 2026-10), where this was `forwardRef`.
   ref,
-) {
+  value,
+  onValueChange,
+  onChange,
+  onFocus,
+  onBlur,
+  kind = "any",
+  labels,
+  error,
+  inputClassName,
+  ...rest
+}: IbanInputProps) {
   const text = useIbanInputLabels(labels);
   const compact = compactIban(value);
   const shown = formatIban(compact);
@@ -222,10 +228,9 @@ export const IbanInput = forwardRef<HTMLInputElement, IbanInputProps>(function I
       // ALWAYS passed, even while there is no message: a field that takes `error`
       // keeps its box, so the message coming and going under the caret never remounts
       // the input (see Input's FieldGroup) — this one comes and goes as you type.
-      error={hasMessage(error) ? error : problem ? messageFor(problem, compact, text) : undefined}
+      error={hasContent(error) ? error : problem ? messageFor(problem, compact, text) : undefined}
       // Groups of four line up only when every digit is the same width.
       inputClassName={cn("tabular-nums", inputClassName)}
     />
   );
-});
-IbanInput.displayName = "IbanInput";
+}