@sixthshift/design-system 0.1.0 → 0.3.0

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

@@ -1,27 +1,31 @@
-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";
 
 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

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";

package/src/components/DateTimeRangePicker/DateTimeRangePicker.tsx

@@ -2,12 +2,23 @@ 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 * as React from "react";
 import { useCallback, useId, useMemo, useState } from "react";
-import { now, Temporal, today } from "../../date-time";
+import {
+  adaptDisabledDates,
+  fromISODateOrUndefined,
+  fromISOInstantRange,
+  fromISOTimeOrUndefined,
+  now,
+  Temporal,
+  type TemporalInstantRange,
+  today,
+  toISOInstant,
+  toISOInstantRange,
+} from "../../date-time";
 
 import { Button } from "../Button";
-import { Calendar } from "../Calendar";
+import { CalendarView } from "../Calendar/CalendarView";
 import type { DateRangeValue } from "../Calendar/calendar.types";
 import { Separator } from "../Separator";
 import { PeriodSelector } from "../TimePicker/PeriodSelector";
@@ -57,9 +68,12 @@ function formatInstantDisplay(instant: Temporal.Instant, clockFormat: "12h" | "2
 }
 
 /**
- * Format an Instant range for display
+ * Format an Instant range for display.
+ *
+ * Takes the internal Temporal range, not the public ISO shape — display runs
+ * below the boundary.
  */
-function formatRangeDisplay(range: DateTimeRangeValue | undefined, clockFormat: "12h" | "24h", showSeconds: boolean): string {
+function formatRangeDisplay(range: TemporalInstantRange | undefined, clockFormat: "12h" | "24h", showSeconds: boolean): string {
   if (!range?.from && !range?.to) {
     return "";
   }
@@ -78,7 +92,7 @@ function formatRangeDisplay(range: DateTimeRangeValue | undefined, clockFormat:
 /**
  * Default preset ranges for DateTimeRangePicker
  *
- * Uses clean hour boundaries and returns Instant values
+ * Uses clean hour boundaries and returns canonical UTC instant strings
  */
 function getDefaultPresets(): DateTimeRangePresetOption[] {
   return [
@@ -87,7 +101,7 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
       value: () => {
         const end = now().round({ smallestUnit: "hour", roundingMode: "ceil" });
         const start = end.subtract({ hours: 1 });
-        return { from: start, to: end };
+        return { from: toISOInstant(start), to: toISOInstant(end) };
       },
     },
     {
@@ -95,7 +109,7 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
       value: () => {
         const end = now().round({ smallestUnit: "hour", roundingMode: "ceil" });
         const start = end.subtract({ hours: 24 });
-        return { from: start, to: end };
+        return { from: toISOInstant(start), to: toISOInstant(end) };
       },
     },
     {
@@ -103,7 +117,7 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
       value: () => {
         const end = now().round({ smallestUnit: "hour", roundingMode: "ceil" });
         const start = end.subtract({ hours: 7 * 24 });
-        return { from: start, to: end };
+        return { from: toISOInstant(start), to: toISOInstant(end) };
       },
     },
     {
@@ -111,7 +125,7 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
       value: () => {
         const end = now().round({ smallestUnit: "hour", roundingMode: "ceil" });
         const start = end.subtract({ hours: 30 * 24 });
-        return { from: start, to: end };
+        return { from: toISOInstant(start), to: toISOInstant(end) };
       },
     },
     {
@@ -121,7 +135,7 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
         const tz = Temporal.Now.timeZoneId();
         const zonedNow = end.toZonedDateTimeISO(tz);
         const startOfMonth = zonedNow.toPlainDate().with({ day: 1 }).toPlainDateTime(Temporal.PlainTime.from("00:00:00")).toZonedDateTime(tz).toInstant();
-        return { from: startOfMonth, to: end };
+        return { from: toISOInstant(startOfMonth), to: toISOInstant(end) };
       },
     },
   ];
@@ -131,9 +145,9 @@ function getDefaultPresets(): DateTimeRangePresetOption[] {
  * DateTimeRangePicker - A component for selecting a datetime range
  *
  * Combines date range selection with separate time pickers for start and end times.
- * Uses Temporal.PlainDateTime for all values.
+ * All values cross the boundary as canonical UTC instant strings.
  */
-export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
+export const DateTimeRangePicker = React.forwardRef<HTMLDivElement, DateTimeRangePickerProps>((props, ref) => {
   const {
     value,
     defaultValue,
@@ -161,11 +175,30 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
   // Open state
   const [open, setOpen] = useState(false);
 
+  // ---------------------------------------------------------------------------
+  // The ISO boundary.
+  //
+  // Both ends of the range cross as canonical UTC instant strings; constraints
+  // cross as ISO dates and times. Below this block everything is Temporal, as
+  // before. Each conversion is memoised on its source value so the Temporal
+  // objects handed downstream stay referentially stable.
+  // ---------------------------------------------------------------------------
+
+  const temporalValue = useMemo(() => fromISOInstantRange(value), [value]);
+  const temporalDefaultValue = useMemo(() => fromISOInstantRange(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: TemporalInstantRange | undefined) => onChange?.(toISOInstantRange(next)), [onChange]);
+
   // Controllable value state (external/committed value)
-  const [committedValue, setCommittedValue] = useControllableState({
-    value,
-    defaultValue,
-    onChange,
+  const [committedValue, setCommittedValue] = useControllableState<TemporalInstantRange | undefined>({
+    value: temporalValue,
+    defaultValue: temporalDefaultValue,
+    onChange: handleChange,
   });
 
   // Draft state (date range + time parts for both start and end)
@@ -303,8 +336,8 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
     };
   }, [clockFormat, draftEndHour, draftEndMinute, draftEndSecond, draftEndPeriod]);
 
-  // Combine draft dates and times into DateTimeRangeValue
-  const getDraftRange = useCallback((): DateTimeRangeValue => {
+  // Combine draft dates and times into the internal Temporal range
+  const getDraftRange = useCallback((): TemporalInstantRange => {
     const tz = Temporal.Now.timeZoneId();
 
     const from = draftDateRange?.from
@@ -392,7 +425,7 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
   // Apply preset
   const _handlePresetClick = useCallback(
     (preset: { label: string; value: DateTimeRangeValue }) => {
-      setCommittedValue(preset.value);
+      setCommittedValue(fromISOInstantRange(preset.value));
       setOpen(false);
     },
     [setCommittedValue]
@@ -445,15 +478,15 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
   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 min-w-125 items-center">
+      <div ref={ref} className="relative flex min-w-125 items-center">
         <CalendarIcon className="pointer-events-none absolute left-3 h-4 w-4 text-fg-subtle" />
         <input
           ref={refs.setReference as React.Ref<HTMLInputElement>}
@@ -531,15 +564,15 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
               )}
 
               {/* Date Calendar */}
-              <Calendar
+              <CalendarView
                 mode="range"
                 value={draftDateRange}
                 onSelect={setDraftDateRange as (range: DateRangeValue | undefined) => void}
                 month={month}
                 onMonthChange={setMonth}
-                minDate={minDate}
-                maxDate={maxDate}
-                disabled={disabledDates}
+                minDate={temporalMinDate}
+                maxDate={temporalMaxDate}
+                disabled={temporalDisabledDates}
                 weekStartsOn={weekStartsOn}
                 showFooter={false}
               />
@@ -676,4 +709,5 @@ export const DateTimeRangePicker = (props: DateTimeRangePickerProps) => {
       )}
     </>
   );
-};
+});
+DateTimeRangePicker.displayName = "DateTimeRangePicker";

package/src/components/DateTimeRangePicker/datetimerangepicker.types.ts

@@ -1,20 +1,25 @@
-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 };
-
-export type DateTimeRangeValue = {
-  from: Temporal.Instant | undefined;
-  to: Temporal.Instant | undefined;
-};
+/**
+ * DateTimeRangePicker types.
+ *
+ * Both ends of the range are absolute instants, exchanged as canonical UTC ISO
+ * strings (`"2026-08-26T00:30:00Z"`). 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, ISOInstantRange, ISOTime, WeekStartsOn } from "../../date-time";
+
+/**
+ * A datetime range.
+ *
+ * Alias of `ISOInstantRange`, kept under this name because it is the historical
+ * public type for this component.
+ */
+export type DateTimeRangeValue = ISOInstantRange;
 
 export type DateTimeRangePresetOption = {
   label: string;
+  /** Called when the picker renders, so relative ranges stay current. */
   value: () => DateTimeRangeValue;
 };
 
@@ -29,13 +34,13 @@ export type DateTimeRangePickerProps = {
   showPresets?: boolean; // Default: true
 
   // Date constraints
-  minDate?: Temporal.PlainDate;
-  maxDate?: Temporal.PlainDate;
-  disabledDates?: DisabledDateMatcher | DisabledDateMatcher[];
+  minDate?: ISODate;
+  maxDate?: ISODate;
+  disabledDates?: DisabledDates | DisabledDates[];
 
   // Time constraints (apply to both start and end times)
-  minTime?: Temporal.PlainTime;
-  maxTime?: Temporal.PlainTime;
+  minTime?: ISOTime;
+  maxTime?: ISOTime;
   minuteStep?: 1 | 5 | 10 | 15 | 30;
 
   // Time format

package/src/components/DateTimeRangePicker/index.ts

@@ -1,2 +1,11 @@
+/**
+ * Public surface of `@sixthshift/design-system/datetime-range-picker`.
+ *
+ * `DisabledDateMatcher` was a Temporal-shaped type and is gone; the ISO
+ * equivalent `DisabledDates` is re-exported here. `DateTimeRangeValue` survives
+ * as an alias of `ISOInstantRange`.
+ */
+
+export type { DisabledDates, ISODate, ISOInstant, ISOInstantRange, ISOTime } from "../../date-time";
 export { DateTimeRangePicker } from "./DateTimeRangePicker";
 export type { DateTimeRangePickerProps, DateTimeRangePresetOption, DateTimeRangeValue } from "./datetimerangepicker.types";

package/src/components/EmptyState/EmptyState.tsx

@@ -1,23 +1,23 @@
 import { Muted } from "@sixthshift/design-system/muted";
 import { cn } from "@sixthshift/design-system/utils";
-import type { HTMLAttributes, ReactNode } from "react";
+import * as React from "react";
 
-export type EmptyStateProps = HTMLAttributes<HTMLDivElement> & {
+export type EmptyStateProps = React.HTMLAttributes<HTMLDivElement> & {
   /** Optional icon to display */
-  icon?: ReactNode;
+  icon?: React.ReactNode;
   /** Message to display */
   message: string;
   /** Optional description for more context */
   description?: string;
   /** Optional action button or element */
-  action?: ReactNode;
+  action?: React.ReactNode;
   /** Additional CSS classes */
   className?: string;
 };
 
-export const EmptyState = ({ icon, message, description, action, className, ...props }: EmptyStateProps) => {
+export const EmptyState = React.forwardRef<HTMLDivElement, EmptyStateProps>(({ icon, message, description, action, className, ...props }, ref) => {
   return (
-    <div className={cn("flex flex-col items-center justify-center gap-3 p-8 text-center", className)} {...props}>
+    <div ref={ref} className={cn("flex flex-col items-center justify-center gap-3 p-8 text-center", className)} {...props}>
       {icon && <div className="text-fg-subtle">{icon}</div>}
       <div className="flex flex-col gap-1">
         <Muted>{message}</Muted>
@@ -26,4 +26,5 @@ export const EmptyState = ({ icon, message, description, action, className, ...p
       {action && <div className="mt-2">{action}</div>}
     </div>
   );
-};
+});
+EmptyState.displayName = "EmptyState";

package/src/components/Field/Field.tsx

@@ -1,5 +1,5 @@
 import { cn } from "@sixthshift/design-system/utils";
-import type { ReactNode } from "react";
+import * as React from "react";
 
 /**
  * The labelled identifier carve-out used by identity-disclosure surfaces
@@ -22,7 +22,7 @@ export type FieldProps = {
   /** The humane label for what the identifier identifies ("WhatsApp", "Email"). */
   label: string;
   /** The identifier itself. Rendered monospaced + breakable by default. */
-  children: ReactNode;
+  children: React.ReactNode;
   /**
    * `stacked` (default): label above, value below — best for long identifiers
    * that need horizontal room to wrap.
@@ -39,12 +39,12 @@ export type FieldProps = {
   className?: string;
 };
 
-export const Field = ({ label, children, layout = "stacked", mono = true, className }: FieldProps) => {
+export const Field = React.forwardRef<HTMLDivElement, FieldProps>(({ label, children, layout = "stacked", mono = true, className }, ref) => {
   const valueClass = cn("text-fg-subtle text-xs", mono && "break-all font-mono");
 
   if (layout === "row") {
     return (
-      <div className={cn("flex items-baseline justify-between gap-3", className)}>
+      <div ref={ref} className={cn("flex items-baseline justify-between gap-3", className)}>
         <span className="shrink-0 text-fg-subtle text-sm">{label}</span>
         <span className={cn(valueClass, "min-w-0 text-right")}>{children}</span>
       </div>
@@ -52,9 +52,10 @@ export const Field = ({ label, children, layout = "stacked", mono = true, classN
   }
 
   return (
-    <div className={cn("flex flex-col gap-1", className)}>
+    <div ref={ref} className={cn("flex flex-col gap-1", className)}>
       <span className="text-fg-subtle text-xs uppercase tracking-wide">{label}</span>
       <span className={valueClass}>{children}</span>
     </div>
   );
-};
+});
+Field.displayName = "Field";