@eifi1/ui-kit 0.51.7 → 0.52.0

package/src/components/date-field.tsx

@@ -2,7 +2,7 @@
 // the clear button — and the props, label hook and trigger format the two share.
 // Moved out of date-picker.tsx as it was (MOD-9, refactor audit 2026-10); date-picker
 // still exports the one public name here, `DateTriggerAttributes`.
-import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { ComponentPropsWithoutRef, ReactNode, Ref, RefObject } from "react";
 import { Calendar, X } from "lucide-react";
 import { cn } from "../lib/cn";
@@ -19,7 +19,13 @@ import {
 import { splitTriggerAria } from "./trigger-aria";
 import type { TriggerAria } from "./trigger-aria";
 import { FIELD_TRIGGER, FIELD_FLOATING_PAD, FIELD_INVALID } from "./field-base";
-import { assignRef, FieldLabelLine, LABEL_ABOVE_BOX, type FieldHelpProps } from "./field-parts";
+import {
+  assignRef,
+  FieldLabelLine,
+  LABEL_ABOVE_BOX,
+  type DisabledReasonDisplay,
+  type FieldHelpProps,
+} from "./field-parts";
 import { FullBleedDialog } from "./full-bleed-dialog";
 import type { RemLength } from "../hooks/use-breakpoint";
 import type { MiniCalendarProps } from "./mini-calendar";
@@ -50,6 +56,22 @@ export interface DatePickerBaseProps extends Omit<ComponentPropsWithoutRef<"div"
    *  `<UiKitProvider labels>`; kept as a prop because it predates the provider. */
   clearLabel?: string;
   disabled?: boolean;
+  /**
+   * Why the date cannot be changed — {@link Select}'s `disabledReason`, for a picker that
+   * SAVES on change (a report's period kept per user, a filter persisted as it moves).
+   * The trigger stays focusable and `aria-disabled`, the calendar does not open, the ‹ ›
+   * and Today buttons refuse, the clear is not offered, and `onChange` never fires; the
+   * reason is a line under the field at Large and on a touch screen, else in the kit
+   * {@link Tooltip} (`disabledReasonDisplay`), and on the trigger's `aria-describedby`.
+   * Wins over `disabled`.
+   *
+   * 0.52 (refactor audit 2026-10-30, API-3): the date pickers and MonthPicker were the
+   * only value fields with no lock opt-in.
+   */
+  disabledReason?: ReactNode;
+  /** Where the reason shows — {@link Button}'s `disabledReasonDisplay`: a line under the
+   *  field at Large and on a touch screen by default, the tooltip otherwise. */
+  disabledReasonDisplay?: DisabledReasonDisplay;
   /** Required and unanswered — {@link FIELD_INVALID}. See {@link Input}'s `invalid`. */
   invalid?: boolean;
   /**
@@ -185,6 +207,9 @@ export interface DateTriggerAttributes {
   /** The field's required state — `Field required` hands it down with the id pair. */
   "aria-required"?: boolean | "true" | "false";
   disabled?: boolean;
+  /** Locked by the write lock (0.52, `commit` / `disabledReason`): focusable, and the
+   *  click opens nothing. Dress a custom trigger for it as for `disabled`. */
+  "aria-disabled"?: true;
   onClick: () => void;
   className: string;
 }
@@ -235,6 +260,7 @@ function DateFieldTrigger({
   valueId,
   padded,
   disabled,
+  locked,
   invalid,
   required,
   panelId,
@@ -260,6 +286,8 @@ function DateFieldTrigger({
   valueId: string;
   padded: boolean;
   disabled?: boolean;
+  /** The write lock: the focusable kind of disabled (see `disabledReason`). */
+  locked: boolean;
   invalid?: boolean;
   /** `aria-required`, on the trigger with the rest of the field's ARIA. */
   required?: boolean | "true" | "false";
@@ -300,8 +328,15 @@ function DateFieldTrigger({
   const attrs: DateTriggerAttributes = {
     ref: triggerRef,
     type: "button",
-    disabled,
-    onClick: toggle,
+    // The focusable kind of disabled while locked (Button's rule): native `disabled`
+    // would take the field out of the tab order, and the reason with it.
+    disabled: locked ? undefined : disabled,
+    "aria-disabled": locked || undefined,
+    // Locked, the calendar does not open. One open when the lock arrives closes: the
+    // picker moves the field into the reason's frame, which remounts it, as Select's.
+    onClick: () => {
+      if (!locked) toggle();
+    },
     // The name has to carry the VALUE. A bare `aria-label={label}` — which is what
     // this was — replaces the button's text outright, so the one field in the form
     // whose entire job is to show a date announced "Due date" and stopped there,
@@ -335,7 +370,7 @@ function DateFieldTrigger({
       FIELD_TRIGGER,
       "pe-9",
       padded && FIELD_FLOATING_PAD,
-      disabled && "cursor-not-allowed opacity-50",
+      (disabled || locked) && "cursor-not-allowed opacity-50",
       // An `aria-invalid` from a Field spread paints too, as on Input and AmountInput.
       isInvalid && FIELD_INVALID,
     ),
@@ -389,6 +424,7 @@ export function DateField({
   hasValue,
   label,
   disabled,
+  locked = false,
   clearable,
   clearLabel,
   panelLabel,
@@ -416,6 +452,9 @@ export function DateField({
   /** A `FieldHint` for the label line, beside the label. */
   labelHint?: ReactNode;
   disabled?: boolean;
+  /** The write lock is on: the trigger is focusable and opens nothing, no clear. The
+   *  picker draws the reason's frame around the field (or its step row). */
+  locked?: boolean;
   clearable?: boolean;
   /** Already resolved by the picker (prop > provider > English). */
   clearLabel: string;
@@ -435,8 +474,19 @@ export function DateField({
   renderTrigger?: TriggerRenderer;
   children: (close: () => void, frame: PanelFrame) => ReactNode;
 }) {
-  const showClear = Boolean(clearable && hasValue && !disabled);
+  // A clear is a change like any other: not offered while locked.
+  const showClear = Boolean(clearable && hasValue && !disabled && !locked);
   const [aria, wrapperRest] = splitTriggerAria(rest);
+  // The trigger, for the clear to hand the focus to (INP-10, below), beside the picker's
+  // own `ref`.
+  const triggerEl = useRef<HTMLButtonElement | null>(null);
+  const toTrigger = useCallback(
+    (node: HTMLButtonElement | null) => {
+      triggerEl.current = node;
+      assignRef(fieldRef, node);
+    },
+    [fieldRef],
+  );
   // The panel is portalled to <body> and leaves the subtree whose `dir` it inherited,
   // so a calendar in an RTL form opened LTR — the grid's columns, its arrow keys and
   // its chevrons all the wrong way round. Read at the moment of opening (the only way
@@ -524,10 +574,11 @@ export function DateField({
       valueId={valueId}
       padded={label !== undefined}
       disabled={disabled}
+      locked={locked}
       invalid={invalid}
       required={ariaRequired}
       renderTrigger={renderTrigger}
-      fieldRef={fieldRef}
+      fieldRef={toTrigger}
     />
   );
   return (
@@ -573,7 +624,13 @@ export function DateField({
         <button
           type="button"
           aria-label={clearLabel}
-          onClick={onClear}
+          onClick={() => {
+            onClear();
+            // The × goes with the value, so a keyboard clear left the focus on a button
+            // that was about to unmount — and it fell to <body> (refactor audit
+            // 2026-10-30, INP-10). The trigger, as SearchField's clear does.
+            triggerEl.current?.focus();
+          }}
           className="absolute end-1.5 top-1/2 -translate-y-1/2 rounded p-1 text-placeholder hover:text-secondary"
         >
           <X className="size-4" />

package/src/components/date-picker.tsx

@@ -1,12 +1,13 @@
-import type { ComponentType } from "react";
+import type { ComponentType, ReactNode } from "react";
 import { CalendarClock, ChevronLeft, ChevronRight } from "lucide-react";
 import { cn } from "../lib/cn";
 import { addDaysIso } from "../lib/dates";
 import { useKitLocale } from "../i18n/kit-labels";
 import { splitTriggerAria } from "./trigger-aria";
 import { FIELD_BASE } from "./field-base";
-import { FieldBox, useFieldMessages } from "./field-parts";
+import { FieldBox, LockedReason, useFieldMessages, useLockReason } from "./field-parts";
 import { Tooltip } from "./tooltip";
+import type { CommitScope } from "./write-lock";
 import { DateField, useDatePickerLabels, useTriggerFormat, withEndHint, type DatePickerBaseProps } from "./date-field";
 import { PanelCalendar } from "./jump-calendar";
 // The shared field, the month-jump calendar and the range picker live in date-field.tsx,
@@ -61,18 +62,34 @@ const STEP_ROW_STACK_AT_LARGE = cn(
 // (`[&_button:focus]:ring-1 [&_button:focus]:ring-inset` on the row) also reached the
 // label's "?" and thinned its 2px focus frame to 1.
 
-/** One ‹ / › day-step button, sized to sit flush beside the field. */
+/**
+ * One ‹ / › day-step (or today) button, sized to sit flush beside the field.
+ *
+ * Two kinds of "cannot" (refactor audit 2026-10-30, INP-4). `off` is natively `disabled`,
+ * out of the tab order: the field is `disabled`, or empty with nothing to step from — no
+ * press of these buttons gets there, so the focus is never on one as it turns. `refused`
+ * is `aria-disabled` with a click that does nothing, JumpCalendar's rule: › pressed onto
+ * `max`, ‹ onto `min` and Today onto today are refused by the very press the focus is on,
+ * and a focused button that turns `disabled` drops the focus to <body>, mid-form
+ * (keksdose's shared date field passes `step` and `today` in 14 files). A lock refuses
+ * too, and the lock's reason describes the button.
+ */
 function StepButton({
   icon: Icon,
   label,
-  disabled,
+  off,
+  refused,
+  reasonId,
   onClick,
   mirror,
   className,
 }: {
   icon: ComponentType<{ className?: string }>;
   label: string;
-  disabled: boolean;
+  off: boolean;
+  refused: boolean;
+  /** While locked: the id of the lock's reason, which the row's frame shows. */
+  reasonId?: string;
   onClick: () => void;
   /** Flip the icon in RTL — for the ‹ › day steps, whose "previous" points to the
    *  reading start. Not for the today icon, which has no direction. */
@@ -80,29 +97,42 @@ function StepButton({
   /** The button's corners in the joined group (see DatePicker). */
   className?: string;
 }) {
+  const button = (
+    <button
+      type="button"
+      aria-label={label}
+      disabled={off}
+      aria-disabled={(!off && refused) || undefined}
+      aria-describedby={reasonId}
+      onClick={() => {
+        if (!refused) onClick();
+      }}
+      className={cn(
+        FIELD_BASE,
+        // FIELD_BASE is `block w-full` for text inputs; a step button is neither, and
+        // px-3 would make it wider than it needs to be. twMerge lets these win.
+        "relative flex h-full w-10 shrink-0 items-center justify-center px-0 text-muted",
+        "hover:bg-hover hover:text-secondary",
+        // Dimmed ICON, not a dimmed box: at 40% opacity the whole button — border
+        // included — faded out of the group and read as a broken, detached control. The
+        // same look for the focusable kind (INP-4).
+        "disabled:cursor-not-allowed disabled:text-placeholder disabled:opacity-60 disabled:hover:bg-surface",
+        "aria-disabled:cursor-not-allowed aria-disabled:text-placeholder aria-disabled:opacity-60 aria-disabled:hover:bg-surface",
+        // A part of a joined row: FIELD_BASE's 2px focus line, whole at 125 % (K5, the
+        // note above this function).
+        className,
+      )}
+    >
+      <Icon className={cn("size-4", mirror && "rtl:-scale-x-100")} />
+    </button>
+  );
+  // Locked, the row's frame holds the reason's bubble; a name bubble of its own as well
+  // would be two on one hover (IconButton drops its own the same way). The wrapper stays
+  // — STEP_ROW_STACK_AT_LARGE lays the buttons out by it.
+  if (reasonId) return <span className="relative inline-flex">{button}</span>;
   return (
     <Tooltip label={label} portal>
-      <button
-        type="button"
-        aria-label={label}
-        disabled={disabled}
-        onClick={onClick}
-        className={cn(
-          FIELD_BASE,
-          // FIELD_BASE is `block w-full` for text inputs; a step button is neither, and
-          // px-3 would make it wider than it needs to be. twMerge lets these win.
-          "relative flex h-full w-10 shrink-0 items-center justify-center px-0 text-muted",
-          "hover:bg-hover hover:text-secondary",
-          // Dimmed ICON, not a dimmed box: at 40% opacity the whole button — border
-          // included — faded out of the group and read as a broken, detached control.
-          "disabled:cursor-not-allowed disabled:text-placeholder disabled:opacity-60 disabled:hover:bg-surface",
-          // A part of a joined row: FIELD_BASE's 2px focus line, whole at 125 % (K5, the
-          // note above this function).
-          className,
-        )}
-      >
-        <Icon className={cn("size-4", mirror && "rtl:-scale-x-100")} />
-      </button>
+      {button}
     </Tooltip>
   );
 }
@@ -114,7 +144,8 @@ export interface DatePickerProps extends DatePickerBaseProps {
   /**
    * Flank the field with ‹ › buttons that move the value one day. For fields whose
    * typical edit is a day or two — opening a calendar to go "yesterday" is three
-   * interactions for what should be one.
+   * interactions for what should be one. A button whose day is outside `min` / `max` is
+   * refused (`aria-disabled`, still focusable — 0.52); with no value both are disabled.
    *
    * Off by default: on a filter or a far-away date the buttons are dead weight, and
    * they cost ~5rem of width that a narrow layout may not have.
@@ -127,7 +158,9 @@ export interface DatePickerProps extends DatePickerBaseProps {
   stepLabels?: { prev: string; next: string };
   /**
    * Today's date as ISO "YYYY-MM-DD". Adds a jump-to-today button beside the field,
-   * disabled once the value already is that day.
+   * refused once the value already is that day — `aria-disabled`, so the focus stays on
+   * the button that was just pressed (0.52) — and disabled while that day is outside
+   * `min` / `max`.
    *
    * Passed in rather than read from a clock here: a component that decides what "today"
    * is cannot be tested at a fixed date, and the consumer already has one definition of
@@ -138,6 +171,15 @@ export interface DatePickerProps extends DatePickerBaseProps {
   today?: string;
   /** Accessible name for the today button; wins over `datePicker.today`. */
   todayLabel?: string;
+  /**
+   * This picker COMMITS — picking a date saves it (a row's date edited in place, a
+   * filter kept as it moves). Under a locked {@link WriteLockProvider} it is locked the
+   * `disabledReason` way, with the lock's reason; a {@link CommitScope}, as on every kit
+   * control. A date field inside a form with its own Save stays editable under the lock —
+   * leave this off there, and put `commit` on the Save. 0.52 (refactor audit 2026-10-30,
+   * API-3).
+   */
+  commit?: CommitScope;
 }
 
 /** Single-date picker: a field showing the formatted date, opening a calendar. */
@@ -162,6 +204,9 @@ export function DatePicker(props: DatePickerProps) {
     clearable,
     clearLabel,
     disabled,
+    disabledReason,
+    disabledReasonDisplay,
+    commit,
     invalid,
     hint,
     help,
@@ -176,8 +221,15 @@ export function DatePicker(props: DatePickerProps) {
   const locale = useKitLocale(localeProp);
   const text = useDatePickerLabels(clearLabel, stepLabels, todayLabel);
   const render = useTriggerFormat("datePicker", locale, formatOptions, formatValue);
+  // The write lock (API-3): Select's — the trigger stays reachable and says why.
+  const lock = useLockReason(commit, disabledReason);
+  const locked = lock.locked;
+  const change = (iso: string) => {
+    if (!locked) onChange(iso);
+  };
   // keksdose K4: the caption and the error under the field, attached to the TRIGGER
-  // (the element a screen reader is on) after any description of the caller's own.
+  // (the element a screen reader is on) after any description of the caller's own; a
+  // lock's reason between the two, as on Select.
   const messages = useFieldMessages({
     hint,
     help,
@@ -186,6 +238,7 @@ export function DatePicker(props: DatePickerProps) {
     invalid,
     describedBy: rest["aria-describedby"],
     ariaInvalid: rest["aria-invalid"],
+    reasonId: locked && lock.reasonId,
   });
   // With a step or a today button beside it the field is no longer the outermost
   // element — the flex row at the bottom is, and a caller's attributes belong on
@@ -207,14 +260,18 @@ export function DatePicker(props: DatePickerProps) {
       clearLabel={text.clear}
       panelLabel={text.panel}
       disabled={disabled}
+      locked={locked}
       invalid={messages.isInvalid}
-      className={step ? "min-w-0 flex-1" : className}
+      // In the row, the field fills what the buttons leave and the caller's classes are
+      // the row's — with `today` alone too: dressed on `step` alone, a today-only row put
+      // them on both (refactor audit 2026-10-30, INP-13). Locked, they are the frame's.
+      className={wrapped ? "min-w-0 flex-1" : locked ? undefined : className}
       // Named for STEP_ROW_STACK_AT_LARGE; only in the row, so a caller's own
       // `data-slot` on a bare field is left alone.
       {...(wrapped ? { "data-slot": "date-step-field" } : {})}
       hasValue={Boolean(value)}
       triggerText={value ? render(value) : (placeholder ?? "")}
-      onClear={() => onChange("")}
+      onClear={() => change("")}
     >
       {(close) => (
         <PanelCalendar
@@ -228,7 +285,7 @@ export function DatePicker(props: DatePickerProps) {
           max={max}
           labels={calendarLabels}
           onSelect={(iso) => {
-            onChange(iso);
+            change(iso);
             close();
           }}
         />
@@ -238,23 +295,32 @@ export function DatePicker(props: DatePickerProps) {
   // Passed at all — even as `undefined` — the field keeps its box; see FieldBox.
   const reserve = "error" in props || "hint" in props;
   const endHint = label === undefined ? messages.labelHint : undefined;
+  // Locked, the field — or the whole row, whose buttons change the value too — sits in
+  // the reason's frame (the line, or the Tooltip), which becomes the outermost box: the
+  // caller's classes move onto it, as on Select, so a lock does not reflow the form.
+  const withReason = (box: ReactNode) =>
+    locked ? (
+      <LockedReason lock={lock} display={disabledReasonDisplay} className={cn("block", className)}>
+        {box}
+      </LockedReason>
+    ) : (
+      box
+    );
   if (!wrapped) {
     return (
       <FieldBox below={messages.below} reserve={reserve}>
-        {withEndHint(field, endHint)}
+        {withReason(withEndHint(field, endHint))}
       </FieldBox>
     );
   }
 
-  // An empty field has nothing to step from, so both buttons are dead until a date
-  // is picked. Bounds are compared as strings: "YYYY-MM-DD" sorts chronologically.
+  // An empty field has nothing to step from, so both buttons are off until a date is
+  // picked. Bounds are compared as strings: "YYYY-MM-DD" sorts chronologically.
   const target = (days: number) => (value ? addDaysIso(value, days) : "");
   const outOfBounds = (iso: string) => Boolean((min && iso < min) || (max && iso > max));
-  const blocked = (days: number) => {
-    const next = target(days);
-    if (!next || disabled) return true;
-    return outOfBounds(next);
-  };
+  // A lock's reason wins over `disabled`, as on Select: the buttons stay focusable then.
+  const fieldOff = Boolean(disabled) && !locked;
+  const reasonId = locked ? lock.reasonId : undefined;
   const row = (
     // ONE joined control, not three boxes in a row: the buttons and the field share
     // their borders (each piece overlaps the previous by a pixel) and only the outer
@@ -283,7 +349,7 @@ export function DatePicker(props: DatePickerProps) {
         // …and its line is 2px, so no side of it reads half-strength at 125 % (live #394,
         // fourth round): FIELD_BASE's inset ring, which every part of the row carries.
         STEP_ROW_STACK_AT_LARGE,
-        className,
+        !locked && className,
       )}
     >
       {step && (
@@ -291,8 +357,10 @@ export function DatePicker(props: DatePickerProps) {
           icon={ChevronLeft}
           mirror
           label={text.previousDay}
-          disabled={blocked(-1)}
-          onClick={() => onChange(target(-1))}
+          off={fieldOff || !value}
+          refused={locked || outOfBounds(target(-1))}
+          reasonId={reasonId}
+          onClick={() => change(target(-1))}
           className="rounded-e-none"
         />
       )}
@@ -302,17 +370,26 @@ export function DatePicker(props: DatePickerProps) {
           icon={ChevronRight}
           mirror
           label={text.nextDay}
-          disabled={blocked(1)}
-          onClick={() => onChange(target(1))}
+          off={fieldOff || !value}
+          refused={locked || outOfBounds(target(1))}
+          reasonId={reasonId}
+          onClick={() => change(target(1))}
           className={cn("rounded-s-none", today && "rounded-e-none")}
         />
       )}
       {today && (
+        // Refused once the value is today: pressable as a no-op would keep the focus too
+        // (INP-4), and this also says there is nothing to jump to. Today outside the
+        // bounds is `off`: no press here gets there, as MonthPicker's stepper has it — it
+        // was refused, a tab stop that could never do anything (0.52 code review,
+        // date-picker.tsx). A lock wins, focusable, to say why.
         <StepButton
           icon={CalendarClock}
           label={text.today}
-          disabled={Boolean(disabled) || value === today || outOfBounds(today)}
-          onClick={() => onChange(today)}
+          off={fieldOff || (!locked && outOfBounds(today))}
+          refused={locked || value === today}
+          reasonId={reasonId}
+          onClick={() => change(today)}
           className="rounded-s-none"
         />
       )}
@@ -322,7 +399,7 @@ export function DatePicker(props: DatePickerProps) {
   // the date, and the steppers are part of how it is entered.
   return (
     <FieldBox below={messages.below} reserve={reserve}>
-      {withEndHint(row, endHint)}
+      {withReason(withEndHint(row, endHint))}
     </FieldBox>
   );
 }