@dashforge/tw 1.0.0 → 1.1.1

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

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

@@ -1,76 +0,0 @@
-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/Container/Container.test.tsx

@@ -1,209 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { render } from '@testing-library/react';
-import { Container } from './Container.js';
-
-describe('<Container>', () => {
-  // ─── Default rendering ──────────────────────────────────────────────
-  describe('default rendering', () => {
-    it('renders a <div> by default', () => {
-      const { container } = render(<Container>x</Container>);
-      expect(container.firstElementChild?.tagName).toBe('DIV');
-    });
-
-    it('has mx-auto + w-full baseline', () => {
-      const { container } = render(<Container>x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('mx-auto');
-      expect(cls).toContain('w-full');
-    });
-
-    it('default size is xl (max-w-screen-xl)', () => {
-      const { container } = render(<Container>x</Container>);
-      expect(container.firstElementChild?.className).toContain('max-w-screen-xl');
-    });
-
-    it('default px is true — responsive padding ramp', () => {
-      const { container } = render(<Container>x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('px-4');
-      expect(cls).toContain('sm:px-6');
-      expect(cls).toContain('lg:px-8');
-    });
-
-    it('default centerContent is false — no flex column', () => {
-      const { container } = render(<Container>x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      // baseline doesn't include flex
-      expect(cls.split(' ')).not.toContain('flex');
-    });
-  });
-
-  // ─── Size axis ──────────────────────────────────────────────────────
-  describe('size', () => {
-    it('size="sm"', () => {
-      const { container } = render(<Container size="sm">x</Container>);
-      expect(container.firstElementChild?.className).toContain('max-w-screen-sm');
-    });
-
-    it('size="lg"', () => {
-      const { container } = render(<Container size="lg">x</Container>);
-      expect(container.firstElementChild?.className).toContain('max-w-screen-lg');
-    });
-
-    it('size="2xl"', () => {
-      const { container } = render(<Container size="2xl">x</Container>);
-      expect(container.firstElementChild?.className).toContain('max-w-screen-2xl');
-    });
-
-    it('size="fluid" emits no max-w-* class', () => {
-      const { container } = render(<Container size="fluid">x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('max-w-screen');
-      // still mx-auto + w-full baseline
-      expect(cls).toContain('mx-auto');
-    });
-  });
-
-  // ─── Padding axis ───────────────────────────────────────────────────
-  describe('padding', () => {
-    it('px={false} skips the responsive padding ramp', () => {
-      const { container } = render(<Container px={false}>x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('px-4');
-      expect(cls).not.toContain('sm:px-6');
-    });
-  });
-
-  // ─── Center content ─────────────────────────────────────────────────
-  describe('centerContent', () => {
-    it('centerContent turns into flex column items-center', () => {
-      const { container } = render(<Container centerContent>x</Container>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('flex');
-      expect(cls).toContain('flex-col');
-      expect(cls).toContain('items-center');
-    });
-  });
-
-  // ─── Override semantics ─────────────────────────────────────────────
-  describe('override', () => {
-    it('sx wins over default size via tailwind-merge', () => {
-      const { container } = render(
-        <Container sx="max-w-3xl">x</Container>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('max-w-3xl');
-      // tailwind-merge collapses the conflicting max-w-screen-xl
-      expect(cls).not.toContain('max-w-screen-xl');
-    });
-
-    it('sx can add vertical padding (Container does not expose it)', () => {
-      const { container } = render(<Container sx="py-12">x</Container>);
-      expect(container.firstElementChild?.className).toContain('py-12');
-    });
-  });
-
-  // ─── Polymorphism ───────────────────────────────────────────────────
-  describe('polymorphism', () => {
-    it('as="main" renders <main> with Container chrome', () => {
-      const { container } = render(<Container as="main">x</Container>);
-      const el = container.firstElementChild;
-      expect(el?.tagName).toBe('MAIN');
-      expect(el?.className).toContain('mx-auto');
-    });
-
-    it('asChild paints onto the child element', () => {
-      const { container } = render(
-        <Container size="lg" asChild>
-          <article>x</article>
-        </Container>,
-      );
-      const el = container.firstElementChild;
-      expect(el?.tagName).toBe('ARTICLE');
-      expect(el?.className).toContain('max-w-screen-lg');
-    });
-
-    it('asChild wins over as when both are passed', () => {
-      const { container } = render(
-        <Container as="main" asChild>
-          <section>x</section>
-        </Container>,
-      );
-      expect(container.firstElementChild?.tagName).toBe('SECTION');
-    });
-  });
-
-  // ─── Pass-through ────────────────────────────────────────────────────
-  describe('pass-through', () => {
-    it('forwards data-* + aria-*', () => {
-      const { container } = render(
-        <Container data-testid="c" aria-label="page">x</Container>,
-      );
-      const el = container.firstElementChild;
-      expect(el?.getAttribute('data-testid')).toBe('c');
-      expect(el?.getAttribute('aria-label')).toBe('page');
-    });
-  });
-
-  // ─── F11-bis edge cases ─────────────────────────────────────────────
-  describe('axis coexistence', () => {
-    it('size + centerContent + px=true (all three combine)', () => {
-      const { container } = render(
-        <Container size="md" centerContent px>x</Container>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('max-w-screen-md');
-      expect(cls).toContain('flex');
-      expect(cls).toContain('flex-col');
-      expect(cls).toContain('items-center');
-      expect(cls).toContain('px-4');
-    });
-
-    it('fluid + centerContent (full-bleed centered hero pattern)', () => {
-      const { container } = render(
-        <Container size="fluid" centerContent>x</Container>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('max-w-screen');
-      expect(cls).toContain('flex-col');
-      expect(cls).toContain('items-center');
-    });
-
-    it('fluid + px=false (full-bleed edge-to-edge — hero image pattern)', () => {
-      const { container } = render(
-        <Container size="fluid" px={false}>x</Container>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).not.toContain('max-w-screen');
-      expect(cls).not.toContain('px-4');
-      // still has mx-auto + w-full baseline
-      expect(cls).toContain('mx-auto');
-    });
-  });
-
-  describe('nested fluid-outer + capped-inner pattern', () => {
-    it('outer fluid colored band + inner capped content renders both', () => {
-      const { container } = render(
-        <Container size="fluid" px={false} sx="bg-primary-50 py-16">
-          <Container size="lg">
-            <p>inner</p>
-          </Container>
-        </Container>,
-      );
-      const outer = container.firstElementChild;
-      const inner = outer?.querySelector('div');
-      expect(outer?.className).toContain('bg-primary-50');
-      expect(outer?.className).not.toContain('max-w-screen');
-      expect(inner?.className).toContain('max-w-screen-lg');
-    });
-  });
-
-  describe('every size value', () => {
-    const SIZES = ['sm', 'md', 'lg', 'xl', '2xl'] as const;
-    it.each(SIZES)('size="%s" emits max-w-screen-%s', (s) => {
-      const { container } = render(<Container size={s}>x</Container>);
-      expect(container.firstElementChild?.className).toContain(`max-w-screen-${s}`);
-    });
-  });
-});

package/src/components/Container/Container.tsx

@@ -1,74 +0,0 @@
-import { forwardRef, type ElementType, type ReactElement } from 'react';
-import { Slot } from '@radix-ui/react-slot';
-import { cn } from '../../utils/cn.js';
-import { containerVariants } from './container.variants.js';
-import type { ContainerProps } from './container.types.js';
-
-/**
- * `<Container>` — centered max-width wrapper for page-level layouts.
- *
- * The pattern is universal: every page-root `<div>` in a non-trivial
- * web app boils down to "mx-auto + max-w-X + responsive horizontal
- * padding". Container collapses that into a typed prop set so the
- * decision lives in ONE place per app section (the Container size),
- * not scattered as utility chains across every page file.
- *
- * Default size is `'xl'` (1280px) — comfortable for full app shells
- * with a left nav + main + optional right rail. Drop to `'lg'` (1024px)
- * for content-heavy docs/marketing, jump to `'2xl'` (1536px) for wide
- * dashboards.
- *
- * Composition pattern — Container at the page root, Stack/Grid inside:
- *
- *   <Container size="lg" as="main">
- *     <Stack gap={8}>
- *       <Typography variant="h1">Page title</Typography>
- *       <Grid container spacing={6}>
- *         <Grid xs={12} md={6}>...</Grid>
- *       </Grid>
- *     </Stack>
- *   </Container>
- *
- * Container handles the page chrome (centered, padded, capped width);
- * Stack/Grid handle the actual layout of children. Two concerns, two
- * primitives.
- *
- * Polymorphism rule (same as Typography/Box/Stack/Grid): when both
- * `as` and `asChild` are passed, `asChild` wins.
- */
-export const Container = forwardRef<HTMLElement, ContainerProps>(
-  function Container(props, ref) {
-    const {
-      size,
-      px,
-      centerContent,
-      as,
-      asChild = false,
-      sx,
-      children,
-      ...rest
-    } = props;
-
-    const classes = cn(
-      containerVariants({ size, px, centerContent }),
-      sx,
-    );
-
-    if (asChild) {
-      return (
-        <Slot ref={ref} className={classes} {...rest}>
-          {children as ReactElement}
-        </Slot>
-      );
-    }
-
-    const Tag = (as ?? 'div') as ElementType;
-    return (
-      <Tag ref={ref as never} className={classes} {...rest}>
-        {children}
-      </Tag>
-    );
-  },
-);
-
-Container.displayName = 'Container';