@sixthshift/design-system 0.2.1 → 0.4.0

package/src/components/DateTimePicker/DateTimePicker.tsx

@@ -1,13 +1,23 @@
 import { autoUpdate, FloatingPortal, flip, offset, shift, useClick, useDismiss, useFloating, useInteractions } from "@floating-ui/react";
 import { useControllableState } from "@sixthshift/design-system/hooks";
 import { cn } from "@sixthshift/design-system/utils";
-import { Clock, X } from "lucide-react";
-import type * as React from "react";
-import { useCallback, useId, useState } from "react";
-import { Temporal, today } from "../../date-time";
-
+import { Clock } from "lucide-react";
+import * as React from "react";
+import { useCallback, useId, useMemo, useState } from "react";
+import {
+  adaptDisabledDates,
+  fromISODateOrUndefined,
+  fromISOInstantOrUndefined,
+  fromISOTimeOrUndefined,
+  Temporal,
+  today,
+  toISOInstantOrUndefined,
+} from "../../date-time";
+
+import { PickerField } from "../../internal";
 import { Button } from "../Button";
-import { Calendar } from "../Calendar";
+import { CalendarView } from "../Calendar/CalendarView";
+import { isDateDisabled } from "../Calendar/calendar.hooks";
 import { Separator } from "../Separator";
 import { PeriodSelector } from "../TimePicker/PeriodSelector";
 import { TimeColumn } from "../TimePicker/TimeColumn";
@@ -22,46 +32,44 @@ import {
   to24Hour,
 } from "../TimePicker/timepicker.hooks";
 import type { ParsedTime, TimePeriod } from "../TimePicker/timepicker.types";
+import { DateTimeSegments } from "./DateTimeSegments";
 import type { DateTimePickerProps } from "./datetimepicker.types";
 
-/**
- * Format an Instant for display
- */
-function formatInstantDisplay(instant: Temporal.Instant, clockFormat: "12h" | "24h", showSeconds: boolean, timeZone?: string): string {
-  const tz = timeZone ?? Temporal.Now.timeZoneId();
-  const zoned = instant.toZonedDateTimeISO(tz);
-  const plainDateTime = zoned.toPlainDateTime();
-
-  // Format date part
-  const datePart = plainDateTime.toLocaleString("en-US", {
-    month: "long",
-    day: "numeric",
-    year: "numeric",
-  });
-
-  // Format time part based on props
-  const timeOptions: Intl.DateTimeFormatOptions = {
-    hour: "numeric",
-    minute: "2-digit",
-    hour12: clockFormat === "12h",
-  };
-
-  if (showSeconds) {
-    timeOptions.second = "2-digit";
-  }
-
-  const timePart = plainDateTime.toLocaleString("en-US", timeOptions);
-
-  return `${datePart}, ${timePart}`;
-}
-
 /**
  * DateTimePicker - A component for selecting both date and time
  *
- * Combines date and time selection in a single popup with side-by-side layout.
- * Uses Temporal.Instant for all values (timezone-aware).
+ * Combines date and time selection in a single popup with side-by-side layout:
+ * a `Calendar` grid on the left, hour/minute(/second) columns on the right.
+ *
+ * The trigger is one typeable field of date *and* time segments — one value, so
+ * the digits roll straight from the year into the hour: `1520260330p` is January
+ * 5th 2026 at 3:30pm, typed without a tab. `segmentOrder` sets the date half's
+ * order (never inferred from the locale), `clockFormat` decides the hour's range
+ * and whether there is an AM/PM segment, and `Alt+ArrowDown` opens the popover
+ * on the month being typed. See `SegmentedField` for the whole keyboard model.
+ * It is not a composition of `DatePicker` and `TimePicker` — it builds
+ * directly on the same internal calendar grid and time-column primitives
+ * those two use, so the two stay visually consistent without either being
+ * mounted as a component.
+ *
+ * The value is a single absolute instant: an `ISOInstant` string
+ * (`"2026-08-26T00:30:00Z"`), always UTC and always ending in `Z`. It is
+ * edited in the viewer's local timezone (`Temporal.Now.timeZoneId()`) and
+ * converted to/from UTC at the boundary, so the same stored instant displays
+ * differently to viewers in different timezones. Input written with a
+ * numeric offset is normalised to the `Z` form. Supports controlled
+ * (`value`/`onChange`) and uncontrolled (`defaultValue`) use.
+ *
+ * Opening the popover seeds date and time drafts from the committed value (or
+ * today + the current time, if none); the footer's Apply combines them into
+ * an instant and commits, Cancel discards the draft. `minDate`/`maxDate` and
+ * `disabledDates` bound the date grid; `minTime`/`maxTime` bound the wall-clock
+ * time columns — these are plain date/time constraints on the picker's grid,
+ * not constraints on the resulting instant. `clockFormat` and `showSeconds`
+ * control the time columns; `clearable` (default `true`) shows the clear
+ * button.
  */
-export const DateTimePicker = (props: DateTimePickerProps) => {
+export const DateTimePicker = React.forwardRef<HTMLDivElement, DateTimePickerProps>((props, ref) => {
   const {
     value,
     defaultValue,
@@ -74,7 +82,6 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
     minuteStep = 1,
     clockFormat = "12h",
     showSeconds = false,
-    placeholder = "Select date and time...",
     weekStartsOn = 0,
     name,
     isDisabled = false,
@@ -82,16 +89,38 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
     className,
     align = "end",
     clearable = true,
+    segmentOrder = "mdy",
   } = props;
 
   // Open state
   const [open, setOpen] = useState(false);
+  // The day grid takes focus only when the popover was opened from the keyboard.
+  const [autoFocusDay, setAutoFocusDay] = useState(false);
+
+  // ---------------------------------------------------------------------------
+  // The ISO boundary.
+  //
+  // The value crosses as a canonical UTC instant string; constraints cross as
+  // ISO dates and times. Below this block everything is Temporal, exactly as
+  // before. Each conversion is memoised on its source string so the Temporal
+  // values stay referentially stable across renders.
+  // ---------------------------------------------------------------------------
+
+  const temporalValue = useMemo(() => fromISOInstantOrUndefined(value), [value]);
+  const temporalDefaultValue = useMemo(() => fromISOInstantOrUndefined(defaultValue), [defaultValue]);
+  const temporalMinDate = useMemo(() => fromISODateOrUndefined(minDate), [minDate]);
+  const temporalMaxDate = useMemo(() => fromISODateOrUndefined(maxDate), [maxDate]);
+  const temporalMinTime = useMemo(() => fromISOTimeOrUndefined(minTime), [minTime]);
+  const temporalMaxTime = useMemo(() => fromISOTimeOrUndefined(maxTime), [maxTime]);
+  const temporalDisabledDates = useMemo(() => adaptDisabledDates(disabledDates), [disabledDates]);
+
+  const handleChange = useCallback((next: Temporal.Instant | undefined) => onChange?.(toISOInstantOrUndefined(next)), [onChange]);
 
   // Controllable value state (external/committed value)
-  const [committedValue, setCommittedValue] = useControllableState({
-    value,
-    defaultValue,
-    onChange,
+  const [committedValue, setCommittedValue] = useControllableState<Temporal.Instant | undefined>({
+    value: temporalValue,
+    defaultValue: temporalDefaultValue,
+    onChange: handleChange,
   });
 
   // Draft state (date + time parts)
@@ -117,6 +146,7 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
   // Sync draft when popup opens
   const handleOpenChange = useCallback(
     (newOpen: boolean) => {
+      if (!newOpen) setAutoFocusDay(false);
       if (newOpen) {
         const tz = Temporal.Now.timeZoneId();
         if (committedValue) {
@@ -229,9 +259,82 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
   const inputId = `datetimepicker-input-${id}`;
 
   // Display value (from committed value)
-  const displayValue = committedValue ? formatInstantDisplay(committedValue, clockFormat, showSeconds) : "";
   const hasValue = Boolean(committedValue);
 
+  // ---------------------------------------------------------------------------
+  // The typeable field.
+  //
+  // The segments show the draft while the popover is open and the committed
+  // value while it is closed, so typing moves the grid and columns, and picking
+  // in either shows up in the segments. Open means the popover's Apply/Cancel
+  // owns the value; closed means a complete date-time commits as soon as it is
+  // complete.
+  //
+  // The draft is a date plus loose time parts, so it only composes into an
+  // instant once the date exists. Until then the field has nothing to show,
+  // which is exactly `undefined`.
+  // ---------------------------------------------------------------------------
+
+  const userZone = Temporal.Now.timeZoneId();
+
+  const draftInstant = useMemo(() => {
+    if (!draftDate) return undefined;
+    const parsed = getDraftTime();
+    return draftDate
+      .toPlainDateTime({ hour: parsed.hour, minute: parsed.minute, second: showSeconds ? parsed.second : 0 })
+      .toZonedDateTime(userZone)
+      .toInstant();
+  }, [draftDate, getDraftTime, showSeconds, userZone]);
+
+  const segmentValue = open ? draftInstant : committedValue;
+
+  /**
+   * A typed instant can fall outside what the grid and columns allow — the date
+   * past `maxDate`, or the time outside `minTime`/`maxTime`. The field flags it
+   * rather than clamping; see `DatePicker` for why.
+   */
+  const outOfBounds = useMemo(() => {
+    if (!segmentValue) return false;
+    const zoned = segmentValue.toZonedDateTimeISO(userZone);
+    return (
+      isDateDisabled(zoned.toPlainDate(), temporalDisabledDates, temporalMinDate, temporalMaxDate) ||
+      isTimeDisabled(zoned.toPlainTime(), temporalMinTime, temporalMaxTime)
+    );
+  }, [segmentValue, temporalDisabledDates, temporalMaxDate, temporalMaxTime, temporalMinDate, temporalMinTime, userZone]);
+
+  const handleSegmentsChange = useCallback(
+    (instant: Temporal.Instant | undefined) => {
+      if (!open) {
+        setCommittedValue(instant);
+        return;
+      }
+      if (!instant) {
+        setDraftDate(undefined);
+        return;
+      }
+      const zoned = instant.toZonedDateTimeISO(userZone);
+      const parsed = temporalToParsed(zoned.toPlainTime());
+      setDraftDate(zoned.toPlainDate());
+      setMonth(zoned.toPlainDate());
+      setDraftHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
+      setDraftMinute(parsed.minute);
+      setDraftSecond(parsed.second);
+      setDraftPeriod(to12Hour(parsed.hour).period);
+    },
+    [clockFormat, open, setCommittedValue, userZone]
+  );
+
+  /** `Alt+ArrowDown` from a segment: open the popover *and* go to the grid. */
+  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]);
+
   // Time selection handlers
   const handleHourChange = (hour: number) => setDraftHour(hour);
   const handleMinuteChange = (minute: number) => setDraftMinute(minute);
@@ -250,47 +353,43 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
   const checkTimeDisabled = useCallback(
     (hour: number, minute: number, second: number): boolean => {
       const temporal = Temporal.PlainTime.from({ hour, minute, second });
-      return isTimeDisabled(temporal, minTime, maxTime);
+      return isTimeDisabled(temporal, temporalMinTime, temporalMaxTime);
     },
-    [minTime, maxTime]
+    [temporalMinTime, temporalMaxTime]
   );
 
   return (
     <>
       {/* Trigger Input */}
-      <div className="relative flex items-center">
-        <Clock 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`,
-            clearable && hasValue ? "pr-9" : "pr-3",
-            isInvalid && "border-border-danger",
-            className
-          )}
-          {...getReferenceProps()}
-        />
-        {clearable && hasValue && !isDisabled && (
-          <button
-            type="button"
-            onClick={handleClear}
-            className="absolute right-3 rounded-sm p-0.5 text-fg-subtle hover:bg-bg-subtle hover:text-fg-normal focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring"
-            aria-label="Clear date and time"
-          >
-            <X className="h-3.5 w-3.5" />
-          </button>
-        )}
+      <div ref={ref} className="relative flex items-center">
+        <PickerField
+          ref={refs.setReference as React.Ref<HTMLDivElement>}
+          className={cn("w-full min-w-80", className)}
+          icon={<Clock className="h-4 w-4" />}
+          toggleLabel="Open date and time picker"
+          toggleProps={getReferenceProps()}
+          isOpen={open}
+          contentId={contentId}
+          isDisabled={isDisabled}
+          isInvalid={isInvalid || outOfBounds}
+          onClear={clearable && hasValue && !isDisabled ? handleClear : undefined}
+          clearLabel="Clear date and time"
+        >
+          <DateTimeSegments
+            className="h-full flex-1"
+            id={inputId}
+            value={segmentValue}
+            onChange={handleSegmentsChange}
+            timeZone={userZone}
+            order={segmentOrder}
+            clockFormat={clockFormat}
+            showSeconds={showSeconds}
+            isDisabled={isDisabled}
+            isInvalid={isInvalid || outOfBounds}
+            onOpenRequest={openWithGridFocus}
+            onSubmit={handleFieldSubmit}
+          />
+        </PickerField>
 
         {/* Hidden input for form submission */}
         {name && committedValue && <input type="hidden" name={name} value={committedValue.toString()} />}
@@ -303,24 +402,25 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
             ref={refs.setFloating}
             id={contentId}
             role="dialog"
-            aria-modal="true"
+            aria-label="Choose date and time"
             style={floatingStyles}
             className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
             {...getFloatingProps()}
           >
             <div className="flex gap-4">
               {/* Date Calendar (left side) */}
-              <Calendar
+              <CalendarView
                 mode="single"
                 value={draftDate}
                 onSelect={setDraftDate as (date: Temporal.PlainDate | undefined) => void}
                 month={month}
                 onMonthChange={setMonth}
-                minDate={minDate}
-                maxDate={maxDate}
-                disabled={disabledDates}
+                minDate={temporalMinDate}
+                maxDate={temporalMaxDate}
+                disabled={temporalDisabledDates}
                 weekStartsOn={weekStartsOn}
                 showFooter={false}
+                autoFocusDay={autoFocusDay}
               />
 
               <Separator orientation="vertical" />
@@ -387,7 +487,7 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
               <Button type="button" variant="ghost" size="sm" onClick={handleCancel}>
                 Cancel
               </Button>
-              <Button type="button" variant="solid" size="sm" onClick={handleApply}>
+              <Button type="button" variant="solid" intent="brand" size="sm" onClick={handleApply}>
                 Apply
               </Button>
             </div>
@@ -396,4 +496,5 @@ export const DateTimePicker = (props: DateTimePickerProps) => {
       )}
     </>
   );
-};
+});
+DateTimePicker.displayName = "DateTimePicker";

package/src/components/DateTimePicker/DateTimeSegments.tsx

@@ -0,0 +1,113 @@
+import { Temporal } from "../../date-time";
+import { SegmentedField, type SegmentSpec, type SegmentValues } from "../../internal";
+import { dateFromSegments, dateSpec, dateToSegments, parseDatePasteIn } from "../DatePicker/DateSegments";
+import type { DateSegmentOrder } from "../DatePicker/datepicker.types";
+import { timeCodec, timeSpec } from "../TimePicker/TimeSegments";
+import type { ClockFormat } from "../TimePicker/timepicker.types";
+
+export type DateTimeSegmentsProps = {
+  /** The instant the segments display, or `undefined` for an empty field. */
+  value: Temporal.Instant | undefined;
+  /**
+   * Fires with a complete instant, or `undefined` the moment the segments stop
+   * describing one. Never fires a partial value.
+   */
+  onChange: (instant: Temporal.Instant | undefined) => void;
+  /** The zone the segments are read and written in. */
+  timeZone: string;
+  order?: DateSegmentOrder | undefined;
+  clockFormat?: ClockFormat | undefined;
+  showSeconds?: boolean | undefined;
+  isDisabled?: boolean | undefined;
+  isInvalid?: boolean | undefined;
+  label?: string | undefined;
+  onOpenRequest?: (() => void) | undefined;
+  onSubmit?: (() => void) | undefined;
+  id?: string | undefined;
+  className?: string | undefined;
+};
+
+/**
+ * The typeable half of `DateTimePicker`: one field of date *and* time segments.
+ *
+ * Deliberately one `SegmentedField` rather than a date field beside a time
+ * field: it is one value, so `Tab` and the digit roll-forward should carry
+ * straight from the year into the hour. `152026330p` is January 5th 2026 at
+ * 3:30pm, typed without a single tab.
+ *
+ * The date and time halves reuse the specs and codecs from `DatePicker` and
+ * `TimePicker`, so the three fields cannot drift apart in behaviour. What is
+ * specific here is the zone: segments are wall-clock, the value is an instant,
+ * and this is where that conversion happens.
+ *
+ * Internal to `DateTimePicker`; not exported from `./index.ts`.
+ */
+export function DateTimeSegments({
+  value,
+  onChange,
+  timeZone,
+  order = "mdy",
+  clockFormat = "12h",
+  showSeconds = false,
+  label = "Date and time",
+  ...rest
+}: DateTimeSegmentsProps) {
+  const format = showSeconds ? "HH:mm:ss" : "HH:mm";
+  // A space, not a slash: it separates the date from the time rather than one
+  // number from the next.
+  const spec: SegmentSpec[] = [...dateSpec(order), ...timeSpec(format, clockFormat, " ")];
+  const time = timeCodec(format, clockFormat);
+
+  const toSegments = (instant: Temporal.Instant | undefined): SegmentValues => {
+    if (!instant) return { ...dateToSegments(undefined), ...time.toSegments(undefined) };
+    const zoned = instant.toZonedDateTimeISO(timeZone);
+    return { ...dateToSegments(zoned.toPlainDate()), ...time.toSegments(zoned.toPlainTime()) };
+  };
+
+  const fromSegments = (values: Record<string, number>): Temporal.Instant => {
+    const date = dateFromSegments(values);
+    const plainTime = time.fromSegments(values);
+    return date.toPlainDateTime(plainTime).toZonedDateTime(timeZone).toInstant();
+  };
+
+  /**
+   * A pasted string is split at the first space: the date half is read by the
+   * date field's rules (ISO always, otherwise the segment order) and the time
+   * half by the clock's. Either half alone is accepted, leaving the other empty.
+   */
+  const parsePaste = (text: string): SegmentValues | null => {
+    const trimmed = text.trim();
+    // An ISO instant pastes as a whole.
+    try {
+      if (/\d{4}-\d{2}-\d{2}T/.test(trimmed)) return toSegments(Temporal.Instant.from(trimmed));
+    } catch {
+      // Not an instant after all; fall through to the halves below.
+    }
+
+    const [datePart, ...timeParts] = trimmed.split(/\s+/);
+    const datePasted = datePart ? parseDatePasteIn(order)(datePart) : null;
+    const timePasted = timeParts.length > 0 ? time.parsePaste(timeParts.join(" ")) : null;
+    if (!datePasted && !timePasted) return null;
+
+    return {
+      ...dateToSegments(undefined),
+      ...time.toSegments(undefined),
+      ...(datePasted ?? {}),
+      ...(timePasted ?? {}),
+    };
+  };
+
+  return (
+    <SegmentedField<Temporal.Instant>
+      spec={spec}
+      value={value}
+      toSegments={toSegments}
+      fromSegments={fromSegments}
+      keyOf={(instant) => instant.toString()}
+      onChange={onChange}
+      parsePaste={parsePaste}
+      label={label}
+      {...rest}
+    />
+  );
+}

package/src/components/DateTimePicker/datetimepicker.types.ts

@@ -1,27 +1,32 @@
-import type { Temporal, WeekStartsOn } from "../../date-time";
-
-export type DisabledDateMatcher =
-  | Temporal.PlainDate
-  | Temporal.PlainDate[]
-  | ((date: Temporal.PlainDate) => boolean)
-  | { before: Temporal.PlainDate }
-  | { after: Temporal.PlainDate }
-  | { from: Temporal.PlainDate; to: Temporal.PlainDate };
+/**
+ * DateTimePicker types.
+ *
+ * The value is an absolute instant, exchanged as a canonical UTC ISO string
+ * (`"2026-08-26T00:30:00Z"`). Input written with a numeric offset is accepted and
+ * normalised to the `Z` form, so one instant always has one representation.
+ *
+ * Date and time constraints are plain dates and wall-clock times, since they
+ * describe the picker's grid rather than an absolute moment.
+ */
+
+import type { DisabledDates, ISODate, ISOInstant, ISOTime, WeekStartsOn } from "../../date-time";
+import type { DateSegmentOrder } from "../DatePicker/datepicker.types";
 
 export type DateTimePickerProps = {
-  // Value (controlled/uncontrolled) - NOW USES INSTANT
-  value?: Temporal.Instant | undefined;
-  defaultValue?: Temporal.Instant | undefined;
-  onChange?: (instant: Temporal.Instant | undefined) => void;
+  // Value (controlled/uncontrolled) — an absolute instant, in UTC
+  value?: ISOInstant | undefined;
+  defaultValue?: ISOInstant | undefined;
+  /** Called with a canonical UTC instant string, or undefined when cleared. */
+  onChange?: (instant: ISOInstant | undefined) => void;
 
   // Date constraints
-  minDate?: Temporal.PlainDate;
-  maxDate?: Temporal.PlainDate;
-  disabledDates?: DisabledDateMatcher | DisabledDateMatcher[];
+  minDate?: ISODate;
+  maxDate?: ISODate;
+  disabledDates?: DisabledDates | DisabledDates[];
 
   // Time constraints
-  minTime?: Temporal.PlainTime;
-  maxTime?: Temporal.PlainTime;
+  minTime?: ISOTime;
+  maxTime?: ISOTime;
   minuteStep?: 1 | 5 | 10 | 15 | 30;
 
   // Time format
@@ -29,9 +34,14 @@ export type DateTimePickerProps = {
   showSeconds?: boolean; // Default: false
 
   // Display
-  placeholder?: string;
   weekStartsOn?: WeekStartsOn;
 
+  /**
+   * Segment order for the date half of the typeable field (default `mdy`).
+   * Never inferred from the locale — `08/09` is a different date under each.
+   */
+  segmentOrder?: DateSegmentOrder;
+
   // Form
   name?: string;
 

package/src/components/DateTimePicker/index.ts

@@ -1,2 +1,10 @@
+/**
+ * Public surface of `@sixthshift/design-system/datetime-picker`.
+ *
+ * `DisabledDateMatcher` was a Temporal-shaped type and is gone; the ISO
+ * equivalent `DisabledDates` is re-exported here.
+ */
+
+export type { DisabledDates, ISODate, ISOInstant, ISOTime } from "../../date-time";
 export { DateTimePicker } from "./DateTimePicker";
-export type { DateTimePickerProps, DisabledDateMatcher } from "./datetimepicker.types";
+export type { DateTimePickerProps } from "./datetimepicker.types";