@eifi1/ui-kit 0.10.0 → 0.12.0

package/src/components/modal.tsx

@@ -11,6 +11,7 @@ import { cn } from "../lib/cn";
 import { useFocusTrap } from "../hooks/use-focus-trap";
 import { useBodyScrollLock } from "../hooks/use-body-scroll-lock";
 import { useOverlayHistory } from "../hooks/use-overlay-history";
+import { useDialogParam, type DialogParam } from "../hooks/use-search-param-state";
 import { OVERLAY_EXIT_MS, prefersReducedMotion, useCloseTransition } from "../hooks/use-close-transition";
 
 /**
@@ -196,6 +197,50 @@ export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"
    * suppressed there — there is nothing beside it to see.
    */
   draggable?: boolean;
+  /**
+   * Bind the open state to a URL search param (0.12.0): `"edit"` is open while
+   * `?edit` is in the query, `{ key: "dialog", value: "create-lease" }` while
+   * `?dialog=create-lease` is. The URL is then the only state — `open` is ignored —
+   * and the dialog opens from anywhere that sets the param: {@link useDialogParam}'s
+   * setter, a `<Link>`, a shared link, a reload.
+   *
+   * kastlan's `useDialogParam` did this beside the dialog, so its open state could be
+   * deep-linked and captured in a feedback report. Here it also owns the history:
+   * opening through `useDialogParam` pushes an entry, so the Back gesture closes the
+   * dialog by leaving it, and a close (Escape, the backdrop, the X) goes back over
+   * that entry rather than stacking a second one. The dialog's own Back handling
+   * ({@link useOverlayHistory}'s throwaway entry) stays off in this mode — the param's
+   * entry already is one, and two would take two Back presses to close one dialog.
+   *
+   * `onClose` still runs, after the param is cleared. Requires a react-router Router.
+   */
+  urlParam?: DialogParam;
+}
+
+/**
+ * The URL-bound dialog: the param is the open state, and closing clears it. A
+ * component of its own so the router hook is only called by a `Modal` that asked for
+ * it — a plain `Modal` must keep working with no Router above it.
+ */
+function UrlParamModal({ urlParam, onClose, ...rest }: ModalProps & { urlParam: DialogParam }) {
+  const [open, setOpen] = useDialogParam(urlParam);
+  // Closed from here the moment the dismissal is decided. Going back is a traversal
+  // the browser lands a task later, and between the two the param still says "open":
+  // without this the panel, already lowered, would pop back up for that task.
+  const [leaving, setLeaving] = useState(false);
+  if (leaving && !open) setLeaving(false);
+  return (
+    <ModalPanel
+      {...rest}
+      open={open && !leaving}
+      ownHistoryEntry={false}
+      onClose={() => {
+        setLeaving(true);
+        setOpen(false);
+        onClose();
+      }}
+    />
+  );
 }
 
 /**
@@ -206,7 +251,15 @@ export interface ModalProps extends Omit<ComponentPropsWithoutRef<"div">, "role"
  * into the panel on open and back to the trigger on close, a Tab focus trap, and
  * `role="dialog"`/`aria-modal`.
  */
-export function Modal({
+export function Modal(props: ModalProps) {
+  return props.urlParam !== undefined ? (
+    <UrlParamModal {...props} urlParam={props.urlParam} />
+  ) : (
+    <ModalPanel {...props} />
+  );
+}
+
+function ModalPanel({
   onClose,
   open,
   children,
@@ -218,8 +271,13 @@ export function Modal({
   draggable,
   style,
   role = "dialog",
+  urlParam: _urlParam,
+  ownHistoryEntry = true,
   ...rest
-}: ModalProps) {
+}: ModalProps & {
+  /** False when the URL already holds an entry for this dialog — see `urlParam`. */
+  ownHistoryEntry?: boolean;
+}) {
   const panelRef = useRef<HTMLDivElement>(null);
   const drag = useDragOffset(Boolean(draggable));
   // Without `open`, mounted means open — the constant `true` every hook below used to
@@ -262,7 +320,7 @@ export function Modal({
   // this the only way out of a dialog is finding its close button — and Back, the
   // gesture everyone reaches for, navigated the page underneath instead (#172).
   // Held only while open: a closed `open={false}` dialog must not own a history entry.
-  useOverlayHistory(active, requestClose);
+  useOverlayHistory(active && ownHistoryEntry, requestClose);
 
   // Through the shared hook and not by hand: this component's own save/restore copy
   // was one half of the pair that left the page permanently unscrollable when a dialog

package/src/components/month-picker.tsx

@@ -1,10 +1,10 @@
 import { useEffect, useId, useMemo, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode, RefObject } from "react";
-import { Calendar, ChevronLeft, ChevronRight } from "lucide-react";
+import { Calendar, ChevronDown, ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn";
 import { dirOf, horizontalStep, type Direction } from "../lib/direction";
 import { monthKey, pad } from "../lib/dates";
-import { FieldLabel, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER } from "./ui";
+import { Button, FieldLabel, FIELD_FLOATING_PAD, FIELD_INVALID, FIELD_TRIGGER, IconButton } from "./ui";
 import { Popover } from "./popover";
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
@@ -27,6 +27,11 @@ export interface MonthPickerLabels {
    * "Aug" read out on its own does not say which year the grid is on.
    */
   month: (monthYear: string) => string;
+  /** `variant="stepper"`: the icon-only arrows that step the value by one month. */
+  previousMonth: string;
+  nextMonth: string;
+  /** `variant="stepper"`: the button that jumps to the current month. Visible text. */
+  today: string;
 }
 
 /** The English starting point every override is merged onto. Exported (unlike the
@@ -37,6 +42,9 @@ export const DEFAULT_MONTH_PICKER_LABELS: MonthPickerLabels = {
   nextYear: "Next year",
   panel: "Choose a month",
   month: (monthYear) => monthYear,
+  previousMonth: "Previous month",
+  nextMonth: "Next month",
+  today: "Today",
 };
 
 /** Merge caller overrides onto the English defaults. */
@@ -95,6 +103,21 @@ export interface MonthPickerProps extends Omit<ComponentPropsWithoutRef<"div">,
   /** Extra classes for the trigger button — e.g. a compact `h-9 w-auto` trigger
    *  sitting between two icon buttons in a toolbar. */
   triggerClassName?: string;
+  /**
+   * `"field"` (default): the field-shaped trigger, for a form.
+   *
+   * `"stepper"`: the header of a month PAGE — the month as a heading that opens the
+   * grid, then Today and ‹ › stepping the value by one month. What a calendar page
+   * assembled by hand around the field (overriding its trigger to look like a
+   * heading). `label`, `placeholder`, `invalid` and `triggerClassName` are the field's
+   * and are not drawn here; with no `value` the arrows step from the current month.
+   */
+  variant?: "field" | "stepper";
+  /** `variant="stepper"`: the heading level the month is set in (`<h2>` by default), or
+   *  `false` for no heading element — the page already has one for the month. */
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6 | false;
+  /** `variant="stepper"`: draw the Today button. Default `true`. */
+  showToday?: boolean;
 }
 
 // ── Month keys ────────────────────────────────────────────────────────────
@@ -140,6 +163,74 @@ const MONTH_NAME_FORMAT: Intl.DateTimeFormatOptions = { month: "long", year: "nu
 
 // ── Trigger ───────────────────────────────────────────────────────────────
 
+/** Hand focus back to the trigger when the panel closes with focus still inside it. */
+function useFocusBackOnClose(open: boolean, triggerRef: RefObject<HTMLButtonElement | null>) {
+  const wasOpen = useRef(false);
+  useEffect(() => {
+    const justClosed = wasOpen.current && !open;
+    wasOpen.current = open;
+    if (!justClosed) return;
+    // Only when focus went down with the panel. An outside click has already put it
+    // somewhere real, and dragging it back here would be worse than leaving it.
+    const active = document.activeElement;
+    if (!active || active === document.body) triggerRef.current?.focus();
+  }, [open, triggerRef]);
+}
+
+/**
+ * The stepper's trigger: the month as a heading-sized button that opens the grid.
+ *
+ * Its own text is its name ("September 2026"), so it needs no label of its own, and
+ * it is `aria-live` for the reason `MiniCalendar`'s caption is: pressing ‹ or › leaves
+ * focus on the arrow, and the heading is the only thing that says where the arrow
+ * went. A plain button with `aria-haspopup`, not the field's `combobox` — it does not
+ * look or behave like a field, and a heading reading "combobox" is a surprise.
+ */
+function MonthHeadingTrigger({
+  open,
+  toggle,
+  triggerRef,
+  text,
+  panelId,
+  disabled,
+  aria,
+}: {
+  open: boolean;
+  toggle: () => void;
+  triggerRef: RefObject<HTMLButtonElement | null>;
+  text: string;
+  panelId: string;
+  disabled?: boolean;
+  aria: TriggerAria;
+}) {
+  useFocusBackOnClose(open, triggerRef);
+  return (
+    <button
+      ref={triggerRef}
+      type="button"
+      disabled={disabled}
+      onClick={toggle}
+      aria-haspopup="dialog"
+      aria-controls={panelId}
+      aria-expanded={open}
+      id={aria.id}
+      aria-label={aria["aria-label"]}
+      aria-labelledby={aria["aria-labelledby"]}
+      aria-describedby={aria["aria-describedby"]}
+      className={cn(
+        "-ms-1.5 inline-flex h-9 min-w-0 items-center gap-1 rounded-md px-1.5 text-lg font-semibold text-[var(--text-primary)] transition-colors",
+        "hover:bg-[var(--bg-hover)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
+        disabled && "cursor-not-allowed opacity-50",
+      )}
+    >
+      <span aria-live="polite" className="truncate">
+        {text || "\u00a0"}
+      </span>
+      <ChevronDown aria-hidden className="size-4 shrink-0 text-[var(--text-muted)]" />
+    </button>
+  );
+}
+
 /**
  * The field-shaped button that opens the grid. The same shape as `DatePicker`'s
  * trigger, for the same reasons written down there: `role="combobox"` so it may carry
@@ -176,16 +267,7 @@ function MonthFieldTrigger({
   invalid?: boolean;
   className?: string;
 }) {
-  const wasOpen = useRef(false);
-  useEffect(() => {
-    const justClosed = wasOpen.current && !open;
-    wasOpen.current = open;
-    if (!justClosed) return;
-    // Only when focus went down with the panel. An outside click has already put it
-    // somewhere real, and dragging it back here would be worse than leaving it.
-    const active = document.activeElement;
-    if (!active || active === document.body) triggerRef.current?.focus();
-  }, [open, triggerRef]);
+  useFocusBackOnClose(open, triggerRef);
 
   return (
     <button
@@ -475,6 +557,9 @@ export function MonthPicker({
   labels: labelsProp,
   className,
   triggerClassName,
+  variant = "field",
+  headingLevel = 2,
+  showToday = true,
   ...rest
 }: MonthPickerProps) {
   const labels = useMonthPickerLabels(labelsProp);
@@ -506,6 +591,89 @@ export function MonthPicker({
   const rootRef = useRef<HTMLDivElement>(null);
   const [dir, setDir] = useState<Direction>("ltr");
 
+  const grid = (close: () => void) => (
+    <MonthGrid
+      value={selected}
+      locale={locale}
+      minKey={minKey}
+      maxKey={maxKey}
+      currentKey={currentKey}
+      labels={labels}
+      onPick={(key) => {
+        onChange(key);
+        close();
+      }}
+    />
+  );
+
+  if (variant === "stepper") {
+    // The arrows step from the value, or from "now" when there is none; each is dead
+    // once the month it leads to is out of bounds, and Today once "now" is.
+    const base = selected ?? parseMonth(currentKey)!;
+    const prevKey = toKey(shiftMonth(base, -1));
+    const nextKey = toKey(shiftMonth(base, 1));
+    const outside = (key: string) => Boolean((minKey && key < minKey) || (maxKey && key > maxKey));
+    const Heading = headingLevel ? (`h${headingLevel}` as const) : null;
+    const trigger = (
+      <Popover
+        width={256}
+        panelId={panelId}
+        labels={{ panel: labels.panel }}
+        dir={dir}
+        trigger={({ open, toggle, ref }) => (
+          <MonthHeadingTrigger
+            open={open}
+            toggle={() => {
+              setDir(dirOf(rootRef.current));
+              toggle();
+            }}
+            triggerRef={ref}
+            text={triggerText}
+            panelId={panelId}
+            disabled={disabled}
+            aria={aria}
+          />
+        )}
+      >
+        {grid}
+      </Popover>
+    );
+    return (
+      <div {...wrapperRest} ref={rootRef} className={cn("flex min-w-0 items-center gap-2", className)}>
+        {Heading ? <Heading className="m-0 min-w-0 text-lg font-semibold">{trigger}</Heading> : trigger}
+        <div className="ms-auto flex shrink-0 items-center gap-1">
+          {showToday && (
+            <Button
+              variant="secondary"
+              size="sm"
+              disabled={disabled || outside(currentKey)}
+              onClick={() => {
+                if (currentKey !== value) onChange(currentKey);
+              }}
+            >
+              {labels.today}
+            </Button>
+          )}
+          <IconButton
+            aria-label={labels.previousMonth}
+            disabled={disabled || outside(prevKey)}
+            onClick={() => onChange(prevKey)}
+          >
+            {/* Mirrored in RTL, where "previous" points the other way. */}
+            <ChevronLeft className="rtl:-scale-x-100" />
+          </IconButton>
+          <IconButton
+            aria-label={labels.nextMonth}
+            disabled={disabled || outside(nextKey)}
+            onClick={() => onChange(nextKey)}
+          >
+            <ChevronRight className="rtl:-scale-x-100" />
+          </IconButton>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <div {...wrapperRest} ref={rootRef} className={cn("relative", className)}>
       {label !== undefined && <FieldLabel>{label}</FieldLabel>}
@@ -550,20 +718,7 @@ export function MonthPicker({
           />
         )}
       >
-        {(close) => (
-          <MonthGrid
-            value={selected}
-            locale={locale}
-            minKey={minKey}
-            maxKey={maxKey}
-            currentKey={currentKey}
-            labels={labels}
-            onPick={(key) => {
-              onChange(key);
-              close();
-            }}
-          />
-        )}
+        {grid}
       </Popover>
       <Calendar
         aria-hidden

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

@@ -94,6 +94,15 @@ export function MultiEntityCombobox<V extends string | number>({
   debounceMs,
   loadErrorLabel,
   "aria-label": ariaLabel,
+  // The control's own wiring, taken off `rest` so it lands on the TRIGGER rather than
+  // the wrapper: `Field`'s render-prop spreads `{ id, aria-describedby, aria-invalid,
+  // aria-required }`, and on the role-less wrapper div the label's `htmlFor` named
+  // nothing and the hint and required state described nothing — kastlan's
+  // communication-page To/Cc/Bcc and lease-tenants-step.tsx read as unnamed pickers.
+  id,
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: MultiEntityComboboxProps<V>) {
   const core = useComboboxCore<V>({
@@ -104,7 +113,11 @@ export function MultiEntityCombobox<V extends string | number>({
     minChars,
     debounceMs,
   });
-  const field = useComboboxFieldError(error, invalid);
+  const field = useComboboxFieldError(
+    error,
+    invalid || ariaInvalid === true || ariaInvalid === "true",
+    ariaDescribedBy,
+  );
   // 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.
   const labels = useKitLabels("combobox", DEFAULT_COMBOBOX_LABELS, {
@@ -154,13 +167,15 @@ export function MultiEntityCombobox<V extends string | number>({
   };
 
   return (
-    // `rest` dresses the wrapper, which has no role; the accessible NAME goes on
-    // the trigger, which has one. Spread FIRST so the trigger's ARIA and the
+    // `rest` dresses the wrapper, which has no role; the accessible NAME — and the
+    // id, description, invalid and required state above — go on the trigger, which
+    // has one. Spread FIRST so the trigger's ARIA and the
     // handlers that open the panel cannot be clobbered from outside.
     <div {...rest} className={cn("relative", className)}>
       {label !== undefined && <FieldLabel>{label}</FieldLabel>}
       <button
         ref={core.triggerRef}
+        id={id}
         type="button"
         // A combobox, not a button. The distinction is not pedantry: this control
         // carried `aria-invalid`, which `button` does not support, so a required
@@ -188,6 +203,7 @@ export function MultiEntityCombobox<V extends string | number>({
         disabled={disabled}
         aria-invalid={field.isInvalid || undefined}
         aria-describedby={field.describedBy}
+        aria-required={ariaRequired}
         onClick={() => !disabled && setOpen((o) => !o)}
         // Down/Up opens the list from the closed trigger, per the APG. Enter and
         // Space already do it through the button's own click.

package/src/components/nav-pills.tsx

@@ -0,0 +1,152 @@
+import type { ComponentPropsWithoutRef, ComponentType, MouseEvent, ReactElement, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useKitLink } from "../i18n/kit-labels";
+import { pickLinkRenderer, RenderedKitLink } from "./text-link";
+
+export interface NavPillItem<T extends string> {
+  value: T;
+  label: ReactNode;
+  /** Where the pill leads. With one it is a link (see `renderLink`); without, a button
+   *  that calls `onSelect`. */
+  href?: string;
+  /** A Lucide icon (or any component taking a `className`), before the label. */
+  icon?: ComponentType<{ className?: string; "aria-hidden"?: boolean }>;
+  /** Buttons only — a link cannot be disabled. */
+  disabled?: boolean;
+}
+
+/** What {@link NavPillsProps.renderLink} is handed. Spread it onto your router's link
+ *  — `({ href, ...p }) => <Link to={href} {...p} />`. */
+export interface NavPillLinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+  "aria-current": NavPillsCurrent | undefined;
+  onClick: (e: MouseEvent<HTMLAnchorElement>) => void;
+}
+
+/** The `aria-current` token the current pill carries. */
+export type NavPillsCurrent = "page" | "step" | "location" | "true";
+
+export interface NavPillsProps<T extends string> extends Omit<ComponentPropsWithoutRef<"nav">, "children" | "onSelect"> {
+  items: NavPillItem<T>[];
+  /** The pill that is current. `null` or a value not in `items`: none is. */
+  current: T | null;
+  /** Called with the pill's value on a click — of a button, and of a link too (before
+   *  the router follows it), for a caller that keeps the choice in state as well. */
+  onSelect?: (value: T) => void;
+  /** Your router's link. Default: the `<UiKitProvider linkComponent>` (for an in-app
+   *  `href`), then `<a>`. The API `Breadcrumbs`, `Chip` and `ListItem` share. */
+  renderLink?: (props: NavPillLinkProps) => ReactElement;
+  /** What `aria-current` says on the current pill. Default `page` where the items
+   *  are links and `true` where they are buttons (keksdose's swipe-surface picker
+   *  switches a panel on the same page, which is not a page). */
+  currentType?: NavPillsCurrent;
+  /** `sm`: 12px pills — the compact size of a {@link ToggleGroup}. Default `md`. */
+  size?: "sm" | "md";
+  /** Render a `<nav>` landmark (default) or a plain `<div role="group">` for a picker
+   *  that is not the page's navigation. Name either with `aria-label`. */
+  landmark?: boolean;
+  /** Classes for every pill. */
+  itemClassName?: string;
+}
+
+// The pill is a ToggleGroup segment's (`rounded`, `px-3 py-1.5`, the inverse fill for
+// the current one), so a strip of these beside a segmented control reads as the same
+// family. Unlike the segments, a pill never truncates: the strip WRAPS instead.
+const PILL =
+  "inline-flex items-center gap-1.5 whitespace-nowrap rounded-md px-3 py-1.5 text-sm font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--border-strong)] [&_svg]:size-4 [&_svg]:shrink-0";
+const PILL_SM = "gap-1 px-2 py-1 text-xs [&_svg]:size-3.5";
+const PILL_CURRENT = "bg-[var(--bg-inverse)] text-[var(--text-inverse)]";
+const PILL_IDLE = "text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]";
+const PILL_DISABLED = "cursor-not-allowed opacity-50 hover:bg-transparent hover:text-[var(--text-secondary)]";
+
+/**
+ * A set of links or buttons that WRAPS onto as many rows as it needs, the current one
+ * filled and marked `aria-current`.
+ *
+ * keksdose's swipe-settings card (swipe-settings-card:152) hand-rolled this: four
+ * surface names that do not fit a 406px phone, and a sideways scroll would hide the
+ * ones that do not fit behind a gesture nothing announces (live #332: *"Have the tabs
+ * in more rows, rather than scrolling sideways"*). It is not {@link Tabs} with `wrap`
+ * because its items are not tabs: a `role="tab"` promises a tabpanel, a roving tab
+ * stop and arrow keys, and a set of links to pages (or of buttons that switch the rest
+ * of a card) promises none of that. So every pill is its own tab stop, the set is a
+ * list (a screen reader hears "list, 4 items"), and "current" is `aria-current` — the
+ * attribute a link to where you already are carries.
+ */
+export function NavPills<T extends string>({
+  items,
+  current,
+  onSelect,
+  renderLink,
+  currentType,
+  size = "md",
+  landmark = true,
+  itemClassName,
+  className,
+  ...rest
+}: NavPillsProps<T>) {
+  const kitLink = useKitLink();
+  const Root = landmark ? "nav" : "div";
+  return (
+    <Root {...rest} role={landmark ? undefined : "group"} className={cn("min-w-0", className)}>
+      <ul className="m-0 flex list-none flex-wrap gap-1 p-0">
+        {items.map((item) => {
+          const isCurrent = item.value === current;
+          const Icon = item.icon;
+          const pillClass = cn(
+            PILL,
+            size === "sm" && PILL_SM,
+            isCurrent ? PILL_CURRENT : PILL_IDLE,
+            item.disabled && item.href === undefined && PILL_DISABLED,
+            itemClassName,
+          );
+          const children = (
+            <>
+              {Icon && <Icon aria-hidden />}
+              {item.label}
+            </>
+          );
+          let pill: ReactNode;
+          if (item.href !== undefined) {
+            const props: NavPillLinkProps = {
+              href: item.href,
+              className: pillClass,
+              children,
+              "aria-current": isCurrent ? (currentType ?? "page") : undefined,
+              onClick: () => onSelect?.(item.value),
+            };
+            const kit = pickLinkRenderer<NavPillLinkProps>(undefined, kitLink, item.href);
+            pill = renderLink ? (
+              renderLink(props)
+            ) : kit ? (
+              <RenderedKitLink render={kit} props={props} />
+            ) : (
+              <a href={props.href} className={props.className} aria-current={props["aria-current"]} onClick={props.onClick}>
+                {props.children}
+              </a>
+            );
+          } else {
+            pill = (
+              <button
+                type="button"
+                disabled={item.disabled}
+                aria-current={isCurrent ? (currentType ?? "true") : undefined}
+                onClick={() => onSelect?.(item.value)}
+                className={pillClass}
+              >
+                {children}
+              </button>
+            );
+          }
+          return (
+            <li key={item.value} className="flex">
+              {pill}
+            </li>
+          );
+        })}
+      </ul>
+    </Root>
+  );
+}

package/src/components/number-field.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useId, useState } from "react";
+import { useId, useState } from "react";
 import type { ComponentProps, ReactNode } from "react";
 import { NumberInput } from "./number-input";
 import { evaluateExpression, formatResult } from "../lib/calc";
@@ -62,6 +62,14 @@ export interface NumberFieldProps
    *  injects `id` / `aria-describedby` / `aria-invalid`) can wrap this directly. */
   "aria-describedby"?: string;
   "aria-invalid"?: boolean | "true" | "false";
+  /**
+   * Set on the `<input>`. Declared, with `id` (from NumberInput) and the two above, so
+   * `Field`'s render-prop spread — `{(ids) => <NumberField {...ids} … />}`, kastlan's
+   * wizard steps — is typed and reaches the input rather than being dropped: before
+   * this, `aria-required` was not in the type and a required number was announced as
+   * optional.
+   */
+  "aria-required"?: boolean | "true" | "false";
 }
 
 /** The locale's decimal mark, as far as this field can type it: "," or ".". A mark
@@ -163,6 +171,7 @@ export function NumberField({
   id,
   "aria-describedby": ariaDescribedBy,
   "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   ...rest
 }: NumberFieldProps) {
   const locale = useKitLocale(localeProp);
@@ -250,15 +259,9 @@ export function NumberField({
   const hasError = error !== undefined && error !== null && error !== false && error !== "";
   const describedBy = [ariaDescribedBy, hasError ? errorId : undefined].filter(Boolean).join(" ");
 
-  // NumberInput takes no `aria-describedby` of its own, so the reference is set on
-  // its <input> directly, found by the id this field hands it. React never renders
-  // that attribute there, so nothing reconciles it away again.
-  useEffect(() => {
-    const input = document.getElementById(fieldId);
-    if (!input) return;
-    if (describedBy) input.setAttribute("aria-describedby", describedBy);
-    else input.removeAttribute("aria-describedby");
-  }, [fieldId, describedBy]);
+  // Straight onto NumberInput's <input>, which declares both now. They used to be set
+  // on the DOM node from an effect, because NumberInput had no props for them.
+  const required = ariaRequired === true || ariaRequired === "true";
 
   const labelWithUnit =
     unit !== undefined && unitPlacement === "label"
@@ -277,6 +280,8 @@ export function NumberField({
     <NumberInput
       {...rest}
       id={fieldId}
+      aria-describedby={describedBy || undefined}
+      aria-required={required || undefined}
       label={labelWithUnit}
       value={draft}
       onChange={onText}

package/src/components/number-input.tsx

@@ -57,6 +57,15 @@ interface NumberInputProps {
   hint?: ReactNode;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
+  /**
+   * Set on the `<input>`, with `id` above. Declared so `Field`'s render-prop spread —
+   * `{(ids) => <NumberInput {...ids} … />}` — is typed and reaches the input: the hint
+   * and error are described, a required number is announced as required, and
+   * `aria-invalid` paints {@link FIELD_INVALID} the way `invalid` does.
+   */
+  "aria-describedby"?: string;
+  "aria-invalid"?: boolean | "true" | "false";
+  "aria-required"?: boolean | "true" | "false";
   /**
    * A static unit shown at the field's right edge — "%", "kg", "km/h".
    *
@@ -156,7 +165,10 @@ export function NumberInput({
   calculator = true,
   variant = "field",
   hint,
-  invalid,
+  invalid: invalidProp,
+  "aria-describedby": ariaDescribedBy,
+  "aria-invalid": ariaInvalid,
+  "aria-required": ariaRequired,
   suffix,
   step,
   min,
@@ -164,6 +176,7 @@ export function NumberInput({
 }: NumberInputProps) {
   const generatedId = useId();
   const fieldId = id ?? generatedId;
+  const invalid = Boolean(invalidProp) || ariaInvalid === true || ariaInvalid === "true";
   const labelled = label !== undefined;
   // On phones we suppress the OS keyboard (inputMode="none" below) for our own
   // calculator numpad, so the desktop popover trigger is hidden (feedback #334).
@@ -234,6 +247,8 @@ export function NumberInput({
         }}
         onKeyDown={onKeyDown}
         aria-invalid={invalid || undefined}
+        aria-describedby={ariaDescribedBy}
+        aria-required={ariaRequired}
         // The end padding sits last so it always wins over an inputClassName that
         // sets its own px. Both trailing controls can be on at once, so the room
         // they need is reserved together rather than by whichever happens to render: