@eifi1/ui-kit 0.34.0 → 0.36.0

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/modal.tsx

@@ -1,4 +1,4 @@
-import { createContext, useEffect, useRef, useState } from "react";
+import { createContext, useEffect, useMemo, useRef, useState } from "react";
 import { createPortal } from "react-dom";
 import type {
   ComponentPropsWithoutRef,
@@ -6,8 +6,10 @@ import type {
   MouseEvent as ReactMouseEvent,
   PointerEvent as ReactPointerEvent,
   ReactNode,
+  Ref,
 } from "react";
 import { cn } from "../lib/cn";
+import { mergeRefs } from "./field-parts";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
@@ -228,6 +230,14 @@ export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"
    * `onClose` still runs, after the param is cleared. Requires a react-router Router.
    */
   urlParam?: DialogParam;
+  /**
+   * The PANEL — the `role="dialog"` element the rest of the props go on, not the
+   * backdrop around it (0.35, round 0.35 R4, the follow-up to API-2; as on
+   * `FullBleedDialog`). Merged with the panel's own ref, which the focus
+   * trap holds. Set while the panel is in the document: `null` while a dialog with
+   * `open={false}` is closed, and after a `urlParam` dialog's param is cleared.
+   */
+  ref?: Ref<HTMLDivElement>;
 }
 
 /**
@@ -286,12 +296,16 @@ function ModalPanel({
   role = "dialog",
   urlParam: _urlParam,
   ownHistoryEntry = true,
+  ref,
   ...rest
 }: ModalProps & {
   /** False when the URL already holds an entry for this dialog — see `urlParam`. */
   ownHistoryEntry?: boolean;
 }) {
   const panelRef = useRef<HTMLDivElement>(null);
+  // The caller's `ref` beside the trap's (round 0.35 R4): memoised, so the panel is not
+  // detached and re-attached on every render.
+  const setPanel = useMemo(() => mergeRefs(panelRef, ref), [ref]);
   const drag = useDragOffset(Boolean(draggable));
   // Without `open`, mounted means open — the constant `true` every hook below used to
   // be given. With it, `open` itself.
@@ -357,9 +371,11 @@ function ModalPanel({
   // One layer on the Escape stack while open (Wave 2, DUP-1): a list, a popover or a
   // tooltip opened inside takes the key before the dialog does, wherever focus is —
   // and the dialog gets it even when focus is not in the panel.
-  useDismissLayer(active, requestClose);
+  const layer = useDismissLayer(active, requestClose);
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
-    runOwnKeyDown(e, onKeyDown);
+    // The caller's handler sees Escape only while this dialog is the layer on top: a
+    // tooltip or a list open over it takes that press first (0.35, KS's gear wizard).
+    runOwnKeyDown(e, onKeyDown, layer);
     // To whatever is on top — this dialog, unless something opened over it — and
     // stopped here. Tab containment lives in useFocusTrap, which listens on the panel.
     takeEscape(e);
@@ -399,7 +415,7 @@ function ModalPanel({
         // losing any of the three is silent, and the symptom (a dialog a screen reader
         // walks straight out of) shows up nowhere near the call site that caused it.
         {...rest}
-        ref={panelRef}
+        ref={setPanel}
         // Normalised at runtime too: an untyped caller's `role="presentation"` must not
         // take the dialog role away (props-passthrough pins that).
         role={role === "alertdialog" ? "alertdialog" : "dialog"}

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,36 +47,26 @@ 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[];
-  /** @deprecated 0.34 — use `value`; removed in 0.35 (refactor audit 2026-10, API-4). */
-  values?: V[];
   onChange: (next: V[]) => void;
-  /** @deprecated 0.34 — use `labels.all`; removed in 0.35 (API-4). Displayed when no
-   *  value is selected (i.e. "all"); wins over `placeholder`, as `labels.all` does. */
-  allLabel?: string;
   /** Singular/plural countable label, used when 1+ items are selected. Default:
    *  `labels.selectedCount`, else `multiSelect.selectedCount` from the provider — the
    *  bare count in English. */
   itemLabel?: (count: number) => string;
-  /** Shown when nothing is picked, unless `labels.all` (or `allLabel`) says otherwise —
-   *  it has always doubled as the "nothing picked" text. */
+  /** Shown when nothing is picked, unless `labels.all` says otherwise — it has always
+   *  doubled as the "nothing picked" text. */
   placeholder?: string;
   /** Embedded top-boundary label, matching the native Input/Select fields. */
   label?: ReactNode;
-  /** @deprecated 0.34 — use `labels.search`; removed in 0.35 (API-4). */
-  searchLabel?: string;
-  /** @deprecated 0.34 — use `labels.selectAll`; removed in 0.35 (API-4). */
-  selectAllLabel?: string;
-  /** @deprecated 0.34 — use `labels.clear`; removed in 0.35 (API-4). */
-  clearLabel?: string;
   /**
    * Per-instance overrides of the provider's `multiSelect` namespace, over English — the
-   * kit's `labels` shape, where this took four string props (API-4). `all` is the trigger
-   * when nothing is picked: `labels.all`, then `allLabel`, then `placeholder`, then the
-   * provider's.
+   * kit's `labels` shape, where this took four string props until 0.35 (API-4: `allLabel`,
+   * `searchLabel`, `selectAllLabel`, `clearLabel`). `all` is the trigger when nothing is
+   * picked: `labels.all`, then `placeholder`, then the provider's.
    */
   labels?: LabelOverride<MultiSelectLabels>;
   /**
@@ -141,21 +132,17 @@ export function MultiSelect<V extends string | number = string | number>(props:
   const {
     options,
     value: valueProp,
-    values,
     onChange,
-    allLabel,
     itemLabel,
     placeholder,
     label,
-    searchLabel,
-    selectAllLabel,
-    clearLabel,
     labels: labelsProp,
     className,
     panelClassName,
     invalid,
     error,
     hint,
+    help,
     disabled,
     disabledReason,
     disabledReasonDisplay,
@@ -172,7 +159,7 @@ export function MultiSelect<V extends string | number = string | number>(props:
     "aria-required": ariaRequired,
     ...rest
   } = props;
-  const value = useMemo<V[]>(() => valueProp ?? values ?? [], [valueProp, values]);
+  const value = useMemo<V[]>(() => valueProp ?? [], [valueProp]);
   // The rows as the family's options — the hint is the sublabel, searched like the label.
   const comboOptions = useMemo(
     () => options.map((o): ComboOption<V> => ({ value: o.value, label: o.label, sublabel: o.hint, disabled: o.disabled })),
@@ -190,14 +177,13 @@ export function MultiSelect<V extends string | number = string | number>(props:
     },
     [ref, triggerRef],
   );
-  // `labels` > the deprecated string props > the provider's `multiSelect` > English. `all`
-  // is resolved apart below: between the instance's and the provider's sits `placeholder`,
-  // which has always doubled as the "nothing picked" text, and a caller who set it must
-  // keep seeing it.
+  // `labels` > the provider's `multiSelect` > English. `all` is resolved apart below:
+  // between the instance's and the provider's sits `placeholder`, which has always
+  // doubled as the "nothing picked" text, and a caller who set it must keep seeing it.
   const text = useKitLabels("multiSelect", DEFAULT_MULTI_SELECT_LABELS, {
-    search: labelsProp?.search ?? searchLabel,
-    selectAll: labelsProp?.selectAll ?? selectAllLabel,
-    clear: labelsProp?.clear ?? clearLabel,
+    search: labelsProp?.search,
+    selectAll: labelsProp?.selectAll,
+    clear: labelsProp?.clear,
     selectedCount: labelsProp?.selectedCount ?? itemLabel,
   });
   const common = useKitLabels("common", DEFAULT_COMMON_LABELS);
@@ -212,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,
@@ -226,7 +214,7 @@ export function MultiSelect<V extends string | number = string | number>(props:
   const allChecked = options.length > 0 && options.every((o) => valueSet.has(o.value));
   const selectedSummary =
     value.length === 0 || allChecked
-      ? (labelsProp?.all ?? allLabel ?? placeholder ?? text.all)
+      ? (labelsProp?.all ?? placeholder ?? text.all)
       : text.selectedCount(value.length);
 
   const toggle = (o: ComboOption<V>) => {

package/src/components/number-input.tsx

@@ -9,8 +9,9 @@ import {
   FLOATING_INPUT_CLASS,
   FloatingField,
 } from "./field-base";
-import { CURRENCIES } from "./currency-select";
-import { FieldCaption, LockedReason, mergeRefs, type DisabledReasonDisplay } from "./field-parts";
+// The data alone (0.35): not the picker, which this field does not render.
+import { CURRENCIES } from "../currencies";
+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";
@@ -18,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,
@@ -35,9 +36,6 @@ export interface NumberInputProps {
   /** Names the field when it has no visible `label` (a table cell, a phone's display
    *  shape). */
   "aria-label"?: string;
-  /** @deprecated 0.34 — use `aria-label`; removed in 0.35 (refactor audit 2026-10, API-1).
-   *  Names the field only when `aria-label` is absent. */
-  ariaLabel?: string;
   /** Names for the calculator this field renders — its trigger, and the controls
    *  inside the popover — and for the numpad sheet it opens on a phone. Overrides
    *  for THIS field only: both resolve the `calculator` namespace of
@@ -319,8 +317,7 @@ export function NumberInput(props: NumberInputProps) {
     onChange,
     onCommit,
     label,
-    "aria-label": ariaLabelAttr,
-    ariaLabel: ariaLabelProp,
+    "aria-label": ariaLabel,
     labels,
     placeholder,
     autoFocus,
@@ -334,8 +331,6 @@ export function NumberInput(props: NumberInputProps) {
     max,
     disabledReasonDisplay,
   } = props;
-  // The DOM spelling wins; `ariaLabel` is the fallback for call sites not moved yet.
-  const ariaLabel = ariaLabelAttr ?? ariaLabelProp;
   const generatedId = useId();
   const fieldId = id ?? generatedId;
   // The engine AmountInput shares (DUP-10): the lock (focusable, `readOnly`, nothing

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,

package/src/components/phone-input.tsx

@@ -148,6 +148,7 @@ export function PhoneInput({
   inputClassName,
   label,
   hint,
+  help,
   error,
   invalid,
   disabled,
@@ -225,6 +226,9 @@ export function PhoneInput({
   // since 0.34, not a copy of its rule (DUP-2, DUP-8).
   const messages = useFieldMessages({
     hint,
+    // The number's label line takes the help's "?" (0.36); the hint is then the caption.
+    help,
+    name: label ?? rest["aria-label"],
     error,
     invalid,
     describedBy: ariaDescribedBy,

package/src/components/popover.tsx

@@ -10,7 +10,9 @@ import { dirOf } from "../lib/direction";
 import type { Direction } from "../lib/direction";
 import { useKitLabels, type LabelOverride } from "../i18n/kit-labels";
 import { DEFAULT_POPOVER_LABELS } from "./popover-labels";
-import { mergeRefs } from "./field-parts";
+// From ../lib/refs, not field-parts (round 0.36): field-parts renders a HelpPopover for a
+// field's `help`, so importing from there would close a cycle, as it did for Tooltip.
+import { mergeRefs } from "../lib/refs";
 
 /** The panel's accessible name. A `role="dialog"` with no name announces as "dialog"
  *  and nothing else, which is worse than the unlabelled div it replaced — so it is a
@@ -159,7 +161,7 @@ export function Popover({
   // A layer on the Escape stack while open (Wave 2, DUP-1): a list opened inside closes
   // first, and the dialog this popover sits in only after it — the calculator on an
   // amount field in a Modal is exactly that.
-  useDismissLayer(open, close);
+  const layer = useDismissLayer(open, close);
 
   useFocusTrap(panelRef, {
     active: open && pos !== null,
@@ -178,8 +180,10 @@ export function Popover({
   const handleKeyDown = (e: KeyboardEvent<HTMLDivElement>) => {
     // A caller's own handler first (0.32.2: RowActions stops Enter / Space at the panel);
     // it used to be dropped, overwritten by this one. A `preventDefault()` on Escape
-    // there keeps the popover open — the owner's claim, as on the dialogs.
-    runOwnKeyDown(e, onKeyDownProp);
+    // there keeps the popover open — the owner's claim, as on the dialogs. And as there,
+    // the handler sees Escape only while this popover is the layer on top: a tooltip or a
+    // menu open over it takes that press first (round 0.35 R2, the dialogs' rule).
+    runOwnKeyDown(e, onKeyDownProp, layer);
     // Focus is in here, the normal case: the key is handed to the top layer and STOPPED,
     // so it does not travel on up the React tree to a dialog around the popover.
     takeEscape(e);

package/src/components/select.tsx

@@ -6,6 +6,7 @@ import {
   LockedReason,
   mergeDescribedBy,
   type DisabledReasonDisplay,
+  type FieldHelpProps,
   useFieldError,
   useFieldHint,
   useLockReason,
@@ -20,7 +21,7 @@ import {
   fieldBelow,
 } from "./field-base";
 
-export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size">, FieldHelpProps {
   label?: ReactNode;
   /** See {@link Input}'s `invalid`. */
   invalid?: boolean;
@@ -33,7 +34,8 @@ export interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement
    *  set in the value's type on top of both the label and the value. On an
    *  UNLABELLED Select (no label line) a FieldHint sits at the field's end edge,
    *  outside the box. Since 0.34 a FieldHint is the caption at Large and on a touch
-   *  screen, as on Input (`useInlineHint`); a `HelpPopover` stays a "?". */
+   *  screen, as on Input (`useInlineHint`); a `HelpPopover` stays a "?". Beside a
+   *  `help` (0.36) the hint is the caption at every size: the help's "?" is the only one. */
   hint?: ReactNode;
   /**
    * `"sm"`: a 28px, 12px-type select for a toolbar or a table header, where the
@@ -109,6 +111,7 @@ export function Select(props: SelectProps) {
     invalid,
     error,
     hint: hintProp,
+    help,
     size,
     selectClassName,
     disabledReason,
@@ -138,7 +141,7 @@ export function Select(props: SelectProps) {
   // and on a touch screen is its words, a caption like any text (§4; a HelpPopover stays
   // on the label line, §10.23). See `hint` above. Through useFieldHint since 0.34, not a
   // copy of its rule (DUP-2, refactor audit 2026-10).
-  const hintParts = useFieldHint(hintProp, rest["aria-describedby"]);
+  const hintParts = useFieldHint(hintProp, rest["aria-describedby"], { help, name: label ?? rest["aria-label"] });
   const hint = hintParts.labelHint;
   const { isInvalid, describedBy, errorEl } = useFieldError(
     error,

package/src/components/series-chart.tsx

@@ -25,7 +25,7 @@
 // "area"` (and `stack`), and the abscissa may be a row of PERIODS (`x.type:
 // "category"`) or real dates (`x.type: "time"`) instead of a number the app had to
 // invent. What each of those does to the zoom is decided in one place,
-// `defaultZoomAxes` in `chart-zoom.tsx`.
+// `defaultZoomAxes` in `chart-zoom-core.tsx`.
 //
 // **An axis budget (0.15.1).** Every visible axis reserves its band, and four of them
 // leave a phone nothing to plot. A chart draws at most `maxVisibleAxes`, and — on its

package/src/components/server-wake.tsx

@@ -69,12 +69,6 @@ export interface ServerWakeNoticeProps {
    *  label says "the app". */
   appName?: string;
   labels?: LabelOverride<ServerWakeLabels>;
-  /**
-   * @deprecated 0.34 — drop it; removed in 0.35. The notice sits at the TOP of the
-   * screen since 0.34, so there is no bottom nav to clear and this does nothing. It was
-   * the height kept clear at the bottom (AppShell's `--app-nav-h`).
-   */
-  navOffset?: string | number;
   /** Extra classes on the fixed anchor — a different width (`max-w-*`), or another
    *  `top-*` for an app that wants it under its top bar rather than over it. Merged, so
    *  a class given here replaces the kit's of the same kind. */

package/src/components/settings-fields.tsx

@@ -52,7 +52,8 @@ export interface ThemeSettingSelectProps
  * choice visible without opening anything, in every app (keksdose offered light and dark
  * only; its store already knew "system"). A {@link ToggleGroup}'s props pass through —
  * `labelPlacement`, `disabledReason`, `commit`, `size`, `overflow` — minus the options
- * and the value, which this owns.
+ * and the value, which this owns. `ref` too: the group, whose `focus()` lands on the
+ * checked option (pinned in round 0.35 R4; the select variant's `ref` is the `<select>`).
  *
  * The options wrap rather than truncate (`overflow="wrap"`), as in its two siblings
  * {@link TextSizeSetting} and {@link ContrastSetting} (0.32.1, Kurvenschmiede's 0.32
@@ -161,7 +162,8 @@ export function LanguageSetting({ options, ...rest }: LanguageSettingProps) {
 /**
  * What {@link TextSizeSetting} and {@link ContrastSetting} take: a {@link ToggleGroup}'s
  * props — `labelPlacement`, `disabledReason`, `commit`, `size`, `overflow` — minus the
- * options and the value, which they own, as {@link ThemeSettingToggleProps} does.
+ * options and the value, which they own, as {@link ThemeSettingToggleProps} does. `ref`
+ * is the group's, as there (round 0.35 R4).
  */
 type AppearanceToggleProps<T extends string> = Omit<ToggleGroupBaseProps<T>, "options" | "label"> & {
   value: T;

package/src/components/slider.tsx

@@ -1,7 +1,7 @@
 import { useId } from "react";
 import type { CSSProperties, ChangeEvent, InputHTMLAttributes, ReactNode, Ref } from "react";
 import { cn } from "../lib/cn";
-import { useFieldMessages } from "./field-parts";
+import { useFieldMessages, type FieldHelpProps } from "./field-parts";
 
 /**
  * A range control on a native `<input type="range">`.
@@ -123,7 +123,8 @@ export interface SliderProps
   extends Omit<
     InputHTMLAttributes<HTMLInputElement>,
     "type" | "value" | "defaultValue" | "onChange" | "min" | "max" | "step" | "children"
-  > {
+  >,
+    FieldHelpProps {
   /** The value. On a log scale this is the real value, not the track position. */
   value: number;
   /** The new value — a number, not the DOM event, like `ToggleGroup`. Fired on every
@@ -201,6 +202,7 @@ export function Slider({
   formatValue,
   label,
   hint,
+  help,
   readout,
   marks,
   className,
@@ -254,7 +256,12 @@ export function Slider({
   const hasMarkLabels = normalizedMarks.some((m) => m.label !== undefined);
 
   // The label line's "?", or the caption under the track (DUP-2).
-  const messages = useFieldMessages({ hint, describedBy: rest["aria-describedby"] });
+  const messages = useFieldMessages({
+    hint,
+    help,
+    name: label ?? rest["aria-label"],
+    describedBy: rest["aria-describedby"],
+  });
   const labelHint = messages.labelHint;
   const hasHeader = label !== undefined || labelHint !== undefined || readout !== undefined;
   const plainReadout = typeof readout === "string" || typeof readout === "number";