@sixthshift/design-system 0.5.0 → 0.6.0

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;
+}