@dashforge/tw 0.1.0-beta

package/src/components/ConfirmDialog/ConfirmDialog.tsx

@@ -0,0 +1,252 @@
+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

@@ -0,0 +1,70 @@
+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;
+}

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

@@ -0,0 +1,76 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<ConfirmDialog>`.
+ *
+ * Built on the native HTML `<dialog>` element + `showModal()`, which
+ * gives us focus-trap, Escape handling, and `::backdrop` pseudo-element
+ * for free. The styling here is for the dialog body — the backdrop is
+ * styled via the `::backdrop` selector inside the dialog rule.
+ *
+ * Slots:
+ *   - `backdrop`      — semi-opaque overlay (`::backdrop` pseudo)
+ *   - `dialog`        — the modal box
+ *   - `title`         — modal heading
+ *   - `body`          — message text
+ *   - `actions`       — bottom button row
+ *   - `confirmButton` — primary action
+ *   - `cancelButton`  — secondary action
+ */
+export const confirmDialogVariants = tv({
+  slots: {
+    backdrop: 'backdrop:bg-black/40 backdrop:backdrop-blur-sm',
+    dialog: [
+      'rounded-lg bg-neutral-50 text-neutral-900 shadow-xl',
+      'border border-neutral-200',
+      'p-0 max-w-md w-[min(28rem,calc(100vw-2rem))]',
+      'open:flex open:flex-col',
+      // Native <dialog> defaults to centered; reinforce for older browsers.
+      'mx-auto my-auto',
+      'focus:outline-none',
+    ],
+    title:
+      'px-5 pt-5 pb-2 text-lg font-semibold text-neutral-900 leading-tight',
+    body: 'px-5 py-2 text-sm text-neutral-700 leading-relaxed',
+    actions:
+      'px-5 py-4 mt-2 flex justify-end gap-2 border-t border-neutral-200',
+    confirmButton: [
+      'inline-flex items-center justify-center px-4 h-9',
+      'rounded-md text-sm font-medium',
+      'outline-none focus-visible:ring-2 focus-visible:ring-offset-2',
+      'transition-colors',
+    ],
+    cancelButton: [
+      'inline-flex items-center justify-center px-4 h-9',
+      'rounded-md text-sm font-medium',
+      'text-neutral-800 bg-neutral-100 hover:bg-neutral-200',
+      'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
+      'transition-colors',
+    ],
+  },
+  variants: {
+    severity: {
+      info: {
+        confirmButton:
+          'bg-primary-600 hover:bg-primary-700 text-white focus-visible:ring-primary-500',
+      },
+      warning: {
+        confirmButton:
+          'bg-warning-600 hover:bg-warning-700 text-white focus-visible:ring-warning-500',
+      },
+      danger: {
+        confirmButton:
+          'bg-danger-600 hover:bg-danger-700 text-white focus-visible:ring-danger-500',
+      },
+      success: {
+        confirmButton:
+          'bg-success-600 hover:bg-success-700 text-white focus-visible:ring-success-500',
+      },
+    },
+  },
+  defaultVariants: {
+    severity: 'info',
+  },
+});
+
+export type ConfirmDialogVariants = VariantProps<typeof confirmDialogVariants>;

package/src/components/DateTimePicker/DateTimePicker.perf.test.tsx

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+/**
+ * Performance + re-render budget tests for `<DateTimePicker>`.
+ *
+ * Guardrails — not absolute benchmarks. They protect against:
+ *
+ *  1. Pathological mount cost (an accidental quadratic in a future
+ *     refactor — much less likely here than in `<Autocomplete>` because
+ *     there's no option list, but the test still pins the budget).
+ *
+ *  2. Sibling re-renders on every keystroke. The bridge subscription
+ *     model (`useDashFieldMeta(name)`) must remain GRANULAR — only the
+ *     field whose value changed re-renders, never a sibling.
+ *
+ *  3. Linear render budget per keystroke for THIS field. Aim for 1
+ *     render per `onChange`; tolerate 2 (RHF / engine reactive snapshot
+ *     batching).
+ *
+ *  4. Mode switch isn't accidentally expensive (cycling between
+ *     `date` / `time` / `datetime` mounts a NEW native input each time
+ *     — but the component itself must not allocate per-key arrays etc.).
+ */
+import { describe, it, expect } from 'vitest';
+import { render, fireEvent, screen } from '@testing-library/react';
+import { DashFormProvider } from '@dashforge/forms';
+import { DateTimePicker, TextField } from '../../index.js';
+
+function withRenderCounter<P>(
+  Component: React.ComponentType<P>,
+  counterRef: { count: number }
+): React.FC<P> {
+  return function Counted(props: P) {
+    counterRef.count++;
+    return <Component {...(props as P & object)} />;
+  };
+}
+
+describe('<DateTimePicker> performance', () => {
+  it('mounts well under 50ms (standalone, no bridge)', () => {
+    const t0 = performance.now();
+    render(<DateTimePicker name="d" label="Date" />);
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(50);
+  });
+
+  it('mounts under 100ms inside DashFormProvider (with bridge wiring)', () => {
+    const t0 = performance.now();
+    render(
+      <DashFormProvider defaultValues={{ d: '2026-05-16' }}>
+        <DateTimePicker name="d" label="Date" />
+      </DashFormProvider>
+    );
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(100);
+  });
+
+  it('processes a value change in under 20ms', () => {
+    render(<DateTimePicker name="d" label="Date" />);
+    const input = screen.getByLabelText('Date') as HTMLInputElement;
+    const t0 = performance.now();
+    fireEvent.change(input, { target: { value: '2026-12-25' } });
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(20);
+  });
+});
+
+describe('<DateTimePicker> re-render budget', () => {
+  it('renders at most 2 times on mount', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(DateTimePicker, counter);
+    render(<Counted name="d" label="Date" />);
+    // 1 initial + (tolerate 1 follow-up commit for any setState
+    // scheduled in a useEffect; today we don't schedule any, but the
+    // budget allows headroom).
+    expect(counter.count).toBeLessThanOrEqual(2);
+  });
+
+  it('keeps controlled re-renders ≤ 1 per value prop change', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(DateTimePicker, counter);
+    const { rerender } = render(
+      <Counted name="d" label="Date" value="2026-01-01" />
+    );
+    const baseline = counter.count;
+    rerender(<Counted name="d" label="Date" value="2026-01-02" />);
+    rerender(<Counted name="d" label="Date" value="2026-01-03" />);
+    rerender(<Counted name="d" label="Date" value="2026-01-04" />);
+    // 3 prop changes ⇒ ≤ 4 renders (one per change + tolerance).
+    expect(counter.count - baseline).toBeLessThanOrEqual(4);
+  });
+
+  it('does NOT re-render an unrelated sibling on each value change', () => {
+    // Critical perf property: typing into one DateTimePicker must not
+    // cause sibling components to re-render. Granular per-field
+    // subscription via `useDashFieldMeta(name)` is what enforces this.
+    const sibCount = { count: 0 };
+    const Sibling = () => {
+      sibCount.count++;
+      return <div data-testid="sib" />;
+    };
+    render(
+      <DashFormProvider defaultValues={{ d: '2026-01-01', other: 'x' }}>
+        <DateTimePicker name="d" label="Date" />
+        <Sibling />
+      </DashFormProvider>
+    );
+    const before = sibCount.count;
+    const input = screen.getByLabelText('Date') as HTMLInputElement;
+    for (let i = 1; i <= 5; i++) {
+      fireEvent.change(input, {
+        target: { value: `2026-01-0${i + 1}` },
+      });
+    }
+    expect(sibCount.count).toBe(before);
+  });
+
+  it('does NOT re-render when a sibling field changes (per-field subscription)', () => {
+    // Inverse of the above: changing the OTHER field in the bridge
+    // must not re-render the DateTimePicker. Verifies the granular
+    // `useDashFieldMeta` subscription is filtering by name.
+    const dtCount = { count: 0 };
+    const Counted = withRenderCounter(DateTimePicker, dtCount);
+    render(
+      <DashFormProvider defaultValues={{ d: '2026-01-01', other: '' }}>
+        <Counted name="d" label="Date" />
+        <TextField name="other" label="Other" />
+      </DashFormProvider>
+    );
+    const baseline = dtCount.count;
+    const other = screen.getByLabelText('Other') as HTMLInputElement;
+    for (let i = 0; i < 5; i++) {
+      fireEvent.change(other, { target: { value: 'a'.repeat(i + 1) } });
+    }
+    // The DateTimePicker may re-render once on initial mount of the
+    // sibling (parent re-render propagation) but NOT on each sibling
+    // keystroke. Budget: 0 additional renders.
+    expect(dtCount.count - baseline).toBeLessThanOrEqual(1);
+  });
+
+  it('mode switch (date ⇄ datetime) does not leak the previous native input', () => {
+    // Switching `mode` changes the native element's `type` attribute —
+    // React reuses the same DOM node (no remount). Assert that the
+    // input element identity is preserved.
+    const { rerender, container } = render(
+      <DateTimePicker name="d" label="X" mode="date" />
+    );
+    const inputBefore = container.querySelector('input');
+    rerender(<DateTimePicker name="d" label="X" mode="datetime" />);
+    const inputAfter = container.querySelector('input');
+    expect(inputBefore).toBe(inputAfter);
+    expect((inputAfter as HTMLInputElement).type).toBe('datetime-local');
+  });
+});