@dashforge/tw 0.1.0-beta

package/src/components/Snackbar/Snackbar.test.tsx

@@ -0,0 +1,327 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, vi, afterEach, beforeEach } from 'vitest';
+import {
+  render,
+  screen,
+  fireEvent,
+  cleanup,
+  act,
+} from '@testing-library/react';
+import { SnackbarProvider, useSnackbar } from './Snackbar.js';
+
+void React;
+afterEach(() => cleanup());
+beforeEach(() => {
+  vi.useRealTimers();
+});
+
+/**
+ * Test trigger — exposes a button per snackbar call. Each click
+ * dispatches with the given options.
+ */
+function Trigger({
+  options,
+  testid = 'trigger',
+}: {
+  options: Parameters<ReturnType<typeof useSnackbar>['enqueue']>[0];
+  testid?: string;
+}) {
+  const { enqueue } = useSnackbar();
+  return (
+    <button data-testid={testid} onClick={() => enqueue(options)}>
+      enqueue
+    </button>
+  );
+}
+
+describe('<SnackbarProvider> + useSnackbar()', () => {
+  describe('basic enqueue + render', () => {
+    it('renders nothing initially', () => {
+      render(
+        <SnackbarProvider>
+          <div />
+        </SnackbarProvider>
+      );
+      expect(screen.queryByRole('region', { name: 'Notifications' })).toBeTruthy();
+      expect(screen.queryByText(/./)).toBeNull();
+    });
+
+    it('shows a snackbar when enqueue() is called', () => {
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'Saved!' }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      expect(screen.getByText('Saved!')).toBeTruthy();
+    });
+
+    it('renders the close button by default', () => {
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'Saved!' }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      expect(
+        screen.getByRole('button', { name: 'Dismiss notification' })
+      ).toBeTruthy();
+    });
+
+    it('hides the close button when showClose=false', () => {
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'No close', showClose: false }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      expect(
+        screen.queryByRole('button', { name: 'Dismiss notification' })
+      ).toBeNull();
+    });
+  });
+
+  describe('dismiss', () => {
+    it('removes the snackbar on close-button click', () => {
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'Saved!', autoHideMs: 0 }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      expect(screen.getByText('Saved!')).toBeTruthy();
+      act(() => {
+        fireEvent.click(
+          screen.getByRole('button', { name: 'Dismiss notification' })
+        );
+      });
+      expect(screen.queryByText('Saved!')).toBeNull();
+    });
+
+    it('dismissAll() clears every visible snackbar', () => {
+      function MultiTrigger() {
+        const { enqueue, dismissAll } = useSnackbar();
+        return (
+          <>
+            <button
+              data-testid="add1"
+              onClick={() => enqueue({ message: 'A', autoHideMs: 0 })}
+            >
+              add A
+            </button>
+            <button
+              data-testid="add2"
+              onClick={() => enqueue({ message: 'B', autoHideMs: 0 })}
+            >
+              add B
+            </button>
+            <button data-testid="clear" onClick={() => dismissAll()}>
+              clear
+            </button>
+          </>
+        );
+      }
+      render(
+        <SnackbarProvider>
+          <MultiTrigger />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('add1'));
+        fireEvent.click(screen.getByTestId('add2'));
+      });
+      expect(screen.getByText('A')).toBeTruthy();
+      expect(screen.getByText('B')).toBeTruthy();
+      act(() => {
+        fireEvent.click(screen.getByTestId('clear'));
+      });
+      expect(screen.queryByText('A')).toBeNull();
+      expect(screen.queryByText('B')).toBeNull();
+    });
+  });
+
+  describe('auto-dismiss', () => {
+    it('auto-dismisses after autoHideMs', () => {
+      vi.useFakeTimers();
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'Auto', autoHideMs: 1000 }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      expect(screen.getByText('Auto')).toBeTruthy();
+      act(() => {
+        vi.advanceTimersByTime(1100);
+      });
+      expect(screen.queryByText('Auto')).toBeNull();
+    });
+
+    it('does NOT auto-dismiss when autoHideMs is 0', () => {
+      vi.useFakeTimers();
+      render(
+        <SnackbarProvider>
+          <Trigger options={{ message: 'Sticky', autoHideMs: 0 }} />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      act(() => {
+        vi.advanceTimersByTime(60_000);
+      });
+      expect(screen.getByText('Sticky')).toBeTruthy();
+    });
+  });
+
+  describe('action button', () => {
+    it('invokes the action callback and dismisses the snackbar', () => {
+      const action = vi.fn();
+      render(
+        <SnackbarProvider>
+          <Trigger
+            options={{
+              message: 'Undo?',
+              autoHideMs: 0,
+              action: { label: 'Undo', onClick: action },
+            }}
+          />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('trigger'));
+      });
+      act(() => {
+        fireEvent.click(screen.getByRole('button', { name: 'Undo' }));
+      });
+      expect(action).toHaveBeenCalledOnce();
+      expect(screen.queryByText('Undo?')).toBeNull();
+    });
+  });
+
+  describe('de-dup (same id)', () => {
+    it('replaces an existing snackbar instead of stacking when ids match', () => {
+      function TwoCallsSameId() {
+        const { enqueue } = useSnackbar();
+        return (
+          <button
+            data-testid="t"
+            onClick={() => {
+              enqueue({ id: 'saved', message: 'Saved v1', autoHideMs: 0 });
+              enqueue({ id: 'saved', message: 'Saved v2', autoHideMs: 0 });
+            }}
+          >
+            twice
+          </button>
+        );
+      }
+      render(
+        <SnackbarProvider>
+          <TwoCallsSameId />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('t'));
+      });
+      // Only v2 should be visible.
+      expect(screen.queryByText('Saved v1')).toBeNull();
+      expect(screen.getByText('Saved v2')).toBeTruthy();
+    });
+  });
+
+  describe('maxVisible queueing', () => {
+    it('caps the visible count and promotes queued items on dismiss', () => {
+      vi.useFakeTimers();
+      function AddMany() {
+        const { enqueue, dismiss } = useSnackbar();
+        return (
+          <>
+            <button
+              data-testid="add-all"
+              onClick={() => {
+                enqueue({ id: 'a', message: 'A', autoHideMs: 0 });
+                enqueue({ id: 'b', message: 'B', autoHideMs: 0 });
+                enqueue({ id: 'c', message: 'C', autoHideMs: 0 });
+              }}
+            >
+              all
+            </button>
+            <button
+              data-testid="kill-a"
+              onClick={() => dismiss('a')}
+            >
+              kill A
+            </button>
+          </>
+        );
+      }
+      render(
+        <SnackbarProvider maxVisible={2}>
+          <AddMany />
+        </SnackbarProvider>
+      );
+      act(() => {
+        fireEvent.click(screen.getByTestId('add-all'));
+      });
+      expect(screen.getByText('A')).toBeTruthy();
+      expect(screen.getByText('B')).toBeTruthy();
+      expect(screen.queryByText('C')).toBeNull(); // queued
+      act(() => {
+        fireEvent.click(screen.getByTestId('kill-a'));
+      });
+      expect(screen.queryByText('A')).toBeNull();
+      expect(screen.getByText('B')).toBeTruthy();
+      expect(screen.getByText('C')).toBeTruthy(); // promoted
+    });
+  });
+
+  describe('useSnackbar() outside provider', () => {
+    it('throws a helpful error', () => {
+      const Lone = () => {
+        useSnackbar();
+        return null;
+      };
+      const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+      expect(() => render(<Lone />)).toThrow(/useSnackbar/);
+      spy.mockRestore();
+    });
+  });
+
+  describe('a11y wiring', () => {
+    it('renders an aria-live="polite" region with label "Notifications"', () => {
+      render(
+        <SnackbarProvider>
+          <div />
+        </SnackbarProvider>
+      );
+      const region = screen.getByRole('region', { name: 'Notifications' });
+      expect(region.getAttribute('aria-live')).toBe('polite');
+    });
+  });
+
+  describe('severity rendering', () => {
+    (['info', 'success', 'warning', 'danger'] as const).forEach((sev) => {
+      it(`renders the ${sev} glyph`, () => {
+        render(
+          <SnackbarProvider>
+            <Trigger options={{ message: sev, severity: sev }} />
+          </SnackbarProvider>
+        );
+        act(() => {
+          fireEvent.click(screen.getByTestId('trigger'));
+        });
+        expect(screen.getByText(sev)).toBeTruthy();
+      });
+    });
+  });
+});

package/src/components/Snackbar/Snackbar.tsx

@@ -0,0 +1,298 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { cn } from '../../utils/cn.js';
+import { snackbarVariants } from './snackbar.variants.js';
+import type {
+  SnackbarApi,
+  SnackbarOptions,
+  SnackbarProviderProps,
+  SnackbarRecord,
+  SnackbarSeverity,
+} from './snackbar.types.js';
+
+const SnackbarContext = createContext<SnackbarApi | null>(null);
+
+/**
+ * `useSnackbar()` — returns `{ enqueue, dismiss, dismissAll }`.
+ *
+ * Throws if called outside `<SnackbarProvider>` — silent no-op would
+ * be a footgun for "Saved!" toasts that silently vanish.
+ */
+export function useSnackbar(): SnackbarApi {
+  const ctx = useContext(SnackbarContext);
+  if (ctx == null) {
+    throw new Error(
+      '[Snackbar] useSnackbar() must be called inside <SnackbarProvider>.'
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Unicode glyphs for severities — keeps the bundle small (no icon dep)
+ * and stays accessible because consumers pass their own message text.
+ * The glyph is `aria-hidden`; the screen reader announces the message
+ * via the live region.
+ */
+const SEVERITY_GLYPH: Record<SnackbarSeverity, string> = {
+  info: 'ⓘ',
+  success: '✓',
+  warning: '⚠',
+  danger: '✕',
+};
+
+/**
+ * Dashforge TW Snackbar provider — transient, stacked toast notifications.
+ *
+ * **Behaviour**:
+ *   - `enqueue(opts)` returns the assigned `id`.
+ *   - Items appear in a fixed-corner stack (`position` prop).
+ *   - At most `maxVisible` (default 5) are shown — extras queue FIFO.
+ *   - Each item auto-dismisses after `autoHideMs` (default 4000); set
+ *     `0` for a persistent snackbar.
+ *   - Re-enqueueing with the SAME `id` reuses the slot and resets the
+ *     timer (de-dup pattern for repeated "Saved" toasts).
+ *
+ * **A11y**:
+ *   - Container is an `aria-live="polite"` region (assistive techs
+ *     announce new messages without stealing focus).
+ *   - Severity icon is `aria-hidden` — the message text carries the
+ *     semantic.
+ *   - Close + action buttons are focusable via Tab; the visual stack
+ *     order is the same as the announcement order.
+ *
+ * **Re-render contract**:
+ *   - Provider re-renders ONLY when the visible set changes.
+ *   - The `api` (returned by `useSnackbar()`) is stable across re-renders
+ *     — `useCallback`'d with no deps, mutates a ref internally.
+ *   - Consumers calling `useSnackbar()` get the same identity each time
+ *     so they can safely pass `enqueue` to `useEffect` deps.
+ */
+export function SnackbarProvider(props: SnackbarProviderProps) {
+  const {
+    children,
+    position = 'bottom-right',
+    maxVisible = 5,
+    defaults,
+    slotProps,
+  } = props;
+
+  /**
+   * The set of CURRENTLY-RENDERED snackbars. Extras enqueued past
+   * `maxVisible` wait in `queueRef` until a slot frees up.
+   */
+  const [visible, setVisible] = useState<SnackbarRecord[]>([]);
+  const queueRef = useRef<SnackbarRecord[]>([]);
+
+  /** Monotonic id seed + tick. */
+  const idSeqRef = useRef(0);
+  const tickSeqRef = useRef(0);
+
+  /** Map<id, timeoutId> for auto-dismiss timers — cleared on dismiss/replace. */
+  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(
+    new Map()
+  );
+
+  /** Stable refs so `api` callbacks don't need to depend on state. */
+  const maxVisibleRef = useRef(maxVisible);
+  maxVisibleRef.current = maxVisible;
+  const defaultsRef = useRef(defaults);
+  defaultsRef.current = defaults;
+
+  const clearTimer = (id: string) => {
+    const t = timersRef.current.get(id);
+    if (t != null) {
+      clearTimeout(t);
+      timersRef.current.delete(id);
+    }
+  };
+
+  /**
+   * `dismiss` — remove a snackbar, then attempt to promote a queued
+   * item into the freed slot.
+   */
+  const dismiss = useCallback((id: string) => {
+    clearTimer(id);
+    setVisible((curr) => {
+      const next = curr.filter((s) => s.id !== id);
+      // Promote one from the queue if there's room.
+      if (next.length < maxVisibleRef.current && queueRef.current.length > 0) {
+        const promoted = queueRef.current.shift();
+        if (promoted != null) {
+          scheduleAutoDismiss(promoted);
+          return [...next, promoted];
+        }
+      }
+      return next;
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /**
+   * Schedule the auto-dismiss timeout for a given record (if its
+   * `autoHideMs > 0`). Stable ref so it can be invoked from inside
+   * `dismiss` without a circular dep.
+   */
+  const dismissRef = useRef(dismiss);
+  dismissRef.current = dismiss;
+  const scheduleAutoDismiss = useCallback((rec: SnackbarRecord) => {
+    const ms = rec.autoHideMs ?? defaultsRef.current?.autoHideMs ?? 4000;
+    if (ms <= 0) return;
+    clearTimer(rec.id);
+    const handle = setTimeout(() => dismissRef.current(rec.id), ms);
+    timersRef.current.set(rec.id, handle);
+  }, []);
+
+  /**
+   * `enqueue` — show a new snackbar.
+   *
+   * De-dup contract: if `options.id` matches a CURRENTLY-VISIBLE or
+   * CURRENTLY-QUEUED entry, the existing entry's content is updated
+   * AND its timer is reset, instead of appending a duplicate.
+   */
+  const enqueue = useCallback((options: SnackbarOptions): string => {
+    const id = options.id ?? `sb-${++idSeqRef.current}`;
+    const tick = ++tickSeqRef.current;
+    const rec: SnackbarRecord = {
+      ...defaultsRef.current,
+      ...options,
+      id,
+      tick,
+    };
+    // Reset timer if id already exists (de-dup).
+    clearTimer(id);
+
+    setVisible((curr) => {
+      const idx = curr.findIndex((s) => s.id === id);
+      if (idx >= 0) {
+        // Replace in-place, reset timer.
+        const next = [...curr];
+        next[idx] = rec;
+        scheduleAutoDismiss(rec);
+        return next;
+      }
+      // Drop the same-id entry from the queue if it's waiting.
+      queueRef.current = queueRef.current.filter((s) => s.id !== id);
+      if (curr.length < maxVisibleRef.current) {
+        scheduleAutoDismiss(rec);
+        return [...curr, rec];
+      }
+      // Stack is full — queue and wait.
+      queueRef.current.push(rec);
+      return curr;
+    });
+    return id;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  /** `dismissAll` — clear everything (visible + queued + timers). */
+  const dismissAll = useCallback(() => {
+    timersRef.current.forEach(clearTimeout);
+    timersRef.current.clear();
+    queueRef.current = [];
+    setVisible([]);
+  }, []);
+
+  // Clean up any straggler timers on unmount.
+  useEffect(
+    () => () => {
+      timersRef.current.forEach(clearTimeout);
+      timersRef.current.clear();
+    },
+    []
+  );
+
+  const api = useMemo<SnackbarApi>(
+    () => ({ enqueue, dismiss, dismissAll }),
+    [enqueue, dismiss, dismissAll]
+  );
+
+  const v = snackbarVariants({ position });
+
+  return (
+    <SnackbarContext.Provider value={api}>
+      {children}
+      <div
+        className={cn(v.container(), slotProps?.container?.className)}
+        role="region"
+        aria-label="Notifications"
+        aria-live="polite"
+        aria-atomic="false"
+      >
+        {visible.map((rec) => {
+          const sev = rec.severity ?? defaults?.severity ?? 'info';
+          const showClose =
+            rec.showClose ?? defaults?.showClose ?? true;
+          const itemClasses = snackbarVariants({
+            position,
+            severity: sev,
+          });
+          return (
+            <div
+              key={rec.id}
+              data-state="entered"
+              data-tick={rec.tick}
+              className={cn(
+                itemClasses.item(),
+                slotProps?.item?.className
+              )}
+            >
+              <span
+                aria-hidden="true"
+                className={cn(
+                  itemClasses.icon(),
+                  slotProps?.icon?.className
+                )}
+              >
+                {SEVERITY_GLYPH[sev]}
+              </span>
+              <div
+                className={cn(
+                  itemClasses.message(),
+                  slotProps?.message?.className
+                )}
+              >
+                {rec.message}
+              </div>
+              {rec.action != null && (
+                <button
+                  type="button"
+                  onClick={() => {
+                    rec.action?.onClick();
+                    dismiss(rec.id);
+                  }}
+                  className={cn(
+                    itemClasses.action(),
+                    slotProps?.action?.className
+                  )}
+                >
+                  {rec.action.label}
+                </button>
+              )}
+              {showClose && (
+                <button
+                  type="button"
+                  aria-label="Dismiss notification"
+                  onClick={() => dismiss(rec.id)}
+                  className={cn(
+                    itemClasses.closeButton(),
+                    slotProps?.closeButton?.className
+                  )}
+                >
+                  ×
+                </button>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </SnackbarContext.Provider>
+  );
+}

package/src/components/Snackbar/snackbar.types.ts

@@ -0,0 +1,83 @@
+import type { ReactNode } from 'react';
+import type { SnackbarVariants } from './snackbar.variants.js';
+
+/** Visual severity — drives icon color + accent on the snackbar surface. */
+export type SnackbarSeverity = 'info' | 'success' | 'warning' | 'danger';
+
+/** Corner anchor for the snackbar stack. */
+export type SnackbarPosition =
+  | 'top-left'
+  | 'top-center'
+  | 'top-right'
+  | 'bottom-left'
+  | 'bottom-center'
+  | 'bottom-right';
+
+/** One snackbar instance — what `useSnackbar().enqueue()` accepts. */
+export interface SnackbarOptions {
+  /** Required text/content. */
+  message: ReactNode;
+  /** Visual severity. @default 'info' */
+  severity?: SnackbarSeverity;
+  /**
+   * Auto-dismiss after this many ms. `0` / negative ⇒ persistent
+   * (only dismissed by the close button or `dismiss(id)`).
+   * @default 4000
+   */
+  autoHideMs?: number;
+  /** Optional action button label + handler. */
+  action?: { label: ReactNode; onClick: () => void };
+  /** Per-instance close-button visibility. @default true */
+  showClose?: boolean;
+  /**
+   * Stable identifier for de-duplication. If a snackbar with the same
+   * `id` is enqueued while already visible, the existing one is REUSED
+   * (auto-dismiss timer reset) instead of stacking a duplicate. Useful
+   * for "Saved" toasts triggered repeatedly from the same action.
+   */
+  id?: string;
+}
+
+/** Internal model — every enqueued snackbar gets a unique id + a tick. */
+export interface SnackbarRecord extends SnackbarOptions {
+  id: string;
+  /**
+   * Monotonic creation tick, used to drive the entry CSS transition
+   * (the consumer's CSS can target `data-state="entered"` keyed by tick).
+   */
+  tick: number;
+}
+
+export interface SnackbarSlotProps {
+  container?: { className?: string };
+  item?: { className?: string };
+  icon?: { className?: string };
+  message?: { className?: string };
+  action?: { className?: string };
+  closeButton?: { className?: string };
+}
+
+/** API exposed by `useSnackbar()`. */
+export interface SnackbarApi {
+  /** Show a snackbar — returns its assigned id (auto-generated if not provided). */
+  enqueue: (options: SnackbarOptions) => string;
+  /** Dismiss a specific snackbar. */
+  dismiss: (id: string) => void;
+  /** Dismiss every visible snackbar. */
+  dismissAll: () => void;
+}
+
+export interface SnackbarProviderProps extends SnackbarVariants {
+  children: ReactNode;
+  /** Corner the stack anchors to. @default 'bottom-right' */
+  position?: SnackbarPosition;
+  /**
+   * Hard cap on simultaneously visible snackbars. Excess enqueued
+   * items wait FIFO until a slot frees up. @default 5
+   */
+  maxVisible?: number;
+  /** Defaults merged into every enqueue. */
+  defaults?: Pick<SnackbarOptions, 'severity' | 'autoHideMs' | 'showClose'>;
+  /** Per-slot className overrides. */
+  slotProps?: SnackbarSlotProps;
+}