@sixthshift/design-system 0.1.0

package/src/hooks/useStack.ts

@@ -0,0 +1,99 @@
+import { type Dispatch, type Reducer, startTransition, useCallback, useEffect, useReducer } from "react";
+
+type Id = string | number;
+type Transition = {
+  duration: number;
+};
+
+export type StackItem = {
+  id: Id;
+  transition?: Transition;
+};
+
+type Action<T extends StackItem> =
+  | { type: "push"; item: T }
+  | { type: "pop"; transition?: Transition }
+  | { type: "remove"; id: Id; transition?: Transition }
+  | { type: "update"; item: Partial<T> & StackItem }
+  | { type: "clear"; transition?: Transition };
+
+export type StackDispatch<T extends StackItem> = Dispatch<Action<T>>;
+
+function createReducer<T extends StackItem>(): Reducer<T[], Action<T>> {
+  return (state: T[], action: Action<T>) => {
+    switch (action.type) {
+      case "push": {
+        if (state.some((item) => item.id === action.item.id)) {
+          return state;
+        } else {
+          return [...state, action.item];
+        }
+      }
+      case "pop": {
+        const firstItems = state.slice(0, -1);
+        if (action.transition) {
+          const lastItem = {
+            ...state.at(-1),
+            transition: action.transition,
+          } as T;
+          return [...firstItems, lastItem];
+        }
+
+        return firstItems;
+      }
+      case "remove": {
+        if (action.transition) {
+          return state.map((s) => (s.id !== action.id ? s : { ...s, transition: action.transition }));
+        }
+
+        return state.filter((s) => s.id !== action.id);
+      }
+      case "update": {
+        return state.map((s) => (s.id !== action.item.id ? s : { ...s, ...action.item }));
+      }
+      case "clear": {
+        if (action.transition) {
+          // Mark all items for transition-based removal
+          return state.map((s) => ({ ...s, transition: action.transition }));
+        }
+        return [];
+      }
+      default: {
+        return state;
+      }
+    }
+  };
+}
+
+export function useStack<T extends StackItem>(initialStack: T[] = []): [T[], StackDispatch<T>] {
+  const reducer = createReducer<T>();
+
+  const [state, dispatch] = useReducer(reducer, initialStack);
+
+  useEffect(() => {
+    const itemsToRemove = state.filter((item) => item.transition);
+
+    if (itemsToRemove.length === 0) {
+      return;
+    }
+
+    itemsToRemove.reverse().forEach((itemToRemove) => {
+      setTimeout(
+        () => {
+          dispatch({ type: "remove", id: itemToRemove.id });
+        }, // We found the item by the `transition` property, so we can be sure it exists.
+        (itemToRemove.transition as Transition).duration
+      );
+    });
+  }, [state]);
+
+  // Memoize the dispatch wrapper to prevent unnecessary re-renders
+  // dispatch from useReducer is stable, so this only creates once
+  const wrappedDispatch = useCallback((params: Action<T>) => {
+    startTransition(() => {
+      dispatch(params);
+    });
+  }, []);
+
+  return [state, wrappedDispatch];
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,105 @@
+import { useCallback, useSyncExternalStore } from "react";
+
+export type Theme = "light" | "dark" | "system";
+export type ResolvedTheme = "light" | "dark";
+
+const STORAGE_KEY = "theme";
+const listeners = new Set<() => void>();
+
+function emit(): void {
+  for (const fn of listeners) fn();
+}
+
+function getSystemTheme(): ResolvedTheme {
+  if (typeof window === "undefined") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function readTheme(): Theme {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return "system";
+    const parsed = JSON.parse(raw);
+    if (parsed === "light" || parsed === "dark" || parsed === "system") return parsed;
+    return "system";
+  } catch {
+    return "system";
+  }
+}
+
+function writeTheme(theme: Theme): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(theme));
+  } catch {
+    // Storage full or unavailable
+  }
+  paint(theme);
+  emit();
+}
+
+function paint(theme: Theme): void {
+  if (typeof document === "undefined") return;
+  document.documentElement.dataset.theme = theme === "system" ? getSystemTheme() : theme;
+}
+
+function subscribe(callback: () => void): () => void {
+  listeners.add(callback);
+  return () => listeners.delete(callback);
+}
+
+function getSnapshot(): Theme {
+  return readTheme();
+}
+
+function getServerSnapshot(): Theme {
+  return "system";
+}
+
+/**
+ * Apply the stored theme now, and subscribe to OS color-scheme changes and
+ * cross-tab `storage` events. If nothing is stored yet, seeds `"system"` so
+ * the source of truth always exists. Call once at app bootstrap.
+ */
+export function bootstrapTheme(): () => void {
+  const theme = readTheme();
+  if (!localStorage.getItem(STORAGE_KEY)) {
+    writeTheme("system");
+  }
+  paint(theme);
+
+  if (typeof window === "undefined") return () => {};
+
+  const mq = window.matchMedia("(prefers-color-scheme: dark)");
+  const onSystemChange = () => {
+    if (readTheme() === "system") {
+      paint("system");
+      emit();
+    }
+  };
+  mq.addEventListener("change", onSystemChange);
+
+  const onStorage = (e: StorageEvent) => {
+    if (e.key !== STORAGE_KEY) return;
+    paint(readTheme());
+    emit();
+  };
+  window.addEventListener("storage", onStorage);
+
+  return () => {
+    mq.removeEventListener("change", onSystemChange);
+    window.removeEventListener("storage", onStorage);
+  };
+}
+
+/** Read/write theme hook. Reads from localStorage via useSyncExternalStore; no effects. */
+export function useTheme() {
+  const theme = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const resolvedTheme: ResolvedTheme = theme === "system" ? getSystemTheme() : theme;
+
+  const setTheme = useCallback((next: Theme) => writeTheme(next), []);
+  const toggleTheme = useCallback(() => {
+    writeTheme(readTheme() === "dark" ? "light" : "dark");
+  }, []);
+
+  return { theme, setTheme, resolvedTheme, toggleTheme };
+}

package/src/internal/Slot.tsx

@@ -0,0 +1,79 @@
+import * as React from "react";
+import type { WritableRefObject } from "./types";
+
+/**
+ * Merges multiple refs into a single callback ref.
+ */
+function mergeRefs<T>(...refs: (React.Ref<T> | undefined)[]): React.RefCallback<T> {
+  return (node) => {
+    refs.forEach((ref) => {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref != null) {
+        (ref as WritableRefObject<T | null>).current = node;
+      }
+    });
+  };
+}
+
+/**
+ * Merges two props objects, composing event handlers and merging classNames.
+ */
+function mergeProps(parentProps: Record<string, unknown>, childProps: Record<string, unknown>): Record<string, unknown> {
+  const merged: Record<string, unknown> = { ...parentProps };
+
+  for (const key of Object.keys(childProps)) {
+    const parentValue = parentProps[key];
+    const childValue = childProps[key];
+
+    // Compose event handlers
+    if (key.startsWith("on") && typeof parentValue === "function" && typeof childValue === "function") {
+      merged[key] = (...args: unknown[]) => {
+        childValue(...args);
+        parentValue(...args);
+      };
+    }
+    // Merge classNames
+    else if (key === "className" && parentValue && childValue) {
+      merged[key] = `${parentValue} ${childValue}`;
+    }
+    // Merge styles
+    else if (key === "style" && parentValue && childValue) {
+      merged[key] = { ...(parentValue as object), ...(childValue as object) };
+    }
+    // Child value takes precedence for other props
+    else if (childValue !== undefined) {
+      merged[key] = childValue;
+    }
+  }
+
+  return merged;
+}
+
+export type SlotProps = React.HTMLAttributes<HTMLElement> & {
+  children?: React.ReactNode;
+};
+
+/**
+ * Slot merges its props onto its immediate child element.
+ * Used for the "asChild" pattern - allows replacing the rendered element
+ * while keeping all component behavior.
+ */
+export const Slot = React.forwardRef<HTMLElement, SlotProps>(({ children, ...props }, ref) => {
+  if (!React.isValidElement(children)) {
+    console.warn("Slot requires a valid React element as its child");
+    return null;
+  }
+
+  // React 19 moved `ref` into props and warns when the legacy `element.ref`
+  // getter is read; React 18 only has the getter. Check props first so neither
+  // version complains.
+  const childProps = children.props as Record<string, unknown> & { ref?: React.Ref<HTMLElement> };
+  const childRef = childProps.ref ?? (children as React.ReactElement & { ref?: React.Ref<HTMLElement> }).ref;
+
+  return React.cloneElement(children, {
+    ...mergeProps(props, childProps),
+    ref: ref ? mergeRefs(ref, childRef) : childRef,
+  } as React.HTMLAttributes<HTMLElement>);
+});
+Slot.displayName = "Slot";

package/src/internal/index.ts

@@ -0,0 +1,2 @@
+export { Slot, type SlotProps } from "./Slot";
+export type { WritableRefObject } from "./types";

package/src/internal/rovingFocus.ts

@@ -0,0 +1,39 @@
+/**
+ * Roving-focus helpers for composite widgets.
+ *
+ * A `radiogroup` is a single tab stop: exactly one option carries
+ * `tabIndex={0}` and the arrow keys move between options. Leaving every option
+ * separately tabbable — the browser default for a row of buttons — breaks the
+ * WAI-ARIA radio pattern.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/radio/
+ */
+
+/**
+ * Given the index of the currently focused option, return the index the key
+ * should move to, or `null` if the key is not a navigation key.
+ *
+ * Callers should pass an already-filtered list of *enabled* options, so
+ * disabled ones are skipped for free. Navigation wraps at both ends.
+ *
+ * `currentIndex` may be -1 (nothing focused yet), in which case forward keys
+ * land on the first option and backward keys on the last.
+ */
+export function getRovingTargetIndex(key: string, currentIndex: number, count: number): number | null {
+  if (count === 0) return null;
+
+  switch (key) {
+    case "Home":
+      return 0;
+    case "End":
+      return count - 1;
+    case "ArrowRight":
+    case "ArrowDown":
+      return currentIndex < 0 ? 0 : (currentIndex + 1) % count;
+    case "ArrowLeft":
+    case "ArrowUp":
+      return currentIndex < 0 ? count - 1 : (currentIndex - 1 + count) % count;
+    default:
+      return null;
+  }
+}

package/src/internal/types.ts

@@ -0,0 +1,10 @@
+/**
+ * A ref object whose `current` this library writes to.
+ *
+ * React 18's types spell this `MutableRefObject<T>`; React 19 removed that alias
+ * and made `RefObject<T>` itself mutable. Neither name type-checks under both
+ * versions, so the structural shape is written out instead — it is what both
+ * aliases resolve to, and it keeps the source valid across the whole
+ * `react@^18.2.0 || ^19.0.0` peer range.
+ */
+export type WritableRefObject<T> = { current: T };

package/src/lib/EmptyBoundary.tsx

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+
+type EmptyBoundaryProps = {
+  isEmpty: boolean;
+  fallback: ReactNode;
+  children: ReactNode;
+};
+
+export const EmptyBoundary = ({ isEmpty, fallback, children }: EmptyBoundaryProps) => {
+  if (isEmpty) return <>{fallback}</>;
+  return <>{children}</>;
+};

package/src/lib/ErrorBoundary.tsx

@@ -0,0 +1,48 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+export type ErrorFallbackProps = {
+  error: Error;
+  reset: () => void;
+};
+
+type Props = {
+  fallback: ReactNode | ((props: ErrorFallbackProps) => ReactNode);
+  children: ReactNode;
+};
+
+type State = {
+  error: Error | null;
+};
+
+export class ErrorBoundary extends Component<Props, State> {
+  constructor(props: Props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error: Error): State {
+    return { error };
+  }
+
+  override componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    console.error("ErrorBoundary caught:", error, errorInfo);
+  }
+
+  reset = () => {
+    this.setState({ error: null });
+  };
+
+  override render() {
+    const { error } = this.state;
+    const { fallback, children } = this.props;
+
+    if (error) {
+      if (typeof fallback === "function") {
+        return fallback({ error, reset: this.reset });
+      }
+      return fallback;
+    }
+
+    return children;
+  }
+}

package/src/lib/contexts/ComponentsContext/ComponentsContext.tsx

@@ -0,0 +1,34 @@
+import { createContext, type PropsWithChildren, type ReactNode, useContext } from "react";
+
+type LinkProps = {
+  href: string;
+  className?: string;
+  title?: string;
+  children: ReactNode;
+};
+
+type LinkComponent = React.ComponentType<LinkProps>;
+
+type Components = {
+  Link: LinkComponent;
+};
+
+const DefaultLink = ({ href, children, ...props }: LinkProps) => (
+  <a href={href} {...props}>
+    {children}
+  </a>
+);
+
+const defaultComponents: Components = { Link: DefaultLink };
+
+const ComponentsContext = createContext<Components>(defaultComponents);
+
+export type ComponentsProviderProps = PropsWithChildren<{
+  components: Partial<Components>;
+}>;
+
+export const ComponentsProvider = ({ components, children }: ComponentsProviderProps) => (
+  <ComponentsContext.Provider value={{ ...defaultComponents, ...components }}>{children}</ComponentsContext.Provider>
+);
+
+export const useComponents = () => useContext(ComponentsContext);

package/src/lib/contexts/ComponentsContext/index.ts

@@ -0,0 +1 @@
+export { ComponentsProvider, type ComponentsProviderProps, useComponents } from "./ComponentsContext";

package/src/lib/contexts/OverlayContext/OverlayContext.tsx

@@ -0,0 +1,93 @@
+import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
+import { type StackItem, useStack } from "@sixthshift/design-system/hooks";
+import { createContext, type FunctionComponent, type PropsWithChildren, useContext, useEffect, useMemo } from "react";
+
+type OverlayContextProps = {
+  modal?: FloatingPortalProps["root"];
+  toast?: FloatingPortalProps["root"];
+};
+
+/** Stack item for overlays - component is a self-contained wrapper */
+type OverlayStackItem = StackItem & {
+  // biome-ignore lint/suspicious/noExplicitAny: Component type needs to be flexible for different overlay types (Toast, Modal, etc.)
+  component: FunctionComponent<any>;
+  /** Live data passed to the component via update() */
+  data?: unknown;
+  /** Close handler for escape key handling */
+  onClose?: (() => void) | undefined;
+};
+
+type OverlayContextType = {
+  modalRoot: FloatingPortalProps["root"];
+  modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
+  toastRoot: FloatingPortalProps["root"];
+  toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
+};
+
+const OverlayContext = createContext<OverlayContextType>(undefined as unknown as OverlayContextType);
+export const useOverlayContext = () => useContext(OverlayContext);
+
+export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }: PropsWithChildren<OverlayContextProps>) => {
+  const resolvedModalRoot = modalRoot ?? document.body;
+  const resolvedToastRoot = toastRoot ?? document.body;
+
+  const modalStack = useStack<OverlayStackItem>([]);
+  const toastStack = useStack<OverlayStackItem>([]);
+
+  const [modals] = modalStack;
+  const [toasts] = toastStack;
+
+  // Global escape key handler - closes topmost modal
+  useEffect(() => {
+    if (modals.length === 0) return;
+
+    const handleEscape = (event: KeyboardEvent) => {
+      if (event.key === "Escape") {
+        const topModal = modals.at(-1);
+        topModal?.onClose?.();
+      }
+    };
+
+    document.addEventListener("keydown", handleEscape);
+    return () => document.removeEventListener("keydown", handleEscape);
+  }, [modals]);
+
+  // Memoize context value to prevent unnecessary re-renders in consumers
+  const contextValue = useMemo(
+    () => ({
+      modalRoot: resolvedModalRoot,
+      modalStack,
+      toastRoot: resolvedToastRoot,
+      toastStack,
+    }),
+    [resolvedModalRoot, modalStack, resolvedToastRoot, toastStack]
+  );
+
+  return (
+    <OverlayContext.Provider value={contextValue}>
+      {children}
+
+      {/* Modal stack - rendered in portal */}
+      {modals.length > 0 && (
+        <FloatingPortal root={resolvedModalRoot}>
+          {modals.map(({ id, component: Component, data }) => (
+            <Component key={id} data={data} />
+          ))}
+        </FloatingPortal>
+      )}
+
+      {/* Toast stack - rendered in portal */}
+      {toasts.length > 0 && (
+        <FloatingPortal root={resolvedToastRoot}>
+          <div className="pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3">
+            {toasts.map(({ id, component: Component, onClose, ...props }) => (
+              <div key={id} className="pointer-events-auto">
+                <Component onClose={onClose} {...props} />
+              </div>
+            ))}
+          </div>
+        </FloatingPortal>
+      )}
+    </OverlayContext.Provider>
+  );
+};

package/src/lib/contexts/OverlayContext/hooks/useModal.tsx

@@ -0,0 +1,125 @@
+import { ModalContextProvider, type ModalProps, type OnClose } from "@sixthshift/design-system/modal";
+import { type ComponentType, type ReactNode, Suspense, useCallback, useId, useRef } from "react";
+import { useOverlayContext } from "../OverlayContext";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** Props passed to modal components */
+export type ModalComponentProps<TData = undefined> = {
+  /** Close this modal */
+  onClose: OnClose;
+  /** Close all open modals */
+  closeAll: () => void;
+  /** Live data passed via update() */
+  data: TData;
+} & Omit<ModalProps, "onOpenChange" | "children">;
+
+/** Modal options passed to openModal */
+export type OpenModalOptions<TData = undefined> = Omit<ModalProps, "onOpenChange" | "children"> & {
+  /** Fallback to show while lazy content is loading */
+  suspenseFallback?: ReactNode;
+  /** Initial data passed to the modal component */
+  data?: TData;
+};
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export const useModal = () => {
+  const {
+    modalStack: [, dispatch],
+  } = useOverlayContext();
+
+  const baseId = useId();
+  const counterRef = useRef(0);
+
+  /**
+   * Close all open modals.
+   */
+  const closeAllModals = useCallback(() => {
+    dispatch({ type: "clear", transition: { duration: 300 } });
+  }, [dispatch]);
+
+  /**
+   * Open a modal by passing a component that renders a Modal.
+   *
+   * The component receives `onClose`, `closeAll`, and any options passed as props.
+   * It should render a `<Modal>` with its content.
+   *
+   * Supports lazy-loaded components via React.lazy().
+   *
+   * @example
+   * ```tsx
+   * const { openModal } = useModal();
+   *
+   * // Inline component — Modal picks up the close handler from context, no prop needed.
+   * openModal(({ onClose, closeAll }) => (
+   *   <Modal>
+   *     <Modal.Header>My Modal</Modal.Header>
+   *     <Modal.Body>Content</Modal.Body>
+   *     <Modal.Footer>
+   *       <Button onClick={onClose}>Close</Button>
+   *       <Button onClick={closeAll}>Close All</Button>
+   *     </Modal.Footer>
+   *   </Modal>
+   * ));
+   *
+   * // Named component
+   * function ConfirmModal({ onClose, closeAll }: ModalComponentProps) {
+   *   return (
+   *     <Modal>
+   *       <Modal.Header>Confirm</Modal.Header>
+   *       <Modal.Body>Are you sure?</Modal.Body>
+   *       <Modal.Footer>
+   *         <Button onClick={closeAll}>Close All</Button>
+   *       </Modal.Footer>
+   *     </Modal>
+   *   );
+   * }
+   * openModal(ConfirmModal);
+   * ```
+   */
+  const openModal = useCallback(
+    <TData = undefined>(Component: ComponentType<ModalComponentProps<TData>>, options: OpenModalOptions<TData> = {} as OpenModalOptions<TData>) => {
+      const id = `${baseId}-${counterRef.current++}`;
+      const { suspenseFallback = null, data: initialData, ...componentProps } = options;
+
+      const closeModal: OnClose = () => {
+        dispatch({ type: "remove", id, transition: { duration: 300 } });
+      };
+
+      const ModalWrapper = ({ data }: { data?: unknown }) => (
+        <ModalContextProvider onClose={closeModal}>
+          <Suspense fallback={suspenseFallback}>
+            <Component onClose={closeModal} closeAll={closeAllModals} data={(data ?? initialData) as TData} {...componentProps} />
+          </Suspense>
+        </ModalContextProvider>
+      );
+
+      dispatch({
+        type: "push",
+        item: {
+          id,
+          component: ModalWrapper,
+          onClose: closeModal,
+          data: initialData,
+        },
+      });
+
+      const update = (newData: TData) => {
+        dispatch({ type: "update", item: { id, data: newData } });
+      };
+
+      return { id, closeModal, update };
+    },
+    [dispatch, baseId, closeAllModals]
+  );
+
+  return {
+    openModal,
+    closeAllModals,
+  };
+};