@sixthshift/design-system 0.5.0 → 0.7.0

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

@@ -1,10 +1,19 @@
+"use client";
+
 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";
+import { hasOpenEscapeLayer } from "../../../internal/escapeLayers";
+import { ToastStack } from "./ToastStack";
+import { toastStore as defaultToastStore, type ToastStore } from "./toastStore";
 
 type OverlayContextProps = {
   modal?: FloatingPortalProps["root"];
   toast?: FloatingPortalProps["root"];
+  /** The toast stack to render. Default: the app's one, which `toast()` opens onto. Hand in your own for a second bundle or a test. */
+  toasts?: ToastStore;
+  /** Merged over the toast stack's container classes, so an app can move it (above a bottom bar, into a corner). */
+  toastClassName?: string;
 };
 
 /** Stack item for overlays - component is a self-contained wrapper */
@@ -18,10 +27,13 @@ type OverlayStackItem = StackItem & {
 };
 
 type OverlayContextType = {
-  modalRoot?: FloatingPortalProps["root"];
+  // `undefined` spelled out rather than an optional `?:` — the context value
+  // below always sets the key, and `exactOptionalPropertyTypes` treats "absent"
+  // and "present but undefined" as different types.
+  modalRoot: FloatingPortalProps["root"] | undefined;
   modalStack: ReturnType<typeof useStack<OverlayStackItem>>;
-  toastRoot?: FloatingPortalProps["root"];
-  toastStack: ReturnType<typeof useStack<OverlayStackItem>>;
+  toastRoot: FloatingPortalProps["root"] | undefined;
+  toastStore: ToastStore;
 };
 
 /**
@@ -35,18 +47,28 @@ const rootProp = (root: FloatingPortalProps["root"] | undefined) => (root === un
 const OverlayContext = createContext<OverlayContextType>(undefined as unknown as OverlayContextType);
 export const useOverlayContext = () => useContext(OverlayContext);
 
-export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }: PropsWithChildren<OverlayContextProps>) => {
-  // The roots pass through unresolved, deliberately. Defaulting them to
-  // `document.body` here read the DOM during render, which threw the whole
-  // tree under SSR — and it bought nothing: `FloatingPortal` already falls
-  // back to `document.body` when no `root` is given, on the client, where a
-  // body exists. Both portals below are behind a non-empty stack, and both
-  // stacks start empty, so nothing portals on the server either way.
+export const OverlayProvider = ({
+  modal: modalRoot,
+  toast: toastRoot,
+  toasts: toastStore = defaultToastStore,
+  toastClassName,
+  children,
+}: PropsWithChildren<OverlayContextProps>) => {
+  // The roots pass through unresolved, deliberately. `"use client"` makes this a
+  // Client Component, but a Client Component is still rendered once on the
+  // server — defaulting to `document.body` here read the DOM at render scope and
+  // threw "document is not defined" on the first App Router request, which
+  // src/testing/stories.ssr.test.tsx and src/exports.ssr.test.tsx now catch. It
+  // bought nothing either: `FloatingPortal` already falls back to
+  // `document.body` when no `root` is given, and does it in an effect, on the
+  // client, where a body exists. Both portals below are behind a non-empty
+  // stack, and both stacks start empty, so nothing portals on the server anyway.
+  //
+  // Modals are a `useStack` here; toasts are a store outside React, so that
+  // `toast()` works from code that is not a component.
   const modalStack = useStack<OverlayStackItem>([]);
-  const toastStack = useStack<OverlayStackItem>([]);
 
   const [modals] = modalStack;
-  const [toasts] = toastStack;
 
   // Global escape key handler - closes topmost modal
   useEffect(() => {
@@ -54,6 +76,10 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
 
     const handleEscape = (event: KeyboardEvent) => {
       if (event.key === "Escape") {
+        // A transient overlay open above the modal (a Select dropdown, a
+        // Popover, a picker calendar) consumes this Escape via its own
+        // dismiss handling — closing the modal too would double-fire.
+        if (hasOpenEscapeLayer()) return;
         const topModal = modals.at(-1);
         topModal?.onClose?.();
       }
@@ -69,9 +95,9 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
       modalRoot,
       modalStack,
       toastRoot,
-      toastStack,
+      toastStore,
     }),
-    [modalRoot, modalStack, toastRoot, toastStack]
+    [modalRoot, modalStack, toastRoot, toastStore]
   );
 
   return (
@@ -87,18 +113,8 @@ export const OverlayProvider = ({ modal: modalRoot, toast: toastRoot, children }
         </FloatingPortal>
       )}
 
-      {/* Toast stack - rendered in portal */}
-      {toasts.length > 0 && (
-        <FloatingPortal {...rootProp(toastRoot)}>
-          <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>
-      )}
+      {/* Toast stack - portals itself, and only while it holds something */}
+      <ToastStack store={toastStore} className={toastClassName} {...rootProp(toastRoot)} />
     </OverlayContext.Provider>
   );
 };

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

@@ -0,0 +1,71 @@
+"use client";
+
+import { FloatingPortal, type FloatingPortalProps } from "@floating-ui/react";
+import { Toast } from "@sixthshift/design-system/toast";
+import { cn } from "@sixthshift/design-system/utils";
+import { useCallback, useEffect, useSyncExternalStore } from "react";
+import { toastStore as defaultStore, type ToastRecord, type ToastStore } from "./toastStore";
+
+const EMPTY: readonly ToastRecord[] = [];
+
+/** The store's stack, re-rendering the caller as it changes. Empty during server rendering. */
+export function useToasts(store: ToastStore = defaultStore): readonly ToastRecord[] {
+  return useSyncExternalStore(store.subscribe, store.snapshot, () => EMPTY);
+}
+
+/**
+ * One toast in the stack: the dismissal timer lives here, not in the store,
+ * so the store stays free of the DOM. Expiry and the X button take the same
+ * path — `open` flips false, `Toast` plays its exit, and `onClose` drops the
+ * record once the animation ends.
+ */
+function ToastItem({ record, store }: { record: ToastRecord; store: ToastStore }) {
+  const { id, duration, closing } = record;
+  // `duration` is the stack's to act on, not the toast's to render.
+  const { component: Component = Toast, duration: _duration, ...props } = record.options;
+
+  useEffect(() => {
+    if (duration <= 0 || closing) return;
+    const timer = setTimeout(() => store.close(id), duration);
+    return () => clearTimeout(timer);
+  }, [id, duration, closing, store]);
+
+  const onClose = useCallback(() => store.remove(id), [store, id]);
+
+  return (
+    <div className="pointer-events-auto" data-toast-id={id} data-toast-intent={props.intent ?? "neutral"}>
+      <Component {...props} standalone={false} open={!closing} onClose={onClose} />
+    </div>
+  );
+}
+
+export type ToastStackProps = {
+  /** The stack to render. Default: the app's one, which `toast()` opens onto. */
+  store?: ToastStore | undefined;
+  /** Portal root (default: `document.body`). */
+  root?: FloatingPortalProps["root"] | undefined;
+  /** Merged over the container's classes, so an app can move the stack (above a bottom bar, to a corner). */
+  className?: string | undefined;
+};
+
+/** The container's own classes: bottom centre, newest at the bottom, click-through between toasts. */
+export const TOAST_STACK_CLASS = "pointer-events-none fixed bottom-6 left-1/2 z-toast flex -translate-x-1/2 flex-col-reverse items-center gap-3";
+
+/**
+ * The open toasts, portalled and positioned. `OverlayProvider` renders one;
+ * render it yourself only when there is no provider to host it.
+ */
+export function ToastStack({ store = defaultStore, root, className }: ToastStackProps) {
+  const toasts = useToasts(store);
+  if (toasts.length === 0) return null;
+  // `root` omitted rather than passed as `undefined`: see OverlayContext's `rootProp`.
+  return (
+    <FloatingPortal {...(root === undefined ? {} : { root })}>
+      <div className={cn(TOAST_STACK_CLASS, className)} data-toast-stack="" data-count={toasts.length}>
+        {toasts.map((record) => (
+          <ToastItem key={record.id} record={record} store={store} />
+        ))}
+      </div>
+    </FloatingPortal>
+  );
+}

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

@@ -1,3 +1,5 @@
+"use client";
+
 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";

package/src/lib/contexts/OverlayContext/hooks/useToast.ts

@@ -1,80 +1,37 @@
-import type { StackItem } from "@sixthshift/design-system/hooks";
-import { Toast, type ToastProps } from "@sixthshift/design-system/toast";
-import { type FunctionComponent, useCallback, useEffect, useId, useRef } from "react";
-import { useOverlayContext } from "../OverlayContext";
-
-// Default auto-dismiss duration in milliseconds
-const DEFAULT_DURATION = 5000;
-
-// Native replacements for lodash functions
-const isFunction = (value: unknown): value is FunctionComponent<ToastProps> => typeof value === "function";
-
-const isPlainObject = (value: unknown): value is ToastPropsWithDuration => typeof value === "object" && value !== null && !Array.isArray(value);
+"use client";
 
-type ToastPropsWithDuration = Omit<ToastProps, "onClose"> & {
-  /** Auto-dismiss duration in ms. Set to 0 to disable. Default: 5000 */
-  duration?: number;
-};
+import { useCallback } from "react";
+import { useOverlayContext } from "../OverlayContext";
+import { toastStore as defaultStore, type ToastOptions } from "../toastStore";
 
 /**
- * Toast stack item - extends base StackItem with component and additional props
- * that are passed through to the Toast component in OverlayContext
+ * Open toasts on the provider's stack, with the content decided at the moment
+ * of opening: an error's message, a count, whatever the action produced.
+ *
+ * @example
+ * ```tsx
+ * const { openToast } = useToast();
+ *
+ * async function save() {
+ *   try {
+ *     await api.save();
+ *     openToast({ intent: "success", title: "Saved" });
+ *   } catch (error) {
+ *     openToast({ intent: "danger", title: "Could not save", children: String(error) });
+ *   }
+ * }
+ * ```
+ *
+ * Outside any provider this opens on the app's default stack, which is also
+ * what the plain `toast()` export uses, so code that is not a component — a
+ * store, a callback from a service worker — has the same door.
  */
-type ToastStackItem = StackItem & {
-  component: FunctionComponent<ToastProps>;
-  onClose?: () => void;
-} & Partial<Omit<ToastProps, "onClose">>;
-
-export const useToast = (args: ToastPropsWithDuration | FunctionComponent<ToastProps>) => {
-  const {
-    toastStack: [, dispatch],
-  } = useOverlayContext();
-
-  const id = useId();
-
-  const customComponent = isFunction(args) ? args : null;
-  const props = isPlainObject(args) ? args : ({} as ToastPropsWithDuration);
-  const { duration = DEFAULT_DURATION, ...toastPropsRaw } = props;
-
-  const closeToast = useCallback(() => {
-    dispatch({ type: "remove", id, transition: { duration: 300 } });
-  }, [dispatch, id]);
-
-  // `openToast` has to be both referentially stable — callers put it in effect
-  // dependency arrays — and able to see the current props. A ref refreshed after
-  // every render gives both.
-  //
-  // It previously memoised the props object against JSON.stringify(props) as a
-  // cache key. JSON.stringify silently drops function-valued properties, so a
-  // changed `onAction` whose serialisable fields were identical did not
-  // invalidate the key, and `openToast` kept firing the stale closure.
-  const latest = useRef({ customComponent, toastProps: toastPropsRaw, duration });
-  useEffect(() => {
-    latest.current = { customComponent, toastProps: toastPropsRaw, duration };
-  });
-
-  const openToast = useCallback(() => {
-    const { customComponent: component, toastProps, duration: autoDismiss } = latest.current;
-
-    dispatch({
-      type: "push",
-      item: {
-        id,
-        component: component ?? Toast,
-        onClose: closeToast,
-        standalone: false, // OverlayContext handles positioning
-        ...toastProps,
-      } as ToastStackItem,
-    });
+export const useToast = () => {
+  const store = useOverlayContext()?.toastStore ?? defaultStore;
 
-    // Auto-dismiss if duration is set
-    if (autoDismiss > 0) {
-      setTimeout(closeToast, autoDismiss);
-    }
-  }, [dispatch, id, closeToast]);
+  const openToast = useCallback((options: ToastOptions) => store.open(options), [store]);
+  const closeToast = useCallback((id: string) => store.close(id), [store]);
+  const closeAllToasts = useCallback(() => store.clear(), [store]);
 
-  return {
-    openToast,
-    closeToast,
-  };
+  return { openToast, closeToast, closeAllToasts };
 };

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

@@ -4,3 +4,5 @@ export { Modal } from "@sixthshift/design-system/modal";
 export * from "./hooks/useModal";
 export * from "./hooks/useToast";
 export * from "./OverlayContext";
+export { TOAST_STACK_CLASS, ToastStack, type ToastStackProps, useToasts } from "./ToastStack";
+export * from "./toastStore";

package/src/lib/contexts/OverlayContext/toastStore.ts

@@ -0,0 +1,138 @@
+import type { ToastProps } from "@sixthshift/design-system/toast";
+import type { FunctionComponent } from "react";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+/** What a caller passes to open a toast: the `Toast`'s own props, plus how long it stays. */
+export type ToastOptions = Omit<ToastProps, "onClose" | "open" | "standalone" | "root"> & {
+  /**
+   * Milliseconds until the toast dismisses itself. `0` keeps it until it is
+   * dismissed by hand. Default: `0` for `intent="danger"` (a failure usually
+   * carries a message worth reading, and often a retry), `5000` otherwise.
+   */
+  duration?: number;
+  /** Render this instead of `Toast`. It receives `ToastProps` and must honour `open` and `onClose` as `Toast` does. */
+  component?: FunctionComponent<ToastProps>;
+};
+
+/** One toast as the stack holds it. */
+export type ToastRecord = {
+  id: string;
+  options: ToastOptions;
+  /** The resolved lifetime, in ms; `0` sticks. */
+  duration: number;
+  /** Playing its exit; removed once the animation ends. */
+  closing: boolean;
+};
+
+/** What `open` hands back: the toast's id, and a way to close it early. */
+export type ToastHandle = { id: string; close: () => void };
+
+/**
+ * The stack of open toasts, with subscribers. No DOM and no timers: the
+ * `ToastStack` that renders it owns dismissal timing, and `Toast` owns the
+ * exit animation. Plain functions, so a toast can be opened from anywhere —
+ * an event handler, a store, a service-worker callback — not only from a
+ * component.
+ */
+export type ToastStore = {
+  /** Register a listener; returns the unsubscribe. */
+  subscribe: (listener: () => void) => () => void;
+  /** The current stack, oldest first. Reference-stable until it changes, as `useSyncExternalStore` needs. */
+  snapshot: () => readonly ToastRecord[];
+  /** Add a toast. Past `max`, the oldest is dropped at once. */
+  open: (options: ToastOptions) => ToastHandle;
+  /** Begin a toast's exit. It leaves the stack when `remove` is called, which `Toast` does after its animation. */
+  close: (id: string) => void;
+  /** Drop a toast at once. */
+  remove: (id: string) => void;
+  /** Begin every toast's exit. */
+  clear: () => void;
+};
+
+export type ToastStoreOptions = {
+  /** How many toasts show at once; the oldest falls off. Default: 3 — a short stack reads on a phone. */
+  max?: number;
+  /** Ids in open order. Injectable so a test can name them. */
+  newId?: () => string;
+};
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_TOAST_DURATION = 5000;
+export const DEFAULT_MAX_TOASTS = 3;
+
+/** The lifetime an intent gets when none is given: failures stay, everything else expires. */
+export function defaultToastDuration(intent: ToastOptions["intent"]): number {
+  return intent === "danger" ? 0 : DEFAULT_TOAST_DURATION;
+}
+
+let opened = 0;
+const nextId = () => `toast-${++opened}`;
+
+// =============================================================================
+// Store
+// =============================================================================
+
+const EMPTY: readonly ToastRecord[] = [];
+
+export function createToastStore({ max = DEFAULT_MAX_TOASTS, newId = nextId }: ToastStoreOptions = {}): ToastStore {
+  let toasts: readonly ToastRecord[] = EMPTY;
+  const listeners = new Set<() => void>();
+
+  const set = (next: readonly ToastRecord[]) => {
+    toasts = next.length === 0 ? EMPTY : next;
+    for (const listener of [...listeners]) listener();
+  };
+
+  const close = (id: string) => {
+    const record = toasts.find((toast) => toast.id === id);
+    if (record === undefined || record.closing) return;
+    set(toasts.map((toast) => (toast === record ? { ...toast, closing: true } : toast)));
+  };
+
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    snapshot: () => toasts,
+    open(options) {
+      const id = newId();
+      const record: ToastRecord = { id, options, duration: options.duration ?? defaultToastDuration(options.intent), closing: false };
+      set([...toasts, record].slice(-max));
+      return { id, close: () => close(id) };
+    },
+    close,
+    remove(id) {
+      const next = toasts.filter((toast) => toast.id !== id);
+      if (next.length !== toasts.length) set(next);
+    },
+    clear() {
+      if (toasts.every((toast) => toast.closing)) return;
+      set(toasts.map((toast) => ({ ...toast, closing: true })));
+    },
+  };
+}
+
+/** The app's one stack: what `OverlayProvider` renders unless handed another. */
+export const toastStore = createToastStore();
+
+/** Open a toast on the app's stack, from anywhere. Returns its id and a way to close it early. */
+export function toast(options: ToastOptions): ToastHandle {
+  return toastStore.open(options);
+}
+
+/** Begin a toast's exit on the app's stack. */
+export function closeToast(id: string): void {
+  toastStore.close(id);
+}
+
+/** Begin every toast's exit on the app's stack. */
+export function closeAllToasts(): void {
+  toastStore.clear();
+}

package/src/lib/withErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { ComponentType, ReactNode } from "react";
 import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";
 

package/src/lib/withSuspenseAndErrorBoundary.tsx

@@ -1,3 +1,5 @@
+"use client";
+
 import type { ComponentType, ReactNode } from "react";
 import { Suspense } from "react";
 import { ErrorBoundary, type ErrorFallbackProps } from "./ErrorBoundary";

package/src/theme/linen/index.css

@@ -0,0 +1,11 @@
+/**
+ * Linen — the exported artifact (`@sixthshift/design-system/themes/linen.css`).
+ * The system's one theme, consolidated from the plans/10 exploration (was
+ * "02 Hue-anchored"; the six alternatives live at the `themes-exploration` tag).
+ * Plain CSS composition, no build step. A theme is exactly two imports: its
+ * own tokens, plus the theme-independent system (recipes, Tailwind config),
+ * which theming/tailwind.css composes.
+ */
+
+@import "./theme.css"; /* imports ./palette.css itself */
+@import "../../theming/tailwind.css"; /* imports every component's *.recipe.css itself */

package/src/theme/linen/palette.css

@@ -0,0 +1,87 @@
+/*
+ * Linen — the palette: the authoring convention behind theme.css, not a
+ * layer. Referenced only by theme.css; not API for consumers.
+ *
+ * Thesis:   One temperature runs through everything, the grey included. Warm
+ *           here — hue ~70 across the board, so the page reads as woven cloth
+ *           rather than blue-grey screen. Named for the warm off-white ground
+ *           a canvas is made of before anything is painted on it: a surface
+ *           with a temperature of its own, not a blank.
+ * Kin:      Radix (sand, sage, olive), IBM Carbon warm grey
+ *
+ * Family names are this theme's own — a palette's names are part of its
+ * premise. theme.css points every semantic token at them.
+ */
+
+:root {
+  --theme-name: "Linen";
+  --theme-version: "1.0.0";
+
+  /* sand (neutral) */
+  --color-sand-50: #f9f9f9;
+  --color-sand-100: #efeeed;
+  --color-sand-200: #dfdddb;
+  --color-sand-300: #c6c4c0;
+  --color-sand-400: #a19e9a;
+  --color-sand-500: #736f6b;
+  --color-sand-600: #5e5a55;
+  --color-sand-700: #484440;
+  --color-sand-800: #302d2a;
+  --color-sand-900: #1d1b19;
+  --color-sand-950: #0c0b09;
+
+  /* blue (accent) */
+  --color-blue-50: #f6f9fe;
+  --color-blue-100: #e6effd;
+  --color-blue-200: #cddff9;
+  --color-blue-300: #abc6ee;
+  --color-blue-400: #7ca0d5;
+  --color-blue-500: #4771ae;
+  --color-blue-600: #315a97;
+  --color-blue-700: #25487c;
+  --color-blue-800: #1b375f;
+  --color-blue-900: #122746;
+  --color-blue-950: #09172c;
+
+  /* green */
+  --color-green-50: #f6faf6;
+  --color-green-100: #e7f2e8;
+  --color-green-200: #cee4d0;
+  --color-green-300: #accfb0;
+  --color-green-400: #7dac83;
+  --color-green-500: #467f50;
+  --color-green-600: #2e693a;
+  --color-green-700: #23552d;
+  --color-green-800: #194121;
+  --color-green-900: #102e16;
+  --color-green-950: #081c0c;
+
+  /* amber */
+  --color-amber-50: #fdf8f3;
+  --color-amber-100: #f9ecdf;
+  --color-amber-200: #f1d9bf;
+  --color-amber-300: #e1bd94;
+  --color-amber-400: #c4945b;
+  --color-amber-500: #9a620b;
+  --color-amber-600: #7e4f00;
+  --color-amber-700: #663f00;
+  --color-amber-800: #4e2f00;
+  --color-amber-900: #392100;
+  --color-amber-950: #241300;
+
+  /* red */
+  --color-red-50: #fff7f6;
+  --color-red-100: #ffe9e5;
+  --color-red-200: #fed1c9;
+  --color-red-300: #f5b1a5;
+  --color-red-400: #dc8274;
+  --color-red-500: #b24b3d;
+  --color-red-600: #9b3225;
+  --color-red-700: #7f251b;
+  --color-red-800: #611c13;
+  --color-red-900: #47120c;
+  --color-red-950: #2d0906;
+
+  --font-sans: Inter Variable, ui-sans-serif, system-ui, sans-serif;
+  --font-mono: JetBrains Mono Variable, ui-monospace, monospace;
+}