@sixthshift/design-system 0.1.0

package/src/components/Calendar/calendar.hooks.ts

@@ -0,0 +1,329 @@
+import { useCallback, useMemo } from "react";
+import { addDays, formatDateMediumYear, isPlainDate, isSameDay, isSameMonth, startOfMonth, startOfWeek, Temporal, today } from "../../date-time";
+import type { DateRangeValue, DateSelectionState, DisabledDateMatcher, SelectionMode } from "./calendar.types";
+
+// =============================================================================
+// Date Comparison Utilities (using Temporal)
+// =============================================================================
+
+/**
+ * Check if two PlainDates represent the same day
+ */
+export function isSameDateTemporal(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) === 0;
+}
+
+/**
+ * Check if date a is before date b
+ */
+export function isBeforeTemporal(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) < 0;
+}
+
+/**
+ * Check if date a is after date b
+ */
+export function isAfterTemporal(a: Temporal.PlainDate, b: Temporal.PlainDate): boolean {
+  return Temporal.PlainDate.compare(a, b) > 0;
+}
+
+/**
+ * Check if a date is between two dates (inclusive)
+ */
+export function isBetweenTemporal(date: Temporal.PlainDate, start: Temporal.PlainDate, end: Temporal.PlainDate): boolean {
+  return !isBeforeTemporal(date, start) && !isAfterTemporal(date, end);
+}
+
+/**
+ * Convert a Temporal.PlainDate to ISO string (for form submission)
+ */
+export function temporalToISO(temporal: Temporal.PlainDate): string {
+  return temporal.toString();
+}
+
+// =============================================================================
+// Disabled Date Checking
+// =============================================================================
+
+/**
+ * Check if a date matches a single disabled matcher
+ */
+function matchesDisabledMatcher(date: Temporal.PlainDate, matcher: DisabledDateMatcher): boolean {
+  // Single date (Temporal.PlainDate)
+  if (isPlainDate(matcher)) {
+    return isSameDateTemporal(date, matcher);
+  }
+
+  // Array of dates
+  if (Array.isArray(matcher)) {
+    return matcher.some((d) => isPlainDate(d) && isSameDateTemporal(date, d));
+  }
+
+  // Function
+  if (typeof matcher === "function") {
+    return matcher(date);
+  }
+
+  // Before constraint
+  if ("before" in matcher && !("to" in matcher)) {
+    return isBeforeTemporal(date, matcher.before);
+  }
+
+  // After constraint
+  if ("after" in matcher) {
+    return isAfterTemporal(date, matcher.after);
+  }
+
+  // Range constraint
+  if ("from" in matcher && "to" in matcher) {
+    return isBetweenTemporal(date, matcher.from, matcher.to);
+  }
+
+  return false;
+}
+
+/**
+ * Check if a date is disabled based on matchers, minDate, and maxDate
+ */
+export function isDateDisabled(
+  date: Temporal.PlainDate,
+  disabled?: DisabledDateMatcher | DisabledDateMatcher[],
+  minDate?: Temporal.PlainDate,
+  maxDate?: Temporal.PlainDate
+): boolean {
+  // Check min/max bounds
+  if (minDate && isBeforeTemporal(date, minDate)) {
+    return true;
+  }
+  if (maxDate && isAfterTemporal(date, maxDate)) {
+    return true;
+  }
+
+  // No disabled matchers
+  if (!disabled) {
+    return false;
+  }
+
+  // Single matcher
+  if (!Array.isArray(disabled)) {
+    return matchesDisabledMatcher(date, disabled);
+  }
+
+  // Array of matchers (any match = disabled)
+  return disabled.some((matcher) => matchesDisabledMatcher(date, matcher));
+}
+
+/**
+ * Hook for checking if dates are disabled
+ */
+export function useIsDateDisabled(disabled?: DisabledDateMatcher | DisabledDateMatcher[], minDate?: Temporal.PlainDate, maxDate?: Temporal.PlainDate) {
+  return useCallback((date: Temporal.PlainDate) => isDateDisabled(date, disabled, minDate, maxDate), [disabled, minDate, maxDate]);
+}
+
+// =============================================================================
+// Selection State
+// =============================================================================
+
+/**
+ * Get the selection state for a date based on mode and current value
+ */
+export function getDateSelectionState(
+  date: Temporal.PlainDate,
+  mode: SelectionMode,
+  value: Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined
+): DateSelectionState {
+  // Default: not selected
+  const notSelected: DateSelectionState = {
+    isSelected: false,
+    rangePosition: "none",
+  };
+
+  if (value === undefined) {
+    return notSelected;
+  }
+
+  // Single mode
+  if (mode === "single") {
+    const singleValue = value as Temporal.PlainDate | undefined;
+    if (!singleValue || !isPlainDate(singleValue)) return notSelected;
+    return {
+      isSelected: isSameDateTemporal(date, singleValue),
+      rangePosition: "single",
+    };
+  }
+
+  // Multiple mode
+  if (mode === "multiple") {
+    const multiValue = value as Temporal.PlainDate[];
+    return {
+      isSelected: multiValue.some((d) => isSameDateTemporal(date, d)),
+      rangePosition: "single",
+    };
+  }
+
+  // Range mode
+  const rangeValue = value as DateRangeValue;
+  const { from, to } = rangeValue;
+
+  // No selection
+  if (!from && !to) {
+    return notSelected;
+  }
+
+  // Only from selected
+  if (from && !to) {
+    return {
+      isSelected: isSameDateTemporal(date, from),
+      rangePosition: "single",
+    };
+  }
+
+  // Only to selected (shouldn't happen normally, but handle it)
+  if (!from && to) {
+    return {
+      isSelected: isSameDateTemporal(date, to),
+      rangePosition: "single",
+    };
+  }
+
+  // Both from and to selected
+  const isFrom = isSameDateTemporal(date, from!);
+  const isTo = isSameDateTemporal(date, to!);
+  const isBetween = isBetweenTemporal(date, from!, to!);
+
+  if (!isBetween && !isFrom && !isTo) {
+    return notSelected;
+  }
+
+  // Same day for from and to
+  if (isFrom && isTo) {
+    return { isSelected: true, rangePosition: "single" };
+  }
+
+  // Start of range
+  if (isFrom) {
+    return { isSelected: true, rangePosition: "start" };
+  }
+
+  // End of range
+  if (isTo) {
+    return { isSelected: true, rangePosition: "end" };
+  }
+
+  // Middle of range
+  return { isSelected: true, rangePosition: "middle" };
+}
+
+/**
+ * Hook for getting selection state
+ */
+export function useSelectionState(mode: SelectionMode, value: Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined) {
+  return useCallback((date: Temporal.PlainDate) => getDateSelectionState(date, mode, value), [mode, value]);
+}
+
+// =============================================================================
+// Display Formatting
+// =============================================================================
+
+/**
+ * Default display format for a date (e.g., "Jan 15, 2025")
+ */
+export function defaultFormatDisplay(date: Temporal.PlainDate): string {
+  return formatDateMediumYear(date);
+}
+
+/**
+ * Format a range for display
+ */
+export function formatRangeDisplay(range: DateRangeValue | undefined, formatFn: (date: Temporal.PlainDate) => string = defaultFormatDisplay): string {
+  if (!range?.from && !range?.to) {
+    return "";
+  }
+
+  if (range.from && !range.to) {
+    return `${formatFn(range.from)} – ...`;
+  }
+
+  if (!range.from && range.to) {
+    return `... – ${formatFn(range.to)}`;
+  }
+
+  return `${formatFn(range.from!)} – ${formatFn(range.to!)}`;
+}
+
+/**
+ * Format multiple dates for display
+ */
+export function formatMultipleDisplay(dates: Temporal.PlainDate[] | undefined, formatFn: (date: Temporal.PlainDate) => string = defaultFormatDisplay): string {
+  if (!dates || dates.length === 0) {
+    return "";
+  }
+
+  if (dates.length === 1) {
+    return formatFn(dates[0]!);
+  }
+
+  if (dates.length <= 3) {
+    return dates.map(formatFn).join(", ");
+  }
+
+  return `${dates.length} dates selected`;
+}
+
+/**
+ * Get display value based on mode
+ */
+export function getDisplayValue(
+  mode: SelectionMode,
+  value: Temporal.PlainDate | DateRangeValue | Temporal.PlainDate[] | undefined,
+  formatFn: (date: Temporal.PlainDate) => string = defaultFormatDisplay
+): string {
+  if (mode === "single") {
+    const singleValue = value as Temporal.PlainDate | undefined;
+    return singleValue ? formatFn(singleValue) : "";
+  }
+
+  if (mode === "range") {
+    return formatRangeDisplay(value as DateRangeValue | undefined, formatFn);
+  }
+
+  return formatMultipleDisplay(value as Temporal.PlainDate[] | undefined, formatFn);
+}
+
+// =============================================================================
+// Month Grid Generation
+// =============================================================================
+
+export interface CalendarDay {
+  /** The date this day represents */
+  date: Temporal.PlainDate;
+  /** Whether this date is in the displayed month */
+  isCurrentMonth: boolean;
+  /** Whether this is today's date */
+  isToday: boolean;
+}
+
+/**
+ * Generate all days to display for a given month.
+ * Returns 42 days (6 weeks) to ensure consistent grid layout.
+ */
+export function useCalendarDays(month: Temporal.PlainDate, weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6 = 0): CalendarDay[] {
+  return useMemo(() => {
+    const todayDate = today();
+    const firstDayOfMonth = startOfMonth(month);
+    const startDate = startOfWeek(firstDayOfMonth, weekStartsOn);
+
+    const days: CalendarDay[] = [];
+
+    for (let i = 0; i < 42; i++) {
+      const date = addDays(startDate, i);
+      days.push({
+        date,
+        isCurrentMonth: isSameMonth(date, month),
+        isToday: isSameDay(date, todayDate),
+      });
+    }
+
+    return days;
+  }, [month, weekStartsOn]);
+}

package/src/components/Calendar/calendar.types.ts

@@ -0,0 +1,117 @@
+/**
+ * Calendar types for the generic date picker calendar component
+ *
+ * This component is used by DatePicker, DateTimePicker, and DateTimeRangePicker
+ * for consistent date selection UI.
+ */
+
+import type { Temporal, WeekStartsOn } from "../../date-time";
+
+/**
+ * Date range value
+ */
+export type DateRangeValue = {
+  from: Temporal.PlainDate | undefined;
+  to: Temporal.PlainDate | undefined;
+};
+
+/**
+ * Selection mode
+ */
+export type SelectionMode = "single" | "range" | "multiple";
+
+/**
+ * Disabled date matchers
+ */
+export type DisabledDateMatcher =
+  | Temporal.PlainDate
+  | Temporal.PlainDate[]
+  | ((date: Temporal.PlainDate) => boolean)
+  | { before: Temporal.PlainDate }
+  | { after: Temporal.PlainDate }
+  | { from: Temporal.PlainDate; to: Temporal.PlainDate };
+
+/**
+ * Preset option (generic over value type)
+ */
+export type PresetOption<T> = {
+  label: string;
+  value: T;
+};
+
+// ============================================================================
+// Discriminated Union Props
+// ============================================================================
+
+type CalendarBaseProps = {
+  /** Current month being displayed */
+  month: Temporal.PlainDate;
+  /** Called when month should change */
+  onMonthChange: (month: Temporal.PlainDate) => void;
+
+  /** Minimum selectable date */
+  minDate?: Temporal.PlainDate | undefined;
+  /** Maximum selectable date */
+  maxDate?: Temporal.PlainDate | undefined;
+  /** Disabled date matchers */
+  disabled?: DisabledDateMatcher | DisabledDateMatcher[] | undefined;
+
+  /** First day of week (0 = Sunday, 1 = Monday) */
+  weekStartsOn?: WeekStartsOn | undefined;
+
+  /** Show footer with Today/Cancel/Apply buttons */
+  showFooter?: boolean | undefined;
+  /** Show Today button (only if showFooter=true) */
+  showToday?: boolean | undefined;
+  /** Called when Apply is clicked */
+  onApply?: (() => void) | undefined;
+  /** Called when Cancel is clicked */
+  onCancel?: (() => void) | undefined;
+
+  /** Additional CSS class */
+  className?: string | undefined;
+};
+
+export type CalendarSingleProps = CalendarBaseProps & {
+  mode: "single";
+  value: Temporal.PlainDate | undefined;
+  onSelect: (date: Temporal.PlainDate | undefined) => void;
+  presets?: PresetOption<Temporal.PlainDate>[] | undefined;
+};
+
+export type CalendarRangeProps = CalendarBaseProps & {
+  mode: "range";
+  value: DateRangeValue | undefined;
+  onSelect: (range: DateRangeValue | undefined) => void;
+  presets?: PresetOption<DateRangeValue>[] | undefined;
+};
+
+export type CalendarMultipleProps = CalendarBaseProps & {
+  mode: "multiple";
+  value: Temporal.PlainDate[];
+  onSelect: (dates: Temporal.PlainDate[]) => void;
+  max?: number | undefined;
+  presets?: PresetOption<Temporal.PlainDate[]>[] | undefined;
+};
+
+/**
+ * Calendar props - discriminated union based on mode
+ */
+export type CalendarProps = CalendarSingleProps | CalendarRangeProps | CalendarMultipleProps;
+
+// ============================================================================
+// Internal Types
+// ============================================================================
+
+/**
+ * Position of a date within a range selection
+ */
+export type RangePosition = "start" | "middle" | "end" | "single" | "none";
+
+/**
+ * Selection state for a date cell
+ */
+export type DateSelectionState = {
+  isSelected: boolean;
+  rangePosition: RangePosition;
+};

package/src/components/Calendar/index.ts

@@ -0,0 +1,28 @@
+export { Calendar } from "./Calendar";
+export {
+  defaultFormatDisplay,
+  formatMultipleDisplay,
+  formatRangeDisplay,
+  getDateSelectionState,
+  getDisplayValue,
+  isAfterTemporal,
+  isBeforeTemporal,
+  isBetweenTemporal,
+  isDateDisabled,
+  isSameDateTemporal,
+  temporalToISO,
+  useIsDateDisabled,
+  useSelectionState,
+} from "./calendar.hooks";
+export type {
+  CalendarMultipleProps,
+  CalendarProps,
+  CalendarRangeProps,
+  CalendarSingleProps,
+  DateRangeValue,
+  DateSelectionState,
+  DisabledDateMatcher,
+  PresetOption,
+  RangePosition,
+  SelectionMode,
+} from "./calendar.types";

package/src/components/Card/Card.tsx

@@ -0,0 +1,47 @@
+import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
+
+export type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
+  /** Optional header title - string or ReactNode */
+  title?: React.ReactNode;
+  /** Optional action element displayed on the right side of the header */
+  headerAction?: React.ReactNode;
+};
+
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(({ className, title, headerAction, children, onClick, onKeyDown, ...props }, ref) => {
+  const isInteractive = !!onClick;
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (isInteractive && (e.key === "Enter" || e.key === " ")) {
+      e.preventDefault();
+      onClick?.(e as unknown as React.MouseEvent<HTMLDivElement>);
+    }
+    onKeyDown?.(e);
+  };
+
+  return (
+    // biome-ignore lint/a11y/noStaticElementInteractions: role="button" + tabIndex are added dynamically when onClick is present
+    <div
+      ref={ref}
+      className={cn(
+        "rounded-xl border border-border-normal bg-bg-normal p-6 text-fg-normal shadow",
+        isInteractive &&
+          "cursor-pointer transition-colors hover:border-border-strong focus-visible:outline-2 focus-visible:outline-border-strong focus-visible:outline-offset-2",
+        className
+      )}
+      onClick={onClick}
+      onKeyDown={handleKeyDown}
+      {...(isInteractive && { role: "button", tabIndex: 0 })}
+      {...props}
+    >
+      {(title || headerAction) && (
+        <header className="mb-4 flex items-start justify-between gap-4">
+          {title && <div className="font-semibold">{title}</div>}
+          {headerAction && <div className="shrink-0">{headerAction}</div>}
+        </header>
+      )}
+      {children}
+    </div>
+  );
+});
+Card.displayName = "Card";

package/src/components/Card/index.ts

@@ -0,0 +1 @@
+export { Card, type CardProps } from "./Card";

package/src/components/Checkbox/Checkbox.tsx

@@ -0,0 +1,144 @@
+import { useControllableState } from "@sixthshift/design-system/hooks";
+import { Label } from "@sixthshift/design-system/label";
+import { cn } from "@sixthshift/design-system/utils";
+import * as React from "react";
+
+export type CheckboxProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "value"> & {
+  /** Controlled checked state */
+  checked?: boolean | "indeterminate";
+  /** Default checked state for uncontrolled mode */
+  defaultChecked?: boolean | "indeterminate";
+  /** Called when checked state changes */
+  onCheckedChange?: (checked: boolean) => void;
+  /** Input name for form submission */
+  name?: string;
+  /** Value submitted with form (defaults to "on") */
+  value?: string;
+  /** Label rendered next to the checkbox. Wraps in a <label> for a11y. */
+  label?: React.ReactNode;
+  /** Classes applied to the wrapping label element when `label` is provided */
+  labelClassName?: string;
+};
+
+const CheckIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="3"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    className="h-3 w-3"
+    aria-hidden="true"
+  >
+    <polyline points="20 6 9 17 4 12" />
+  </svg>
+);
+
+const IndeterminateIcon = () => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="3"
+    strokeLinecap="round"
+    className="h-3 w-3"
+    aria-hidden="true"
+  >
+    <line x1="5" y1="12" x2="19" y2="12" />
+  </svg>
+);
+
+const Checkbox = React.forwardRef<HTMLButtonElement, CheckboxProps>(
+  (
+    {
+      className,
+      checked: controlledChecked,
+      defaultChecked = false,
+      onCheckedChange,
+      disabled,
+      name,
+      value = "on",
+      label,
+      labelClassName,
+      id: idProp,
+      ...props
+    },
+    ref
+  ) => {
+    const generatedId = React.useId();
+    const id = idProp ?? (label ? generatedId : undefined);
+
+    const [checked, setChecked] = useControllableState({
+      value: controlledChecked,
+      defaultValue: defaultChecked,
+      onChange: onCheckedChange as ((value: boolean | "indeterminate") => void) | undefined,
+    });
+
+    const isChecked = checked === true;
+    const isIndeterminate = checked === "indeterminate";
+
+    const button = (
+      <>
+        {/* biome-ignore lint/a11y/useSemanticElements: Custom checkbox implementation with button role="checkbox" is WAI-ARIA best practice for styled checkboxes */}
+        <button
+          type="button"
+          role="checkbox"
+          id={id}
+          aria-checked={isIndeterminate ? "mixed" : isChecked}
+          data-state={isIndeterminate ? "indeterminate" : isChecked ? "checked" : "unchecked"}
+          disabled={disabled}
+          ref={ref}
+          onClick={() => setChecked(!isChecked)}
+          className={cn(
+            "peer h-4 w-4 shrink-0 cursor-pointer rounded-xs border border-border-brand shadow focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-focus-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+            (isChecked || isIndeterminate) && "bg-bg-brand text-fg-on-brand",
+            className
+          )}
+          {...props}
+        >
+          <span className="flex items-center justify-center text-current">
+            {isChecked && <CheckIcon />}
+            {isIndeterminate && <IndeterminateIcon />}
+          </span>
+        </button>
+        {name && (
+          <input
+            type="checkbox"
+            aria-hidden
+            tabIndex={-1}
+            name={name}
+            value={value}
+            checked={isChecked}
+            disabled={disabled}
+            readOnly
+            style={{
+              position: "absolute",
+              pointerEvents: "none",
+              opacity: 0,
+              margin: 0,
+              width: 0,
+              height: 0,
+            }}
+          />
+        )}
+      </>
+    );
+
+    if (!label) return button;
+
+    return (
+      <div className={cn("flex items-center gap-2", labelClassName)}>
+        {button}
+        <Label htmlFor={id} className={cn(disabled && "cursor-not-allowed opacity-50")}>
+          {label}
+        </Label>
+      </div>
+    );
+  }
+);
+Checkbox.displayName = "Checkbox";
+
+export { Checkbox };

package/src/components/Checkbox/index.ts

@@ -0,0 +1 @@
+export { Checkbox, type CheckboxProps } from "./Checkbox";