@eifi1/ui-kit 0.11.0 → 0.12.0

package/src/components/mini-calendar.tsx

@@ -175,6 +175,18 @@ export interface MiniCalendarProps extends Omit<ComponentPropsWithoutRef<"div">,
    * it is what names the grid.
    */
   hideNavigation?: boolean;
+  /**
+   * Fill the leading and trailing cells with the neighbouring months' days, muted —
+   * the wall-calendar look, where the first row does not start on a hole.
+   *
+   * They are real days, not decoration: each is named with its whole date, honours
+   * `min`/`max`, and a click selects it and moves the grid to its month (focus goes
+   * with it). They are NOT stops of the roving tabindex — the keyboard already reaches
+   * them by arrowing off the month's edge, which moves the grid the same way — and
+   * `renderDay` is not called for them, so a day's events are drawn once, in its own
+   * month. Default `false`: the cells stay empty.
+   */
+  showOutsideDays?: boolean;
   /** Extra classes for the calendar's root. */
   className?: string;
 }
@@ -256,6 +268,7 @@ export function MiniCalendar({
   month,
   onMonthChange,
   hideNavigation,
+  showOutsideDays = false,
   className,
   ...rest
 }: MiniCalendarProps) {
@@ -335,12 +348,19 @@ export function MiniCalendar({
 
   const firstOfMonth = new Date(view.year, view.month, 1);
   const lastOfMonth = new Date(view.year, view.month + 1, 0);
-  // Leading blanks up to the first of the month, counted from the week's first day.
+  // Leading blanks up to the first of the month, counted from the week's first day —
+  // or the previous month's last days, with `showOutsideDays` (and the next month's
+  // first ones at the end). `new Date(y, m, 0)` is the day before the 1st, so the
+  // offsets below roll into the neighbouring month by themselves.
   const startWeekday = weekdayIndex(firstOfMonth, weekStart);
   const cells: (Date | null)[] = [];
-  for (let i = 0; i < startWeekday; i++) cells.push(null);
+  for (let i = 0; i < startWeekday; i++) {
+    cells.push(showOutsideDays ? new Date(view.year, view.month, i - startWeekday + 1) : null);
+  }
   for (let d = 1; d <= lastOfMonth.getDate(); d++) cells.push(new Date(view.year, view.month, d));
-  while (cells.length % 7 !== 0) cells.push(null);
+  for (let extra = 1; cells.length % 7 !== 0; extra++) {
+    cells.push(showOutsideDays ? new Date(view.year, view.month + 1, extra) : null);
+  }
   const weeks: (Date | null)[][] = [];
   for (let i = 0; i < cells.length; i += 7) weeks.push(cells.slice(i, i + 7));
 
@@ -588,6 +608,55 @@ export function MiniCalendar({
               }
               const iso = toLocalIso(d);
               const disabled = isDisabled(d);
+              // A neighbouring month's day (`showOutsideDays`): a muted, selectable
+              // cell outside the tab order — see the prop.
+              if (d.getMonth() !== view.month) {
+                return (
+                  <div
+                    key={di}
+                    role="none"
+                    className={cn(
+                      "relative flex",
+                      lg ? cn("min-w-0", LG_CELL_HEIGHT) : "h-8 items-center justify-center",
+                    )}
+                  >
+                    <button
+                      type="button"
+                      role="gridcell"
+                      data-iso={iso}
+                      data-outside=""
+                      tabIndex={-1}
+                      aria-label={labels.day(formatDay(d))}
+                      aria-selected={!disabled && inRange(d)}
+                      aria-disabled={disabled || undefined}
+                      onClick={() => {
+                        if (disabled) return;
+                        // Focus follows into the month the click moves the grid to:
+                        // this button is gone after the next commit.
+                        pendingFocus.current = iso;
+                        handleClick(d);
+                      }}
+                      onKeyDown={onDayKeyDown}
+                      className={cn(
+                        "text-xs tabular-nums text-[var(--text-placeholder)] transition-colors",
+                        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--brand)]",
+                        disabled ? "cursor-not-allowed opacity-60" : "hover:bg-[var(--bg-hover)]",
+                        lg
+                          ? cn("flex w-full min-w-0 items-start bg-[var(--bg-surface-2)] p-1.5", LG_CELL_HEIGHT)
+                          : "size-8 rounded-full",
+                      )}
+                    >
+                      {lg ? (
+                        <span className="inline-flex size-6 items-center justify-center">
+                          {dayNumber.format(d.getDate())}
+                        </span>
+                      ) : (
+                        dayNumber.format(d.getDate())
+                      )}
+                    </button>
+                  </div>
+                );
+              }
               const isStart = !disabled && fromDate && sameYmd(d, fromDate);
               const isEnd = !disabled && toDate && sameYmd(d, toDate);
               const isToday = sameYmd(d, today);

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

@@ -1,5 +1,7 @@
 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;
@@ -33,7 +35,8 @@ export interface NavPillsProps<T extends string> extends Omit<ComponentPropsWith
   /** 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 `<a>`. The API `Breadcrumbs`, `Chip` and `ListItem` share. */
+  /** 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
@@ -84,6 +87,7 @@ export function NavPills<T extends string>({
   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)}>
@@ -113,8 +117,11 @@ export function NavPills<T extends string>({
               "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}

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: