@sixthshift/design-system 0.3.0 → 0.5.0

package/src/components/DatePicker/DatePicker.tsx

@@ -3,7 +3,7 @@ import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
 import { Calendar as CalendarIcon, X } from "lucide-react";
 import * as React from "react";
-import { useCallback, useId, useMemo, useState } from "react";
+import { useCallback, useId, useMemo, useRef, useState } from "react";
 import {
   adaptDisabledDates,
   fromISODate,
@@ -18,8 +18,11 @@ import {
   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";
 
@@ -35,6 +38,49 @@ function toTemporal(mode: DatePickerProps["mode"], value: ISODate | ISODateRange
   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",
@@ -50,6 +96,7 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
     className,
     align = "end",
     clearable = true,
+    segmentOrder = "mdy",
   } = props;
 
   // Get mode-specific props
@@ -60,6 +107,9 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
 
   // 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.
@@ -127,6 +177,8 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
     (newOpen: boolean) => {
       if (newOpen) {
         setDraftValue(committedValue);
+      } else {
+        setAutoFocusDay(false);
       }
       setOpen(newOpen);
     },
@@ -219,35 +271,233 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
 
   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 ref={ref} 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}
@@ -280,7 +530,7 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
             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()}
@@ -301,6 +551,7 @@ export const DatePicker = React.forwardRef<HTMLDivElement, DatePickerProps>((pro
               showToday={mode !== "range"}
               onApply={handleApply}
               onCancel={handleCancel}
+              autoFocusDay={autoFocusDay}
               {...(mode === "multiple" && max ? { max } : {})}
             />
           </div>

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}
+    />
+  );
+}

package/src/components/DatePicker/datepicker.types.ts

@@ -19,6 +19,16 @@ import type { PresetOption as CalendarPresetOption } from "../Calendar/calendar.
  */
 export type DatePickerMode = "single" | "range" | "multiple";
 
+/**
+ * Which order the typeable segments read in.
+ *
+ * Explicit rather than inferred from the runtime locale: `08/09` is a different
+ * date under `mdy` than under `dmy`, and a component that guesses is wrong for
+ * half its users. Defaults to `mdy`, matching the `en-US` formatting the rest
+ * of the library's display helpers use.
+ */
+export type DateSegmentOrder = "mdy" | "dmy" | "ymd";
+
 // =============================================================================
 // Internal (Temporal) types
 // =============================================================================
@@ -56,7 +66,11 @@ type DatePickerBaseProps = {
   /** Which dates to refuse. See `DisabledDates`. */
   disabled?: DisabledDates | DisabledDates[];
 
-  /** Placeholder text */
+  /**
+   * Placeholder for the read-only text trigger, which only `multiple` mode
+   * still uses. `single` and `range` are typeable fields whose segments show
+   * their own placeholders (`mm/dd/yyyy`).
+   */
   placeholder?: string;
 
   /** Input name for form submission */
@@ -76,6 +90,12 @@ type DatePickerBaseProps = {
 
   /** Whether the clear button is shown when a value is present (default: true) */
   clearable?: boolean;
+
+  /**
+   * Segment order for the typeable field (`single` mode only; default `mdy`).
+   * See {@link DateSegmentOrder}.
+   */
+  segmentOrder?: DateSegmentOrder;
 };
 
 export type DatePickerSingleProps = DatePickerBaseProps & {

package/src/components/DatePicker/index.ts

@@ -10,4 +10,11 @@
 export type { DisabledDates, ISODate, ISODateRange } from "../../date-time";
 export type { PresetOption } from "../Calendar/calendar.types";
 export { DatePicker } from "./DatePicker";
-export type { DatePickerMode, DatePickerMultipleProps, DatePickerProps, DatePickerRangeProps, DatePickerSingleProps } from "./datepicker.types";
+export type {
+  DatePickerMode,
+  DatePickerMultipleProps,
+  DatePickerProps,
+  DatePickerRangeProps,
+  DatePickerSingleProps,
+  DateSegmentOrder,
+} from "./datepicker.types";

package/src/components/DateRangePicker/DateRangePicker.tsx

@@ -60,8 +60,26 @@ function getDefaultPresets(): PresetOption[] {
 /**
  * DateRangePicker - A specialized date range picker component
  *
- * Wraps DatePicker with mode="range" and adds common range presets.
- * All date values are canonical ISO 8601 strings ("2026-08-26").
+ * Wraps `DatePicker` with `mode="range"` and adds common range presets
+ * ("Today", "Last 7 days", "This month", …). Anything `DatePicker` does in
+ * range mode — two typeable fields, draft/commit via Apply/Cancel, keyboard
+ * navigation, form submission via hidden `name.from`/`name.to` inputs — carries
+ * over unchanged.
+ *
+ * Range mode renders the two ends as separate segmented fields rather than one
+ * field holding both: each end is typed and cleared on its own, and the shared
+ * popover anchors to whichever half you are editing.
+ *
+ * The value is an `ISODateRange` (`{ from?: ISODate, to?: ISODate }`), both
+ * ends canonical ISO 8601 date strings ("2026-08-26"). Supports controlled
+ * (`value`/`onChange`) and uncontrolled (`defaultValue`) use.
+ *
+ * `presets` (a `PresetOption[]` whose `value` is a zero-arg function) replaces
+ * the built-in list; the function form lets relative ranges like "Last 7 days"
+ * compute from the current date on every render rather than being frozen when
+ * the preset list is defined. Set `showPresets={false}` to hide the sidebar
+ * entirely. `minDate`/`maxDate`/`disabled` bound and exclude dates exactly as
+ * in `DatePicker`.
  */
 export const DateRangePicker = React.forwardRef<HTMLDivElement, DateRangePickerProps>((props, ref) => {
   const {
@@ -73,8 +91,8 @@ export const DateRangePicker = React.forwardRef<HTMLDivElement, DateRangePickerP
     disabled,
     presets: customPresets,
     showPresets = true,
-    placeholder = "Select date range...",
     weekStartsOn,
+    segmentOrder,
     name,
     isDisabled,
     isInvalid,
@@ -101,7 +119,6 @@ export const DateRangePicker = React.forwardRef<HTMLDivElement, DateRangePickerP
   // Build props for DatePicker (only include defined values)
   const datePickerProps: Record<string, unknown> = {
     mode: "range",
-    placeholder,
     ...(value !== undefined && { value }),
     ...(defaultValue !== undefined && { defaultValue }),
     ...(onChange !== undefined && { onChange }),
@@ -110,6 +127,7 @@ export const DateRangePicker = React.forwardRef<HTMLDivElement, DateRangePickerP
     ...(disabled && { disabled }),
     ...(datePickerPresets && { presets: datePickerPresets }),
     ...(weekStartsOn !== undefined && { weekStartsOn }),
+    ...(segmentOrder !== undefined && { segmentOrder }),
     ...(name && { name }),
     ...(isDisabled && { isDisabled }),
     ...(isInvalid && { isInvalid }),

package/src/components/DateRangePicker/daterangepicker.types.ts

@@ -6,6 +6,7 @@
  */
 
 import type { DisabledDates, ISODate, ISODateRange, WeekStartsOn } from "../../date-time";
+import type { DateSegmentOrder } from "../DatePicker/datepicker.types";
 
 /**
  * A preset range.
@@ -34,9 +35,14 @@ export type DateRangePickerProps = {
   showPresets?: boolean; // Default: true
 
   // Display
-  placeholder?: string;
   weekStartsOn?: WeekStartsOn;
 
+  /**
+   * Segment order for both typeable fields (default `mdy`). Never inferred from
+   * the locale — `08/09` is a different date under each.
+   */
+  segmentOrder?: DateSegmentOrder;
+
   // Form
   name?: string;