@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/components/field-parts.tsx

@@ -1,10 +1,13 @@
 import { createContext, isValidElement, useContext, useId } from "react";
-import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode, Ref, RefCallback } from "react";
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from "react";
 import { HelpCircle } from "lucide-react";
 import { cn } from "../lib/cn";
 import { hasContent } from "../lib/presence";
+import { plainText } from "../lib/plain-text";
+import { DEFAULT_COMMON_LABELS, useKitLabels } from "../i18n/kit-labels";
 import { useInlineFacts } from "../hooks/use-large-text";
 import { FOCUS_RING } from "./focus-ring";
+import { HelpPopover } from "./help-popover";
 import { Tooltip, type TooltipSide } from "./tooltip";
 import { useCommitReason, type CommitScope } from "./write-lock";
 
@@ -41,23 +44,9 @@ export function mergeDescribedBy(...ids: Array<string | false | null | undefined
   return list.length ? list.join(" ") : undefined;
 }
 
-/** Point a ref — a callback or an object — at `node`. `undefined` and `null` are no ref. */
-export function assignRef<T>(ref: Ref<T> | undefined, node: T | null): void {
-  if (typeof ref === "function") ref(node);
-  else if (ref) (ref as { current: T | null }).current = node;
-}
-
-/**
- * One callback ref feeding several — the caller's forwarded `ref` and a field's own
- * (DUP-11: AmountInput, FormActions, ScrollArea and SearchField each wrote this by hand).
- * Wrap it in `useCallback` (or `useMemo`) over the same refs where a new callback every
- * render would detach and re-attach the node.
- */
-export function mergeRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
-  return (node) => {
-    for (const ref of refs) assignRef(ref, node);
-  };
-}
+// The ref plumbing lives in ../lib/refs since round 0.35 (Tooltip needs it, and this module
+// renders a Tooltip); the fields keep importing it from here.
+export { assignRef, mergeRefs } from "../lib/refs";
 
 /* ── the static label ─────────────────────────────────────────────────────── */
 
@@ -216,16 +205,82 @@ export function FieldHint({
  * The kit's fields call it through {@link useFieldHint} / {@link useFieldMessages}; a
  * field that resolves its own `hint` (an app's, or one of the kit's own outside this
  * file) calls it first and then treats the result as it treated a text hint.
+ *
+ * `withHelp` (round 0.36): the field has a `help`, whose "?" is the field's only one
+ * ({@link fieldHelpMark}) — so a FieldHint is its words at EVERY size, not only at Large
+ * and on touch.
  */
-export function useInlineHint(hint: ReactNode): ReactNode {
+export function useInlineHint(hint: ReactNode, withHelp = false): ReactNode {
   const inline = useInlineFacts();
-  if (inline && isValidElement(hint) && hint.type === FieldHint) {
+  if ((inline || withHelp) && isValidElement(hint) && hint.type === FieldHint) {
     const words = (hint.props as FieldHintProps).label;
     if (words) return words;
   }
   return hint;
 }
 
+/* ── help (round 0.36, docs/text-size-harmonization.md §4, §10.23) ─────────── */
+
+/**
+ * The doc every field's `help` prop points at.
+ *
+ * A field may carry two kinds of words (§10.23): a FACT — a format, a limit, a
+ * consequence — which stays visible, and HELP — why the field exists, how to choose,
+ * what the options mean — which the field is usable without and which may sit behind a
+ * "?". Until 0.36 a field had one slot, `hint`, so a field with both had to drop one or
+ * print a paragraph (Kurvenschmiede's "How it was measured", round 0.36 H). Now:
+ *
+ * - `hint` is the fact, the caption under the field, on its `aria-describedby`;
+ * - `help` is the help, a {@link HelpPopover} "?" on the label line (an unlabelled
+ *   field's at its end edge, as a hint's), named "About <label>" (`common.aboutField`,
+ *   from the label's text, else the `aria-label`, else `common.help`). Pass a
+ *   `HelpPopover` as `help` to name it yourself ("What do the statuses mean?").
+ *
+ * The help's "?" is then the field's ONLY "?": a `FieldHint` passed as `hint` beside it
+ * draws none of its own and shows its words as the caption at every size, as it does at
+ * Large and on touch; any other `hint` is the caption too. Two "?" side by side would
+ * look the same and open different things.
+ */
+export interface FieldHelpProps {
+  /**
+   * Help the field is usable without — why it exists, how to choose, what the options
+   * mean — behind the field's one "?" on its label line: a {@link HelpPopover} named
+   * "About <label>" that opens on a tap (round 0.36, docs/text-size-harmonization.md §4).
+   * Pass a `HelpPopover` to name it yourself. `hint` stays the visible fact: with `help`
+   * set it is the caption under the field at every size, a `FieldHint` included.
+   */
+  help?: ReactNode;
+}
+
+/**
+ * The "?" for a field's `help` — the field's own name, "About <label>", in the reader's
+ * language. A component so that a field without `help` asks the labels nothing.
+ */
+function FieldHelp({ name, children }: { name: ReactNode; children: ReactNode }) {
+  const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
+  const text = plainText(name);
+  return <HelpPopover label={text === undefined ? common.help : common.aboutField(text)}>{children}</HelpPopover>;
+}
+
+/**
+ * A field's `help` as the "?" for its label line, or `undefined` when there is none. A
+ * {@link HelpPopover} is used as it is (it carries its own name); anything else is put
+ * in one named "About <name>" — `name` is the field's label, else its `aria-label`.
+ */
+export function fieldHelpMark(help: ReactNode, name: ReactNode): ReactNode | undefined {
+  if (!hasContent(help)) return undefined;
+  if (isValidElement(help) && help.type === HelpPopover) return help;
+  return <FieldHelp name={name}>{help}</FieldHelp>;
+}
+
+/** What {@link useFieldHint} needs to draw a field's `help`. */
+export interface FieldHelpSource {
+  /** The field's `help`. */
+  help?: ReactNode;
+  /** What names its "?": the field's label, else its `aria-label`. */
+  name?: ReactNode;
+}
+
 
 /**
  * Whether a `hint` is a CAPTION (plain text: a non-empty string or a number) or
@@ -250,26 +305,43 @@ export interface FieldHintParts {
   describedBy: string | undefined;
   /** The caption's id while there is one. */
   captionId: string | undefined;
-  /** The caption itself, or `undefined` for a hint that is not text. */
-  captionText: string | number | undefined;
-  /** A non-text hint (a FieldHint) for the label line — or, on a field with no label
-   *  line, the end edge outside the box. `undefined` when there is none. */
+  /** The caption itself — a text hint, or any hint beside a `help` — or `undefined`. */
+  captionText: ReactNode | undefined;
+  /** What rides the label line — the `help`'s "?" ({@link fieldHelpMark}), else a
+   *  non-text hint (a FieldHint) — or, on a field with no label line, the end edge
+   *  outside the box. `undefined` when there is none. */
   labelHint: ReactNode | undefined;
 }
 
+/**
+ * Whether a resolved `hint` goes under the field as its caption: text always (see
+ * {@link isTextHint}); with a `help` beside it, whatever it is — the label line's "?"
+ * is the help's (round 0.36, §4).
+ */
+export function isHintCaption(hint: ReactNode, withHelp: boolean): boolean {
+  return isTextHint(hint) || (withHelp && hasContent(hint));
+}
+
 /**
  * Split a field's `hint` into the caption under it (attached with `aria-describedby`)
- * or the "?" on its label line. See {@link isTextHint}.
+ * or the "?" on its label line. See {@link isTextHint}. With a `help` ({@link
+ * FieldHelpProps}), the help's "?" takes the label line and the hint is the caption.
  */
-export function useFieldHint(hintProp: ReactNode, describedBy: string | undefined): FieldHintParts {
-  const hint = useInlineHint(hintProp);
+export function useFieldHint(
+  hintProp: ReactNode,
+  describedBy: string | undefined,
+  { help, name }: FieldHelpSource = {},
+): FieldHintParts {
+  const helpMark = fieldHelpMark(help, name);
+  const withHelp = helpMark !== undefined;
+  const hint = useInlineHint(hintProp, withHelp);
   const captionId = useId();
-  const text = isTextHint(hint);
+  const caption = isHintCaption(hint, withHelp);
   return {
-    describedBy: text ? mergeDescribedBy(describedBy, captionId) : describedBy,
-    captionId: text ? captionId : undefined,
-    captionText: text ? hint : undefined,
-    labelHint: !text && hasContent(hint) ? hint : undefined,
+    describedBy: caption ? mergeDescribedBy(describedBy, captionId) : describedBy,
+    captionId: caption ? captionId : undefined,
+    captionText: caption ? hint : undefined,
+    labelHint: helpMark ?? (!caption && hasContent(hint) ? hint : undefined),
   };
 }
 
@@ -312,7 +384,7 @@ export function useFieldError(
   invalid: boolean | undefined,
   describedBy: string | undefined,
   /** The caller's own `aria-invalid`. A form library sets THIS (see `@eifi1/ui-kit/rhf`
-   *  `FormControl`), not our `invalid` prop — and a field that announces invalid should
+   *  `RhfField`), not our `invalid` prop — and a field that announces invalid should
    *  look it too. */
   ariaInvalid?: unknown,
 ): { isInvalid: boolean; describedBy: string | undefined; errorEl: ReactNode } {
@@ -589,24 +661,26 @@ export interface FieldMessages {
   describedBy: string | undefined;
   /** The caption and the error, for under the field; `null` when there is neither. */
   below: ReactNode;
-  /** The hint for the LABEL line (a `FieldHint`), or `undefined` when the hint is a
-   *  caption or there is none. */
+  /** What rides the LABEL line — the `help`'s "?", else a `FieldHint` — or `undefined`
+   *  when the hint is a caption and there is no help. */
   labelHint: ReactNode;
 }
 
 /**
- * `hint` / `error` / `invalid` resolved the way `Select` resolves them —
+ * `hint` / `help` / `error` / `invalid` resolved the way `Select` resolves them —
  * {@link useFieldHint} and {@link useFieldError} together, for a field that draws what
  * goes under it in one place (a picker, a group, a field built on another).
  */
 export function useFieldMessages({
   hint,
+  help,
+  name,
   error,
   invalid,
   describedBy,
   ariaInvalid,
   reasonId,
-}: {
+}: FieldHelpSource & {
   hint?: ReactNode;
   error?: ReactNode;
   invalid?: boolean;
@@ -616,7 +690,7 @@ export function useFieldMessages({
    *  caption and before the error, as on Select. */
   reasonId?: string | false;
 }): FieldMessages {
-  const hintParts = useFieldHint(hint, describedBy);
+  const hintParts = useFieldHint(hint, describedBy, { help, name });
   const field = useFieldError(error, invalid, mergeDescribedBy(hintParts.describedBy, reasonId), ariaInvalid);
   return {
     isInvalid: field.isInvalid,

package/src/components/field-strip.tsx

@@ -1,12 +1,6 @@
 import { useId } from "react";
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
-import { LabelStrip, useFieldMessages } from "./field-parts";
-
-/**
- * How far down the content starts, under the 11px label — see {@link FieldStripProps.pad}.
- * Since 0.34 both are the one 20px strip.
- */
-export type FieldStripPad = "clear" | "field";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import { LabelStrip, useFieldMessages, type FieldHelpProps } from "./field-parts";
 
 /** What a {@link FieldStrip} hands render-prop children. */
 export interface FieldStripIds {
@@ -19,7 +13,12 @@ export interface FieldStripIds {
   describedBy: string | undefined;
 }
 
-export interface FieldStripProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+/**
+ * A `div`'s props, `ref` included since 0.35 (round 0.35 R4, as Card and EmptyState took
+ * it in 0.34, API-2): the ref is the root — the group, or the plain box under
+ * `group={false}` — which a caller scrolls into view or measures.
+ */
+export interface FieldStripProps extends Omit<ComponentPropsWithRef<"div">, "children">, FieldHelpProps {
   /** The 11px static label, on the line a labelled field's label sits on. */
   label: ReactNode;
   /**
@@ -37,21 +36,6 @@ export interface FieldStripProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * turns its map into a picture and drops its buttons, which no flag here could guess.
    */
   disabled?: boolean;
-  /**
-   * @deprecated 0.34 — drop it; removed in 0.35. Both values are the same 20px strip
-   * since 0.34, and the prop does nothing; it stays so a caller that passes it still
-   * compiles.
-   *
-   * It chose between `"clear"` (20px) and `"field"` (16px: the strip plus a 26px
-   * bordered control made a labelled Input's 42px). The label row — the label and its
-   * "?" — ends 18px down, so over a 16px strip it crossed the content's top border by
-   * 2px (keksdose dev#593; the arithmetic is on `LABEL_STRIP_PAD` in field-parts.tsx).
-   * For a row of 42px fields, make the content 22px tall: 20 + 22 = 42, the shape
-   * ToggleGroup's `labelPlacement="strip"` has since 0.34.
-   *
-   * A `className` still merges after the strip's padding.
-   */
-  pad?: FieldStripPad;
   /**
    * The wrapper is a `role="group"` named by the label (default), so a screen reader
    * entering the map or the first button hears "Location, group" — what the visible
@@ -102,22 +86,23 @@ export interface FieldStripProps extends Omit<ComponentPropsWithoutRef<"div">, "
 export function FieldStrip({
   label,
   hint,
+  help,
   error,
   disabled = false,
-  // Taken off so it never reaches the DOM; see `pad` (deprecated, one strip since 0.34).
-  pad: _pad,
   group = true,
   className,
   children,
   ...rest
 }: FieldStripProps) {
   const labelId = useId();
-  const messages = useFieldMessages({ hint, error });
+  const messages = useFieldMessages({ hint, help, name: label, error });
   const content = typeof children === "function" ? children({ labelId, describedBy: messages.describedBy }) : children;
   // The caller's own description first, then the caption, then the error — the order
   // every kit field reads them in.
   const groupDescribedBy = [rest["aria-describedby"], messages.describedBy].filter(Boolean).join(" ") || undefined;
   return (
+    // `rest` carries the caller's `ref` too (a plain prop in React 19): LabelStrip spreads
+    // its own rest onto the wrapper `<div>`, so the ref lands on the root.
     <LabelStrip
       {...rest}
       {...(group

package/src/components/field-sync.tsx

@@ -38,13 +38,6 @@ export interface FieldSyncLabels {
 // Defined in ./field-sync-labels, which holds no component code (0.34, KS U8).
 export { DEFAULT_FIELD_SYNC_LABELS };
 
-/** @deprecated 0.34 — `useKitLabels("fieldSync", DEFAULT_FIELD_SYNC_LABELS, labels)`, which
- *  the provider reaches too, or the field's own `labels`; removed in 0.35 (refactor audit
- *  2026-10, API-6a). A merge from before the provider, which no kit component calls. */
-export function resolveFieldSyncLabels(labels?: Partial<FieldSyncLabels>): FieldSyncLabels {
-  return labels ? { ...DEFAULT_FIELD_SYNC_LABELS, ...labels } : DEFAULT_FIELD_SYNC_LABELS;
-}
-
 export interface UseFieldSyncOptions<T> {
   /** What the database currently holds. Changing it re-seeds a CLEAN field. */
   value: T;

package/src/components/field.tsx

@@ -29,10 +29,10 @@
  *
  * Deliberately knows neither the wizard nor react-hook-form: `error` is a plain
  * value. Pass `wizard.fieldErrors.iban`, a step-local error, or
- * `fieldState.error?.message` from a `FormField` render — the markup is the same
- * whichever of them gates the step, so a step can move between them without its
- * fields changing. (Inside a react-hook-form form, `FormItem` + `FormLabel` from
- * `@eifi1/ui-kit/rhf` do the same job with the ids taken from the form.)
+ * `fieldState.error?.message` from a react-hook-form `Controller` — the markup is the
+ * same whichever of them gates the step, so a step can move between them without its
+ * fields changing. (Inside a react-hook-form form, `RhfField` from `@eifi1/ui-kit/rhf`
+ * does the same job with the ids taken from the form.)
  *
  * The error is NOT `role="alert"`, for the reason the kit's `error` prop gives (see
  * `useFieldError` in components/field-parts.tsx): it is read when focus reaches the control.
@@ -40,7 +40,7 @@
 import { useId, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { hasContent } from "../lib/presence";
-import { useInlineHint } from "./field-parts";
+import { fieldHelpMark, useInlineHint, type FieldHelpProps } from "./field-parts";
 import { Label } from "./field-base";
 
 /** What a `Field` hands its render-prop children, to spread on the control. */
@@ -91,7 +91,7 @@ const LABEL_VISIBILITY: Record<FieldLabelVisibility, string | undefined> = {
   "below-lg": "lg:sr-only",
 };
 
-export interface FieldProps {
+export interface FieldProps extends FieldHelpProps {
   /** The label above the control. Omit it for a group whose control is labelled
    *  some other way; the hint and error still render. */
   label?: ReactNode;
@@ -123,6 +123,7 @@ export function Field({
   label,
   required,
   hint: hintProp,
+  help,
   error,
   htmlFor,
   disabled,
@@ -138,7 +139,10 @@ export function Field({
   const labelId = `${generated}-label`;
   // §4: a FieldHint under the control is its words at Large and on a touch screen, not
   // a lone "?" (DUP-2, refactor audit 2026-10). A HelpPopover stays a "?".
-  const hint = useInlineHint(hintProp);
+  // With a `help` (0.36) its "?" follows the label, and a FieldHint is its words at
+  // every size: the help's is the field's only "?".
+  const helpMark = fieldHelpMark(help, label);
+  const hint = useInlineHint(hintProp, helpMark !== undefined);
   const hasHint = hasContent(hint);
   const hasError = hasContent(error);
   const describedBy = [hasHint && hintId, hasError && errorId].filter(Boolean).join(" ");
@@ -148,6 +152,19 @@ export function Field({
     "aria-invalid": hasError || undefined,
     "aria-required": required || undefined,
   };
+  const labelEl = label !== undefined && (
+    <Label
+      id={labelId}
+      htmlFor={id}
+      required={required}
+      disabled={disabled}
+      size={labelSize}
+      data-error={hasError || undefined}
+      className={cn("data-[error=true]:text-danger", LABEL_VISIBILITY[labelVisibility])}
+    >
+      {label}
+    </Label>
+  );
   return (
     <div
       data-slot="field"
@@ -162,18 +179,14 @@ export function Field({
         className,
       )}
     >
-      {label !== undefined && (
-        <Label
-          id={labelId}
-          htmlFor={id}
-          required={required}
-          disabled={disabled}
-          size={labelSize}
-          data-error={hasError || undefined}
-          className={cn("data-[error=true]:text-danger", LABEL_VISIBILITY[labelVisibility])}
-        >
-          {label}
-        </Label>
+      {helpMark === undefined && labelEl}
+      {helpMark !== undefined && (
+        // The label and its "?" on one line; the "?" stays visible where the label is
+        // hidden (`labelVisibility`) — a hidden button would still take the focus.
+        <div className="flex items-center gap-1">
+          {labelEl}
+          <span className="flex shrink-0 items-center">{helpMark}</span>
+        </div>
       )}
       {typeof children === "function"
         ? children(control, { labelId: label !== undefined ? labelId : undefined })

package/src/components/full-bleed-dialog.tsx

@@ -174,14 +174,15 @@ export function FullBleedDialog({
   // to whichever of them is topmost — one press dismissing the sheet AND the edit
   // behind it was Keksdose live #309 (*"Mouse Back does not only close the select but
   // also the whole edit or create dialog"*) on a different key.
-  useDismissLayer(open, requestClose);
+  const layer = useDismissLayer(open, requestClose);
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     // The caller's handler first (keksdose's transaction-search keeps its list keys on
     // the dialog); a `preventDefault()` IN THAT HANDLER claims Escape. Only there: a
     // descendant's does not count. A SearchField in the header prevents Escape to stop
     // Chromium clearing a type=search input, and in 0.8.0 that silently stopped Escape
-    // from closing the dialog (keksdose). The one rule `Modal` now shares.
-    runOwnKeyDown(e, onKeyDown);
+    // from closing the dialog (keksdose). The one rule `Modal` now shares — as is this
+    // one: the handler sees Escape only while this dialog is the layer on top (0.35).
+    runOwnKeyDown(e, onKeyDown, layer);
     takeEscape(e);
   };
 

package/src/components/help-popover.tsx

@@ -42,12 +42,14 @@ const HELP_WIDTH: RemLength = "20rem";
  * 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.
+ * **On a field: its `help`** (0.36, round 0.36 decision 1). Every kit field that takes a
+ * `hint` takes a `help` beside it, and the `@eifi1/ui-kit/rhf` bindings too: pass the
+ * help's words and the field draws this "?" on its label line (an unlabelled one at its
+ * end edge, outside the box), named "About <label>" — or pass a HelpPopover to name it
+ * yourself. `hint` stays the FACT, printed under the field; while `help` is set a
+ * FieldHint there draws no "?" of its own, so the field has one. Passed as `hint`, as in
+ * 0.34, it still rides the label line. 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
@@ -60,7 +62,7 @@ const HELP_WIDTH: RemLength = "20rem";
  * accepted and cleared?", keksdose live #247); "!" is a warning.
  *
  * ```tsx
- * <Select label="Status" hint={
+ * <Select label="Status" hint="Cleared and reconciled rows are locked." help={
  *   <HelpPopover label="What do the statuses mean?">
  *     Pending: … Accepted: … Cleared: … Reconciled: …
  *   </HelpPopover>

package/src/components/hover-menu.tsx

@@ -20,12 +20,13 @@ 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 deprecated ({@link PhysicalAlign}). 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" | PhysicalAlign;
+  align?: "start" | "end";
   panelClassName?: string;
   /** Extra classes for the WRAPPER (the panel has {@link panelClassName}). */
   className?: string;
@@ -34,14 +35,6 @@ export interface HoverMenuProps extends Omit<ComponentPropsWithoutRef<"div">, "c
   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 HoverMenu's `align` — and TopBarActionMenu's and
- * FeedbackMenu's, which hand it on — still take.
- */
-type PhysicalAlign = "left" | "right";
-
 // Hovering waits briefly before opening so sweeping the cursor across a row of
 // triggers doesn't flash menus; closing waits so the cursor can travel from
 // trigger to panel. Click/keyboard toggling is instant (no "opening" phase).
@@ -50,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"]';
@@ -188,7 +181,7 @@ export function HoverMenu({
   // 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.
-  useDismissLayer(open, () => {
+  const layer = useDismissLayer(open, () => {
     const hadFocus = wrapperRef.current?.contains(document.activeElement) ?? false;
     close();
     if (hadFocus) triggerEl()?.focus();
@@ -298,7 +291,10 @@ export function HoverMenu({
       onMouseEnter={handleMouseEnter}
       onMouseLeave={handleMouseLeave}
       onKeyDown={(e) => {
-        runOwnKeyDown(e, rest.onKeyDown);
+        // 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);

package/src/components/icon-picker.tsx

@@ -7,7 +7,7 @@ import { TILE_SIZE, TileRadioGroup } from "./tile-radio";
 import type { TileItem, TileSize } from "./tile-radio";
 import { hasContent } from "../lib/presence";
 import { foldForSearch } from "../lib/text-match";
-import { LabelStrip, useFieldMessages } from "./field-parts";
+import { LabelStrip, useFieldMessages, type FieldHelpProps } from "./field-parts";
 import { DEFAULT_ICON_PICKER_LABELS } from "./icon-picker-labels";
 
 export interface IconPickerLabels {
@@ -52,7 +52,8 @@ export interface IconOption<T extends string> {
 }
 
 export interface IconPickerProps<T extends string>
-  extends Omit<ComponentPropsWithRef<"div">, "onChange" | "children" | "defaultValue"> {
+  extends Omit<ComponentPropsWithRef<"div">, "onChange" | "children" | "defaultValue">,
+    FieldHelpProps {
   options: IconOption<T>[];
   /** The chosen icon, or `null` for none. */
   value: T | null;
@@ -122,6 +123,7 @@ export function IconPicker<T extends string>({
   labels,
   label,
   hint,
+  help,
   className,
   "aria-label": ariaLabel,
   "aria-labelledby": ariaLabelledBy,
@@ -134,9 +136,12 @@ export function IconPicker<T extends string>({
   const mixedId = useId();
   const labelId = useId();
   const labelled = hasContent(label);
-  // The label line's "?", or the caption under the grid (DUP-2). Only with a label.
+  // The label line's "?", or the caption under the grid (DUP-2). Only with a label, the
+  // help's "?" too (0.36).
   const messages = useFieldMessages({
     hint: labelled ? hint : undefined,
+    help: labelled ? help : undefined,
+    name: label,
     describedBy: ariaDescribedBy,
     reasonId: mixed && mixedId,
   });

package/src/components/inline-entity-combobox.tsx

@@ -34,6 +34,7 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import { hasContent } from "../lib/presence";
 import { useCommitReason, type CommitScope } from "./write-lock";
@@ -47,7 +48,8 @@ const CREATE_ROW_CLASS = "flex items-center gap-2 font-medium text-brand";
 /** `id` is the INPUT's and `onChange` is the field's — see {@link ComboboxProps}
  *  for why the div's spellings of them are omitted. */
 export interface InlineEntityComboboxProps<V extends string | number, C extends ComboClearValue = null>
-  extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "id" | "onChange">,
+    FieldHelpProps {
   /** Selected option id; `null` or `clearValue` when nothing is selected. */
   value: V | C | null;
   /** Required and unanswered — see {@link Combobox}'s `invalid`. */
@@ -83,7 +85,7 @@ export interface InlineEntityComboboxProps<V extends string | number, C extends
   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`;
+   *  whose label is drawn by someone else — a bound field's label;
    *  `RhfInlineEntityCombobox` hands its label over here (0.24). Default: `label`.
    *  See {@link Combobox}'s `sheetTitle`. */
   sheetTitle?: ReactNode;
@@ -226,6 +228,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
     invalid,
     error,
     hint,
+    help,
     ref,
     "aria-label": ariaLabel,
     // Off `rest` and onto the <input>, which is the combobox a reader meets: `Field`'s
@@ -239,7 +242,7 @@ export function InlineEntityCombobox<V extends string | number, C extends ComboC
   // The clear value reads as "nothing selected", whichever one the caller picked —
   // so from here down `value` is the id or `null`, as it always was.
   const value: V | null = rawValue == null || rawValue === clearValue ? null : (rawValue as V);
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? ariaLabel });
   const field = useFieldError(error, invalid, hintParts.describedBy, ariaInvalid);
   const generated = useId();
   const fieldId = id ?? generated;