@dashforge/tw 1.1.0 → 1.2.0

package/src/components/ConfirmDialog/ConfirmDialog.test.tsx

@@ -1,311 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest';
-import {
-  render,
-  screen,
-  fireEvent,
-  cleanup,
-  act,
-  waitFor,
-} from '@testing-library/react';
-import {
-  ConfirmDialogProvider,
-  useConfirm,
-} from './ConfirmDialog.js';
-
-void React;
-afterEach(() => cleanup());
-
-// jsdom 22 doesn't implement HTMLDialogElement open/close. Shim the bits
-// our component touches BEFORE any test runs — without this the very
-// first `dlg.showModal()` call throws "not implemented".
-beforeAll(() => {
-  if (typeof HTMLDialogElement === 'undefined') return;
-  const proto = HTMLDialogElement.prototype as unknown as {
-    showModal?: () => void;
-    close?: (returnValue?: string) => void;
-    open?: boolean;
-  };
-  if (typeof proto.showModal !== 'function') {
-    proto.showModal = function (this: HTMLDialogElement) {
-      this.setAttribute('open', '');
-      // Mirror native dispatch order (open is sync, no 'open' event).
-    };
-  }
-  if (typeof proto.close !== 'function') {
-    proto.close = function (this: HTMLDialogElement) {
-      this.removeAttribute('open');
-      this.dispatchEvent(new Event('close'));
-    };
-  }
-});
-
-/**
- * Test harness — exposes the imperative `confirm()` to the test via a
- * `data-` attribute on a click target. Each click triggers a NEW
- * confirm call, and `last result` is recorded on the harness for
- * assertions.
- */
-function Harness({
-  capture,
-  options,
-}: {
-  capture: { last?: boolean | null };
-  options?: Parameters<ReturnType<typeof useConfirm>>[0];
-}) {
-  const confirm = useConfirm();
-  return (
-    <button
-      type="button"
-      data-testid="trigger"
-      onClick={async () => {
-        capture.last = null;
-        const ok = await confirm(options);
-        capture.last = ok;
-      }}
-    >
-      Open
-    </button>
-  );
-}
-
-describe('<ConfirmDialogProvider> + useConfirm()', () => {
-  describe('rendering', () => {
-    it('renders only its children when no request is active', () => {
-      render(
-        <ConfirmDialogProvider>
-          <div data-testid="child">app</div>
-        </ConfirmDialogProvider>
-      );
-      expect(screen.getByTestId('child')).toBeTruthy();
-      // The <dialog> exists (always mounted) but has no `open` attribute.
-      const dlg = document.querySelector('dialog');
-      expect(dlg).toBeTruthy();
-      expect(dlg?.hasAttribute('open')).toBe(false);
-    });
-
-    it('opens the native dialog when confirm() is called', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} options={{ title: 'T', body: 'B' }} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const dlg = document.querySelector('dialog') as HTMLDialogElement;
-      expect(dlg.hasAttribute('open')).toBe(true);
-      expect(screen.getByText('T')).toBeTruthy();
-      expect(screen.getByText('B')).toBeTruthy();
-    });
-  });
-
-  describe('event resolution', () => {
-    it('resolves true on Confirm click', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      await act(async () => {
-        fireEvent.click(screen.getByRole('button', { name: 'Confirm' }));
-      });
-      await waitFor(() => expect(capture.last).toBe(true));
-    });
-
-    it('resolves false on Cancel click', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      await act(async () => {
-        fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
-      });
-      await waitFor(() => expect(capture.last).toBe(false));
-    });
-
-    it('resolves false on backdrop click', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const dlg = document.querySelector('dialog') as HTMLDialogElement;
-      // Backdrop click: event target equals the dialog element itself.
-      await act(async () => {
-        fireEvent.click(dlg);
-      });
-      await waitFor(() => expect(capture.last).toBe(false));
-    });
-
-    it('does NOT close on backdrop when disableBackdropClose=true', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness
-            capture={capture}
-            options={{ disableBackdropClose: true }}
-          />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const dlg = document.querySelector('dialog') as HTMLDialogElement;
-      await act(async () => {
-        fireEvent.click(dlg);
-      });
-      // No resolution yet — dialog stays open.
-      expect(capture.last).toBeNull();
-      expect(dlg.hasAttribute('open')).toBe(true);
-    });
-  });
-
-  describe('useConfirm() outside provider', () => {
-    it('throws a helpful error', () => {
-      const Lone = () => {
-        useConfirm();
-        return null;
-      };
-      // Suppress React's console.error noise for this expected throw.
-      const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
-      expect(() => render(<Lone />)).toThrow(/useConfirm/);
-      spy.mockRestore();
-    });
-  });
-
-  describe('severity', () => {
-    it('applies the danger color class on the confirm button', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} options={{ severity: 'danger' }} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const btn = screen.getByRole('button', { name: 'Confirm' });
-      expect(btn.className).toMatch(/danger/);
-    });
-  });
-
-  describe('queueing', () => {
-    it('processes concurrent confirm() calls FIFO', async () => {
-      const captures: Array<{ last?: boolean | null }> = [{}, {}];
-      function Multi() {
-        const confirm = useConfirm();
-        return (
-          <>
-            <button
-              data-testid="t1"
-              onClick={async () => {
-                captures[0].last = await confirm({ title: 'First' });
-              }}
-            >
-              t1
-            </button>
-            <button
-              data-testid="t2"
-              onClick={async () => {
-                captures[1].last = await confirm({ title: 'Second' });
-              }}
-            >
-              t2
-            </button>
-          </>
-        );
-      }
-      render(
-        <ConfirmDialogProvider>
-          <Multi />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('t1'));
-        fireEvent.click(screen.getByTestId('t2'));
-      });
-      // First request is showing.
-      expect(screen.getByText('First')).toBeTruthy();
-      // Resolve the first one — second should pop up.
-      await act(async () => {
-        fireEvent.click(screen.getByRole('button', { name: 'Confirm' }));
-      });
-      await waitFor(() => expect(captures[0].last).toBe(true));
-      await waitFor(() => expect(screen.getByText('Second')).toBeTruthy());
-      // Resolve the second one.
-      await act(async () => {
-        fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
-      });
-      await waitFor(() => expect(captures[1].last).toBe(false));
-    });
-  });
-
-  describe('custom labels', () => {
-    it('renders confirmLabel + cancelLabel from options', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness
-            capture={capture}
-            options={{ confirmLabel: 'Delete', cancelLabel: 'Keep' }}
-          />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      expect(screen.getByRole('button', { name: 'Delete' })).toBeTruthy();
-      expect(screen.getByRole('button', { name: 'Keep' })).toBeTruthy();
-    });
-  });
-
-  describe('a11y wiring', () => {
-    it('sets aria-labelledby when a title is provided', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} options={{ title: 'Heads up' }} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const dlg = document.querySelector('dialog') as HTMLDialogElement;
-      const labelledBy = dlg.getAttribute('aria-labelledby');
-      expect(labelledBy).toBeTruthy();
-      expect(
-        labelledBy ? document.getElementById(labelledBy)?.textContent : null
-      ).toBe('Heads up');
-    });
-
-    it('does NOT set aria-labelledby when no title', async () => {
-      const capture: { last?: boolean | null } = {};
-      render(
-        <ConfirmDialogProvider>
-          <Harness capture={capture} options={{ body: 'no title' }} />
-        </ConfirmDialogProvider>
-      );
-      await act(async () => {
-        fireEvent.click(screen.getByTestId('trigger'));
-      });
-      const dlg = document.querySelector('dialog') as HTMLDialogElement;
-      expect(dlg.getAttribute('aria-labelledby')).toBeNull();
-    });
-  });
-});

package/src/components/ConfirmDialog/ConfirmDialog.tsx

@@ -1,252 +0,0 @@
-import {
-  createContext,
-  useCallback,
-  useContext,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react';
-import { cn } from '../../utils/cn.js';
-import { confirmDialogVariants } from './confirmDialog.variants.js';
-import type {
-  ConfirmDialogProviderProps,
-  ConfirmFn,
-  ConfirmOptions,
-  ConfirmDialogSlotProps,
-} from './confirmDialog.types.js';
-
-/**
- * Internal queue entry — the live request being shown PLUS the resolver
- * for its promise.
- */
-interface ActiveRequest {
-  options: ConfirmOptions;
-  resolve: (value: boolean) => void;
-}
-
-const ConfirmContext = createContext<ConfirmFn | null>(null);
-
-/**
- * `useConfirm()` — returns the imperative `confirm()` function.
- *
- * Throws if called outside a `<ConfirmDialogProvider>`. The thrown error
- * tells the developer exactly what to do — no silent no-op (silently
- * resolving `false` would be a footgun for destructive actions).
- */
-export function useConfirm(): ConfirmFn {
-  const ctx = useContext(ConfirmContext);
-  if (ctx == null) {
-    throw new Error(
-      '[ConfirmDialog] useConfirm() must be called inside <ConfirmDialogProvider>.'
-    );
-  }
-  return ctx;
-}
-
-/**
- * Dashforge TW ConfirmDialog provider.
- *
- * Imperative confirmation modal built on the native HTML `<dialog>`
- * element + `showModal()`. Why native:
- *
- *  1. **AAA-grade a11y for free** — browsers implement focus trap,
- *     Escape key, inert background, and `aria-modal` semantics natively.
- *  2. **Zero new deps** — no `@radix-ui/react-dialog` or Aria stack.
- *  3. **Smaller bundle** — ~1 KB of logic vs. ~25 KB for Aria Dialog.
- *
- * **Behaviour**:
- *   - `confirm(opts)` returns a `Promise<boolean>`.
- *   - Backdrop click resolves `false` (unless `disableBackdropClose`).
- *   - Escape key resolves `false` (unless `disableEscapeClose`).
- *   - Cancel button resolves `false`.
- *   - Confirm button resolves `true`.
- *   - At most ONE dialog open at a time — concurrent `confirm()` calls
- *     queue and fire FIFO (so a destructive action can't accidentally
- *     race a benign one).
- *
- * **A11y**:
- *   - `<dialog>` ⇒ implicit `role="dialog"` + `aria-modal="true"`.
- *   - `aria-labelledby` wires the title id to the dialog.
- *   - Focus is auto-trapped by `showModal()`.
- *   - First focusable element receives focus on open (browser-managed).
- */
-export function ConfirmDialogProvider(props: ConfirmDialogProviderProps) {
-  const { children, defaults, slotProps: providerSlotProps, severity } = props;
-
-  const [active, setActive] = useState<ActiveRequest | null>(null);
-  // FIFO queue of pending requests. We process them strictly in order
-  // so a quick `confirm(A); confirm(B)` keeps the user's mental model
-  // (A first, then B) instead of dropping/overlapping.
-  const queueRef = useRef<ActiveRequest[]>([]);
-  const dialogRef = useRef<HTMLDialogElement | null>(null);
-  const titleId = `confirm-dialog-title`;
-
-  /** Drain one item from the queue into the active slot, if any. */
-  const advanceQueue = useCallback(() => {
-    const next = queueRef.current.shift();
-    setActive(next ?? null);
-  }, []);
-
-  /**
-   * Public API — enqueue a confirmation and return a promise that
-   * resolves when the user picks an option (or the dialog is dismissed).
-   *
-   * Implementation note: we ALWAYS push the new request into
-   * `queueRef.current`, then ask React to advance — `setActive` runs
-   * with a functional updater, so it sees the latest `active` even when
-   * two `confirm()` calls fire back-to-back in the same tick (before
-   * a re-render). This is what makes the FIFO contract reliable under
-   * synchronous bursts.
-   */
-  const confirm = useCallback<ConfirmFn>(
-    (options) => {
-      return new Promise<boolean>((resolve) => {
-        const merged: ConfirmOptions = { ...defaults, ...options };
-        const entry: ActiveRequest = { options: merged, resolve };
-        queueRef.current.push(entry);
-        setActive((curr) => curr ?? queueRef.current.shift() ?? null);
-      });
-    },
-    [defaults]
-  );
-
-  // Open / close the native dialog in sync with `active`.
-  // `showModal()` MUST be called from a side effect (post-render) so
-  // React has finished mounting the `<dialog>` element.
-  useEffect(() => {
-    const dlg = dialogRef.current;
-    if (!dlg) return;
-    if (active != null && !dlg.open) {
-      dlg.showModal();
-    } else if (active == null && dlg.open) {
-      dlg.close();
-    }
-  }, [active]);
-
-  /** Resolve the current promise with `value` and pop the next request. */
-  const finish = useCallback(
-    (value: boolean) => {
-      if (active == null) return;
-      active.resolve(value);
-      advanceQueue();
-    },
-    [active, advanceQueue]
-  );
-
-  /**
-   * Wire the native `close` event — fires for Escape OR for `dialog.close()`.
-   * We need this so an Escape press (handled internally by the browser
-   * without going through our React handlers) still resolves the promise.
-   */
-  useEffect(() => {
-    const dlg = dialogRef.current;
-    if (!dlg) return;
-    const handler = () => {
-      if (active == null) return;
-      // Browser closed (Escape). If consumer disabled Esc, re-open.
-      if (active.options.disableEscapeClose) {
-        dlg.showModal();
-        return;
-      }
-      finish(false);
-    };
-    dlg.addEventListener('close', handler);
-    return () => dlg.removeEventListener('close', handler);
-  }, [active, finish]);
-
-  /**
-   * Backdrop click ⇒ resolve false. The native `<dialog>` element
-   * receives the click event when the user clicks OUTSIDE the dialog
-   * body (the click lands on the `::backdrop` pseudo) — we detect
-   * that by checking the event target equals the dialog itself.
-   */
-  const handleDialogClick = (event: React.MouseEvent<HTMLDialogElement>) => {
-    if (active == null) return;
-    if (active.options.disableBackdropClose) return;
-    if (event.target === event.currentTarget) {
-      finish(false);
-    }
-  };
-
-  // Memoize the context value so consumers that re-render for unrelated
-  // reasons don't trigger the entire provider subtree.
-  const ctxValue = useMemo<ConfirmFn>(() => confirm, [confirm]);
-
-  const opts = active?.options;
-  const mergedSlotProps: ConfirmDialogSlotProps = {
-    ...providerSlotProps,
-    ...opts?.slotProps,
-  };
-  const v = confirmDialogVariants({
-    severity: opts?.severity ?? severity ?? 'info',
-  });
-
-  return (
-    <ConfirmContext.Provider value={ctxValue}>
-      {children}
-      {/*
-        The native <dialog> is ALWAYS mounted (even when `active` is null)
-        so the ref is stable and the open/close effect can run on the
-        same DOM node across requests. The contents render conditionally.
-      */}
-      <dialog
-        ref={dialogRef}
-        aria-labelledby={opts?.title != null ? titleId : undefined}
-        onClick={handleDialogClick}
-        className={cn(
-          v.backdrop(),
-          v.dialog(),
-          mergedSlotProps.backdrop?.className,
-          mergedSlotProps.dialog?.className
-        )}
-      >
-        {opts != null && (
-          <>
-            {opts.title != null && (
-              <h2
-                id={titleId}
-                className={cn(v.title(), mergedSlotProps.title?.className)}
-              >
-                {opts.title}
-              </h2>
-            )}
-            {opts.body != null && (
-              <div className={cn(v.body(), mergedSlotProps.body?.className)}>
-                {opts.body}
-              </div>
-            )}
-            <div
-              className={cn(
-                v.actions(),
-                mergedSlotProps.actions?.className
-              )}
-            >
-              <button
-                type="button"
-                onClick={() => finish(false)}
-                className={cn(
-                  v.cancelButton(),
-                  mergedSlotProps.cancelButton?.className
-                )}
-              >
-                {opts.cancelLabel ?? 'Cancel'}
-              </button>
-              <button
-                type="button"
-                onClick={() => finish(true)}
-                autoFocus
-                className={cn(
-                  v.confirmButton(),
-                  mergedSlotProps.confirmButton?.className
-                )}
-              >
-                {opts.confirmLabel ?? 'Confirm'}
-              </button>
-            </div>
-          </>
-        )}
-      </dialog>
-    </ConfirmContext.Provider>
-  );
-}

package/src/components/ConfirmDialog/confirmDialog.types.ts

@@ -1,70 +0,0 @@
-import type { ReactNode } from 'react';
-import type { ConfirmDialogVariants } from './confirmDialog.variants.js';
-
-/**
- * Severity / intent of the confirmation request — drives the accent
- * color of the confirm button (info / warning / danger / success).
- */
-export type ConfirmSeverity = 'info' | 'warning' | 'danger' | 'success';
-
-export interface ConfirmDialogSlotProps {
-  backdrop?: { className?: string };
-  dialog?: { className?: string };
-  title?: { className?: string };
-  body?: { className?: string };
-  actions?: { className?: string };
-  confirmButton?: { className?: string };
-  cancelButton?: { className?: string };
-}
-
-/**
- * One-shot confirmation request.
- *
- * Passed to `confirm()` from `useConfirm()` — the consumer awaits the
- * returned promise. Resolves `true` when the user clicks confirm,
- * `false` otherwise (cancel, backdrop, Escape).
- */
-export interface ConfirmOptions {
-  title?: ReactNode;
-  /**
-   * Body content. Either a plain node (rendered inside `<p>`) or a
-   * fully custom render — accepted as a ReactNode to keep the API simple.
-   */
-  body?: ReactNode;
-  /** Confirm button label. @default 'Confirm' */
-  confirmLabel?: ReactNode;
-  /** Cancel button label. @default 'Cancel' */
-  cancelLabel?: ReactNode;
-  /** Severity drives confirm button color. @default 'info' */
-  severity?: ConfirmSeverity;
-  /** Disable the backdrop-click close. @default false */
-  disableBackdropClose?: boolean;
-  /** Disable the Escape-key close. @default false */
-  disableEscapeClose?: boolean;
-  /** Per-slot className overrides for this single invocation. */
-  slotProps?: ConfirmDialogSlotProps;
-}
-
-/**
- * Imperative API exposed by `useConfirm()`.
- *
- * ```tsx
- * const confirm = useConfirm();
- * const ok = await confirm({
- *   title: 'Delete record?',
- *   body: 'This action cannot be undone.',
- *   severity: 'danger',
- *   confirmLabel: 'Delete',
- * });
- * if (ok) { ... }
- * ```
- */
-export type ConfirmFn = (options?: ConfirmOptions) => Promise<boolean>;
-
-export interface ConfirmDialogProviderProps extends ConfirmDialogVariants {
-  children: ReactNode;
-  /** Default options merged into every `confirm()` invocation. */
-  defaults?: ConfirmOptions;
-  /** Per-slot className overrides applied to ALL invocations. */
-  slotProps?: ConfirmDialogSlotProps;
-}