@sixthshift/design-system 0.1.0

package/src/components/TimePicker/PeriodSelector.tsx

@@ -0,0 +1,28 @@
+import { cn } from "@sixthshift/design-system/utils";
+import type { TimePeriod } from "./timepicker.types";
+
+export type PeriodSelectorProps = {
+  value: TimePeriod;
+  onChange: (period: TimePeriod) => void;
+};
+
+export const PeriodSelector = ({ value, onChange }: PeriodSelectorProps) => {
+  return (
+    <div className="flex h-48 w-12 flex-col items-center justify-center gap-1 rounded-lg border border-border-subtle bg-bg-subtle/50">
+      {(["AM", "PM"] as const).map((period) => (
+        <button
+          key={period}
+          type="button"
+          onClick={() => onChange(period)}
+          className={cn(
+            `w-10 cursor-pointer rounded-md py-1.5 text-center text-sm transition-colors focus-visible:outline-hidden`,
+            `hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-inset`,
+            value === period && "bg-bg-brand text-fg-on-brand hover:bg-bg-brand-strong"
+          )}
+        >
+          {period}
+        </button>
+      ))}
+    </div>
+  );
+};

package/src/components/TimePicker/TimeColumn.tsx

@@ -0,0 +1,62 @@
+import { cn } from "@sixthshift/design-system/utils";
+import { useEffect, useRef } from "react";
+
+export type TimeColumnProps = {
+  values: number[];
+  selected: number;
+  onSelect: (value: number) => void;
+  formatValue?: (value: number) => string;
+  disabled?: (value: number) => boolean;
+};
+
+export const TimeColumn = ({ values, selected, onSelect, formatValue = (v) => String(v).padStart(2, "0"), disabled }: TimeColumnProps) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const selectedRef = useRef<HTMLButtonElement>(null);
+
+  // Scroll selected item into view on mount and when selection changes
+  useEffect(() => {
+    if (selectedRef.current && containerRef.current) {
+      const container = containerRef.current;
+      const item = selectedRef.current;
+      const containerRect = container.getBoundingClientRect();
+      const itemRect = item.getBoundingClientRect();
+      const scrollTop = item.offsetTop - container.offsetTop - containerRect.height / 2 + itemRect.height / 2;
+      container.scrollTo({ top: scrollTop, behavior: "smooth" });
+    }
+  }, []);
+
+  return (
+    <div ref={containerRef} role="listbox" className="h-48 w-14 overflow-y-auto overscroll-contain rounded-lg border border-border-subtle bg-bg-subtle/50">
+      {/* Top spacer for centering first items */}
+      <div className="h-19" aria-hidden="true" />
+      <div className="flex flex-col gap-0.5">
+        {values.map((value) => {
+          const isSelected = value === selected;
+          const isDisabled = disabled?.(value) ?? false;
+
+          return (
+            <button
+              key={value}
+              ref={isSelected ? selectedRef : undefined}
+              type="button"
+              role="option"
+              aria-selected={isSelected}
+              onClick={() => !isDisabled && onSelect(value)}
+              disabled={isDisabled}
+              className={cn(
+                `mx-1 cursor-pointer rounded-md py-1.5 text-center text-sm transition-colors focus-visible:outline-hidden`,
+                `hover:bg-bg-subtle focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-inset`,
+                isSelected && "bg-bg-brand text-fg-on-brand hover:bg-bg-brand-strong",
+                isDisabled && "cursor-not-allowed opacity-50"
+              )}
+            >
+              {formatValue(value)}
+            </button>
+          );
+        })}
+      </div>
+      {/* Bottom spacer for centering last items */}
+      <div className="h-19" aria-hidden="true" />
+    </div>
+  );
+};

package/src/components/TimePicker/TimePicker.tsx

@@ -0,0 +1,323 @@
+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 { Button } from "../Button";
+import { Separator } from "../Separator";
+import { PeriodSelector } from "./PeriodSelector";
+import { TimeColumn } from "./TimeColumn";
+import {
+  formatTimeDisplay,
+  generateHours,
+  generateMinutes,
+  generateSeconds,
+  getCurrentTime,
+  isTimeDisabled,
+  parsedToTemporal,
+  temporalTimeToISO,
+  temporalToParsed,
+  to12Hour,
+  to24Hour,
+} from "./timepicker.hooks";
+import type { ParsedTime, TimePeriod, TimePickerProps, TimePresetOption } from "./timepicker.types";
+
+export type { TimePickerProps };
+
+export const TimePicker = (props: TimePickerProps) => {
+  const {
+    value,
+    defaultValue,
+    onChange,
+    format = "HH:mm",
+    clockFormat = "12h",
+    minuteStep = 1,
+    minTime,
+    maxTime,
+    presets,
+    placeholder = "Select time",
+    name,
+    isDisabled = false,
+    isInvalid = false,
+    className,
+  } = props;
+
+  // Open state
+  const [open, setOpen] = useState(false);
+
+  // Controllable value state (external/committed value)
+  const [committedValue, setCommittedValue] = useControllableState({
+    value,
+    defaultValue,
+    onChange,
+  });
+
+  // Parse committed value
+  const parsedCommitted = committedValue ? temporalToParsed(committedValue) : undefined;
+
+  // Draft state (internal while popup is open)
+  const [draftHour, setDraftHour] = useState<number>(parsedCommitted?.hour ?? 12);
+  const [draftMinute, setDraftMinute] = useState<number>(parsedCommitted?.minute ?? 0);
+  const [draftSecond, setDraftSecond] = useState<number>(parsedCommitted?.second ?? 0);
+  const [draftPeriod, setDraftPeriod] = useState<TimePeriod>(() => {
+    if (parsedCommitted) {
+      return to12Hour(parsedCommitted.hour).period;
+    }
+    return "AM";
+  });
+
+  // Sync draft when popup opens
+  const handleOpenChange = useCallback(
+    (newOpen: boolean) => {
+      if (newOpen) {
+        if (committedValue) {
+          const parsed = temporalToParsed(committedValue);
+          setDraftHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
+          setDraftMinute(parsed.minute);
+          setDraftSecond(parsed.second);
+          setDraftPeriod(to12Hour(parsed.hour).period);
+        } else {
+          // Default to current time
+          const now = getCurrentTime();
+          const currentHour = now.hour;
+          setDraftHour(clockFormat === "12h" ? to12Hour(currentHour).hour12 : currentHour);
+          setDraftMinute(now.minute);
+          setDraftSecond(now.second);
+          setDraftPeriod(to12Hour(currentHour).period);
+        }
+      }
+      setOpen(newOpen);
+    },
+    [committedValue, clockFormat]
+  );
+
+  // Get the current draft as a parsed time (24-hour)
+  const getDraftTime = useCallback((): ParsedTime => {
+    const hour24 = clockFormat === "12h" ? to24Hour(draftHour, draftPeriod) : draftHour;
+    return {
+      hour: hour24,
+      minute: draftMinute,
+      second: draftSecond,
+    };
+  }, [clockFormat, draftHour, draftMinute, draftSecond, draftPeriod]);
+
+  // Apply changes
+  const handleApply = useCallback(() => {
+    const parsed = getDraftTime();
+    const temporalTime = parsedToTemporal(parsed);
+
+    // Check if disabled
+    if (isTimeDisabled(temporalTime, minTime, maxTime)) {
+      return;
+    }
+
+    setCommittedValue(temporalTime);
+    setOpen(false);
+  }, [getDraftTime, minTime, maxTime, setCommittedValue]);
+
+  // Cancel changes
+  const handleCancel = useCallback(() => {
+    setOpen(false);
+  }, []);
+
+  // Clear value
+  const handleClear = useCallback(
+    (e: React.MouseEvent) => {
+      e.stopPropagation();
+      e.preventDefault();
+      setCommittedValue(undefined);
+    },
+    [setCommittedValue]
+  );
+
+  // Now button
+  const handleNow = useCallback(() => {
+    const now = getCurrentTime();
+    const currentHour = now.hour;
+    setDraftHour(clockFormat === "12h" ? to12Hour(currentHour).hour12 : currentHour);
+    setDraftMinute(now.minute);
+    setDraftSecond(now.second);
+    setDraftPeriod(to12Hour(currentHour).period);
+  }, [clockFormat]);
+
+  // Preset selection
+  const handlePresetClick = useCallback(
+    (preset: TimePresetOption) => {
+      const parsed = temporalToParsed(preset.value);
+      setDraftHour(clockFormat === "12h" ? to12Hour(parsed.hour).hour12 : parsed.hour);
+      setDraftMinute(parsed.minute);
+      setDraftSecond(parsed.second);
+      setDraftPeriod(to12Hour(parsed.hour).period);
+    },
+    [clockFormat]
+  );
+
+  // Check if a preset is currently active
+  const isPresetActive = useCallback(
+    (preset: TimePresetOption): boolean => {
+      const draftTime = getDraftTime();
+      const presetParsed = temporalToParsed(preset.value);
+
+      return (
+        draftTime.hour === presetParsed.hour && draftTime.minute === presetParsed.minute && (format === "HH:mm" || draftTime.second === presetParsed.second)
+      );
+    },
+    [getDraftTime, format]
+  );
+
+  // Floating UI setup
+  const { refs, floatingStyles, context } = useFloating({
+    open,
+    onOpenChange: handleOpenChange,
+    placement: "bottom-end",
+    middleware: [offset(8), flip(), shift({ padding: 8 })],
+    whileElementsMounted: autoUpdate,
+  });
+
+  const click = useClick(context);
+  const dismiss = useDismiss(context);
+  const { getReferenceProps, getFloatingProps } = useInteractions([click, dismiss]);
+
+  // IDs for accessibility
+  const id = useId();
+  const contentId = `timepicker-content-${id}`;
+  const inputId = `timepicker-input-${id}`;
+
+  // Display value
+  const displayValue = committedValue ? formatTimeDisplay(committedValue, clockFormat, format) : "";
+  const hasValue = Boolean(committedValue);
+
+  // Generate column values
+  const hours = generateHours(clockFormat);
+  const minutes = generateMinutes(minuteStep);
+  const seconds = generateSeconds();
+
+  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`,
+            hasValue ? "pr-9" : "pr-3",
+            isInvalid && "border-border-danger",
+            className
+          )}
+          {...getReferenceProps()}
+        />
+        {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 time"
+          >
+            <X className="h-3.5 w-3.5" />
+          </button>
+        )}
+
+        {/* Hidden input for form submission */}
+        {name && committedValue && <input type="hidden" name={name} value={temporalTimeToISO(committedValue, format)} />}
+      </div>
+
+      {/* Popover Content */}
+      {open && (
+        <FloatingPortal>
+          <div
+            ref={refs.setFloating}
+            id={contentId}
+            role="dialog"
+            aria-modal="true"
+            style={floatingStyles}
+            className="z-popover rounded-xl border border-border-normal bg-bg-normal p-4 shadow-lg"
+            {...getFloatingProps()}
+          >
+            <div className="flex">
+              {/* Presets Sidebar */}
+              {presets && presets.length > 0 && (
+                <div className="mr-3 flex flex-col gap-1 border-border-normal border-r pr-3">
+                  {presets.map((preset) => (
+                    <button
+                      key={preset.label}
+                      type="button"
+                      onClick={() => handlePresetClick(preset)}
+                      className={cn(
+                        `rounded-md px-3 py-1.5 text-left text-sm transition-colors`,
+                        `hover:bg-bg-subtle focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-inset`,
+                        isPresetActive(preset) && "bg-bg-brand-subtle text-fg-brand"
+                      )}
+                    >
+                      {preset.label}
+                    </button>
+                  ))}
+                </div>
+              )}
+
+              {/* Time Columns */}
+              <div className="flex flex-col gap-3">
+                {/* Column Headers */}
+                <div className="flex items-center justify-center gap-2">
+                  <div className="w-14 text-center font-medium text-fg-subtle text-xs">Hour</div>
+                  <div className="w-14 text-center font-medium text-fg-subtle text-xs">Min</div>
+                  {format === "HH:mm:ss" && <div className="w-14 text-center font-medium text-fg-subtle text-xs">Sec</div>}
+                  {clockFormat === "12h" && <div className="w-12 text-center font-medium text-fg-subtle text-xs" />}
+                </div>
+
+                {/* Scrollable Columns */}
+                <div className="flex items-start gap-2">
+                  {/* Hours */}
+                  <TimeColumn
+                    values={hours}
+                    selected={draftHour}
+                    onSelect={setDraftHour}
+                    formatValue={clockFormat === "12h" ? (v) => String(v) : (v) => String(v).padStart(2, "0")}
+                  />
+
+                  {/* Minutes */}
+                  <TimeColumn values={minutes} selected={draftMinute} onSelect={setDraftMinute} />
+
+                  {/* Seconds (optional) */}
+                  {format === "HH:mm:ss" && <TimeColumn values={seconds} selected={draftSecond} onSelect={setDraftSecond} />}
+
+                  {/* AM/PM (12-hour only) */}
+                  {clockFormat === "12h" && <PeriodSelector value={draftPeriod} onChange={setDraftPeriod} />}
+                </div>
+
+                <Separator />
+
+                {/* Footer with Now / Cancel / Apply */}
+                <div className="flex items-center justify-between">
+                  <Button type="button" variant="ghost" size="sm" onClick={handleNow}>
+                    Now
+                  </Button>
+                  <div className="flex gap-2">
+                    <Button type="button" variant="ghost" size="sm" onClick={handleCancel}>
+                      Cancel
+                    </Button>
+                    <Button type="button" variant="solid" size="sm" onClick={handleApply}>
+                      Apply
+                    </Button>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </FloatingPortal>
+      )}
+    </>
+  );
+};

package/src/components/TimePicker/index.ts

@@ -0,0 +1,7 @@
+export { TimePicker } from "./TimePicker";
+export type {
+  ClockFormat,
+  TimeFormat,
+  TimePickerProps,
+  TimePresetOption,
+} from "./timepicker.types";

package/src/components/TimePicker/timepicker.hooks.ts

@@ -0,0 +1,173 @@
+import { formatTimePadded, Temporal } from "../../date-time";
+import type { ClockFormat, ParsedTime, TimeFormat, TimePeriod } from "./timepicker.types";
+
+// =============================================================================
+// Temporal ↔ ParsedTime Conversion
+// =============================================================================
+
+/**
+ * Convert Temporal.PlainTime to ParsedTime
+ */
+export function temporalToParsed(time: Temporal.PlainTime): ParsedTime {
+  return {
+    hour: time.hour,
+    minute: time.minute,
+    second: time.second,
+  };
+}
+
+/**
+ * Convert ParsedTime to Temporal.PlainTime
+ */
+export function parsedToTemporal(parsed: ParsedTime): Temporal.PlainTime {
+  return Temporal.PlainTime.from({
+    hour: parsed.hour,
+    minute: parsed.minute,
+    second: parsed.second,
+  });
+}
+
+/**
+ * Convert Temporal.PlainTime to ISO string (for form submission)
+ */
+export function temporalTimeToISO(time: Temporal.PlainTime, format: TimeFormat = "HH:mm"): string {
+  if (format === "HH:mm:ss") {
+    return time.toString().slice(0, 8); // "HH:mm:ss"
+  }
+  return time.toString().slice(0, 5); // "HH:mm"
+}
+
+// =============================================================================
+// Time Formatting
+// =============================================================================
+
+/**
+ * Format Temporal.PlainTime for display
+ */
+export function formatTimeDisplay(time: Temporal.PlainTime, clockFormat: ClockFormat = "12h", format: TimeFormat = "HH:mm"): string {
+  if (clockFormat === "12h") {
+    return formatTimePadded(time);
+  }
+  // 24h format
+  if (format === "HH:mm:ss") {
+    return time.toLocaleString("en-US", {
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      hour12: false,
+    });
+  }
+  return time.toLocaleString("en-US", {
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+}
+
+// =============================================================================
+// Time Comparison
+// =============================================================================
+
+/**
+ * Check if time a is before time b
+ */
+export function isTimeBefore(a: Temporal.PlainTime, b: Temporal.PlainTime): boolean {
+  return Temporal.PlainTime.compare(a, b) < 0;
+}
+
+/**
+ * Check if time a is after time b
+ */
+export function isTimeAfter(a: Temporal.PlainTime, b: Temporal.PlainTime): boolean {
+  return Temporal.PlainTime.compare(a, b) > 0;
+}
+
+/**
+ * Check if a time is within min/max bounds
+ */
+export function isTimeDisabled(time: Temporal.PlainTime, minTime?: Temporal.PlainTime, maxTime?: Temporal.PlainTime): boolean {
+  if (minTime && isTimeBefore(time, minTime)) {
+    return true;
+  }
+  if (maxTime && isTimeAfter(time, maxTime)) {
+    return true;
+  }
+  return false;
+}
+
+// =============================================================================
+// 12-Hour / 24-Hour Conversion
+// =============================================================================
+
+/**
+ * Convert 24-hour hour to 12-hour format
+ */
+export function to12Hour(hour24: number): { hour12: number; period: TimePeriod } {
+  if (hour24 === 0) {
+    return { hour12: 12, period: "AM" };
+  }
+  if (hour24 < 12) {
+    return { hour12: hour24, period: "AM" };
+  }
+  if (hour24 === 12) {
+    return { hour12: 12, period: "PM" };
+  }
+  return { hour12: hour24 - 12, period: "PM" };
+}
+
+/**
+ * Convert 12-hour format to 24-hour hour
+ */
+export function to24Hour(hour12: number, period: TimePeriod): number {
+  if (period === "AM") {
+    return hour12 === 12 ? 0 : hour12;
+  }
+  return hour12 === 12 ? 12 : hour12 + 12;
+}
+
+// =============================================================================
+// Time Generation
+// =============================================================================
+
+/**
+ * Generate array of hours for display
+ */
+export function generateHours(clockFormat: ClockFormat): number[] {
+  if (clockFormat === "12h") {
+    return [12, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+  }
+  return Array.from({ length: 24 }, (_, i) => i);
+}
+
+/**
+ * Generate array of minutes based on step
+ */
+export function generateMinutes(step: number = 1): number[] {
+  const minutes: number[] = [];
+  for (let m = 0; m < 60; m += step) {
+    minutes.push(m);
+  }
+  return minutes;
+}
+
+/**
+ * Generate array of seconds
+ */
+export function generateSeconds(): number[] {
+  return Array.from({ length: 60 }, (_, i) => i);
+}
+
+/**
+ * Get current time as Temporal.PlainTime, rounded to minute precision
+ * to avoid nanosecond drift causing unnecessary re-renders
+ */
+export function getCurrentTime(): Temporal.PlainTime {
+  return Temporal.Now.plainTimeISO().round({ smallestUnit: "minute", roundingMode: "floor" });
+}
+
+/**
+ * Round time to nearest step
+ */
+export function roundToStep(minute: number, step: number): number {
+  return Math.round(minute / step) * step;
+}

package/src/components/TimePicker/timepicker.types.ts

@@ -0,0 +1,101 @@
+/**
+ * TimePicker types
+ *
+ * All time values use Temporal.PlainTime at the component boundary.
+ * This provides type safety and semantic clarity about what kind of time is expected.
+ */
+
+import type { Temporal } from "../../date-time";
+
+// =============================================================================
+// Value Types
+// =============================================================================
+
+/**
+ * Time value format for display and serialization
+ * - "HH:mm" for minute precision (default)
+ * - "HH:mm:ss" for second precision
+ */
+export type TimeFormat = "HH:mm" | "HH:mm:ss";
+
+/**
+ * Clock format for display
+ * - "12h" shows AM/PM selector
+ * - "24h" shows 00-23 hours
+ */
+export type ClockFormat = "12h" | "24h";
+
+// =============================================================================
+// Preset Options
+// =============================================================================
+
+export type TimePresetOption = {
+  label: string;
+  value: Temporal.PlainTime;
+};
+
+// =============================================================================
+// Props
+// =============================================================================
+
+export type TimePickerProps = {
+  /** Controlled value */
+  value?: Temporal.PlainTime | undefined;
+
+  /** Default value for uncontrolled mode */
+  defaultValue?: Temporal.PlainTime | undefined;
+
+  /** Called when time changes */
+  onChange?: (time: Temporal.PlainTime | undefined) => void;
+
+  /** Time format for the value (affects seconds visibility) */
+  format?: TimeFormat;
+
+  /** Clock display format */
+  clockFormat?: ClockFormat;
+
+  /** Minute step interval (default: 1) */
+  minuteStep?: 1 | 5 | 10 | 15 | 30;
+
+  /** Minimum selectable time */
+  minTime?: Temporal.PlainTime;
+
+  /** Maximum selectable time */
+  maxTime?: Temporal.PlainTime;
+
+  /** Preset options (shown in sidebar) */
+  presets?: TimePresetOption[];
+
+  /** Placeholder text */
+  placeholder?: string;
+
+  /** Input name for form submission */
+  name?: string;
+
+  /** Whether the picker is disabled */
+  isDisabled?: boolean;
+
+  /** Error state */
+  isInvalid?: boolean;
+
+  /** Additional class name for the trigger input */
+  className?: string;
+};
+
+// =============================================================================
+// Internal Types
+// =============================================================================
+
+/**
+ * Parsed time value for internal use
+ */
+export type ParsedTime = {
+  hour: number; // 0-23
+  minute: number; // 0-59
+  second: number; // 0-59
+};
+
+/**
+ * AM/PM period
+ */
+export type TimePeriod = "AM" | "PM";