@sixthshift/design-system 0.1.0

package/src/date-time/validate.ts

@@ -0,0 +1,278 @@
+/**
+ * Validation utilities: string validation and type guards
+ *
+ * Use these to validate input before parsing, or to narrow types at runtime.
+ */
+
+import { Temporal } from "@js-temporal/polyfill";
+
+// =============================================================================
+// String validation (is this string valid ISO 8601?)
+// =============================================================================
+
+/**
+ * Check if a string is a valid ISO 8601 date (YYYY-MM-DD)
+ *
+ * @example
+ * isISODate('2025-01-15')  // true
+ * isISODate('2025-13-45')  // false
+ * isISODate('not a date')  // false
+ */
+export function isISODate(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    Temporal.PlainDate.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is a valid ISO 8601 time (HH:mm:ss or HH:mm)
+ *
+ * @example
+ * isISOTime('14:30:00')  // true
+ * isISOTime('14:30')     // true
+ * isISOTime('25:00:00')  // false
+ */
+export function isISOTime(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    Temporal.PlainTime.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is a valid ISO 8601 datetime (YYYY-MM-DDTHH:mm:ss)
+ *
+ * @example
+ * isISODateTime('2025-01-15T14:30:00')  // true
+ * isISODateTime('2025-01-15')           // false (date only)
+ * isISODateTime('invalid')              // false
+ */
+export function isISODateTime(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    Temporal.PlainDateTime.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is a valid ISO 8601 instant (with Z or offset)
+ *
+ * @example
+ * isISOInstant('2025-01-15T14:30:00.000Z')     // true
+ * isISOInstant('2025-01-15T14:30:00+05:30')    // true
+ * isISOInstant('2025-01-15T14:30:00')          // false (no timezone)
+ * isISOInstant('2025-01-15')                   // false (date only)
+ */
+export function isISOInstant(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    Temporal.Instant.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is a valid ISO 8601 zoned datetime
+ *
+ * @example
+ * isISOZoned('2025-01-15T14:30:00[America/New_York]')           // true
+ * isISOZoned('2025-01-15T14:30:00-05:00[America/New_York]')     // true
+ * isISOZoned('2025-01-15T14:30:00Z')                            // false (instant, not zoned)
+ */
+export function isISOZoned(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  // Must contain a bracketed timezone identifier
+  if (!value.includes("[") || !value.includes("]")) return false;
+  try {
+    Temporal.ZonedDateTime.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is a valid ISO 8601 duration
+ *
+ * @example
+ * isISODuration('PT1H30M')    // true (1 hour 30 minutes)
+ * isISODuration('P1D')        // true (1 day)
+ * isISODuration('P1Y2M3D')    // true (1 year 2 months 3 days)
+ * isISODuration('1 hour')     // false
+ */
+export function isISODuration(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  try {
+    Temporal.Duration.from(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a string is any valid ISO 8601 date/time format
+ * (date, time, datetime, instant, or zoned)
+ *
+ * @example
+ * isISOString('2025-01-15')                    // true
+ * isISOString('2025-01-15T14:30:00.000Z')      // true
+ * isISOString('not a date')                    // false
+ */
+export function isISOString(value: unknown): value is string {
+  return isISODate(value) || isISOTime(value) || isISODateTime(value) || isISOInstant(value) || isISOZoned(value);
+}
+
+// =============================================================================
+// Type guards (is this value a Temporal type?)
+// =============================================================================
+
+/**
+ * Check if a value is a Temporal.PlainDate
+ */
+export function isPlainDate(value: unknown): value is Temporal.PlainDate {
+  return value instanceof Temporal.PlainDate;
+}
+
+/**
+ * Check if a value is a Temporal.PlainTime
+ */
+export function isPlainTime(value: unknown): value is Temporal.PlainTime {
+  return value instanceof Temporal.PlainTime;
+}
+
+/**
+ * Check if a value is a Temporal.PlainDateTime
+ */
+export function isPlainDateTime(value: unknown): value is Temporal.PlainDateTime {
+  return value instanceof Temporal.PlainDateTime;
+}
+
+/**
+ * Check if a value is a Temporal.Instant
+ */
+export function isInstant(value: unknown): value is Temporal.Instant {
+  return value instanceof Temporal.Instant;
+}
+
+/**
+ * Check if a value is a Temporal.ZonedDateTime
+ */
+export function isZonedDateTime(value: unknown): value is Temporal.ZonedDateTime {
+  return value instanceof Temporal.ZonedDateTime;
+}
+
+/**
+ * Check if a value is a Temporal.Duration
+ */
+export function isDuration(value: unknown): value is Temporal.Duration {
+  return value instanceof Temporal.Duration;
+}
+
+/**
+ * Check if a value is any Temporal date/time type
+ */
+export function isTemporal(
+  value: unknown
+): value is Temporal.PlainDate | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.Instant | Temporal.ZonedDateTime | Temporal.Duration {
+  return isPlainDate(value) || isPlainTime(value) || isPlainDateTime(value) || isInstant(value) || isZonedDateTime(value) || isDuration(value);
+}
+
+// =============================================================================
+// Validation with error messages
+// =============================================================================
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+}
+
+/**
+ * Validate an ISO date string and return detailed error if invalid
+ */
+export function validateISODate(value: unknown): ValidationResult {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, got ${typeof value}` };
+  }
+  try {
+    Temporal.PlainDate.from(value);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof Error ? e.message : "Invalid ISO date",
+    };
+  }
+}
+
+/**
+ * Validate an ISO instant string and return detailed error if invalid
+ */
+export function validateISOInstant(value: unknown): ValidationResult {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, got ${typeof value}` };
+  }
+  try {
+    Temporal.Instant.from(value);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof Error ? e.message : "Invalid ISO instant",
+    };
+  }
+}
+
+/**
+ * Validate an ISO zoned datetime string and return detailed error if invalid
+ */
+export function validateISOZoned(value: unknown): ValidationResult {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, got ${typeof value}` };
+  }
+  if (!value.includes("[") || !value.includes("]")) {
+    return {
+      valid: false,
+      error: "Zoned datetime must include timezone in brackets, e.g. [America/New_York]",
+    };
+  }
+  try {
+    Temporal.ZonedDateTime.from(value);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof Error ? e.message : "Invalid ISO zoned datetime",
+    };
+  }
+}
+
+/**
+ * Validate an ISO duration string and return detailed error if invalid
+ */
+export function validateISODuration(value: unknown): ValidationResult {
+  if (typeof value !== "string") {
+    return { valid: false, error: `Expected string, got ${typeof value}` };
+  }
+  try {
+    Temporal.Duration.from(value);
+    return { valid: true };
+  } catch (e) {
+    return {
+      valid: false,
+      error: e instanceof Error ? e.message : "Invalid ISO duration",
+    };
+  }
+}

package/src/hooks/index.ts

@@ -0,0 +1,10 @@
+export { useCollapsible } from "./useCollapsible";
+export { useControllableState } from "./useControllableState";
+export { useDebouncedCallback } from "./useDebouncedCallback";
+export { useDebouncedState } from "./useDebouncedState";
+export { type DeviceFormFactor, useDeviceFormFactor } from "./useDeviceFormFactor";
+export { useLocalStorage } from "./useLocalStorage";
+export { useMergedFloatingRef } from "./useMergedFloatingRef";
+export { usePresence } from "./usePresence";
+export { type StackItem, useStack } from "./useStack";
+export { bootstrapTheme, type ResolvedTheme, type Theme, useTheme } from "./useTheme";

package/src/hooks/useCollapsible.ts

@@ -0,0 +1,16 @@
+import { useCallback, useState } from "react";
+
+export function useCollapsible(defaultExpanded = true) {
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  const toggle = useCallback(() => setExpanded((prev) => !prev), []);
+  const collapse = useCallback(() => setExpanded(false), []);
+  const expand = useCallback(() => setExpanded(true), []);
+
+  return {
+    expanded,
+    toggle,
+    collapse,
+    expand,
+  };
+}

package/src/hooks/useControllableState.ts

@@ -0,0 +1,54 @@
+import { useCallback, useRef, useState } from "react";
+
+declare const process: undefined | { env?: { NODE_ENV?: string } };
+
+interface UseControllableStateOptions<T> {
+  /** Controlled value */
+  value?: T | undefined;
+  /** Default value for uncontrolled mode */
+  defaultValue: T;
+  /** Callback when value changes */
+  onChange?: ((value: T) => void) | undefined;
+}
+
+/**
+ * Hook for managing controlled/uncontrolled state pattern.
+ * If `value` is provided, the component is controlled.
+ * Otherwise, it manages its own internal state starting with `defaultValue`.
+ */
+export function useControllableState<T>({ value: controlledValue, defaultValue, onChange }: UseControllableStateOptions<T>): [T, (value: T) => void] {
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
+
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : uncontrolledValue;
+
+  const wasControlledRef = useRef(isControlled);
+  if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+    if (wasControlledRef.current && !isControlled) {
+      console.warn(
+        "useControllableState: switched from controlled to uncontrolled. This usually means `value` changed from a defined value to `undefined`. Decide between controlled and uncontrolled for the lifetime of the component."
+      );
+    }
+    if (!wasControlledRef.current && isControlled) {
+      console.warn(
+        "useControllableState: switched from uncontrolled to controlled. This usually means `value` changed from `undefined` to a defined value. Use `defaultValue` for uncontrolled components, or provide `value` from the first render."
+      );
+    }
+    if (isControlled && !onChange) {
+      console.warn("useControllableState: controlled component has `value` but no `onChange`. The component will be read-only.");
+    }
+  }
+  wasControlledRef.current = isControlled;
+
+  const setValue = useCallback(
+    (newValue: T) => {
+      if (!isControlled) {
+        setUncontrolledValue(newValue);
+      }
+      onChange?.(newValue);
+    },
+    [isControlled, onChange]
+  );
+
+  return [value, setValue];
+}

package/src/hooks/useDebouncedCallback.ts

@@ -0,0 +1,21 @@
+import { useCallback, useRef } from "react";
+
+/**
+ * Returns a debounced version of the callback.
+ * The callback is invoked after `delay` ms of inactivity.
+ */
+export const useDebouncedCallback = <T extends (...args: never[]) => void>(callback: T, delay: number): T => {
+  // Passed explicitly: React 19's types dropped the zero-argument `useRef`
+  // overload, so the initial value has to be spelled out to build on both 18 and 19.
+  const timeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
+  return useCallback(
+    ((...args: Parameters<T>) => {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = setTimeout(() => callbackRef.current(...args), delay);
+    }) as T,
+    [delay]
+  );
+};

package/src/hooks/useDebouncedState.ts

@@ -0,0 +1,20 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Debounces a value by delaying updates until after the specified delay.
+ * Useful for delaying API calls until user stops typing.
+ *
+ * @param value - The value to debounce
+ * @param delay - The delay in milliseconds
+ * @returns The debounced value
+ */
+export const useDebouncedState = <T>(value: T, delay: number): T => {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+};

package/src/hooks/useDeviceFormFactor.ts

@@ -0,0 +1,49 @@
+import { useSyncExternalStore } from "react";
+
+/**
+ * Breakpoint thresholds for adaptive rendering.
+ *
+ * These define the minimum width for each form factor:
+ * - mobile:  0 – 639px
+ * - tablet:  640 – 1023px
+ * - desktop: 1024px+
+ */
+const breakpoints = {
+  mobile: 0,
+  tablet: 640,
+  desktop: 1024,
+} as const;
+
+export type DeviceFormFactor = keyof typeof breakpoints;
+
+function getFormFactor(width: number): DeviceFormFactor {
+  if (width >= breakpoints.desktop) return "desktop";
+  if (width >= breakpoints.tablet) return "tablet";
+  return "mobile";
+}
+
+function getServerSnapshot(): DeviceFormFactor {
+  return "desktop";
+}
+
+function getSnapshot(): DeviceFormFactor {
+  return getFormFactor(window.innerWidth);
+}
+
+function subscribe(callback: () => void): () => void {
+  window.addEventListener("resize", callback);
+  return () => window.removeEventListener("resize", callback);
+}
+
+/**
+ * Returns the current device form factor based on viewport width.
+ *
+ * - mobile:  0 – 639px
+ * - tablet:  640 – 1023px
+ * - desktop: 1024px+
+ *
+ * Uses useSyncExternalStore for efficient subscription to resize events.
+ */
+export function useDeviceFormFactor(): DeviceFormFactor {
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,67 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+type SetValue<T> = T | ((prev: T) => T);
+
+function getStorageValue<T>(key: string, defaultValue: T): T {
+  if (typeof window === "undefined") {
+    return defaultValue;
+  }
+
+  try {
+    const item = window.localStorage.getItem(key);
+    return item ? (JSON.parse(item) as T) : defaultValue;
+  } catch {
+    return defaultValue;
+  }
+}
+
+function setStorageValue<T>(key: string, value: T): void {
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  try {
+    const serialized = JSON.stringify(value);
+    window.localStorage.setItem(key, serialized);
+    window.dispatchEvent(new StorageEvent("storage", { key, newValue: serialized }));
+  } catch {
+    // Storage full or unavailable
+  }
+}
+
+export function useLocalStorage<T>(key: string, defaultValue: T): [T, (value: SetValue<T>) => void] {
+  const subscribe = useCallback(
+    (callback: () => void) => {
+      const handleStorage = (e: StorageEvent) => {
+        if (e.key === key || e.key === null) {
+          callback();
+        }
+      };
+
+      window.addEventListener("storage", handleStorage);
+      return () => window.removeEventListener("storage", handleStorage);
+    },
+    [key]
+  );
+
+  const getSnapshot = useCallback(() => {
+    return JSON.stringify(getStorageValue(key, defaultValue));
+  }, [key, defaultValue]);
+
+  const getServerSnapshot = useCallback(() => {
+    return JSON.stringify(defaultValue);
+  }, [defaultValue]);
+
+  const storedValue = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+
+  const setValue = useCallback(
+    (value: SetValue<T>) => {
+      const currentValue = getStorageValue(key, defaultValue);
+      const newValue = value instanceof Function ? value(currentValue) : value;
+      setStorageValue(key, newValue);
+    },
+    [key, defaultValue]
+  );
+
+  return [JSON.parse(storedValue) as T, setValue];
+}

package/src/hooks/useMergedFloatingRef.ts

@@ -0,0 +1,29 @@
+import { useCallback } from "react";
+import type { WritableRefObject } from "../internal/types";
+
+type FloatingRefs = {
+  setFloating: (node: HTMLElement | null) => void;
+};
+
+type PresenceRef = (node: HTMLElement | null) => void;
+
+type ConsumerRef<T extends HTMLElement> = React.Ref<T> | undefined;
+
+/**
+ * Merges a floating-ui ref, a usePresence ref, and an optional consumer ref
+ * into a single callback ref. Used by Modal, Sheet, and Toast.
+ */
+export function useMergedFloatingRef<T extends HTMLElement = HTMLElement>(floatingRefs: FloatingRefs, presenceRef: PresenceRef, consumerRef?: ConsumerRef<T>) {
+  return useCallback(
+    (node: T | null) => {
+      floatingRefs.setFloating(node);
+      presenceRef(node);
+      if (typeof consumerRef === "function") {
+        consumerRef(node);
+      } else if (consumerRef && "current" in consumerRef) {
+        (consumerRef as WritableRefObject<T | null>).current = node;
+      }
+    },
+    [floatingRefs, presenceRef, consumerRef]
+  );
+}

package/src/hooks/usePresence.ts

@@ -0,0 +1,127 @@
+import { type RefCallback, useCallback, useEffect, useRef, useState } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+type PresenceState = "hidden" | "entering" | "visible" | "exiting";
+
+type UsePresenceReturn = {
+  /** Ref callback to attach to the animated element */
+  ref: RefCallback<HTMLElement>;
+  /** Current presence state */
+  state: PresenceState;
+  /** Whether the component should be mounted in the DOM */
+  isMounted: boolean;
+  /** Whether the component is visible (entering or fully visible) */
+  isVisible: boolean;
+  /** Call to start showing the component */
+  show: () => void;
+  /** Call to start hiding the component, with optional callback after animation */
+  hide: (onComplete?: () => void) => void;
+};
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * Manages mount/unmount presence with CSS animation support.
+ *
+ * Coordinates component lifecycle with CSS @keyframes animations by listening
+ * to `animationend` events. This is more robust than setTimeout because:
+ * 1. The browser tells us when the animation actually ends
+ * 2. No need to keep JS duration in sync with CSS duration
+ * 3. Works correctly even if animations are interrupted
+ *
+ * @example
+ * ```tsx
+ * function Modal({ open, onClose }) {
+ *   const { ref, state, isMounted, show, hide } = usePresence();
+ *
+ *   useEffect(() => {
+ *     if (open) show();
+ *   }, [open, show]);
+ *
+ *   if (!isMounted) return null;
+ *
+ *   return (
+ *     <div
+ *       ref={ref}
+ *       data-state={state}
+ *       className={cn(
+ *         state === "entering" && "animate-fade-in",
+ *         state === "exiting" && "animate-fade-out",
+ *       )}
+ *     >
+ *       ...
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePresence(): UsePresenceReturn {
+  const [state, setState] = useState<PresenceState>("hidden");
+  const nodeRef = useRef<HTMLElement | null>(null);
+  const onExitCompleteRef = useRef<(() => void) | null>(null);
+
+  // Track if we were exiting to know when to call the callback
+  const wasExitingRef = useRef(false);
+
+  // Handle animation end events
+  const handleAnimationEnd = useCallback(() => {
+    setState((current) => {
+      if (current === "entering") return "visible";
+      if (current === "exiting") return "hidden";
+      return current;
+    });
+  }, []);
+
+  // Call exit callback after state transitions to hidden (after render completes)
+  // This avoids the "Cannot update a component while rendering" warning
+  useEffect(() => {
+    if (state === "exiting") {
+      wasExitingRef.current = true;
+    } else if (state === "hidden" && wasExitingRef.current) {
+      wasExitingRef.current = false;
+      const callback = onExitCompleteRef.current;
+      onExitCompleteRef.current = null;
+      callback?.();
+    }
+  }, [state]);
+
+  // Ref callback to manage event listeners
+  const ref: RefCallback<HTMLElement> = useCallback(
+    (node) => {
+      // Cleanup old node
+      if (nodeRef.current) {
+        nodeRef.current.removeEventListener("animationend", handleAnimationEnd);
+      }
+
+      // Setup new node
+      nodeRef.current = node;
+      if (node) {
+        node.addEventListener("animationend", handleAnimationEnd);
+      }
+    },
+    [handleAnimationEnd]
+  );
+
+  const show = useCallback(() => {
+    setState("entering");
+  }, []);
+
+  const hide = useCallback((onComplete?: () => void) => {
+    onExitCompleteRef.current = onComplete ?? null;
+    setState("exiting");
+  }, []);
+
+  return {
+    ref,
+    state,
+    isMounted: state !== "hidden",
+    isVisible: state === "visible" || state === "entering",
+    show,
+    hide,
+  };
+}