@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/DatePicker/DatePicker.tsx

@@ -2,16 +2,86 @@ import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss,
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { Calendar as CalendarIcon, X } from "lucide-react";
-import type * as React from "react";
-import { useCallback, useId, useState } from "react";
-import { isPlainDate, type Temporal, today } from "../../date-time";
-import { Calendar } from "../Calendar";
+import * as React from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
+import {
+  adaptDisabledDates,
+  fromISODate,
+  fromISODateOrUndefined,
+  fromISODateRange,
+  type ISODate,
+  type ISODateRange,
+  isPlainDate,
+  type Temporal,
+  today,
+  toISODate,
+  toISODateOrUndefined,
+  toISODateRange,
+} from "../../date-time";
+import { PickerField } from "../../internal";
+import { CalendarView } from "../Calendar/CalendarView";
+import { isDateDisabled } from "../Calendar/calendar.hooks";
+import type { PresetOption } from "../Calendar/calendar.types";
+import { DateSegments } from "./DateSegments";
 import { defaultFormatDisplay, getDisplayValue, temporalToISO } from "./datepicker.hooks";
 import type { DatePickerProps, DateRangeValue } from "./datepicker.types";
 
 export type { DatePickerProps };
 
-export const DatePicker = (props: DatePickerProps) => {
+/** The Temporal-shaped value the picker holds internally, across all modes. */
+type InternalValue = Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined;
+
+/** Widen a public, mode-appropriate ISO value to {@link InternalValue}. */
+function toTemporal(mode: DatePickerProps["mode"], value: ISODate | ISODateRange | ISODate[] | undefined): InternalValue {
+  if (mode === "multiple") return ((value as ISODate[] | undefined) ?? []).map(fromISODate);
+  if (mode === "range") return fromISODateRange(value as ISODateRange | undefined);
+  return fromISODateOrUndefined(value as ISODate | undefined);
+}
+
+/**
+ * A typeable date field and a `Calendar` popover, as one control. `mode`
+ * (`"single" | "range" | "multiple"`, default `"single"`) decides the shape of
+ * `value`/`defaultValue`/`onChange`: an `ISODate` string, an `ISODateRange`
+ * (`{ from?, to? }`), or an `ISODate[]`.
+ *
+ * In `single` mode the field is three `role="spinbutton"` segments rather than a
+ * text box. It is built to be typed straight through: `152026` is January the
+ * 5th 2026, because a digit that cannot extend the segment being typed rolls
+ * into the next one instead of restarting it. Separators (`/`, `-`, `.`) say
+ * done-with-this-one, arrows step a segment, `Backspace` takes back one digit
+ * (then clears, then steps back), `Alt+ArrowDown` opens the grid and moves focus
+ * there, and a paste fills all three. Segments rather than free
+ * text because `08/09` cannot be read without knowing the order: `segmentOrder`
+ * (default `mdy`) says which, the labels say it to a screen reader, and no
+ * parser has to guess. `range` and `multiple` keep the read-only text trigger —
+ * a list of dates has no sensible typed form.
+ *
+ * Typing and picking move one value. The segments show the draft while the
+ * popover is open and the committed value while it is closed, so typing a date
+ * moves the grid to it and picking a day shows up in the segments. The commit
+ * contract stays single: while the popover is open its Apply/Cancel owns the
+ * value (`Enter` in a segment is Apply); while it is closed, a date commits as
+ * soon as all three segments describe one. A partial date is never reported —
+ * clearing a segment reports `undefined`.
+ *
+ * Supports both controlled (`value`/`onChange`) and uncontrolled
+ * (`defaultValue`) use. Opening the popover seeds a draft from the committed
+ * value; picking a date only updates the draft; the footer's Apply commits it
+ * and closes, Cancel discards it and reverts to the last committed value. The
+ * clear button (hidden when `clearable={false}`) bypasses the draft and
+ * commits immediately.
+ *
+ * `minDate`/`maxDate` bound selectable dates inclusively; `disabled` accepts a
+ * single date, a list, or a declarative matcher (before/after/range/weekday)
+ * or predicate — see `DisabledDates`. `presets` renders a sidebar of quick
+ * picks whose values must match `mode`. When `name` is set, the committed
+ * value is mirrored into hidden `<input>`s for native form submission
+ * (`name.from`/`name.to` in range mode, `name[]` per entry in multiple mode).
+ *
+ * Keyboard interaction — arrow keys/Home/End/PageUp/PageDown on the day
+ * grid — is inherited from `Calendar`.
+ */
+export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((props, ref) => {
   const {
     mode = "single",
     weekStartsOn = 0,
@@ -26,6 +96,7 @@ export const DatePicker = (props: DatePickerProps) => {
     className,
     align = "end",
     clearable = true,
+    segmentOrder = "mdy",
   } = props;
 
   // Get mode-specific props
@@ -36,12 +107,66 @@ export const DatePicker = (props: DatePickerProps) => {
 
   // Open state
   const [open, setOpen] = useState(false);
+  // Whether the day grid should take focus when the popover mounts — true only
+  // when the popover was opened from the keyboard. See `openWithGridFocus`.
+  const [autoFocusDay, setAutoFocusDay] = useState(false);
+
+  // ---------------------------------------------------------------------------
+  // The ISO boundary.
+  //
+  // Props arrive as canonical ISO strings and callbacks emit them; everything
+  // below this block — state, the calendar grid, display formatting — works in
+  // Temporal, exactly as before.
+  //
+  // Each conversion is memoised on the string it derives from. Temporal values
+  // have no value identity, so converting unmemoised would hand CalendarView a
+  // fresh object every render and invalidate its grid memos. Strings compare by
+  // value, which makes this strictly more stable than passing Temporal in.
+  // ---------------------------------------------------------------------------
+
+  const temporalMinDate = useMemo(() => fromISODateOrUndefined(minDate), [minDate]);
+  const temporalMaxDate = useMemo(() => fromISODateOrUndefined(maxDate), [maxDate]);
+  const temporalDisabled = useMemo(() => adaptDisabledDates(disabled), [disabled]);
+
+  const temporalPresets = useMemo(() => {
+    if (!presets) return undefined;
+    if (mode === "single") {
+      return (presets as PresetOption<ISODate>[]).map((preset) => ({ label: preset.label, value: fromISODate(preset.value) }));
+    }
+    if (mode === "multiple") {
+      return (presets as PresetOption<ISODate[]>[]).map((preset) => ({ label: preset.label, value: preset.value.map(fromISODate) }));
+    }
+    return (presets as PresetOption<ISODateRange>[]).map((preset) => ({
+      label: preset.label,
+      value: fromISODateRange(preset.value) ?? { from: undefined, to: undefined },
+    }));
+  }, [mode, presets]);
+
+  const temporalValue = useMemo(() => toTemporal(mode, value), [mode, value]);
+  // Read once, on mount, by useControllableState's useState initialiser.
+  const temporalDefaultValue = useMemo(() => toTemporal(mode, defaultValue), [mode, defaultValue]);
+
+  const handleChange = useCallback(
+    (next: InternalValue) => {
+      if (!onChange) return;
+      if (mode === "single") {
+        (onChange as (date: ISODate | undefined) => void)(toISODateOrUndefined(next as Temporal.PlainDate | undefined));
+        return;
+      }
+      if (mode === "multiple") {
+        (onChange as (dates: ISODate[]) => void)(((next as Temporal.PlainDate[] | undefined) ?? []).map(toISODate));
+        return;
+      }
+      (onChange as (range: ISODateRange | undefined) => void)(toISODateRange(next as DateRangeValue | undefined));
+    },
+    [mode, onChange]
+  );
 
   // Controllable value state (external/committed value)
-  const [committedValue, setCommittedValue] = useControllableState({
-    value: value as Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined,
-    defaultValue: defaultValue as Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined,
-    onChange: onChange as ((value: Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined) => void) | undefined,
+  const [committedValue, setCommittedValue] = useControllableState<InternalValue>({
+    value: temporalValue,
+    defaultValue: temporalDefaultValue,
+    onChange: handleChange,
   });
 
   // Draft value (internal state while popup is open)
@@ -52,6 +177,8 @@ export const DatePicker = (props: DatePickerProps) => {
     (newOpen: boolean) => {
       if (newOpen) {
         setDraftValue(committedValue);
+      } else {
+        setAutoFocusDay(false);
       }
       setOpen(newOpen);
     },
@@ -144,35 +271,233 @@ export const DatePicker = (props: DatePickerProps) => {
 
   const rangeFormValues = getRangeFormValues();
 
+  // ---------------------------------------------------------------------------
+  // The typeable field (single mode).
+  //
+  // One value, two ways to move it. The segments show the draft while the
+  // popover is open and the committed value while it is closed, which is what
+  // makes typing and clicking feel like one control: type a date and the grid
+  // follows it, click a day and the segments follow that. The commit contract
+  // stays single — open means the popover's Apply/Cancel owns it, closed means a
+  // complete date commits as soon as it is complete.
+  // ---------------------------------------------------------------------------
+
+  const segmentSource = open ? draftValue : committedValue;
+  const segmentValue = isPlainDate(segmentSource) ? segmentSource : undefined;
+
+  /**
+   * A typed date can be one the grid would refuse — nothing stops you typing
+   * past `maxDate`. Rather than silently clamping it (which loses what was
+   * typed) or refusing it (which strands the field mid-edit), the field says so:
+   * `aria-invalid` and the danger border, with the value still reported so the
+   * caller's own validation sees the attempt.
+   */
+  const outOfBounds = useCallback(
+    (date: Temporal.PlainDate | undefined) => date !== undefined && isDateDisabled(date, temporalDisabled, temporalMinDate, temporalMaxDate),
+    [temporalDisabled, temporalMaxDate, temporalMinDate]
+  );
+
+  const handleSegmentsChange = useCallback(
+    (date: Temporal.PlainDate | undefined) => {
+      // Keep the grid on the month being typed, so opening it lands where the
+      // user already is rather than on today.
+      if (date) setMonth(date);
+      if (open) {
+        setDraftValue(date);
+        return;
+      }
+      setCommittedValue(date as Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[]);
+    },
+    [open, setCommittedValue]
+  );
+
+  /** `Alt+ArrowDown` from a segment: open the grid *and* go there. */
+  const openWithGridFocus = useCallback(() => {
+    setAutoFocusDay(true);
+    handleOpenChange(true);
+  }, [handleOpenChange]);
+
+  /** `Enter` in a segment commits the draft, matching the popover's Apply. */
+  const handleFieldSubmit = useCallback(() => {
+    if (open) handleApply();
+  }, [handleApply, open]);
+
+  // ---------------------------------------------------------------------------
+  // Range mode: two fields, not one.
+  //
+  // A range is two dates, and typing one of them should not require knowing
+  // where the other ends. Each half is its own segmented field with its own
+  // clear button; they share the one popover, which anchors to whichever half
+  // you are in so it opens under the date you are editing.
+  // ---------------------------------------------------------------------------
+
+  const rangeSource = (open ? draftValue : committedValue) as DateRangeValue | undefined;
+
+  const setRangeEnd = useCallback(
+    (end: "from" | "to", date: Temporal.PlainDate | undefined) => {
+      if (date) setMonth(date);
+      const current = (open ? draftValue : committedValue) as DateRangeValue | undefined;
+      const next: DateRangeValue = { from: current?.from, to: current?.to, [end]: date };
+      if (open) {
+        setDraftValue(next);
+        return;
+      }
+      setCommittedValue(next as Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[]);
+    },
+    [committedValue, draftValue, open, setCommittedValue]
+  );
+
+  const clearRangeEnd = useCallback(
+    (end: "from" | "to") => (event: React.MouseEvent) => {
+      event.stopPropagation();
+      event.preventDefault();
+      const existing = committedValue as DateRangeValue | undefined;
+      const next: DateRangeValue = {
+        from: end === "from" ? undefined : existing?.from,
+        to: end === "to" ? undefined : existing?.to,
+      };
+      // Clearing the last remaining end clears the range itself, so a consumer
+      // gets `undefined` rather than a husk with two empty ends.
+      const cleared = !next.from && !next.to;
+      setCommittedValue((cleared ? undefined : next) as Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[]);
+    },
+    [committedValue, setCommittedValue]
+  );
+
+  // The popover anchors to the half being edited, so it opens under the date in
+  // question rather than under the middle of a wide trigger.
+  const rangeHalves = useRef<Record<"from" | "to", HTMLDivElement | null>>({ from: null, to: null });
+  const anchorToHalf = useCallback(
+    (end: "from" | "to") => {
+      const node = rangeHalves.current[end];
+      if (node) refs.setPositionReference(node);
+    },
+    [refs]
+  );
+
+  /**
+   * One end of the range. A render function rather than a component so the
+   * fields are not remounted — and so focus is not dropped — on every keystroke.
+   */
+  const renderRangeHalf = (end: "from" | "to", label: string) => {
+    const shown = end === "from" ? rangeSource?.from : rangeSource?.to;
+    const settled = end === "from" ? (committedValue as DateRangeValue | undefined)?.from : (committedValue as DateRangeValue | undefined)?.to;
+
+    return (
+      <PickerField
+        ref={(node) => {
+          rangeHalves.current[end] = node;
+        }}
+        onFocusCapture={() => anchorToHalf(end)}
+        className="min-w-45 flex-1"
+        icon={<CalendarIcon className="h-4 w-4" />}
+        toggleLabel={`Open calendar for ${label.toLowerCase()}`}
+        // Both handlers have to run: Floating UI's opens the popover, and ours
+        // points it at this half. Spreading after `onClick` would drop ours on
+        // the floor, which is how the popover ended up anchored to the whole
+        // trigger.
+        toggleProps={getReferenceProps({ onClick: () => anchorToHalf(end) })}
+        isOpen={open}
+        contentId={contentId}
+        isDisabled={isDisabled}
+        isInvalid={isInvalid || outOfBounds(shown)}
+        onClear={clearable && settled && !isDisabled ? clearRangeEnd(end) : undefined}
+        clearLabel={`Clear ${label.toLowerCase()}`}
+      >
+        <DateSegments
+          className="h-full flex-1"
+          label={label}
+          value={shown}
+          onChange={(date) => setRangeEnd(end, date)}
+          order={segmentOrder}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid || outOfBounds(shown)}
+          onOpenRequest={() => {
+            anchorToHalf(end);
+            openWithGridFocus();
+          }}
+          onSubmit={handleFieldSubmit}
+        />
+      </PickerField>
+    );
+  };
+
   return (
     <>
       {/* Trigger Input */}
-      <div className={cn("relative flex items-center", mode === "range" && "min-w-91.25", mode !== "range" && "min-w-65")}>
-        <CalendarIcon className="pointer-events-none absolute left-3 h-4 w-4 text-fg-subtle" />
-        <input
-          ref={refs.setReference as React.Ref<HTMLInputElement>}
-          id={inputId}
-          type="text"
-          readOnly
-          value={displayValue}
-          placeholder={placeholder}
-          disabled={isDisabled}
-          role="combobox"
-          aria-invalid={isInvalid}
-          aria-haspopup="dialog"
-          aria-expanded={open}
-          aria-controls={open ? contentId : undefined}
-          className={cn(
-            `flex h-9 w-full cursor-pointer rounded-md border border-border-normal bg-transparent py-1 pl-9 text-sm shadow-xs transition-colors placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
-            mode === "range" && "min-w-91.25",
-            mode !== "range" && "min-w-65",
-            clearable && hasValue ? "pr-9" : "pr-3",
-            isInvalid && "border-border-danger",
-            className
-          )}
-          {...getReferenceProps()}
-        />
-        {clearable && hasValue && !isDisabled && (
+      <div
+        ref={(node) => {
+          // The container is the interaction reference, so a click in either
+          // range half counts as inside; range mode then re-points the
+          // *position* reference at the half being edited.
+          refs.setReference(node);
+          if (typeof ref === "function") ref(node);
+          else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+        }}
+        className={cn("relative flex items-center gap-2", mode === "range" && "min-w-91.25", mode !== "range" && "min-w-65")}
+      >
+        {mode === "range" ? (
+          <>
+            {renderRangeHalf("from", "Start date")}
+            <span aria-hidden="true" className="text-fg-subtle">
+              –
+            </span>
+            {renderRangeHalf("to", "End date")}
+          </>
+        ) : mode === "single" ? (
+          <PickerField
+            className={cn("w-full min-w-65", className)}
+            icon={<CalendarIcon className="h-4 w-4" />}
+            toggleLabel="Open calendar"
+            toggleProps={getReferenceProps()}
+            isOpen={open}
+            contentId={contentId}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid || outOfBounds(segmentValue)}
+            onClear={clearable && hasValue && !isDisabled ? handleClear : undefined}
+            clearLabel="Clear date"
+          >
+            <DateSegments
+              className="h-full flex-1"
+              id={inputId}
+              value={segmentValue}
+              onChange={handleSegmentsChange}
+              order={segmentOrder}
+              isDisabled={isDisabled}
+              isInvalid={isInvalid || outOfBounds(segmentValue)}
+              onOpenRequest={openWithGridFocus}
+              onSubmit={handleFieldSubmit}
+            />
+          </PickerField>
+        ) : (
+          <>
+            <CalendarIcon className="pointer-events-none absolute left-3 h-4 w-4 text-fg-subtle" />
+            <input
+              id={inputId}
+              type="text"
+              readOnly
+              value={displayValue}
+              placeholder={placeholder}
+              disabled={isDisabled}
+              role="combobox"
+              aria-invalid={isInvalid}
+              aria-haspopup="dialog"
+              aria-expanded={open}
+              aria-controls={open ? contentId : undefined}
+              className={cn(
+                `flex h-9 w-full cursor-pointer rounded-md border border-border-normal bg-transparent py-1 pl-9 text-sm shadow-xs transition-colors placeholder:text-fg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring disabled:cursor-not-allowed disabled:opacity-50`,
+                "min-w-65",
+                clearable && hasValue ? "pr-9" : "pr-3",
+                isInvalid && "border-border-danger",
+                className
+              )}
+              {...getReferenceProps()}
+            />
+          </>
+        )}
+        {/* `multiple` mode still uses the read-only input, so its clear button
+            stays here; the other two modes get theirs from `PickerField`. */}
+        {clearable && hasValue && !isDisabled && mode === "multiple" && (
           <button
             type="button"
             onClick={handleClear}
@@ -205,27 +530,28 @@ export const DatePicker = (props: DatePickerProps) => {
             ref={refs.setFloating}
             id={contentId}
             role="dialog"
-            aria-modal="true"
+            aria-label="Choose date"
             style={floatingStyles}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
           >
             {/* @ts-expect-error - TypeScript can't properly narrow discriminated union props across component boundaries */}
-            <Calendar
+            <CalendarView
               mode={mode}
               value={draftValue}
               onSelect={setDraftValue}
               month={month}
               onMonthChange={setMonth}
-              minDate={minDate}
-              maxDate={maxDate}
-              disabled={disabled}
+              minDate={temporalMinDate}
+              maxDate={temporalMaxDate}
+              disabled={temporalDisabled}
               weekStartsOn={weekStartsOn}
-              presets={presets}
+              presets={temporalPresets}
               showFooter
               showToday={mode !== "range"}
               onApply={handleApply}
               onCancel={handleCancel}
+              autoFocusDay={autoFocusDay}
               {...(mode === "multiple" && max ? { max } : {})}
             />
           </div>
@@ -233,4 +559,5 @@ export const DatePicker = (props: DatePickerProps) => {
       )}
     </>
   );
-};
+});
+DatePicker.displayName = "DatePicker";

package/src/components/DatePicker/DateSegments.tsx

@@ -0,0 +1,125 @@
+import { type Temporal, today, toISODate } from "../../date-time";
+import { SegmentedField, type SegmentSpec, type SegmentValues } from "../../internal";
+import type { DateSegmentOrder } from "./datepicker.types";
+
+type SegmentName = "day" | "month" | "year";
+
+export type DateSegmentsProps = {
+  /** The date the segments display. `undefined` leaves them empty. */
+  value: Temporal.PlainDate | undefined;
+  /**
+   * Fires with a complete date, or `undefined` the moment the segments stop
+   * describing one. Never fires a partial date.
+   */
+  onChange: (date: Temporal.PlainDate | undefined) => void;
+  order?: DateSegmentOrder | undefined;
+  isDisabled?: boolean | undefined;
+  isInvalid?: boolean | undefined;
+  /** Accessible name for the segment group. */
+  label?: string | undefined;
+  /** `Alt+ArrowDown` — the combobox convention for "open the popup". */
+  onOpenRequest?: (() => void) | undefined;
+  /** `Enter` — the caller decides whether that means commit, submit or nothing. */
+  onSubmit?: (() => void) | undefined;
+  id?: string | undefined;
+  className?: string | undefined;
+};
+
+export const DATE_ORDERS: Record<DateSegmentOrder, SegmentName[]> = {
+  mdy: ["month", "day", "year"],
+  dmy: ["day", "month", "year"],
+  ymd: ["year", "month", "day"],
+};
+
+const BASE: Record<SegmentName, Omit<Extract<SegmentSpec, { kind?: "numeric" }>, "separatorBefore" | "stepFrom">> = {
+  day: { name: "day", label: "Day", placeholder: "dd", digits: 2, min: 1, max: 31 },
+  month: { name: "month", label: "Month", placeholder: "mm", digits: 2, min: 1, max: 12 },
+  year: { name: "year", label: "Year", placeholder: "yyyy", digits: 4, min: 1, max: 9999 },
+};
+
+/** Days in a (year, month). `day: 1` keeps `with` from constraining a stale day. */
+const daysInMonth = (year: number, month: number) => today().with({ year, month, day: 1 }).daysInMonth;
+
+export const dateToSegments = (date: Temporal.PlainDate | undefined): SegmentValues =>
+  date ? { day: date.day, month: date.month, year: date.year } : { day: null, month: null, year: null };
+
+/**
+ * The day is clamped rather than rejected: typing `31` and then moving the month
+ * to February is a normal editing path, and snapping to the 28th keeps the field
+ * describing a date the user can see and correct. Nothing else can be out of
+ * range — the segments cap themselves as they are typed.
+ */
+export const dateFromSegments = (values: Record<string, number>): Temporal.PlainDate => {
+  const year = values.year!;
+  const month = values.month!;
+  return today().with({ year, month, day: Math.min(values.day!, daysInMonth(year, month)) });
+};
+
+/**
+ * ISO is always accepted — it is unambiguous, and it is what the rest of the
+ * library speaks. Anything else is read in the field's own segment order, which
+ * is the only reading that cannot be wrong.
+ */
+export function parseDatePasteIn(order: DateSegmentOrder) {
+  return (text: string): SegmentValues | null => {
+    const iso = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+    const parts = iso ? [iso[1]!, iso[2]!, iso[3]!] : text.split(/[/\-.\s]+/);
+    const names = iso ? DATE_ORDERS.ymd : DATE_ORDERS[order];
+    if (parts.length !== 3 || parts.some((part) => !/^\d+$/.test(part))) return null;
+
+    const next: SegmentValues = { day: null, month: null, year: null };
+    names.forEach((name, index) => {
+      const numeric = Number(parts[index]);
+      next[name] = numeric >= BASE[name].min && numeric <= BASE[name].max ? numeric : null;
+    });
+    return next;
+  };
+}
+
+/**
+ * The typeable half of `DatePicker`: a date as three spinbutton segments.
+ *
+ * A thin spec over `SegmentedField`, which owns the keyboard model — digits
+ * rolling forward, separators, digit-aware `Backspace`, deferred `onChange`.
+ * What belongs to dates specifically lives here: the segment order (never
+ * inferred from the locale, because `08/09` is a different date under each),
+ * clamping the day to the month, and accepting a pasted ISO date.
+ *
+ * Internal to `DatePicker`; not exported from `./index.ts`.
+ */
+/**
+ * The three date segments in the given order.
+ *
+ * Exported because `DateTimePicker` builds one field out of these plus the time
+ * segments, rather than two fields glued together.
+ */
+export function dateSpec(order: DateSegmentOrder): SegmentSpec[] {
+  const separator = order === "ymd" ? "-" : "/";
+  const current = dateToSegments(today());
+
+  return DATE_ORDERS[order].map((name, index) => ({
+    ...BASE[name],
+    // An arrow key on an empty segment starts from today, not from 1: the year
+    // is the segment most likely to already be right.
+    stepFrom: current[name] ?? BASE[name].min,
+    separatorBefore: index > 0 ? separator : undefined,
+  }));
+}
+
+export function DateSegments({ value, onChange, order = "mdy", label = "Date", ...rest }: DateSegmentsProps) {
+  const spec = dateSpec(order);
+
+  return (
+    <SegmentedField<Temporal.PlainDate>
+      spec={spec}
+      value={value}
+      toSegments={dateToSegments}
+      fromSegments={dateFromSegments}
+      keyOf={toISODate}
+      onChange={onChange}
+      parsePaste={parseDatePasteIn(order)}
+      label={label}
+      {...rest}
+    />
+  );
+}