@dashforge/tw 1.1.0 → 1.2.0

package/src/components/Alert/alert.types.ts

@@ -1,144 +0,0 @@
-import type { ComponentPropsWithoutRef, ReactNode } from 'react';
-import type { ClassValue } from 'tailwind-variants';
-import type { Engine } from '@dashforge/ui-core';
-import type { AccessRequirement } from '@dashforge/rbac';
-import type { Severity, SeverityVariant } from '../_shared/severity/severity.types.js';
-
-/**
- * Per-slot override props for `<Alert>`. Mirrors the standard
- * `slotProps` contract used across `@dashforge/tw` components.
- */
-export interface AlertSlotProps {
-  root?: ComponentPropsWithoutRef<'div'>;
-  icon?: ComponentPropsWithoutRef<'span'>;
-  content?: ComponentPropsWithoutRef<'div'>;
-  action?: ComponentPropsWithoutRef<'div'>;
-  closeButton?: ComponentPropsWithoutRef<'button'>;
-}
-
-/**
- * Props for the `<Alert>` component.
- *
- * Mirrors the MUI Alert API surface 1:1 (drop-in muscle memory) with
- * a single deliberate divergence: `severity` uses `'danger'` instead of
- * MUI's `'error'` for alignment with the `danger.*` token palette in
- * `@dashforge/tw-tokens`.
- *
- * In addition to the MUI surface, Dashforge adds:
- *   - `visibleWhen` — engine-reactive visibility predicate (same
- *     contract as `<TextField>` / `<Checkbox>` / etc.)
- *   - `access` — RBAC integration via `@dashforge/rbac`
- *
- * @see https://mui.com/material-ui/api/alert/
- */
-export interface AlertProps {
-  /**
-   * Visual severity. Drives the color treatment and the default ARIA
-   * role (`alert` for warning / danger, `status` for info / success).
-   *
-   * Note: this is `danger`, not MUI's `error`. The runtime behaviour
-   * is identical; the naming follows the Dashforge token palette.
-   */
-  severity: Severity;
-
-  /**
-   * Variant of the severity surface. Mirrors MUI's three-way axis.
-   *
-   * - `'standard'` (default) — tinted soft surface, severity-toned
-   *   text. The "all-purpose" reading.
-   * - `'filled'` — solid colored surface, light text. High visual
-   *   weight, for blocking / critical messages.
-   * - `'outlined'` — transparent surface, severity border + text.
-   *   Minimal weight, for dense layouts.
-   *
-   * @default 'standard'
-   */
-  variant?: SeverityVariant;
-
-  /** Body content of the alert. */
-  children?: ReactNode;
-
-  /**
-   * Icon control with full MUI parity.
-   *
-   * - omitted / `undefined` → default per-severity icon (lib's inline
-   *   stroke SVG)
-   * - `ReactNode` → consumer-provided custom icon (Lucide, Phosphor,
-   *   Tabler, custom SVG — bring your own iconography)
-   * - `false` → no icon rendered (the colored surface carries the
-   *   severity signal; use when icons compete with the layout)
-   */
-  icon?: ReactNode | false;
-
-  /**
-   * When defined, the alert renders a trailing close button that
-   * fires this callback on click. Ignored if `action` is provided
-   * (`action` slot wins, matching MUI behaviour).
-   */
-  onClose?: () => void;
-
-  /**
-   * `aria-label` for the close button.
-   * @default 'Close'
-   */
-  closeText?: string;
-
-  /**
-   * Custom trailing slot — CTA buttons, links, inline forms. When
-   * provided, replaces the auto-rendered close button. The consumer
-   * is responsible for wiring any close behaviour into the custom
-   * action node.
-   */
-  action?: ReactNode;
-
-  /**
-   * Override the auto-derived ARIA role. Defaults to `'alert'` for
-   * `severity={'warning' | 'danger'}` (assertive announcement) and
-   * `'status'` for `severity={'info' | 'success'}` (polite).
-   */
-  role?: 'alert' | 'status';
-
-  /**
-   * Reactive visibility predicate. Re-evaluated on every engine state
-   * change when the alert is mounted inside a `<DashForm>`; outside a
-   * form, evaluated as a plain predicate (the consumer captures any
-   * external state in the closure).
-   *
-   * When the predicate returns `false`, the component renders `null`
-   * — same contract as form fields.
-   */
-  visibleWhen?: (engine: Engine) => boolean;
-
-  /**
-   * RBAC requirement. When the current subject does not satisfy the
-   * requirement, the alert is hidden (or disabled / read-only,
-   * per `onUnauthorized`).
-   */
-  access?: AccessRequirement;
-
-  /** Root-element class shortcut (string or `clsx`-compatible value). */
-  sx?: ClassValue;
-
-  /** Standard React `className` — appended to the root via `cn()`. */
-  className?: string;
-
-  /** Per-slot overrides — typed handles for the inner elements. */
-  slotProps?: AlertSlotProps;
-}
-
-/**
- * Props for the `<AlertTitle>` sub-component.
- *
- * AlertTitle is a separate exported component, not a prop on Alert —
- * follows MUI's pattern. Pass it as the first child of `<Alert>`:
- *
- * @example
- * <Alert severity="warning">
- *   <AlertTitle>Subscription expires soon</AlertTitle>
- *   Your Pro plan ends on 2026-06-20.
- * </Alert>
- */
-export interface AlertTitleProps {
-  children: ReactNode;
-  className?: string;
-}

package/src/components/Alert/alert.variants.ts

@@ -1,71 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<Alert>`.
- *
- * Slots:
- *   - `root`         — outer surface, severity + variant color classes
- *                      come from `_shared/severity/severityVariants`
- *                      (NOT baked into this recipe, to keep the matrix
- *                      shared across Alert / Snackbar / future Banner)
- *   - `icon`         — leading severity icon container
- *   - `titleSlot`    — `<AlertTitle>` rendered as the first content row
- *   - `content`      — body text container
- *   - `action`       — trailing action / close button container
- *   - `closeButton`  — built-in close `×` (when `onClose` is defined)
- *
- * The severity color classes are merged at render time via `cn()` in
- * `Alert.tsx` — see the call sites of `getSeverityClasses(variant,
- * severity)`. This recipe owns layout + spacing + typography only.
- */
-export const alertVariants = tv({
-  slots: {
-    root: [
-      'relative flex items-start gap-3',
-      'px-4 py-3',
-      'rounded-lg border',
-      'text-sm',
-      // Smooth visibility transition (opacity only) — matches the
-      // Snackbar entry timing, gated on motion-reduce per WCAG 2.3.3.
-      'transition-opacity duration-150 motion-reduce:transition-none motion-reduce:duration-0',
-    ],
-    icon: [
-      'shrink-0 mt-0.5',
-      'inline-flex items-center justify-center',
-    ],
-    titleSlot: [
-      'block font-medium leading-snug mb-1',
-    ],
-    content: [
-      'flex-1 min-w-0',
-      'leading-relaxed',
-    ],
-    action: [
-      'shrink-0 inline-flex items-center',
-      'ml-auto',
-    ],
-    closeButton: [
-      'shrink-0 inline-flex items-center justify-center w-6 h-6',
-      'rounded-md',
-      'opacity-70 hover:opacity-100',
-      'outline-none focus-visible:ring-2 focus-visible:ring-current',
-      'transition-opacity',
-    ],
-  },
-  variants: {
-    /**
-     * Layout density. Defaults to comfortable spacing; `compact`
-     * tightens the vertical padding for inline contexts (form
-     * validation summary at the top of a tight modal, etc.).
-     */
-    density: {
-      comfortable: { root: 'px-4 py-3' },
-      compact: { root: 'px-3 py-2 text-[13px]' },
-    },
-  },
-  defaultVariants: {
-    density: 'comfortable',
-  },
-});
-
-export type AlertVariantProps = VariantProps<typeof alertVariants>;

package/src/components/AppShell/AppShell.test.tsx

@@ -1,223 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import {
-  render,
-  screen,
-  fireEvent,
-  cleanup,
-} from '@testing-library/react';
-import { AppShell } from './AppShell.js';
-
-void React;
-afterEach(() => cleanup());
-
-describe('<AppShell>', () => {
-  describe('rendering', () => {
-    it('renders main landmark with children', () => {
-      render(
-        <AppShell>
-          <p>page</p>
-        </AppShell>
-      );
-      const main = screen.getByRole('main');
-      expect(main.textContent).toBe('page');
-    });
-
-    it('renders header slot', () => {
-      render(
-        <AppShell header={<div data-testid="hdr">H</div>}>
-          <p>page</p>
-        </AppShell>
-      );
-      expect(screen.getByTestId('hdr')).toBeTruthy();
-    });
-
-    it('renders footer slot', () => {
-      render(
-        <AppShell footer={<div data-testid="ftr">F</div>}>
-          <p>page</p>
-        </AppShell>
-      );
-      expect(screen.getByTestId('ftr')).toBeTruthy();
-    });
-
-    it('renders nav slot (twice — desktop inline + mobile drawer)', () => {
-      const { container } = render(
-        <AppShell nav={<div data-testid="nav">N</div>}>
-          <p>page</p>
-        </AppShell>
-      );
-      // Both copies are in the DOM; the mobile one is hidden via CSS.
-      expect(container.querySelectorAll('[data-testid="nav"]')).toHaveLength(2);
-    });
-
-    it('does NOT render the nav-side asides when nav is omitted', () => {
-      const { container } = render(
-        <AppShell>
-          <p>page</p>
-        </AppShell>
-      );
-      // Only the <main> remains inside the body row.
-      expect(container.querySelectorAll('aside')).toHaveLength(0);
-    });
-  });
-
-  describe('mobile drawer', () => {
-    it('renders the mobile aside with aria-hidden=true by default', () => {
-      const { container } = render(
-        <AppShell nav={<div>N</div>}>
-          <p>page</p>
-        </AppShell>
-      );
-      const mobile = container.querySelectorAll('aside')[1];
-      expect(mobile.getAttribute('aria-hidden')).toBe('true');
-    });
-
-    it('exposes the mobile aside (aria-hidden=false) when navOpen', () => {
-      const { container } = render(
-        <AppShell nav={<div>N</div>} navOpen onNavOpenChange={vi.fn()}>
-          <p>page</p>
-        </AppShell>
-      );
-      const mobile = container.querySelectorAll('aside')[1];
-      expect(mobile.getAttribute('aria-hidden')).toBe('false');
-    });
-
-    it('fires onNavOpenChange(false) when the backdrop is clicked', () => {
-      const cb = vi.fn();
-      render(
-        <AppShell nav={<div>N</div>} navOpen onNavOpenChange={cb}>
-          <p>page</p>
-        </AppShell>
-      );
-      fireEvent.click(screen.getByTestId('appshell-backdrop'));
-      expect(cb).toHaveBeenCalledWith(false);
-    });
-
-    it('fires onNavOpenChange(false) when Escape is pressed', () => {
-      const cb = vi.fn();
-      render(
-        <AppShell nav={<div>N</div>} navOpen onNavOpenChange={cb}>
-          <p>page</p>
-        </AppShell>
-      );
-      fireEvent.keyDown(document, { key: 'Escape' });
-      expect(cb).toHaveBeenCalledWith(false);
-    });
-
-    it('does NOT fire Escape callback when drawer is closed', () => {
-      const cb = vi.fn();
-      render(
-        <AppShell nav={<div>N</div>} onNavOpenChange={cb}>
-          <p>page</p>
-        </AppShell>
-      );
-      fireEvent.keyDown(document, { key: 'Escape' });
-      expect(cb).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('body scroll lock', () => {
-    it('locks body overflow while navOpen is true', () => {
-      const { rerender, unmount } = render(
-        <AppShell nav={<div>N</div>} navOpen>
-          <p>page</p>
-        </AppShell>
-      );
-      expect(document.body.style.overflow).toBe('hidden');
-      rerender(
-        <AppShell nav={<div>N</div>}>
-          <p>page</p>
-        </AppShell>
-      );
-      expect(document.body.style.overflow).not.toBe('hidden');
-      unmount();
-    });
-
-    it('restores body overflow on unmount even if still open', () => {
-      const { unmount } = render(
-        <AppShell nav={<div>N</div>} navOpen>
-          <p>page</p>
-        </AppShell>
-      );
-      expect(document.body.style.overflow).toBe('hidden');
-      unmount();
-      expect(document.body.style.overflow).not.toBe('hidden');
-    });
-  });
-});
-
-describe('<AppShell> performance', () => {
-  it('mounts under 30ms with all slots filled', () => {
-    const t0 = performance.now();
-    render(
-      <AppShell
-        header={<div>H</div>}
-        nav={<div>N</div>}
-        footer={<div>F</div>}
-      >
-        <p>page</p>
-      </AppShell>
-    );
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(30);
-  });
-
-  it('renders at most 2 times on mount', () => {
-    let count = 0;
-    const Counted = (p: React.ComponentProps<typeof AppShell>) => {
-      count++;
-      return <AppShell {...p} />;
-    };
-    render(
-      <Counted nav={<div>N</div>}>
-        <p>page</p>
-      </Counted>
-    );
-    expect(count).toBeLessThanOrEqual(2);
-  });
-
-  it('toggling navOpen costs ≤ 1 extra render on the wrapper', () => {
-    let count = 0;
-    const Counted = (p: React.ComponentProps<typeof AppShell>) => {
-      count++;
-      return <AppShell {...p} />;
-    };
-    const { rerender } = render(
-      <Counted nav={<div>N</div>} navOpen={false}>
-        <p>page</p>
-      </Counted>
-    );
-    const baseline = count;
-    rerender(
-      <Counted nav={<div>N</div>} navOpen={true}>
-        <p>page</p>
-      </Counted>
-    );
-    expect(count - baseline).toBeLessThanOrEqual(2);
-  });
-
-  it('does NOT re-render an unrelated sibling on navOpen toggle', () => {
-    const sibCount = { count: 0 };
-    const Sibling = () => {
-      sibCount.count++;
-      return null;
-    };
-    const Tree = ({ open }: { open: boolean }) => (
-      <div>
-        <AppShell nav={<div>N</div>} navOpen={open}>
-          <p>page</p>
-        </AppShell>
-        <Sibling />
-      </div>
-    );
-    const { rerender } = render(<Tree open={false} />);
-    const before = sibCount.count;
-    rerender(<Tree open={true} />);
-    rerender(<Tree open={false} />);
-    // Each parent re-render triggers the sibling once. 2 parent
-    // rerenders ⇒ ≤ 2 extra sibling renders (tolerance +1).
-    expect(sibCount.count - before).toBeLessThanOrEqual(3);
-  });
-});

package/src/components/AppShell/AppShell.tsx

@@ -1,239 +0,0 @@
-import { useEffect, useRef } from 'react';
-import { cn } from '../../utils/cn.js';
-import { appShellVariants } from './appShell.variants.js';
-import type { AppShellProps } from './appShell.types.js';
-
-/**
- * Query selector for natively-focusable elements + anything with an
- * explicit positive (or implicit `0`) tabindex. Used by the focus
- * trap to enumerate the drawer's interactive content.
- *
- * Notes:
- *  - Excludes `[tabindex="-1"]` (intentionally non-tabbable).
- *  - Excludes `:disabled` — the browser already skips them in tab
- *    order; including them here would route focus to dead elements.
- *  - `details > summary` is the standard way to get a focusable
- *    `<details>` toggle.
- *
- * @internal
- */
-const FOCUSABLE_SELECTOR = [
-  'a[href]',
-  'button:not(:disabled)',
-  'input:not(:disabled):not([type="hidden"])',
-  'select:not(:disabled)',
-  'textarea:not(:disabled)',
-  '[tabindex]:not([tabindex="-1"]):not(:disabled)',
-  'details > summary:first-of-type',
-].join(',');
-
-/**
- * Dashforge TW AppShell — top-level layout orchestrator.
- *
- *   ┌──────────────────────────────────────────┐
- *   │              header                      │  ← `header` slot
- *   ├────────┬─────────────────────────────────┤
- *   │        │                                 │
- *   │  nav   │           main                  │  ← `nav` + `children`
- *   │        │                                 │
- *   ├────────┴─────────────────────────────────┤
- *   │              footer                      │  ← `footer` slot
- *   └──────────────────────────────────────────┘
- *
- * **Responsive**:
- *   - `≥ md`: nav stays in the inline slot at the left.
- *   - `< md`: nav becomes a slide-in drawer toggled by `navOpen`.
- *     A backdrop closes the drawer on click (mirrors `<Dialog>` UX).
- *
- * **Body scroll lock**: when the mobile drawer is open we add
- * `overflow-hidden` to `<body>` to prevent dual-scroll wobble. The
- * effect cleans up on close + on unmount.
- *
- * **A11y**:
- *   - `<main>` landmark wraps the content area.
- *   - `<header>` / `<footer>` come for free from their HTML tags.
- *   - The mobile drawer + backdrop participate in the standard
- *     "click outside to close" pattern — `Escape` closes the drawer
- *     too (added via global keydown).
- *   - **Focus trap** (WCAG 2.4.3) — when the mobile drawer opens:
- *       1. The previously-focused element is captured.
- *       2. Focus moves to the first focusable element inside the drawer.
- *       3. Tab / Shift+Tab wrap inside the drawer (cycle from
- *          last → first and first → last) — Tab can never escape
- *          to the page underneath while the drawer is open.
- *       4. On close, focus returns to the captured element (typically
- *          the hamburger toggle the user pressed to open the drawer).
- *     This pattern matches WAI-ARIA APG's modal dialog guidance even
- *     though the drawer isn't strictly a dialog — same focus
- *     management makes keyboard users' experience predictable.
- *   - **`role="dialog"` + `aria-modal="true"`** are applied to the
- *     drawer when open so screen readers announce it as a modal
- *     overlay rather than just an aside.
- */
-export function AppShell(props: AppShellProps) {
-  const {
-    header,
-    nav,
-    footer,
-    children,
-    navOpen = false,
-    onNavOpenChange,
-    sx,
-    slotProps,
-  } = props;
-
-  const v = appShellVariants({ navOpen });
-
-  // Lock body scroll while the mobile drawer is open.
-  useEffect(() => {
-    if (!navOpen) return;
-    const prev = document.body.style.overflow;
-    document.body.style.overflow = 'hidden';
-    return () => {
-      document.body.style.overflow = prev;
-    };
-  }, [navOpen]);
-
-  // Esc closes the drawer.
-  useEffect(() => {
-    if (!navOpen || !onNavOpenChange) return;
-    const handler = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') onNavOpenChange(false);
-    };
-    document.addEventListener('keydown', handler);
-    return () => document.removeEventListener('keydown', handler);
-  }, [navOpen, onNavOpenChange]);
-
-  /*
-   * Focus trap for the mobile drawer.
-   *
-   * Implementation:
-   *  - On open: capture the currently-focused element (`document.activeElement`)
-   *    so we can restore it on close. Then move focus to the first
-   *    focusable element inside the drawer.
-   *  - While open: a Tab/Shift+Tab keydown listener wraps focus inside
-   *    the drawer subtree (last → first on Tab from end, first → last
-   *    on Shift+Tab from start).
-   *  - On close: restore focus to the captured element.
-   *
-   * Hand-rolled (no `focus-trap-react` dep) — the logic is ~20 LOC and
-   * scoped to a single drawer; adding a runtime dep felt like overkill.
-   * If we ever need more sophisticated trap semantics (nested traps,
-   * sentinel nodes, etc.) the dep is the right call.
-   */
-  const drawerRef = useRef<HTMLDivElement | null>(null);
-  const restoreFocusRef = useRef<HTMLElement | null>(null);
-
-  useEffect(() => {
-    if (!navOpen) return;
-    // 1) Capture the element that had focus before the drawer opened.
-    restoreFocusRef.current = document.activeElement as HTMLElement | null;
-
-    // 2) Move focus to the first focusable element inside the drawer.
-    //    Defer via rAF so the drawer DOM (slide-in animation start) has
-    //    settled and the elements are actually visible/focusable.
-    const raf = requestAnimationFrame(() => {
-      const drawer = drawerRef.current;
-      if (!drawer) return;
-      const first = drawer.querySelector<HTMLElement>(FOCUSABLE_SELECTOR);
-      first?.focus();
-    });
-
-    // 3) Trap Tab / Shift+Tab inside the drawer.
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key !== 'Tab') return;
-      const drawer = drawerRef.current;
-      if (!drawer) return;
-      const focusables = Array.from(
-        drawer.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)
-      );
-      if (focusables.length === 0) {
-        event.preventDefault();
-        return;
-      }
-      const first = focusables[0];
-      const last = focusables[focusables.length - 1];
-      const active = document.activeElement as HTMLElement | null;
-      if (event.shiftKey) {
-        // Shift+Tab on first → wrap to last.
-        if (active === first || !drawer.contains(active)) {
-          event.preventDefault();
-          last.focus();
-        }
-      } else {
-        // Tab on last → wrap to first.
-        if (active === last || !drawer.contains(active)) {
-          event.preventDefault();
-          first.focus();
-        }
-      }
-    };
-    document.addEventListener('keydown', onKeyDown);
-
-    return () => {
-      cancelAnimationFrame(raf);
-      document.removeEventListener('keydown', onKeyDown);
-      // 4) Restore focus to the previously-focused element on close.
-      //    Guard against the element being removed from the DOM (rare
-      //    but possible if the consumer re-renders the page while the
-      //    drawer is open).
-      const restore = restoreFocusRef.current;
-      if (restore && document.body.contains(restore)) {
-        restore.focus();
-      }
-    };
-  }, [navOpen]);
-
-  return (
-    <div className={cn(v.root(), sx, slotProps?.root?.className)}>
-      {header && (
-        <div className={cn(v.header(), slotProps?.header?.className)}>
-          {header}
-        </div>
-      )}
-
-      <div className={v.body()}>
-        {nav && (
-          <>
-            <aside className={cn(v.nav(), slotProps?.nav?.className)}>
-              {nav}
-            </aside>
-            <aside
-              ref={drawerRef}
-              className={cn(v.navMobile(), slotProps?.navMobile?.className)}
-              aria-hidden={!navOpen}
-              // When open, the drawer is a modal overlay — `dialog` +
-              // `aria-modal="true"` so screen readers announce it as
-              // such. When closed, drop both attributes (the aria-
-              // hidden=true above already removes it from the AT tree).
-              role={navOpen ? 'dialog' : undefined}
-              aria-modal={navOpen ? true : undefined}
-              // The drawer is the SAME nav content rendered twice — once
-              // inline (desktop) and once as a slide-in (mobile). We
-              // mark the inactive copy hidden from AT to avoid double
-              // announcements.
-            >
-              {nav}
-            </aside>
-            <div
-              className={cn(v.backdrop(), slotProps?.backdrop?.className)}
-              role="presentation"
-              onClick={() => onNavOpenChange?.(false)}
-              data-testid="appshell-backdrop"
-            />
-          </>
-        )}
-
-        <main className={cn(v.main(), slotProps?.main?.className)}>
-          {children}
-        </main>
-      </div>
-
-      {footer && (
-        <div className={cn(v.footer(), slotProps?.footer?.className)}>
-          {footer}
-        </div>
-      )}
-    </div>
-  );
-}