@eifi1/ui-kit 0.35.0 → 0.36.0

package/src/components/field-parts.tsx

@@ -3,8 +3,11 @@ import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from
 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";
 
@@ -202,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
@@ -236,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),
   };
 }
 
@@ -575,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;
@@ -602,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,6 +1,6 @@
 import { useId } from "react";
 import type { ComponentPropsWithRef, ReactNode } from "react";
-import { LabelStrip, useFieldMessages } from "./field-parts";
+import { LabelStrip, useFieldMessages, type FieldHelpProps } from "./field-parts";
 
 /** What a {@link FieldStrip} hands render-prop children. */
 export interface FieldStripIds {
@@ -18,7 +18,7 @@ export interface FieldStripIds {
  * 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"> {
+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;
   /**
@@ -86,6 +86,7 @@ export interface FieldStripProps extends Omit<ComponentPropsWithRef<"div">, "chi
 export function FieldStrip({
   label,
   hint,
+  help,
   error,
   disabled = false,
   group = true,
@@ -94,7 +95,7 @@ export function FieldStrip({
   ...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.

package/src/components/field.tsx

@@ -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/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/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`. */
@@ -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;

package/src/components/input.tsx

@@ -12,6 +12,7 @@ import {
   LockedReason,
   mergeDescribedBy,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
   useFieldError,
   useFieldHint,
   useLockReason,
@@ -38,7 +39,7 @@ import {
 // open the picker on a click anywhere in the field instead (feedback #224).
 const PICKER_TYPES = new Set(["date", "datetime-local", "month", "time", "week"]);
 
-export interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
+export interface InputProps extends InputHTMLAttributes<HTMLInputElement>, FieldHelpProps {
   label?: ReactNode;
   /** Classes for the `<input>` itself, as distinct from `className`, which
    *  styles the field WRAPPER once a `label` turns this into a FloatingField.
@@ -156,6 +157,7 @@ export function Input(props: InputProps) {
     invalid,
     error,
     hint,
+    help,
     showCount,
     countLabels,
     passwordLabels,
@@ -171,7 +173,7 @@ export function Input(props: InputProps) {
   const generated = useId();
   const fieldId = id ?? generated;
   const countId = useId();
-  const hintParts = useFieldHint(hint, rest["aria-describedby"]);
+  const hintParts = useFieldHint(hint, rest["aria-describedby"], { help, name: label ?? rest["aria-label"] });
   const maxLength = rest.maxLength;
   const counting = Boolean(showCount) && typeof maxLength === "number" && maxLength > 0;
   const length = useTypedLength(rest.value, rest.defaultValue);

package/src/components/month-picker.tsx

@@ -13,7 +13,7 @@ import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
 import { useKitDateFormatter, useKitLabels, useKitLocale, type LabelOverride } from "../i18n/kit-labels";
 import { hasContent } from "../lib/presence";
-import { FieldBox, FieldLabelLine, LABEL_ABOVE_BOX, mergeRefs, useFieldMessages } from "./field-parts";
+import { FieldBox, FieldLabelLine, LABEL_ABOVE_BOX, mergeRefs, useFieldMessages, type FieldHelpProps } from "./field-parts";
 import { DEFAULT_MONTH_PICKER_LABELS } from "./month-picker-labels";
 
 /**
@@ -63,7 +63,7 @@ function useMonthPickerLabels(partial?: Partial<MonthPickerLabels>): MonthPicker
  * a `FormEvent`, and this one answers with a month key. Everything else reaches the
  * field's root, so a test id or a `data-tour` anchor can find it.
  */
-export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">, "onChange">, FieldHelpProps {
   /**
    * The selected month as a `"YYYY-MM"` key, or `""` for none.
    *
@@ -831,6 +831,7 @@ export function MonthPicker(props: MonthPickerProps) {
     invalid,
     error,
     hint,
+    help,
     size = "md",
     mode = "month",
     formatOptions,
@@ -877,7 +878,13 @@ export function MonthPicker(props: MonthPickerProps) {
   // keksdose K4: the caption and the error, on the trigger after the caller's own
   // description. Painted for `invalid` and a message — not for a bare `aria-invalid`,
   // which this field has never painted for.
-  const messages = useFieldMessages({ hint, error, describedBy: rest["aria-describedby"] });
+  const messages = useFieldMessages({
+    hint,
+    help,
+    name: label ?? rest["aria-label"],
+    error,
+    describedBy: rest["aria-describedby"],
+  });
   const [ownAria, wrapperRest] = splitTriggerAria(rest);
   // The field's trigger is described by the caption and the error too; the stepper
   // draws neither, so its heading keeps the caller's own description.

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

@@ -28,13 +28,15 @@ import {
   useFieldHint,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import { useCommitReason, type CommitScope } from "./write-lock";
 
 /** `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 MultiEntityComboboxProps<V extends string | number>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange">,
+    FieldHelpProps {
   /** Selected ids. */
   value: V[];
   onChange: (value: V[]) => void;
@@ -144,6 +146,7 @@ export function MultiEntityCombobox<V extends string | number>(props: MultiEntit
     invalid,
     error,
     hint,
+    help,
     filter,
     minChars,
     debounceMs,
@@ -169,7 +172,7 @@ export function MultiEntityCombobox<V extends string | number>(props: MultiEntit
     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/multi-select.tsx

@@ -13,6 +13,7 @@ import {
   useFieldMessages,
   useLockReason,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
 } from "./field-parts";
 import type { CommitScope } from "./write-lock";
 import {
@@ -46,7 +47,8 @@ export interface MultiSelectOption<V extends string | number = string | number>
  *  inferred from `options` and `value`, so `onChange` hands back `number[]` for number
  *  ids and `string[]` for string ones, and no call site casts. */
 export interface MultiSelectProps<V extends string | number = string | number>
-  extends Omit<ComponentPropsWithoutRef<"div">, "onChange"> {
+  extends Omit<ComponentPropsWithoutRef<"div">, "onChange">,
+    FieldHelpProps {
   options: MultiSelectOption<V>[];
   /** The chosen values — the select family's `value` (API-4). */
   value?: V[];
@@ -140,6 +142,7 @@ export function MultiSelect<V extends string | number = string | number>(props:
     invalid,
     error,
     hint,
+    help,
     disabled,
     disabledReason,
     disabledReasonDisplay,
@@ -195,6 +198,8 @@ export function MultiSelect<V extends string | number = string | number>(props:
   // The caller's ids, the caption, a lock's reason, the error — Select's order.
   const field = useFieldMessages({
     hint,
+    help,
+    name: label ?? ariaLabel,
     error,
     invalid,
     describedBy: ariaDescribedBy,

package/src/components/number-input.tsx

@@ -11,7 +11,7 @@ import {
 } from "./field-base";
 // The data alone (0.35): not the picker, which this field does not render.
 import { CURRENCIES } from "../currencies";
-import { FieldCaption, LockedReason, mergeRefs, type DisabledReasonDisplay } from "./field-parts";
+import { FieldCaption, LockedReason, mergeRefs, type DisabledReasonDisplay, type FieldHelpProps } from "./field-parts";
 import { useEndWidth, useNumericField } from "./numeric-field";
 import type { CommitScope } from "./write-lock";
 import { cn } from "../lib/cn";
@@ -19,7 +19,7 @@ import { commitExpression, formatResult } from "../lib/calc";
 
 /** {@link NumberInput}'s props — exported since 0.34 (refactor audit 2026-10, API-9): a
  *  wrapper typed itself off `ComponentProps<typeof NumberInput>` until then. */
-export interface NumberInputProps {
+export interface NumberInputProps extends FieldHelpProps {
   /** The text, DOT-decimal ("1234.5", or a calculation being typed: "12+5"), as
    *  `onChange` reports it — so a caller's `Number(value)` reads it. The field SHOWS it
    *  in the locale's mark (see `locale`). A comma here is read as the decimal mark too,

package/src/components/numeric-field.ts

@@ -8,6 +8,7 @@ import {
   useFieldError,
   useFieldHint,
   useLockReason,
+  type FieldHelpProps,
   type FieldHintParts,
   type LockReason,
 } from "./field-parts";
@@ -28,7 +29,9 @@ import type { CommitScope } from "./write-lock";
  */
 
 /** The props both fields take and this engine reads. */
-export interface NumericFieldProps {
+export interface NumericFieldProps extends FieldHelpProps {
+  /** What names the `help` "?" — "About <label>" — with the `aria-label`. */
+  label?: ReactNode;
   hint?: ReactNode;
   error?: ReactNode;
   invalid?: boolean;
@@ -39,6 +42,7 @@ export interface NumericFieldProps {
   calculator?: boolean;
   variant?: "field" | "display";
   locale?: string;
+  "aria-label"?: string;
   "aria-describedby"?: string;
   "aria-invalid"?: boolean | "true" | "false";
 }
@@ -94,7 +98,11 @@ export function useNumericField(props: NumericFieldProps, { settle, display }: N
   const lock = useLockReason(props.commit, props.disabledReason);
   const locked = lock.locked;
   // §4: a FieldHint is the caption at Large and on touch, as on every field.
-  const hint = useFieldHint(props.hint, props["aria-describedby"]);
+  // A `help` is the label line's one "?" and turns the hint into the caption (0.36).
+  const hint = useFieldHint(props.hint, props["aria-describedby"], {
+    help: props.help,
+    name: props.label ?? props["aria-label"],
+  });
   // The standing advice first, the news second: the caller's ids, the caption, the
   // error — a lock's reason between the last two, as on Select.
   const field = useFieldError(

package/src/components/one-time-code-input.tsx

@@ -1,7 +1,7 @@
 import { useId, useState } from "react";
 import type { ChangeEvent, ClipboardEvent, FocusEvent, InputHTMLAttributes, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
-import { EndHintRow, FieldCaption, useFieldError, useFieldHint } from "./field-parts";
+import { EndHintRow, FieldCaption, useFieldError, useFieldHint, type FieldHelpProps } from "./field-parts";
 import {
   FIELD_BASE,
   FIELD_INVALID,
@@ -60,7 +60,8 @@ export interface OneTimeCodeInputProps
   extends Omit<
     InputHTMLAttributes<HTMLInputElement>,
     "value" | "defaultValue" | "onChange" | "type" | "inputMode" | "autoComplete" | "maxLength" | "pattern"
-  > {
+  >,
+    FieldHelpProps {
   /** The digits so far — a string, so leading zeros survive. */
   value: string;
   /** The cleaned code after every edit: digits only, never longer than `length`. */
@@ -130,6 +131,7 @@ export function OneTimeCodeInput(props: OneTimeCodeInputProps) {
     onComplete,
     label,
     hint,
+    help,
     error,
     invalid: invalidProp,
     className,
@@ -151,7 +153,7 @@ export function OneTimeCodeInput(props: OneTimeCodeInputProps) {
   // Text is a caption under the field; a FieldHint rides the label line, and is that
   // caption at Large and on touch (§4). See `hint`. Through useFieldHint and
   // useFieldError since 0.34, not copies of their rules (DUP-2, DUP-8).
-  const hintParts = useFieldHint(hint, ariaDescribedBy);
+  const hintParts = useFieldHint(hint, ariaDescribedBy, { help, name: label ?? rest["aria-label"] });
   const {
     isInvalid: invalid,
     describedBy,