@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/components/data-table-labels.ts

@@ -6,7 +6,6 @@
 // A type-only import: erased at build time, so this module stays free of the table
 // itself (and of react-router), which `i18n/defaults` relies on.
 import type { DataTableSortLabels } from "./data-table";
-import type { LabelOverride } from "../i18n/kit-labels";
 
 /** The phone sort control's four keys (`sortBy`, `sortDefault`, `sortAscending`,
  *  `sortDescending`, 0.22.0) are {@link DataTableSortLabels}', declared beside the
@@ -89,7 +88,7 @@ export interface DataTableLabels extends DataTableSortLabels {
    * A column's filter button and panel: "Filter Amount", and "Filter Amount (active)"
    * while the column is filtered (round 0.34 Wave 2, BUG-7c). Every column's used to be
    * "Filter" alike, and "filtered" was a colour. An app that translated only `filter`
-   * gets `"<filter>: <column>"` from it — see {@link resolveDataTableLabels}.
+   * gets `"<filter>: <column>"` from it: DataTable derives the one from the other.
    */
   filterColumn: (column: string, active: boolean) => string;
 
@@ -171,90 +170,9 @@ export const DEFAULT_DATA_TABLE_LABELS: DataTableLabels = {
   // The phone sort control (0.22.0). The same words as `DEFAULT_DATA_TABLE_SORT_LABELS`
   // in data-table.tsx, written out rather than spread in: importing that VALUE here
   // would make data-table.tsx and this module import each other (data-table.tsx reads
-  // its resolver from here), and would pull the whole table into `i18n/defaults`.
+  // these defaults from here), and would pull the whole table into `i18n/defaults`.
   sortBy: "Sort by",
   sortDefault: "Default order",
   sortAscending: "Ascending",
   sortDescending: "Descending",
 };
-
-/**
- * Merge caller overrides onto the English defaults (presets merged too, key by key, as
- * the provider merges them — so the parameter is a {@link LabelOverride}).
- *
- * The parameter is lenient on purpose — a table with no labels at all still
- * renders — but that is also how a translated app ends up half English and never
- * hears about it: lenkbank ships nineteen of these keys in English in a German UI
- * today, because every one of them is backfilled silently. The kit will not start
- * throwing over it (three apps depend on the lenient merge), so
- * {@link missingDataTableLabels} is the other half: it answers which keys fell back,
- * and an app asserts on that in its OWN test, where the answer is actionable.
- *
- * @deprecated 0.34 — pass `labels` to DataTable, or the provider's `dataTable`, which this
- * merge serves; removed in 0.35 from the public surface, where DataTable keeps it as its
- * own (refactor audit 2026-10, API-6a). One app test calls it.
- */
-export function resolveDataTableLabels(partial?: LabelOverride<DataTableLabels>): DataTableLabels {
-  if (!partial) return DEFAULT_DATA_TABLE_LABELS;
-  // An `undefined` preset is skipped, as the provider skips it, rather than blanking one.
-  const presets = { ...DEFAULT_DATA_TABLE_LABELS.presets };
-  for (const [key, text] of Object.entries(partial.presets ?? {})) if (text !== undefined) presets[key] = text;
-  const merged: DataTableLabels = { ...DEFAULT_DATA_TABLE_LABELS, ...partial, presets };
-  // `columnsCount` was split out of `columns` + a template literal. Consumers have
-  // been translating `columns` since 0.1, and backfilling the English default over
-  // that would hand them "Columns (4/9)" back for having translated the key that
-  // existed at the time — the same silent-English failure the audit records against
-  // this file. So the count is derived from the RESOLVED `columns` unless the caller
-  // states the whole sentence, which is the escape hatch for a language where the
-  // parenthetical does not fit.
-  if (partial.columns !== undefined && partial.columnsCount === undefined) {
-    merged.columnsCount = (visible, total) => `${merged.columns} (${visible}/${total})`;
-  }
-  // The same for `filterColumn` (0.34), from a translated `filter`: the app's own word
-  // with the column, rather than English for having translated the key that existed.
-  if (partial.filter !== undefined && partial.filterColumn === undefined) {
-    merged.filterColumn = (column) => `${merged.filter}: ${column}`;
-  }
-  return merged;
-}
-
-/**
- * The label keys `labels` does not supply, and which therefore come back English
- * from {@link resolveDataTableLabels}.
- *
- * For a consumer's own test:
- *
- * ```ts
- * expect(missingDataTableLabels(de.dataTable)).toEqual([]);
- * ```
- *
- * which fails the day the kit adds a key — which is the point. Adding a label is
- * additive here and a silent regression in a translated app, and nothing else in
- * either repository can tell the two apart.
- *
- * Preset labels are reported one at a time (`presets.yesterday`), because `presets`
- * is a `Record` merged key by key: answering `"presets"` would say nothing about
- * which of the eleven are still English.
- *
- * @deprecated 0.34 — `missingKitLabels(labels, DEFAULT_UI_KIT_LABELS)`, which checks every
- * namespace, the table's among them, and which all three apps' tests already call;
- * removed in 0.35 (refactor audit 2026-10, API-6a).
- */
-export function missingDataTableLabels(labels?: Partial<DataTableLabels>): string[] {
-  const missing: string[] = [];
-  for (const key of Object.keys(DEFAULT_DATA_TABLE_LABELS) as Array<keyof DataTableLabels>) {
-    if (key === "presets") continue;
-    if (labels?.[key] !== undefined) continue;
-    // `columnsCount` is DERIVED from a translated `columns` by the resolver above,
-    // so a caller who set that one is not leaking English here. Reporting it would
-    // send them to translate a key they have already covered, and an `toEqual([])`
-    // assertion built on this would never go green.
-    if (key === "columnsCount" && labels?.columns !== undefined) continue;
-    if (key === "filterColumn" && labels?.filter !== undefined) continue;
-    missing.push(key);
-  }
-  for (const preset of Object.keys(DEFAULT_DATA_TABLE_LABELS.presets)) {
-    if (labels?.presets?.[preset] === undefined) missing.push(`presets.${preset}`);
-  }
-  return missing;
-}

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

@@ -1,13 +1,16 @@
 import type { CSSProperties, ReactNode } from "react";
 import { ROW_ACTIONS_KEY } from "./data-table-row-actions";
-import type { DataTableLabels } from "./data-table-labels";
+import { DEFAULT_DATA_TABLE_LABELS, type DataTableLabels } from "./data-table-labels";
 import type { DataTableCellProps, DataTableColumn, DataTableHeadProps } from "./data-table";
+import type { LabelOverride } from "../i18n/kit-labels";
 
 // What DataTable shares with its header (data-table-head.tsx), its column panel and its
 // phone layout (data-table-mobile.tsx): the cell-attribute and alignment rules, a
 // column's plain-text name, and the row link. Moved out of data-table.tsx unchanged
 // (refactor audit 2026-10, MOD-3), into a module of their own so none of those has to
-// import data-table.tsx at run time — which imports them.
+// import data-table.tsx at run time — which imports them. Since 0.35 also the table's
+// label resolver, which DataTable and its FilterPopover share and the barrel no longer
+// exports (round 0.35 R1).
 
 /**
  * Split a caller's cell attributes into what may reach the element and what the kit
@@ -80,6 +83,56 @@ export function columnLabel<T>(col: DataTableColumn<T>, labels?: DataTableLabels
   return col.headerText ?? (typeof col.header === "string" ? col.header : col.key);
 }
 
+/**
+ * The table's labels: caller overrides merged onto the English defaults (presets merged
+ * too, key by key, as the provider merges them — so the parameter is a
+ * {@link LabelOverride}).
+ *
+ * DataTable's own, and FilterPopover's: public until 0.35, when it left the barrel for
+ * DataTable's `labels` and the provider's `dataTable`, which it serves (round 0.35 R1,
+ * refactor audit 2026-10 API-6a). It stays a resolver rather than `useKitLabels` for the
+ * two keys it derives (`columnsCount`, `filterColumn`), which a plain merge would not.
+ *
+ * Lenient on purpose — a table with no labels at all still renders — so a translated app
+ * finds out what fell back to English from `missingKitLabels(labels,
+ * DEFAULT_UI_KIT_LABELS)` in its own test, where the answer is actionable.
+ */
+export function resolveDataTableLabels(
+  ...layers: (LabelOverride<DataTableLabels> | undefined)[]
+): DataTableLabels {
+  if (!layers.some(Boolean)) return DEFAULT_DATA_TABLE_LABELS;
+  // The layers in order, the provider's then the prop's, later winning key by key. An
+  // `undefined` key is skipped, as `useKitLabels` skips it, rather than blanking the word
+  // under it: DataTable spread `{ ...provider, ...prop }`, so `labels={{ autoSize:
+  // undefined }}` blanked the provider's word and the English one (round 0.35). `presets`
+  // is a record and is merged the same way, so renaming one keeps the other ten.
+  const partial: Partial<Omit<DataTableLabels, "presets">> = {};
+  const presets = { ...DEFAULT_DATA_TABLE_LABELS.presets };
+  for (const layer of layers) {
+    for (const [key, value] of Object.entries(layer ?? {})) {
+      if (value === undefined) continue;
+      if (key !== "presets") Object.assign(partial, { [key]: value });
+      else for (const [preset, text] of Object.entries(value)) if (text !== undefined) presets[preset] = text;
+    }
+  }
+  const merged: DataTableLabels = { ...DEFAULT_DATA_TABLE_LABELS, ...partial, presets };
+  // `columnsCount` was split out of `columns` + a template literal. Consumers have
+  // been translating `columns` since 0.1, and backfilling the English default over
+  // that would hand them "Columns (4/9)" back for having translated the key that
+  // existed at the time. So the count is derived from the RESOLVED `columns` unless the
+  // caller states the whole sentence, which is the escape hatch for a language where
+  // the parenthetical does not fit.
+  if (partial.columns !== undefined && partial.columnsCount === undefined) {
+    merged.columnsCount = (visible, total) => `${merged.columns} (${visible}/${total})`;
+  }
+  // The same for `filterColumn` (0.34), from a translated `filter`: the app's own word
+  // with the column, rather than English for having translated the key that existed.
+  if (partial.filter !== undefined && partial.filterColumn === undefined) {
+    merged.filterColumn = (column) => `${merged.filter}: ${column}`;
+  }
+  return merged;
+}
+
 /**
  * Whether a click that reached `row`'s handler did not start in the row's own DOM.
  *

package/src/components/data-table.tsx

@@ -5,7 +5,15 @@ import { Spinner } from "./spinner";
 import { ROW_ACTIONS_KEY, useRowActionColumn } from "./data-table-row-actions";
 import { useColumnResize } from "./data-table-resize";
 import { useRangeSelection } from "./data-table-selection";
-import { RowLink, cleanAttrs, columnLabel, fromOutside, logicalAlign, splitCellProps } from "./data-table-shared";
+import {
+  RowLink,
+  cleanAttrs,
+  columnLabel,
+  fromOutside,
+  logicalAlign,
+  resolveDataTableLabels,
+  splitCellProps,
+} from "./data-table-shared";
 import { MobileFilters, MobileRow, MobileSort, StackedFields } from "./data-table-mobile";
 import { DataTableHead } from "./data-table-head";
 import { ColumnSettingsPanel } from "./data-table-column-settings";
@@ -20,7 +28,7 @@ import type { SwipeAction } from "./swipeable-row";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import { usePhoneLayout } from "../hooks/use-breakpoint";
 import { useAnnounce } from "../hooks/use-announce";
-import { DEFAULT_DATA_TABLE_LABELS, resolveDataTableLabels, type DataTableLabels } from "./data-table-labels";
+import { DEFAULT_DATA_TABLE_LABELS, type DataTableLabels } from "./data-table-labels";
 import { useKitLabelOverrides, useKitLocale, useKitTableStorageKeyPrefix, type LabelOverride } from "../i18n/kit-labels";
 import { useEdgeFade } from "../lib/strip-fade";
 import { dirOf, type Direction } from "../lib/direction";
@@ -294,6 +302,16 @@ export interface DataTableProps<T> {
   onFiltersChange?: (next: FilterState) => void;
   sorts?: SortState[];
   onSortsChange?: (next: SortState[]) => void;
+  /**
+   * Controlled page size, as `sorts` above: the table pages by it and hands its pager's
+   * choice to `onPageSizeChange` (`Infinity` is "All"). For tables that page ALIKE —
+   * `TranslationReviewPanel`'s groups share one page size as they share one sort
+   * (0.35). Left out, the table keeps its own, from `defaultPageSize`, the URL and
+   * `storageKey`. A change of value sends a client-side table back to page 1. In
+   * `serverPagination` mode the page size is `serverPagination.pageSize`.
+   */
+  pageSize?: number;
+  onPageSizeChange?: (pageSize: number) => void;
   /**
    * Opt-in multi-row selection (desktop table only). When provided, a leading
    * checkbox column is rendered with a select-all box in the header; the owner
@@ -556,7 +574,7 @@ export interface DataTableProps<T> {
    * On a phone it heads the summary card, which is also named by it.
    *
    * There is no built-in default word: a new kit label key is a silent English string
-   * in every translated app (see `missingDataTableLabels`), and the caller has the
+   * in every translated app (see `missingKitLabels`), and the caller has the
    * word in its own catalogue already. Without it the row is unlabelled on screen —
    * pass one.
    */
@@ -728,6 +746,8 @@ export function DataTable<T>({
   onFiltersChange,
   sorts: sortsProp,
   onSortsChange,
+  pageSize: pageSizeProp,
+  onPageSizeChange,
   selection,
   labels: labelsProp,
   locale: localeProp,
@@ -775,19 +795,7 @@ export function DataTable<T>({
   // prop to, `TranslationReviewPanel`'s among them.
   const providerStorageKeyPrefix = useKitTableStorageKeyPrefix();
   const storageKeyPrefix = storageKeyPrefixProp ?? providerStorageKeyPrefix ?? DEFAULT_PERSIST_PREFIX;
-  const labels = useMemo(
-    () =>
-      resolveDataTableLabels(
-        labelOverrides || labelsProp
-          ? {
-              ...labelOverrides,
-              ...labelsProp,
-              presets: { ...labelOverrides?.presets, ...labelsProp?.presets },
-            }
-          : undefined,
-      ),
-    [labelOverrides, labelsProp],
-  );
+  const labels = useMemo(() => resolveDataTableLabels(labelOverrides, labelsProp), [labelOverrides, labelsProp]);
   const locale = useKitLocale(localeProp);
 
   // ---- Row actions ---- (data-table-row-actions.tsx)
@@ -830,6 +838,8 @@ export function DataTable<T>({
     defaultPageSize,
     sortsProp,
     filtersProp,
+    // Ignored in `serverPagination` mode, where the owner's is the page size.
+    pageSizeProp: isServer ? undefined : pageSizeProp,
   });
 
   // With the controls that change them switched off, persisted widths and hidden
@@ -1841,7 +1851,9 @@ export function DataTable<T>({
                 isServer
                   ? serverPagination!.onPageSizeChange
                   : (n) => {
-                      setPageSize(n);
+                      // To the owner when it holds the page size, as `commitSorts` does.
+                      if (onPageSizeChange) onPageSizeChange(n);
+                      else setPageSize(n);
                       setPage(0);
                     }
               }

package/src/components/date-field.tsx

@@ -19,7 +19,7 @@ import {
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
 import { FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
-import { assignRef, FieldLabelLine, LABEL_ABOVE_BOX } from "./field-parts";
+import { assignRef, FieldLabelLine, LABEL_ABOVE_BOX, type FieldHelpProps } from "./field-parts";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import type { RemLength } from "../hooks/use-breakpoint";
 import type { MiniCalendarProps } from "./mini-calendar";
@@ -34,7 +34,7 @@ import { Popover } from "./popover";
  * `FormEvent`, while both pickers answer with ISO date strings. Each declares its own
  * (date-picker.tsx, date-range-picker.tsx).
  */
-export interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+export interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange">, FieldHelpProps {
   /** BCP 47 tag for the trigger's date and the calendar. Falls back to
    *  `<UiKitProvider locale>`, then to the runtime's default. */
   locale?: string;

package/src/components/date-picker.tsx

@@ -170,6 +170,7 @@ export function DatePicker(props: DatePickerProps) {
     disabled,
     invalid,
     hint,
+    help,
     error,
     // Named so it reaches the field (and so its trigger) when a step/today row is the
     // root and takes the rest of the caller's props.
@@ -185,6 +186,8 @@ export function DatePicker(props: DatePickerProps) {
   // (the element a screen reader is on) after any description of the caller's own.
   const messages = useFieldMessages({
     hint,
+    help,
+    name: label ?? rest["aria-label"],
     error,
     invalid,
     describedBy: rest["aria-describedby"],

package/src/components/date-range-picker.tsx

@@ -394,6 +394,7 @@ export function DateRangePicker(props: DateRangePickerProps) {
     disabled,
     invalid,
     hint,
+    help,
     error,
     // The trigger's (API-3).
     ref,
@@ -404,6 +405,8 @@ export function DateRangePicker(props: DateRangePickerProps) {
   const render = useTriggerFormat("dateRangePicker", locale, formatOptions, formatValue);
   const messages = useFieldMessages({
     hint,
+    help,
+    name: label ?? rest["aria-label"],
     error,
     invalid,
     describedBy: rest["aria-describedby"],

package/src/components/dialog-frame.tsx

@@ -23,7 +23,9 @@ export { DEFAULT_DIALOG_FRAME_LABELS };
  * (`children` is the body here, not the whole panel) and `title`, which is the dialog's
  * HEADING and a ReactNode rather than the browser's tooltip string — the collision
  * `PickerSheet` met first. Everything else, `size`, `draggable`, `fullBleed`,
- * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal`.
+ * `onKeyDown`, a `data-tour` anchor, still reaches the `Modal` — and since 0.35 `ref`
+ * (round 0.35 R4): the panel, the `role="dialog"` element the frame's header, body and
+ * actions sit in.
  */
 export interface DialogFrameProps extends Omit<ModalProps, "labelledBy" | "children" | "title"> {
   /** The heading, and therefore the dialog's accessible name (`aria-labelledby`). */

package/src/components/dropdown.tsx

@@ -11,6 +11,7 @@ import { createPortal } from "react-dom";
 import { Search } from "lucide-react";
 import { anchoredInline, useAnchoredPanel } from "../hooks/use-anchored-panel";
 import { runOwnKeyDown, takeEscape, useDismissLayer, useOutsideClick } from "../hooks/use-dismiss";
+import type { DismissLayer } from "../hooks/use-dismiss";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
 import { cn } from "../lib/cn";
 import { FIELD_TOUCH_TEXT } from "./field-base";
@@ -18,6 +19,12 @@ import { mergeRefs } from "./field-parts";
 import { FOCUS_RING } from "./focus-ring";
 import { useAnchorDir } from "./use-anchor-dir";
 
+/** Each list's Escape layer, filed under the refs {@link useDropdown} and
+ *  {@link useDropdownSearch} hand out (`panelRef`, `inputRef`), for the panel and the
+ *  search box those refs are passed to — see "The caller's own handler" on
+ *  {@link useDropdown} (round 0.35 R2). Weak: a list's refs go with its component. */
+const listLayers = new WeakMap<object, DismissLayer>();
+
 /**
  * Open state + close-on-outside-click for a custom dropdown — the two input-shaped
  * comboboxes, and an app's own panel. (MultiSelect, CurrencySelect, GroupedPicker and
@@ -88,6 +95,16 @@ import { useAnchorDir } from "./use-anchor-dir";
  * and stop it there — so a caller passes nothing new, AmountInput's currency chip
  * included.
  *
+ * ## The caller's own handler (round 0.35 R2)
+ *
+ * A caller's `onKeyDown` on {@link DropdownPanel} or {@link DropdownSearchHeader} hears
+ * Escape only while this list is the layer on top — the rule the dialogs got first. A
+ * tooltip over a row takes that press first, and the next one is the handler's, whose
+ * `preventDefault()` still keeps the list. The two find the list's layer through the
+ * refs this hook hands out — the panel through `panelRef`, the search box through
+ * {@link useDropdownSearch}'s `inputRef` — so a caller passes nothing new. One handed
+ * neither (an un-anchored panel may leave `panelRef` off) hears every key, as before.
+ *
  * `escapeLayer: false` is for a caller that registers its own layer: the editable
  * comboboxes, whose list can be "open" with nothing in it to show — an Escape there
  * belongs to the dialog.
@@ -129,7 +146,11 @@ export function useDropdown<T extends HTMLElement = HTMLDivElement>({
   }, []);
   useOutsideClick([wrapperRef, panelRef], close, open && !panelIsSheet);
   // See "Escape inside a dialog" above.
-  useDismissLayer(open && escapeLayer, closeToTrigger);
+  const layer = useDismissLayer(open && escapeLayer, closeToTrigger);
+  // Filed under `panelRef` for the panel's own handler — "The caller's own handler" above.
+  useEffect(() => {
+    listLayers.set(panelRef, layer);
+  }, [panelRef, layer]);
   // Same close path Escape and an outside click take, so a list dismissed by Back
   // cannot end up in a different state from one dismissed any other way.
   useOverlayHistory(open && backCloses, close);
@@ -145,6 +166,12 @@ export function useDropdownSearch<T extends HTMLElement = HTMLDivElement>() {
     useDropdown<T>();
   const [query, setQuery] = useState("");
   const inputRef = useRef<HTMLInputElement>(null);
+  // The list's layer again, under `inputRef` for the search box's handler (round 0.35
+  // R2). `useDropdown`'s effect, which runs first, has filed it under `panelRef`.
+  useEffect(() => {
+    const layer = listLayers.get(panelRef);
+    if (layer) listLayers.set(inputRef, layer);
+  }, [panelRef]);
   useEffect(() => {
     if (open) {
       // eslint-disable-next-line react-hooks/set-state-in-effect -- reset the query on open
@@ -237,7 +264,9 @@ export function DropdownSearchHeader({
         value={query}
         onChange={(e) => onQueryChange(e.target.value)}
         onKeyDown={(e) => {
-          runOwnKeyDown(e, onKeyDown);
+          // The caller's handler hears Escape only while the list is on top (round 0.35
+          // R2) — the layer filed under `inputRef`, when {@link useDropdownSearch} made it.
+          runOwnKeyDown(e, onKeyDown, listLayers.get(inputRef));
           // Focus is in this box while the list is up, so this is where Escape lands
           // first — see "Escape inside a dialog" on {@link useDropdown}.
           takeEscape(e);
@@ -271,30 +300,23 @@ export interface DropdownPanelProps extends ComponentPropsWithoutRef<"div"> {
   anchorRef?: RefObject<HTMLElement | null>;
   /** {@link useDropdown}'s `panelRef`, so an outside-click sees this as inside. Escape
    *  anywhere in the panel, on a row as in the search box, closes the list rather than
-   *  a dialog around it. */
+   *  a dialog around it. It is also how the panel finds the list's Escape layer, for
+   *  its `onKeyDown` (round 0.35 R2: see "The caller's own handler" there). */
   panelRef?: RefObject<HTMLDivElement | null>;
   /** Panel width in px, for the anchored form (the CSS `w-*` cannot be measured). */
   width?: number;
-  /** Which of the panel's edges lines up with the trigger's, room permitting.
-   *  `start`/`end` follow the trigger's reading direction — `end` is the right edge
-   *  in a left-to-right form and the left one in a right-to-left form — and are what
-   *  the kit's own pickers pass; `left`/`right` are physical and deprecated
-   *  ({@link PhysicalAlign}). Default `end`, which is the old `right` in a
-   *  left-to-right page. */
-  align?: "start" | "end" | PhysicalAlign;
+  /** Which of the panel's edges lines up with the trigger's, room permitting, by the
+   *  trigger's reading direction — `end` is the right edge in a left-to-right form and
+   *  the left one in a right-to-left form. Default `end`. 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";
   children: ReactNode;
   /** The panel, where the rest of the props go (0.34, API-2, refactor audit 2026-10) —
    *  merged with `panelRef`, so the outside-click still sees it. */
   ref?: Ref<HTMLDivElement>;
 }
 
-/**
- * @deprecated 0.34 — `"start"` / `"end"`, which follow the reading direction: `"right"`
- * is `"end"` in a left-to-right page, the default; removed in 0.35 (refactor audit
- * 2026-10, API-6e). The physical edges DropdownPanel's `align` still takes.
- */
-type PhysicalAlign = "left" | "right";
-
 /**
  * The floating popover surface for the searchable dropdowns: bordered/shadowed
  * panel, an optional `header` slot (search box, plus any actions), and a
@@ -344,7 +366,9 @@ export function DropdownPanel({
   // A row the keyboard reached by Tab holds focus too, and its Escape has to close the
   // list as the search box's does (BUG-1). The caller's handler first, as everywhere.
   const handleKeyDown = (e: ReactKeyboardEvent<HTMLDivElement>) => {
-    runOwnKeyDown(e, onKeyDown);
+    // It hears Escape only while the list is on top, a tooltip over a row taking the
+    // press first (round 0.35 R2) — the layer filed under `panelRef`, when handed one.
+    runOwnKeyDown(e, onKeyDown, panelRef && listLayers.get(panelRef));
     takeEscape(e);
   };
   const body = (

package/src/components/entity-combobox.tsx

@@ -25,6 +25,7 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import { useCommitReason, type CommitScope } from "./write-lock";
 
@@ -33,7 +34,8 @@ export type { ComboClearValue, ComboOption } from "./combobox-core";
 /** `onChange` is the kit's — "a selection was made", carrying values — rather
  *  than the div's form event, so the DOM's spelling of it is omitted. */
 export interface EntityComboboxProps<V extends string | number, C extends ComboClearValue = null>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange">,
+    FieldHelpProps {
   /** Selected id; `null`, `undefined` or `clearValue` when nothing is selected. */
   value: V | C | null | undefined;
   /** Selecting an option emits its value; the clear button emits `clearValue`. */
@@ -73,7 +75,7 @@ export interface EntityComboboxProps<V extends string | number, C extends ComboC
    *  so it is the one control here that MUST be in the reader's language. */
   closeLabel?: string;
   /** The phone sheet's heading (and, as a string, its accessible name) for a picker
-   *  whose label is drawn by someone else — a form's `FormLabel`; `RhfCombobox`
+   *  whose label is drawn by someone else — a bound field's label; `RhfCombobox`
    *  hands its label over here (0.24). Default: `label`, then `placeholder`. */
   sheetTitle?: ReactNode;
   disabled?: boolean;
@@ -182,6 +184,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     invalid,
     error,
     hint,
+    help,
     filter,
     minChars,
     debounceMs,
@@ -206,7 +209,7 @@ export function EntityCombobox<V extends string | number, C extends ComboClearVa
     minChars,
     debounceMs,
   });
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });
   const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);
   // The props are the per-instance overrides, the provider the app-wide ones; a
   // prop left `undefined` falls through to the provider rather than masking it.

package/src/components/field-base.tsx

@@ -457,17 +457,6 @@ export interface PasswordRevealLabels {
 // Defined in ./ui-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_PASSWORD_REVEAL_LABELS };
 
-/** @deprecated 0.34 — `useKitLabels("passwordReveal", DEFAULT_PASSWORD_REVEAL_LABELS, labels)`,
- *  which the provider reaches too, or Input's own `passwordLabels`; removed in 0.35
- *  (refactor audit 2026-10, API-6a). A merge from before the provider, which no kit
- *  component calls. */
-export function resolvePasswordRevealLabels(
-  partial?: Partial<PasswordRevealLabels>,
-): PasswordRevealLabels {
-  if (!partial) return DEFAULT_PASSWORD_REVEAL_LABELS;
-  return { ...DEFAULT_PASSWORD_REVEAL_LABELS, ...partial };
-}
-
 /**
  * What the character counter of {@link Input} and {@link Textarea} (`showCount`) says.
  * The visible "12/80" is digits and a slash and is not translated; these are the words