sid-ui 0.0.0-stage → 0.1.1

package/src/components/TimeDial.tsx

@@ -0,0 +1,260 @@
+"use client";
+
+import { useRef, useState, type KeyboardEvent, type PointerEvent } from "react";
+
+import {
+  HOURS_PER_HALF,
+  MINUTES_PER_HOUR,
+  from12,
+  meridiemOf,
+  pad2,
+  parseTime,
+  formatTime,
+  to12,
+  type HourCycle,
+  type Meridiem,
+  type MinuteStep,
+  type TimeUnit,
+} from "./time";
+
+import type { ControlSize } from "./size";
+
+/** Ring radii as a percent of the face. The 24-hour inner ring holds 00 and 13–23. */
+const OUTER_RING = 38;
+const INNER_RING = 25;
+const RING_SPLIT = (OUTER_RING + INNER_RING) / 2;
+const LABEL_STEP = 5;
+const FULL_TURN = 360;
+const QUARTER_TURN = 90;
+const HOUR_LABELS = [12, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+const INNER_LABELS = [0, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23];
+
+export interface TimeDialProps {
+  value: string;
+  onChange?: (value: string) => void;
+  hourCycle?: HourCycle;
+  withSeconds?: boolean;
+  /** Minute snapping. Drag lands on any multiple; labels show every five. */
+  minuteStep?: MinuteStep;
+  size?: ControlSize;
+  disabled?: boolean;
+  /** Accessible name for the dial. */
+  label?: string;
+}
+
+function point(index: number, total: number, radius: number) {
+  const angle = (index / total) * Math.PI * 2 - Math.PI / 2;
+  return { x: 50 + radius * Math.cos(angle), y: 50 + radius * Math.sin(angle) };
+}
+
+/** An analog face. Tap or drag the hand; hours hand off to minutes automatically. */
+export function TimeDial({
+  value,
+  onChange,
+  hourCycle = "12h",
+  withSeconds = false,
+  minuteStep = 5,
+  size = "md",
+  disabled,
+  label = "Time",
+}: TimeDialProps) {
+  const parts = parseTime(value) ?? { h: 0, m: 0, s: 0 };
+  const [unit, setUnit] = useState<TimeUnit>("hour");
+  const [dragging, setDragging] = useState(false);
+  const faceRef = useRef<HTMLDivElement>(null);
+  const meridiem = meridiemOf(parts.h);
+  const inner = hourCycle === "24h" && (parts.h === 0 || parts.h > HOURS_PER_HALF);
+
+  function commit(next: Partial<typeof parts>) {
+    onChange?.(formatTime({ ...parts, ...next }, withSeconds));
+  }
+
+  function pick(clientX: number, clientY: number) {
+    const rect = faceRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    const dx = clientX - (rect.left + rect.width / 2);
+    const dy = clientY - (rect.top + rect.height / 2);
+    const degrees = (Math.atan2(dy, dx) * 180) / Math.PI + QUARTER_TURN;
+    const turn = ((degrees % FULL_TURN) + FULL_TURN) % FULL_TURN;
+    const distance = (Math.hypot(dx, dy) / rect.width) * 100;
+
+    if (unit === "hour") {
+      const slot = Math.round(turn / (FULL_TURN / HOURS_PER_HALF)) % HOURS_PER_HALF;
+      if (hourCycle === "24h")
+        commit({ h: distance < RING_SPLIT ? INNER_LABELS[slot] : slot === 0 ? 12 : slot });
+      else commit({ h: from12(slot === 0 ? HOURS_PER_HALF : slot, meridiem) });
+    } else {
+      const snap = unit === "minute" ? minuteStep : 1;
+      const raw = Math.round(turn / (FULL_TURN / MINUTES_PER_HOUR) / snap) * snap;
+      commit(unit === "minute" ? { m: raw % MINUTES_PER_HOUR } : { s: raw % MINUTES_PER_HOUR });
+    }
+  }
+
+  function onPointerDown(event: PointerEvent<HTMLDivElement>) {
+    if (disabled) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    setDragging(true);
+    pick(event.clientX, event.clientY);
+  }
+
+  function onPointerUp() {
+    if (!dragging) return;
+    setDragging(false);
+    if (unit === "hour") setUnit("minute");
+    else if (unit === "minute" && withSeconds) setUnit("second");
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    const delta = { ArrowUp: 1, ArrowRight: 1, ArrowDown: -1, ArrowLeft: -1 }[event.key];
+    if (event.key === "Enter") {
+      event.preventDefault();
+      setUnit(unit === "hour" ? "minute" : unit === "minute" && withSeconds ? "second" : "hour");
+      return;
+    }
+    if (!delta) return;
+    event.preventDefault();
+    if (unit === "hour") commit({ h: parts.h + delta });
+    else if (unit === "minute") commit({ m: parts.m + delta * minuteStep });
+    else commit({ s: parts.s + delta });
+  }
+
+  const handTurn =
+    unit === "hour"
+      ? (parts.h % HOURS_PER_HALF) * (FULL_TURN / HOURS_PER_HALF)
+      : (unit === "minute" ? parts.m : parts.s) * (FULL_TURN / MINUTES_PER_HOUR);
+  const handLength = unit === "hour" && inner ? INNER_RING : OUTER_RING;
+  const active = unit === "hour" ? parts.h : unit === "minute" ? parts.m : parts.s;
+  const onLabel = unit !== "hour" && active % LABEL_STEP !== 0;
+  const hourText = hourCycle === "12h" ? pad2(to12(parts.h)) : pad2(parts.h);
+  const unitValue = { hour: hourText, minute: pad2(parts.m), second: pad2(parts.s) }[unit];
+
+  function meridiemButton(option: Meridiem) {
+    return (
+      <button
+        key={option}
+        type="button"
+        className="os-dial-meridiem"
+        aria-pressed={meridiem === option}
+        disabled={disabled}
+        onClick={() =>
+          meridiem !== option &&
+          commit({ h: parts.h + (option === "PM" ? HOURS_PER_HALF : -HOURS_PER_HALF) })
+        }
+      >
+        {option}
+      </button>
+    );
+  }
+
+  function unitButton(target: TimeUnit, text: string) {
+    return (
+      <button
+        type="button"
+        className="os-dial-unit"
+        aria-pressed={unit === target}
+        disabled={disabled}
+        onClick={() => setUnit(target)}
+      >
+        {text}
+      </button>
+    );
+  }
+
+  return (
+    <div
+      className={["os-dial", `os-dial-${size}`, disabled && "os-dial-disabled"]
+        .filter(Boolean)
+        .join(" ")}
+    >
+      <div className="os-dial-readout">
+        <div className="os-dial-digits">
+          {unitButton("hour", hourText)}
+          <span className="os-dial-colon">:</span>
+          {unitButton("minute", pad2(parts.m))}
+          {withSeconds && (
+            <>
+              <span className="os-dial-colon">:</span>
+              {unitButton("second", pad2(parts.s))}
+            </>
+          )}
+        </div>
+        {hourCycle === "12h" && (
+          <div className="os-dial-meridiems">{(["AM", "PM"] as const).map(meridiemButton)}</div>
+        )}
+      </div>
+
+      <div
+        ref={faceRef}
+        className={dragging ? "os-dial-face os-dial-dragging" : "os-dial-face"}
+        role="slider"
+        tabIndex={disabled ? -1 : 0}
+        aria-label={`${label}, ${unit}`}
+        aria-valuetext={`${unit} ${unitValue}`}
+        aria-valuenow={active}
+        aria-disabled={disabled || undefined}
+        onPointerDown={onPointerDown}
+        onPointerMove={(event) => dragging && pick(event.clientX, event.clientY)}
+        onPointerUp={onPointerUp}
+        onPointerCancel={() => setDragging(false)}
+        onKeyDown={onKeyDown}
+      >
+        <svg className="os-dial-hand" viewBox="0 0 100 100" aria-hidden>
+          <g style={{ transform: `rotate(${handTurn}deg)` }}>
+            <line x1="50" y1="50" x2="50" y2={50 - handLength} />
+            <circle className="os-dial-knob" cx="50" cy={50 - handLength} r="6.5" />
+            {onLabel && (
+              <circle className="os-dial-knob-dot" cx="50" cy={50 - handLength} r="1.3" />
+            )}
+          </g>
+          <circle className="os-dial-hub" cx="50" cy="50" r="1.8" />
+        </svg>
+
+        {unit === "hour"
+          ? HOUR_LABELS.map((hour, index) => {
+              const at = point(index, HOURS_PER_HALF, OUTER_RING);
+              const on = hourCycle === "12h" ? to12(parts.h) === hour : !inner && parts.h === hour;
+              return (
+                <span
+                  key={hour}
+                  className={on ? "os-dial-label os-dial-label-on" : "os-dial-label"}
+                  style={{ left: `${at.x}%`, top: `${at.y}%` }}
+                >
+                  {hourCycle === "24h" ? pad2(hour) : hour}
+                </span>
+              );
+            })
+          : HOUR_LABELS.map((_, index) => {
+              const mark = index * LABEL_STEP;
+              const at = point(index, HOURS_PER_HALF, OUTER_RING);
+              return (
+                <span
+                  key={mark}
+                  className={active === mark ? "os-dial-label os-dial-label-on" : "os-dial-label"}
+                  style={{ left: `${at.x}%`, top: `${at.y}%` }}
+                >
+                  {pad2(mark)}
+                </span>
+              );
+            })}
+        {unit === "hour" &&
+          hourCycle === "24h" &&
+          INNER_LABELS.map((hour, index) => {
+            const at = point(index, HOURS_PER_HALF, INNER_RING);
+            return (
+              <span
+                key={hour}
+                className={
+                  parts.h === hour
+                    ? "os-dial-label os-dial-label-inner os-dial-label-on"
+                    : "os-dial-label os-dial-label-inner"
+                }
+                style={{ left: `${at.x}%`, top: `${at.y}%` }}
+              >
+                {pad2(hour)}
+              </span>
+            );
+          })}
+      </div>
+    </div>
+  );
+}

package/src/components/TimeField.tsx

@@ -0,0 +1,196 @@
+"use client";
+
+import { useState } from "react";
+
+import { Button } from "./Action";
+import { PickerShell } from "./PickerShell";
+import { ChoiceSegment, NumberSegment, SegmentDivider } from "./Segment";
+import {
+  HOURS_PER_HALF,
+  MERIDIEMS,
+  formatTime,
+  from12,
+  meridiemOf,
+  pad2,
+  parseTime,
+  to12,
+  type HourCycle,
+  type Meridiem,
+  type MinuteStep,
+} from "./time";
+import { TimeColumns } from "./TimeColumns";
+import { TimeDial } from "./TimeDial";
+import { TimeSlots, type TimeSlotsProps } from "./TimeSlots";
+
+import type { ControlSize } from "./size";
+
+export type TimePicker = "columns" | "dial" | "slots" | "none";
+
+export interface TimeFieldProps {
+  value: string;
+  onChange?: (value: string) => void;
+  hourCycle?: HourCycle;
+  withSeconds?: boolean;
+  minuteStep?: MinuteStep;
+  /** What the dropdown shows. `none` makes a type-only field. */
+  picker?: TimePicker;
+  /** Passed through when `picker="slots"`. */
+  slots?: Pick<TimeSlotsProps, "start" | "end" | "interval" | "unavailable" | "grouped">;
+  size?: ControlSize;
+  disabled?: boolean;
+  error?: boolean;
+  label?: string;
+  labelledBy?: string;
+}
+
+interface Draft {
+  hour: number | null;
+  minute: number | null;
+  second: number | null;
+  meridiem: Meridiem | null;
+}
+
+function draftOf(value: string, hourCycle: HourCycle): Draft {
+  const parts = parseTime(value);
+  if (!parts) return { hour: null, minute: null, second: null, meridiem: null };
+  return {
+    hour: hourCycle === "12h" ? to12(parts.h) : parts.h,
+    minute: parts.m,
+    second: parts.s,
+    meridiem: meridiemOf(parts.h),
+  };
+}
+
+/** Type the time, or open the dropdown and pick it. Both stay in sync. */
+export function TimeField({
+  value,
+  onChange,
+  hourCycle = "12h",
+  withSeconds = false,
+  minuteStep = 5,
+  picker = "columns",
+  slots,
+  size = "md",
+  disabled,
+  error,
+  label = "Time",
+  labelledBy,
+}: TimeFieldProps) {
+  const twelve = hourCycle === "12h";
+  const [open, setOpen] = useState(false);
+  const [draft, setDraft] = useState(() => draftOf(value, hourCycle));
+  const [seen, setSeen] = useState(value);
+  if (seen !== value) {
+    setSeen(value);
+    setDraft(draftOf(value, hourCycle));
+  }
+
+  function update(patch: Partial<Draft>) {
+    const next = { ...draft, ...patch };
+    setDraft(next);
+    const empty = next.hour == null && next.minute == null && (!withSeconds || next.second == null);
+    if (empty) return onChange?.("");
+    if (next.hour == null || next.minute == null || (withSeconds && next.second == null)) return;
+    const h = twelve ? from12(next.hour, next.meridiem ?? "AM") : next.hour;
+    onChange?.(formatTime({ h, m: next.minute, s: next.second ?? 0 }, withSeconds));
+  }
+
+  function setNow() {
+    const now = new Date();
+    onChange?.(
+      formatTime({ h: now.getHours(), m: now.getMinutes(), s: now.getSeconds() }, withSeconds),
+    );
+  }
+
+  const panelProps = { value, onChange, hourCycle, withSeconds, minuteStep, size, disabled };
+  const panel =
+    picker === "none" ? undefined : (
+      <div className="os-picker-body">
+        {picker === "columns" && <TimeColumns {...panelProps} />}
+        {picker === "dial" && <TimeDial {...panelProps} label={label} />}
+        {picker === "slots" && (
+          <TimeSlots
+            {...slots}
+            value={value}
+            hourCycle={hourCycle}
+            size={size}
+            onChange={(next) => {
+              onChange?.(next);
+              setOpen(false);
+            }}
+          />
+        )}
+        {picker !== "slots" && (
+          <div className="os-picker-footer">
+            <Button label="Now" variant="ghost" size="sm" onClick={setNow} />
+            <Button label="Done" variant="primary" size="sm" onClick={() => setOpen(false)} />
+          </div>
+        )}
+      </div>
+    );
+
+  return (
+    <PickerShell
+      open={open}
+      onOpenChange={setOpen}
+      icon="clock"
+      label={label}
+      labelledBy={labelledBy}
+      size={size}
+      error={error}
+      disabled={disabled}
+      panel={panel}
+      segments={
+        <>
+          <NumberSegment
+            label="Hour"
+            value={draft.hour}
+            min={twelve ? 1 : 0}
+            max={twelve ? HOURS_PER_HALF : 23}
+            digits={2}
+            placeholder="--"
+            disabled={disabled}
+            format={twelve ? String : pad2}
+            onChange={(hour) => update({ hour })}
+          />
+          <SegmentDivider>:</SegmentDivider>
+          <NumberSegment
+            label="Minute"
+            value={draft.minute}
+            min={0}
+            max={59}
+            digits={2}
+            placeholder="--"
+            disabled={disabled}
+            onChange={(minute) => update({ minute })}
+          />
+          {withSeconds && (
+            <>
+              <SegmentDivider>:</SegmentDivider>
+              <NumberSegment
+                label="Second"
+                value={draft.second}
+                min={0}
+                max={59}
+                digits={2}
+                placeholder="--"
+                disabled={disabled}
+                onChange={(second) => update({ second })}
+              />
+            </>
+          )}
+          {twelve && (
+            <ChoiceSegment
+              label="AM or PM"
+              value={draft.meridiem}
+              options={MERIDIEMS}
+              placeholder="AM"
+              disabled={disabled}
+              onChange={(meridiem) => update({ meridiem })}
+            />
+          )}
+        </>
+      }
+    />
+  );
+}

package/src/components/TimeInput.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { useId } from "react";
+
+import {
+  HOURS_PER_HALF,
+  MERIDIEMS,
+  MINUTES_PER_HOUR,
+  formatTime,
+  from12,
+  meridiemOf,
+  pad2,
+  parseTime,
+  range,
+  to12,
+  type HourCycle,
+  type MinuteStep,
+} from "./time";
+import { TimeColumns } from "./TimeColumns";
+import { TimeDial } from "./TimeDial";
+import { TimeField, type TimePicker } from "./TimeField";
+import { TimeSlots, type TimeSlotsProps } from "./TimeSlots";
+
+import type { FieldSize } from "./size";
+
+export type { HourCycle, MinuteStep } from "./time";
+
+/**
+ * field   — type it, or open a dropdown (columns, dial, or slots).
+ * select  — one native dropdown per unit.
+ * dial    — an analog face you tap or drag.
+ * columns — scrolling wheels, always open.
+ * slots   — a grid of bookable times.
+ */
+export type TimeInputVariant = "field" | "select" | "dial" | "columns" | "slots";
+
+export interface TimeInputProps {
+  label: string;
+  value: string;
+  onChange?: (value: string) => void;
+  variant?: TimeInputVariant;
+  /** The dropdown inside `variant="field"`. */
+  picker?: TimePicker;
+  size?: FieldSize;
+  hourCycle?: HourCycle;
+  withSeconds?: boolean;
+  minuteStep?: MinuteStep;
+  slots?: Pick<TimeSlotsProps, "start" | "end" | "interval" | "unavailable" | "grouped">;
+  disabled?: boolean;
+  error?: boolean;
+  helper?: string;
+  description?: string;
+}
+
+function TimeSelects({
+  value,
+  onChange,
+  hourCycle,
+  withSeconds,
+  minuteStep,
+  size,
+  disabled,
+  error,
+  labelledBy,
+}: Required<Pick<TimeInputProps, "hourCycle" | "withSeconds" | "minuteStep" | "size">> &
+  Pick<TimeInputProps, "value" | "onChange" | "disabled" | "error"> & { labelledBy: string }) {
+  const parts = parseTime(value) ?? { h: 0, m: 0, s: 0 };
+  const twelve = hourCycle === "12h";
+  const cls = [
+    "os-control",
+    `os-control-${size}`,
+    "os-time-select",
+    error && "os-control-error",
+    disabled && "os-control-disabled",
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  function commit(next: Partial<typeof parts>) {
+    onChange?.(formatTime({ ...parts, ...next }, withSeconds));
+  }
+
+  return (
+    <div className="os-time-selects" role="group" aria-labelledby={labelledBy}>
+      <span className={cls}>
+        <select
+          aria-label="Hour"
+          disabled={disabled}
+          value={twelve ? to12(parts.h) : parts.h}
+          onChange={(e) =>
+            commit({
+              h: twelve
+                ? from12(Number(e.target.value), meridiemOf(parts.h))
+                : Number(e.target.value),
+            })
+          }
+        >
+          {(twelve ? range(1, HOURS_PER_HALF) : range(0, 23)).map((h) => (
+            <option key={h} value={h}>
+              {twelve ? h : pad2(h)}
+            </option>
+          ))}
+        </select>
+      </span>
+      <span className="os-segment-divider">:</span>
+      <span className={cls}>
+        <select
+          aria-label="Minute"
+          disabled={disabled}
+          value={parts.m}
+          onChange={(e) => commit({ m: Number(e.target.value) })}
+        >
+          {range(0, MINUTES_PER_HOUR - 1, minuteStep).map((m) => (
+            <option key={m} value={m}>
+              {pad2(m)}
+            </option>
+          ))}
+        </select>
+      </span>
+      {withSeconds && (
+        <>
+          <span className="os-segment-divider">:</span>
+          <span className={cls}>
+            <select
+              aria-label="Second"
+              disabled={disabled}
+              value={parts.s}
+              onChange={(e) => commit({ s: Number(e.target.value) })}
+            >
+              {range(0, MINUTES_PER_HOUR - 1).map((s) => (
+                <option key={s} value={s}>
+                  {pad2(s)}
+                </option>
+              ))}
+            </select>
+          </span>
+        </>
+      )}
+      {twelve && (
+        <span className={cls}>
+          <select
+            aria-label="AM or PM"
+            disabled={disabled}
+            value={meridiemOf(parts.h)}
+            onChange={(e) =>
+              commit({ h: from12(to12(parts.h), e.target.value as (typeof MERIDIEMS)[number]) })
+            }
+          >
+            {MERIDIEMS.map((m) => (
+              <option key={m}>{m}</option>
+            ))}
+          </select>
+        </span>
+      )}
+    </div>
+  );
+}
+
+/** One time value, five ways to enter it. Every variant reads and writes "HH:mm". */
+export function TimeInput({
+  label,
+  value,
+  onChange,
+  variant = "field",
+  picker = "columns",
+  size = "md",
+  hourCycle = "12h",
+  withSeconds = false,
+  minuteStep = 5,
+  slots,
+  disabled,
+  error,
+  helper,
+  description,
+}: TimeInputProps) {
+  const labelId = useId();
+  const shared = { value, onChange, hourCycle, withSeconds, minuteStep, size, disabled };
+
+  return (
+    <div className={`os-field-group os-time-input os-time-input-${variant}`}>
+      <span className="os-field-label" id={labelId}>
+        {label}
+      </span>
+      {description && <p className="os-field-description">{description}</p>}
+      {variant === "field" && (
+        <TimeField
+          {...shared}
+          picker={picker}
+          slots={slots}
+          error={error}
+          label={label}
+          labelledBy={labelId}
+        />
+      )}
+      {variant === "select" && <TimeSelects {...shared} error={error} labelledBy={labelId} />}
+      {variant === "dial" && <TimeDial {...shared} label={label} />}
+      {variant === "columns" && <TimeColumns {...shared} />}
+      {variant === "slots" && (
+        <TimeSlots
+          {...slots}
+          value={value}
+          onChange={onChange}
+          hourCycle={hourCycle}
+          size={size}
+          disabled={disabled}
+        />
+      )}
+      {helper && (
+        <span className={error ? "os-field-helper-error" : "os-field-helper"}>{helper}</span>
+      )}
+    </div>
+  );
+}