@eifi1/ui-kit 0.23.0 → 0.24.1

package/dist/wizard.d.ts

@@ -6,10 +6,7 @@ export { WizardStep, WizardStepProps } from './wizard/wizard-step.js';
 export { WizardSummary } from './wizard/wizard-summary.js';
 export { StepperNav } from './wizard/stepper-nav.js';
 import 'react';
-import './feedback-BxeQVzwq.js';
-import './feedback-attachment-fGAzZPf0.js';
-import './feedback/feedback-inbox.js';
-import 'lucide-react';
+import './feedback-DOwPu-Il.js';
 import './components/tooltip.js';
 import './hooks/use-anchored-rect.js';
 import './lib/clipping.js';
@@ -20,6 +17,7 @@ import './components/mini-calendar.js';
 import './components/calendar-heatmap.js';
 import './components/popover.js';
 import './components/chip.js';
+import 'lucide-react';
 import './components/field-sync.js';
 import './tour/tour.js';
 import './search/command-palette.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eifi1/ui-kit",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "type": "module",
   "description": "App-agnostic shared design system: domain-free React components, theme and tokens.",
   "_sideEffects": "The barrel (src/index.ts) re-exports EVERY component, including components/chart, which statically imports recharts. Without this field a bundler must assume each of those modules has side effects, so it cannot drop the unused ones: importing a Button from '@eifi1/ui-kit' dragged all 433KB of recharts into the consumer's ENTRY chunk, and Keksdose was preloading it on every page load, login included. Nothing in src/ imports for side effects (no bare imports, no CSS imports from JS, no module-level global writes) — the token stylesheet is its own './tokens.css' export — so this is safe. CSS is still listed so any future stylesheet survives. Re-checked when `flag-icons` left `dependencies` and tsup started emitting a `\"use client\"` banner: neither touches this. The flag stylesheet was never imported from JS in the first place (that was the finding), and a directive prologue is a string literal every bundler lifts out before it decides whether a module is inert.",
@@ -117,7 +117,7 @@
   "_dependencies": "Only what the package imports AND owns the version of. `lucide-react` is a PEER: every consumer already declares `lucide-react: ^0.511.0` itself, so a hard dependency here bought each of them a second copy of the icon set in node_modules — and pinned to 0.511.x it held all three behind a release line that is now at 1.x. The range is deliberately wide (`>=0.400.0 <2`): the kit imports named icon components and nothing else, which has been stable across that whole span, so the app picks the version. `flag-icons` was never imported at all — 5.6 MB of stylesheet and SVG installed into every consumer to support class NAMES (`fi fi-xx`) that CurrencyFlag, CurrencySelect and LanguageMenu render as strings. The host supplies that stylesheet; see the dependency section of README.md. It stays a devDependency because the showcase imports it.",
   "dependencies": {
     "clsx": "^2.1.1",
-    "tailwind-merge": "^3.3.0",
+    "tailwind-merge": "^3.7.0",
     "zustand": "^5.0.5"
   },
   "devDependencies": {

package/src/components/amount-input.tsx

@@ -60,17 +60,26 @@ interface AmountInputProps {
   className?: string;
   /**
    * Classes for the `<input>` itself — {@link NumberInput}'s and {@link Input}'s prop of
-   * the same name, merged the same way: after the field's own base classes, so it can
-   * restyle the figure (`text-end` for a money column whose decimal points line up,
-   * `font-medium`, a tighter `py-1` in a table cell), and before the end padding the
-   * calculator and the currency chip reserve and before the invalid border, so neither
-   * can be taken away by accident.
+   * the same name, merged the same way: after everything the field sets for LOOKS — the
+   * base classes, the plain end padding, the display shape's centring and the `tone`
+   * colour — so it can restyle the figure (`text-end` for a money column whose decimal
+   * points line up, `font-medium`, a tighter `py-1` or a symmetric `px-2` in a table
+   * cell, `text-transparent` while a figure is being re-fetched), and before what the
+   * field needs to WORK: the end padding the calculator and the currency chip reserve,
+   * and the invalid border. Neither of those can be taken away by accident — a caller's
+   * `px-2` keeps its start edge and the digits still stop short of the chip, and a
+   * borderless cell's `border-transparent` still turns red when the value is wrong.
    *
    * keksdose G7: the invoice's VAT cell right-aligns its figure, and with only
    * `className` (the wrapper) it reached the element through `[&_input]:text-end` — a
    * descendant selector that depends on the field's inner markup, which the kit is free
    * to change, and that a reader of the call site has to decode. {@link MoneyField}
    * passes it through, and `RhfMoneyField` takes it too.
+   *
+   * keksdose 0.24: until then it sat BEFORE the plain end padding (`pe-3`) and the tone,
+   * so the budget's assigned cell could not make its padding symmetric (`px-2` came out
+   * `px-2 pe-3`) and the holdings price could not hide an outflow-toned figure while
+   * re-fetching — both were back on `[&_input]:` selectors on the wrapper.
    */
   inputClassName?: string;
   id?: string;
@@ -337,6 +346,17 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
     // fighting itself through responsive overrides. `useMediaQuery` reads
     // synchronously on mount, so there is no field→figure flash.
     const asDisplay = variant === "display" && isMobile;
+    // Room for the trailing controls — the calculator and the currency chip — or
+    // nothing when neither trails. showCalc is always false on a phone, so the display
+    // shape only ever has to clear the currency chip — and it clears it by the chip's
+    // actual width (a text-sm code plus a chevron, ~58px) rather than the 5rem the
+    // boxed shape reserves. On a 375px screen those 16px are the difference between a
+    // readable figure and a clipped one (feedback #430 rework).
+    const trailingRoom = asDisplay
+      ? currency ? (editable ? "pe-16" : "pe-12") : undefined
+      : showCalc
+        ? currency ? (editable ? "pe-24" : "pe-16") : "pe-10"
+        : currency ? (editable ? "pe-20" : "pe-14") : undefined;
     const innerRef = useRef<HTMLInputElement>(null);
     const setRefs = useCallback(
       (el: HTMLInputElement | null) => {
@@ -521,27 +541,24 @@ export const AmountInput = forwardRef<HTMLInputElement, AmountInputProps>(
             // (feedback #314). FLOATING_INPUT_CLASS already bundles the peer +
             // transparent-placeholder bits.
             asDisplay ? DISPLAY_INPUT_CLASS : label !== undefined ? FLOATING_INPUT_CLASS : FIELD_BASE,
-            // The caller's, over the base and under everything below (see `inputClassName`).
-            inputClassName,
-            // Room for the trailing controls. showCalc is always false on a phone,
-            // so the display shape only ever has to clear the currency chip — and
-            // it clears it by the chip's actual width (a text-sm code plus a
-            // chevron, ~58px) rather than the 5rem the boxed shape reserves. On a
-            // 375px screen those 16px are the difference between a readable figure
-            // and a clipped one (feedback #430 rework).
-            asDisplay
-              ? currency ? (editable ? "pe-16" : "pe-12") : "pe-0"
-              : showCalc
-                ? currency ? (editable ? "pe-24" : "pe-16") : "pe-10"
-                : currency ? (editable ? "pe-20" : "pe-14") : "pe-3",
+            // The plain end padding, with nothing trailing: cosmetic, so the caller's
+            // to change (keksdose 0.24 — a symmetric `px-2` in a budget cell).
+            !trailingRoom && (asDisplay ? "pe-0" : "pe-3"),
             // Centred display shape: centre in what is LEFT of the currency chip.
             // `text-center` alone would centre the figure in the whole box, i.e.
-            // partly underneath the chip; the padding above is what takes the chip
+            // partly underneath the chip; the padding below is what takes the chip
             // out of the centring, and nothing is added at the start because a
             // mirrored reservation would spend the width twice (see `align`).
             asDisplay && align === "center" && "text-center",
-            // Last, so it wins over the base class's own text colour.
+            // Over the base class's own text colour.
             TONE_CLASS[tone],
+            // The caller's, over all of the above — base, plain padding, alignment and
+            // tone — and under only what the field needs to work (see `inputClassName`).
+            inputClassName,
+            // Room for the trailing controls, after the caller's so a `px-2` cannot run
+            // the digits under the chip (NumberInput's order, which reserves its unit
+            // and calculator the same way).
+            trailingRoom,
             invalid && FIELD_INVALID,
           )}
           aria-invalid={invalid || undefined}

package/src/components/autocomplete.tsx

@@ -14,6 +14,7 @@ import { useAnchorDir } from "./use-anchor-dir";
 import {
   ComboboxFieldLabel,
   DISABLED_ROW_CLASS,
+  endHintRowProps,
   isOptionEnabled,
   stepEnabled,
   useActiveOptionScroll,
@@ -120,6 +121,11 @@ export interface AutocompleteProps<V extends string | number = string>
    * `aria-describedby`, before any error; a {@link FieldHint} "?" rides the label line,
    * or with no label sits at the field's end edge, outside the box. Not the list's
    * `status` line, which talks about the lookup, not the field.
+   *
+   * Pass it — even as `undefined` — on a field whose hint comes and goes (0.24): the
+   * unlabelled field then keeps its end-hint row whether or not a "?" is in it, so the
+   * `<input>` is never re-parented, and focus and caret survive the toggle. The rule
+   * the rest of the family has had since 0.23 (and the fields since 0.22).
    */
   hint?: ReactNode;
   /**
@@ -159,7 +165,10 @@ export interface AutocompleteProps<V extends string | number = string>
 }
 
 function AutocompleteInner<V extends string | number = string>(
-  {
+  props: AutocompleteProps<V>,
+  ref: ForwardedRef<HTMLInputElement>,
+) {
+  const {
     value,
     onChange,
     options,
@@ -194,9 +203,7 @@ function AutocompleteInner<V extends string | number = string>(
     "aria-labelledby": ariaLabelledBy,
     "aria-describedby": ariaDescribedBy,
     ...rest
-  }: AutocompleteProps<V>,
-  ref: ForwardedRef<HTMLInputElement>,
-) {
+  } = props;
   const generated = useId();
   const fieldId = id ?? generated;
   // Off the GENERATED id: a caller's `id` is theirs to collide with.
@@ -303,7 +310,11 @@ function AutocompleteInner<V extends string | number = string>(
           {label}
         </ComboboxFieldLabel>
       )}
-      <EndHintRow hint={hasLabel ? undefined : hintParts.labelHint}>
+      {/* `"hint" in props`: the family's 0.22 rule (see `endHintRowProps`) — passed at
+          all, even as `undefined`, a hint keeps the unlabelled field's end-hint row, so
+          a "?" coming and going never re-parents the <input> under the caret (0.24, the
+          last of the family to get it; the siblings had it in 0.23). */}
+      <EndHintRow {...endHintRowProps("hint" in props, hasLabel, hintParts.labelHint)}>
         {withLock(
           <div ref={fieldRef} className={cn("relative", locked && "cursor-not-allowed")}>
             {icon && (

package/src/components/column-mapper.tsx

@@ -1,5 +1,5 @@
-import { useEffect, useEffectEvent, useState } from "react";
-import type { ChangeEvent, DragEvent, ReactNode } from "react";
+import { useCallback, useEffect, useEffectEvent, useRef, useState } from "react";
+import type { ChangeEvent, DragEvent, HTMLAttributes, ReactNode } from "react";
 import { Upload } from "lucide-react";
 
 import { useKitLabels, useKitLocale } from "../i18n/kit-labels";
@@ -17,6 +17,7 @@ import type {
   ColumnMapping,
   ColumnRole,
 } from "../lib/column-mapping";
+import { scrollIntoStrip, useStripFade } from "../lib/strip-fade";
 import { parseTextTable } from "../lib/table-text";
 import type { TableSeparator, TextTable } from "../lib/table-text";
 import { AlertBanner } from "./alert-banner";
@@ -100,7 +101,8 @@ export interface ColumnMapperLabels {
   roleOf: (column: string) => string;
   /** The role select's "no role" option. */
   ignore: string;
-  /** A required role in the select. */
+  /** A required role in the select — only while some role is NOT required: when
+   *  every one is, the mark tells no role from another (0.24, Kurvenschmiede). */
   requiredRole: (role: string) => string;
   /** Under the preview, when it shows fewer rows than were read. */
   previewOf: (shown: number, total: number) => string;
@@ -176,6 +178,29 @@ function formatList(
 
 // ── ColumnRoleTable ───────────────────────────────────────────────────────────
 
+/** A `data-*` attribute, typed so `{ "data-private": "" }` needs no cast. */
+type DataAttributes = { [key: `data-${string}`]: string | number | boolean | undefined };
+
+/**
+ * What {@link ColumnRoleTableProps.bodyProps} puts on the preview's `<tbody>`: `data-*`
+ * hooks, an `id`, a class, a style.
+ */
+export type ColumnRoleTableBodyProps = Omit<
+  HTMLAttributes<HTMLTableSectionElement>,
+  "children" | "dangerouslySetInnerHTML"
+> &
+  DataAttributes;
+
+/**
+ * What {@link ColumnRoleTableProps.rowProps} returns for one preview row's `<tr>` —
+ * the same shape as LineItems' `LineItemsRowProps`, on a table row.
+ */
+export type ColumnRoleTableRowProps = Omit<
+  HTMLAttributes<HTMLTableRowElement>,
+  "children" | "dangerouslySetInnerHTML"
+> &
+  DataAttributes;
+
 export interface ColumnRoleTableProps<
   R extends string,
   M extends ColumnMapping<R> = ColumnMapping<R>,
@@ -202,6 +227,26 @@ export interface ColumnRoleTableProps<
   /** Every role select disabled — keksdose locks them while a re-sniff replaces the
    *  table they point into. */
   disabled?: boolean;
+  /**
+   * Extra attributes for the preview's `<tbody>` (0.24) — keksdose: the sample rows are
+   * the user's own bank data (payees, memos, amounts), and its demo mode blurs exactly
+   * that through `.demo-mode [data-private]` (#336). With nowhere to put the attribute,
+   * its map step reached into the table with a `useLayoutEffect` that set it on the
+   * `<tbody>` after every commit; `bodyProps={{ "data-private": "" }}` declares it.
+   * There is deliberately no head counterpart: the column names and the role selects
+   * are what such a mode is there to show.
+   *
+   * Spread on the kit `TableBody`; a `className` is added to its own.
+   */
+  bodyProps?: ColumnRoleTableBodyProps;
+  /**
+   * Extra attributes for one preview row's `<tr>`, from its cells and its index in the
+   * preview (0.24) — the contract of LineItems' `rowProps` (keksdose K20), on a table:
+   * `data-*` hooks (a per-row `data-private`, a test id), an `id`, a class. Called for
+   * the rows drawn, the first {@link previewRows}. The row has no attributes of its own
+   * to protect; a `className` is added after its classes.
+   */
+  rowProps?: (row: readonly string[], index: number) => ColumnRoleTableRowProps | undefined;
   labels?: Partial<ColumnMapperLabels>;
   className?: string;
 }
@@ -217,13 +262,25 @@ export interface ColumnRoleTableProps<
  * not after the import. A column with no role says "Ignore" and its values are dimmed:
  * the state that most needs to be visible in a twelve-column bank export.
  *
- * Picking a role another column holds MOVES it ({@link assignColumnRole}). Required
- * roles say so in the list, and what the table still needs is named under it — a
- * required group as "either Amount, Debit or Credit".
+ * Picking a role another column holds MOVES it ({@link assignColumnRole}). What the
+ * table still needs is named under it — a required group as "either Amount, Debit or
+ * Credit". Required roles say "(required)" in the list only where some role is not
+ * (0.24): Kurvenschmiede's roles are all required, so the mark told no option from
+ * another, and on a phone it cut the role's own name short ("Zeit (s) (erforderl…")
+ * — the part of the option the reader has to read. The "Still needed" line already
+ * says what is missing; a mark that distinguishes nothing is only noise.
  *
  * The table scrolls sideways inside its own box (the kit {@link Table}'s wrapper, a
  * named, keyboard-reachable region while it overflows), so a wide export never widens
- * the page at 390px.
+ * the page at 390px. An edge with columns behind it fades out (0.24, Kurvenschmiede:
+ * on a phone the fourth column's select sat off-screen and nothing said there was more
+ * to the right; phone scrollbars are overlays that show only while you drag). It is
+ * the kit Tabs strip's measured fade: drawn only while something is hidden on that
+ * side, so a table that fits is painted as before; both ends once scrolled into the
+ * middle; the reading direction's own in RTL; never animated, so there is nothing for
+ * reduced motion to turn off; and a `mask-image`, which changes no layout and needs no
+ * background colour to fade to. A role select focused behind the fade is scrolled
+ * clear of it.
  */
 export function ColumnRoleTable<
   R extends string,
@@ -238,6 +295,8 @@ export function ColumnRoleTable<
   previewRows = 5,
   totalRows,
   disabled,
+  bodyProps,
+  rowProps,
   labels: labelsProp,
   className,
 }: ColumnRoleTableProps<R, M>) {
@@ -265,86 +324,119 @@ export function ColumnRoleTable<
       ? labelOf(gap[0])
       : labels.oneOf(formatList(gap.map(labelOf), "disjunction", locale)),
   );
+  // "(required)" only where it tells one option from another.
+  const markRequired = roles.some((role) => role.required !== true);
+
+  // The Table's own scroll wrapper — the `<table>`'s parent — is what overflows; the
+  // fade is measured on it and drawn on the box round it, which has the same edges.
+  const scroller = useRef<HTMLElement | null>(null);
+  const tableRef = useCallback((table: HTMLTableElement | null) => {
+    scroller.current = table?.parentElement ?? null;
+  }, []);
+  const fade = useStripFade(scroller);
 
   return (
     <div
       className={cn("min-w-0 space-y-1.5", className)}
       data-slot="column-role-table"
     >
-      <Table density="compact" framed aria-label={labels.table}>
-        <TableHead>
-          <TableRow>
-            {columns.map((column) => {
-              const role = roleOfColumn(roles, mapping, column);
-              const name = nameOf(column);
-              return (
-                <TableHeaderCell
-                  key={column}
-                  scope="col"
-                  className="min-w-36 py-2 align-top"
-                >
-                  <span className="block max-w-56 truncate pb-1 text-[11px] font-normal text-[var(--text-muted)]">
-                    {name}
-                  </span>
-                  <Select
-                    size="sm"
-                    className="w-full"
-                    aria-label={labels.roleOf(name)}
-                    value={role ?? ""}
-                    disabled={disabled}
-                    onChange={(event) =>
-                      onMappingChange(
-                        assignColumnRole(
-                          roles,
-                          mapping,
-                          column,
-                          event.target.value === ""
-                            ? null
-                            : (event.target.value as R),
-                        ),
-                      )
-                    }
+      <div
+        data-slot="column-role-table-scroll"
+        // In reading-direction terms ("start", "end", "both"), for a caller's styling.
+        data-overflow={fade.overflow}
+        style={
+          fade.mask
+            ? { maskImage: fade.mask, WebkitMaskImage: fade.mask }
+            : undefined
+        }
+      >
+        <Table
+          ref={tableRef}
+          density="compact"
+          framed
+          aria-label={labels.table}
+        >
+          <TableHead>
+            <TableRow>
+              {columns.map((column) => {
+                const role = roleOfColumn(roles, mapping, column);
+                const name = nameOf(column);
+                return (
+                  <TableHeaderCell
+                    key={column}
+                    scope="col"
+                    className="min-w-36 py-2 align-top"
                   >
-                    <option value="">{labels.ignore}</option>
-                    {roles.map((option) => (
-                      <option key={option.value} value={option.value}>
-                        {option.required === true
-                          ? labels.requiredRole(option.label)
-                          : option.label}
-                      </option>
-                    ))}
-                  </Select>
-                </TableHeaderCell>
-              );
-            })}
-          </TableRow>
-        </TableHead>
-        <TableBody>
-          {shown.map((row, index) => (
-            <TableRow key={index}>
-              {columns.map((column) => (
-                <TableCell
-                  key={column}
-                  data-ignored={
-                    roleOfColumn(roles, mapping, column) === null || undefined
-                  }
-                  className={cn(
-                    "font-mono whitespace-nowrap",
-                    // Dimmed, not hidden: its values are what tell you whether ignoring
-                    // it was right.
-                    roleOfColumn(roles, mapping, column) === null &&
-                      "text-[var(--text-muted)]",
-                  )}
-                >
-                  <span className="block max-w-56 truncate">
-                    {row[column] ?? ""}
-                  </span>
-                </TableCell>
-              ))}
+                    <span className="block max-w-56 truncate pb-1 text-[11px] font-normal text-[var(--text-muted)]">
+                      {name}
+                    </span>
+                    <Select
+                      size="sm"
+                      className="w-full"
+                      aria-label={labels.roleOf(name)}
+                      value={role ?? ""}
+                      disabled={disabled}
+                      // Focus brings a select behind the fade clear of it — the browser's
+                      // own scroll stops at the edge, under the fade.
+                      onFocus={(event) => {
+                        const cell = event.currentTarget.closest("th");
+                        if (scroller.current && cell)
+                          scrollIntoStrip(scroller.current, cell);
+                      }}
+                      onChange={(event) =>
+                        onMappingChange(
+                          assignColumnRole(
+                            roles,
+                            mapping,
+                            column,
+                            event.target.value === ""
+                              ? null
+                              : (event.target.value as R),
+                          ),
+                        )
+                      }
+                    >
+                      <option value="">{labels.ignore}</option>
+                      {roles.map((option) => (
+                        <option key={option.value} value={option.value}>
+                          {option.required === true && markRequired
+                            ? labels.requiredRole(option.label)
+                            : option.label}
+                        </option>
+                      ))}
+                    </Select>
+                  </TableHeaderCell>
+                );
+              })}
             </TableRow>
-          ))}
-        </TableBody>
-      </Table>
+          </TableHead>
+          <TableBody {...bodyProps}>
+            {shown.map((row, index) => (
+              <TableRow {...rowProps?.(row, index)} key={index}>
+                {columns.map((column) => (
+                  <TableCell
+                    key={column}
+                    data-ignored={
+                      roleOfColumn(roles, mapping, column) === null || undefined
+                    }
+                    className={cn(
+                      "font-mono whitespace-nowrap",
+                      // Dimmed, not hidden: its values are what tell you whether ignoring
+                      // it was right.
+                      roleOfColumn(roles, mapping, column) === null &&
+                        "text-[var(--text-muted)]",
+                    )}
+                  >
+                    <span className="block max-w-56 truncate">
+                      {row[column] ?? ""}
+                    </span>
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))}
+          </TableBody>
+        </Table>
+      </div>
       {total > shown.length && (
         <p className="text-xs text-[var(--text-muted)]">
           {labels.previewOf(shown.length, total)}
@@ -392,6 +484,12 @@ export interface ColumnMapperProps<R extends string> {
    *  order. */
   guess?: (table: TextTable) => ColumnMapping<R>;
   disabled?: boolean;
+  /** The preview table's `<tbody>` attributes — {@link ColumnRoleTableProps.bodyProps}
+   *  (0.24): `{ "data-private": "" }` for a table of someone's own data. */
+  bodyProps?: ColumnRoleTableBodyProps;
+  /** One preview row's `<tr>` attributes — {@link ColumnRoleTableProps.rowProps}
+   *  (0.24). `row` is the row as read, `index` its place in the preview. */
+  rowProps?: (row: readonly string[], index: number) => ColumnRoleTableRowProps | undefined;
   labels?: Partial<ColumnMapperLabels>;
   className?: string;
 }
@@ -439,6 +537,8 @@ export function ColumnMapper<R extends string>({
   previewRows = 5,
   guess,
   disabled = false,
+  bodyProps,
+  rowProps,
   labels: labelsProp,
   className,
 }: ColumnMapperProps<R>) {
@@ -632,6 +732,8 @@ export function ColumnMapper<R extends string>({
             onMappingChange={(mapping) => commit({ ...state, mapping })}
             previewRows={previewRows}
             disabled={disabled}
+            bodyProps={bodyProps}
+            rowProps={rowProps}
             labels={labelsProp}
           />
           {unread.length > 0 && (

package/src/components/combobox.tsx

@@ -1,5 +1,5 @@
 import { Fragment, useId, useMemo, useRef, useState } from "react";
-import type { ComponentPropsWithoutRef, ReactNode, RefObject } from "react";
+import type { ComponentPropsWithoutRef, ReactNode, Ref, RefObject } from "react";
 import { createPortal } from "react-dom";
 import { ChevronDown, Plus, X } from "lucide-react";
 import { FIELD_BASE, FIELD_FLOATING_PAD, FIELD_INVALID, PHONE_QUERY } from "./ui";
@@ -244,6 +244,14 @@ export interface ComboboxProps
   maxSuggestions?: number;
   searchPlaceholder?: string;
   closeLabel?: string;
+  /**
+   * The phone sheet's heading — and, as a string, the dialog's accessible name — for a
+   * field whose label is drawn by someone else: a form's `FormLabel` above it,
+   * which `RhfTextCombobox` hands over here (0.24). Default: `label`. Without either, the
+   * full-screen sheet opened untitled and unnamed, the one screen on a phone that has to
+   * say what it is asking for (live #200).
+   */
+  sheetTitle?: ReactNode;
   /**
    * Label for the row that COMMITS a value the list does not contain — e.g.
    * `(v) => \`Add "${v}" as payee\``. Supplying it turns the free text into
@@ -260,6 +268,15 @@ export interface ComboboxProps
    * values are all supposed to already exist.
    */
   createLabel?: (value: string) => string;
+  /**
+   * The `<input>` — the control a reader types in and the one focus belongs on — as a
+   * React 19 ref prop, the way {@link CountrySelect} takes its trigger's (0.24, kastlan:
+   * react-hook-form's focus-on-error calls `focus()` on whatever `field.ref` is handed,
+   * and a combobox with no ref inside a hand-wired `RhfField` gave it nothing, so a
+   * failed submit could not take the user to it). Not the wrapper: a ref is for focus,
+   * measurement and selection, and all three are the input's. `RhfTextCombobox` passes it.
+   */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /**
@@ -285,6 +302,7 @@ export function Combobox(props: ComboboxProps) {
     maxSuggestions,
     searchPlaceholder,
     closeLabel,
+    sheetTitle,
     createLabel,
     invalid,
     error,
@@ -296,6 +314,7 @@ export function Combobox(props: ComboboxProps) {
     autoFocus,
     onBlur,
     onSubmit,
+    ref,
     "aria-label": ariaLabel,
     // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
     // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
@@ -481,6 +500,7 @@ export function Combobox(props: ComboboxProps) {
               `peer`, so it is dimmed by hand above). */
           <div ref={fieldRef} className={cn("relative", inert && "cursor-not-allowed opacity-50")}>
             <input
+              ref={ref}
               id={fieldId}
               value={value}
               placeholder={placeholder}
@@ -616,7 +636,7 @@ export function Combobox(props: ComboboxProps) {
         <PickerSheet
           open={open && !inert}
           onClose={() => setOpen(false)}
-          title={label}
+          title={sheetTitle ?? label}
           // The sheet's input IS the field: this is a free-text control, so what is
           // typed here is the value (a brand-new payee is just a name nothing
           // matches), and the list below narrows as it changes.
@@ -794,6 +814,11 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
    *  list simply does not open. Default: `combobox.noResults` from the provider. */
   emptyLabel?: string;
   closeLabel?: string;
+  /** The phone sheet's heading (and, as a string, its accessible name) for a field
+   *  whose label is drawn by someone else — a form's `FormLabel`;
+   *  `RhfInlineEntityCombobox` hands its label over here (0.24). Default: `label`.
+   *  See {@link Combobox}'s `sheetTitle`. */
+  sheetTitle?: ReactNode;
   /** Offer a clear "×" in place of the chevron whenever something is selected.
    *
    *  Emptying the text already clears (see {@link reconcile}), and on a desktop that
@@ -870,6 +895,16 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
    * `commit`: a locked field opens no list at all.
    */
   createCommit?: boolean;
+  /**
+   * The `<input>` — the focusable control, the one a reader types in — as a React 19
+   * ref prop (0.24, kastlan). Its account picker is this component inside an
+   * `RhfField` render, and react-hook-form's focus-on-error calls `focus()` on whatever
+   * `field.ref` is handed: with no ref there was nothing to hand it, so a line-item form
+   * whose account was missing failed its submit and left the caret where it was. Pass
+   * `field.ref` here, or use `RhfInlineEntityCombobox`, which does. The wrapper is not
+   * reachable this way — focus and selection are the input's. See {@link Combobox}'s `ref`.
+   */
+  ref?: Ref<HTMLInputElement>;
 }
 
 /**
@@ -907,6 +942,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     searchPlaceholder,
     emptyLabel,
     closeLabel,
+    sheetTitle,
     clearable,
     clearLabel,
     disabledReason,
@@ -918,6 +954,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     invalid,
     error,
     hint,
+    ref,
     "aria-label": ariaLabel,
     // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
     // render-prop spreads `{ id, aria-describedby, aria-invalid, aria-required }`, and
@@ -1146,6 +1183,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
               `peer`, so it is dimmed by hand above). */
           <div ref={fieldRef} className={cn("relative", inert && "cursor-not-allowed opacity-50")}>
             <input
+              ref={ref}
               id={fieldId}
               value={shown}
               placeholder={placeholder}
@@ -1300,7 +1338,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
           // Closing without choosing keeps the value: `text` was never emptied, so
           // reconcile has nothing to undo — it just puts the label back.
           onClose={reconcile}
-          title={label}
+          title={sheetTitle ?? label}
           query={sheetQuery}
           onQueryChange={(v) => {
             setSheetQuery(v);