@dashforge/tw 0.1.0-beta

package/src/components/AppShell/AppShell.tsx

@@ -0,0 +1,114 @@
+import { useEffect } from 'react';
+import { cn } from '../../utils/cn.js';
+import { appShellVariants } from './appShell.variants.js';
+import type { AppShellProps } from './appShell.types.js';
+
+/**
+ * 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).
+ */
+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]);
+
+  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
+              className={cn(v.navMobile(), slotProps?.navMobile?.className)}
+              aria-hidden={!navOpen}
+              // 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>
+  );
+}

package/src/components/AppShell/appShell.types.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import type { AppShellVariants } from './appShell.variants.js';
+
+export interface AppShellSlotProps {
+  root?: { className?: string };
+  header?: { className?: string };
+  nav?: { className?: string };
+  navMobile?: { className?: string };
+  main?: { className?: string };
+  footer?: { className?: string };
+  backdrop?: { className?: string };
+}
+
+/**
+ * Props for `<AppShell>`.
+ *
+ * Top-level layout orchestrator with 4 named slots:
+ *
+ *   - `header` (top, sticky)
+ *   - `nav`    (left side, fixed-width on desktop, drawer on mobile)
+ *   - `footer` (bottom, non-sticky)
+ *   - `children` (main content, scrolls independently)
+ *
+ * Responsive behavior:
+ *   - **≥ md (768px)**: nav is rendered inline at the left.
+ *   - **< md**:        nav slides in as an overlay drawer when
+ *                      `navOpen={true}` (controlled).
+ *
+ * The shell is router-agnostic — pass any nav/header content. Typical
+ * pairing is `<LeftNav>` + `<TopBar>` (with a hamburger button in
+ * `TopBar.start` that flips `navOpen`).
+ */
+export interface AppShellProps extends AppShellVariants {
+  header?: ReactNode;
+  nav?: ReactNode;
+  footer?: ReactNode;
+  children?: ReactNode;
+  /**
+   * Mobile drawer open state. Controlled — provide
+   * `onNavOpenChange` to update. When `undefined`, the mobile drawer
+   * is always closed (consumer hasn't wired up the toggle yet).
+   */
+  navOpen?: boolean;
+  onNavOpenChange?: (open: boolean) => void;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot className overrides. */
+  slotProps?: AppShellSlotProps;
+}

package/src/components/AppShell/appShell.variants.ts

@@ -0,0 +1,48 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * Tailwind-variants recipe for `<AppShell>`.
+ *
+ * Slots:
+ *   - `root`      — outer flex column (full viewport)
+ *   - `header`    — top region
+ *   - `body`      — flex row holding nav + main
+ *   - `nav`       — desktop nav rail (md+)
+ *   - `navMobile` — mobile drawer (slide-in)
+ *   - `main`      — scrollable content area
+ *   - `footer`    — bottom region
+ *   - `backdrop`  — semi-opaque overlay behind the mobile drawer
+ */
+export const appShellVariants = tv({
+  slots: {
+    root: 'flex flex-col min-h-screen bg-neutral-100',
+    header: 'shrink-0',
+    body: 'flex flex-1 min-h-0',
+    nav: 'hidden md:flex shrink-0',
+    navMobile: [
+      'flex md:hidden fixed inset-y-0 left-0 z-40',
+      'transition-transform duration-200 ease-out',
+      '-translate-x-full',
+    ],
+    main: 'flex-1 min-w-0 overflow-y-auto',
+    footer: 'shrink-0',
+    backdrop: [
+      'md:hidden fixed inset-0 z-30 bg-black/40',
+      'transition-opacity duration-200',
+      'opacity-0 pointer-events-none',
+    ],
+  },
+  variants: {
+    navOpen: {
+      true: {
+        navMobile: 'translate-x-0',
+        backdrop: 'opacity-100 pointer-events-auto',
+      },
+    },
+  },
+  defaultVariants: {
+    navOpen: false,
+  },
+});
+
+export type AppShellVariants = VariantProps<typeof appShellVariants>;

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

@@ -0,0 +1,225 @@
+// @vitest-environment jsdom
+/**
+ * Performance + re-render budget tests for `<Autocomplete>`.
+ *
+ * These are NOT "is X fast" benchmarks — they're guardrails against
+ * regressions in the things that matter for a 1000+ option combobox:
+ *
+ *  1. **Filter memoization**: `filteredOptions` must be reference-stable
+ *     when its inputs (options + filter text + selection state) don't
+ *     change. A stable reference means downstream lists don't re-mount.
+ *
+ *  2. **Render budget**: typing N characters must cause O(N) renders
+ *     of the component, not O(N²) or worse. With our internals there
+ *     are 2 renders per keystroke (one for `inputValue`, one for the
+ *     popover opening on first keystroke), so the budget is `2N + k`
+ *     for a small constant `k`.
+ *
+ *  3. **Initial render time** with a large option list must finish
+ *     within a generous wall-clock budget. This catches a future
+ *     refactor that, say, accidentally calls `getOptionLabel` 1000²
+ *     times during mount.
+ */
+import { describe, it, expect } from 'vitest';
+import { useEffect, useRef } from 'react';
+import { render, fireEvent, screen } from '@testing-library/react';
+import { Autocomplete } from './Autocomplete.js';
+import type { AutocompleteOption } from './autocomplete.types.js';
+
+// Generate `n` deterministic options.
+function makeOptions(n: number): AutocompleteOption[] {
+  return Array.from({ length: n }, (_, i) => ({
+    value: `o-${i}`,
+    label: `Option ${i}`,
+  }));
+}
+
+/**
+ * Wrap a component and expose a render-counter ref so tests can assert
+ * how many times React re-rendered the wrapped subtree.
+ */
+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('<Autocomplete> performance', () => {
+  it('mounts a 1000-option list well under 500ms', () => {
+    const options = makeOptions(1000);
+    const t0 = performance.now();
+    render(<Autocomplete name="x" options={options} label="X" />);
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(500);
+  });
+
+  it('filters a 1000-option list well under 100ms per keystroke', () => {
+    const options = makeOptions(1000);
+    render(<Autocomplete name="x" options={options} label="X" />);
+    const input = screen.getByRole('combobox') as HTMLInputElement;
+    const t0 = performance.now();
+    fireEvent.change(input, { target: { value: '9' } });
+    const t1 = performance.now();
+    expect(t1 - t0).toBeLessThan(100);
+  });
+});
+
+describe('<Autocomplete> re-render budget', () => {
+  it('renders at most 2 times on mount (StrictMode-free path)', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(Autocomplete, counter);
+    render(<Counted name="x" options={makeOptions(20)} label="X" />);
+    // 1 initial render — and we tolerate up to 2 to account for the
+    // synchronous useState callbacks that schedule a follow-up commit.
+    expect(counter.count).toBeLessThanOrEqual(2);
+  });
+
+  it('keeps renders linear in keystrokes (≤ 3 renders per char)', () => {
+    const counter = { count: 0 };
+    const Counted = withRenderCounter(Autocomplete, counter);
+    const { container } = render(
+      <Counted name="x" options={makeOptions(50)} label="X" />
+    );
+    const baseline = counter.count;
+    const input = container.querySelector(
+      'input[role="combobox"]'
+    ) as HTMLInputElement;
+    const N = 10;
+    for (let i = 0; i < N; i++) {
+      fireEvent.change(input, { target: { value: 'a'.repeat(i + 1) } });
+    }
+    const perChar = (counter.count - baseline) / N;
+    // 1-2 renders per keystroke is the design budget; allow some slack
+    // for popover-open transitions on the first keystroke and the
+    // highlight reset useState call.
+    expect(perChar).toBeLessThanOrEqual(3);
+  });
+
+  it('does NOT re-render an unrelated sibling on each keystroke', () => {
+    // Critical perf property: typing into one Autocomplete must not
+    // cause sibling components in the same tree to re-render. We check
+    // this by mounting a sibling whose render count we count directly.
+    const sibCount = { count: 0 };
+    const Sibling = () => {
+      sibCount.count++;
+      return <div data-testid="sib" />;
+    };
+    render(
+      <div>
+        <Autocomplete name="x" options={makeOptions(50)} label="X" />
+        <Sibling />
+      </div>
+    );
+    const before = sibCount.count;
+    const input = screen.getByRole('combobox') as HTMLInputElement;
+    for (let i = 0; i < 5; i++) {
+      fireEvent.change(input, { target: { value: 'a'.repeat(i + 1) } });
+    }
+    // No state in the parent changes ⇒ sibling never re-renders.
+    expect(sibCount.count).toBe(before);
+  });
+
+  it('filteredOptions reference is stable across unrelated re-renders', () => {
+    // Functional contract: if the deps (options, filter text, selection)
+    // don't change, `useMemo` should return the same array reference.
+    // We verify by triggering a parent re-render with no relevant input
+    // change and asserting the `<li>` DOM elements are reused (same id
+    // identities ⇒ React reused the keys).
+    const options = makeOptions(20);
+    const seenIds = new Set<string>();
+    const { rerender } = render(
+      <Autocomplete name="x" options={options} label="X" />
+    );
+    const input = screen.getByRole('combobox') as HTMLInputElement;
+    fireEvent.focus(input); // open popover so the list renders
+    const lis1 = Array.from(
+      document.querySelectorAll('[role="option"]')
+    ).map((el) => el.id);
+    lis1.forEach((id) => seenIds.add(id));
+
+    // Trigger an unrelated re-render: same options ref, same input
+    // value, same selection.
+    rerender(<Autocomplete name="x" options={options} label="X" />);
+    const lis2 = Array.from(
+      document.querySelectorAll('[role="option"]')
+    ).map((el) => el.id);
+
+    // Same ids ⇒ React keyed reuse held; list DOM was not torn down.
+    expect(lis2).toEqual(lis1);
+  });
+
+  it('captures number of options accessor calls during one filter cycle', () => {
+    // Implementation detail with strong perf relevance: filtering 1000
+    // options must call `getOptionLabel` at most O(N) times per filter
+    // (NOT O(N²) or anything weirdly memoized that re-computes per
+    // child).
+    let labelCalls = 0;
+    let valueCalls = 0;
+    const N = 200;
+    const options: AutocompleteOption[] = makeOptions(N);
+    render(
+      <Autocomplete
+        name="x"
+        options={options}
+        label="X"
+        getOptionLabel={(o) => {
+          labelCalls++;
+          return o.label;
+        }}
+        getOptionValue={(o) => {
+          valueCalls++;
+          return o.value;
+        }}
+      />
+    );
+    const input = screen.getByRole('combobox') as HTMLInputElement;
+    labelCalls = 0;
+    valueCalls = 0;
+    fireEvent.change(input, { target: { value: '5' } });
+    // Budget: O(N) on both. Allow 4x N to cover the filter pass plus
+    // the popover-open render's per-option `getOptionValue` for ids
+    // and `getOptionLabel` for the rendered <li> body.
+    expect(labelCalls).toBeLessThanOrEqual(4 * N);
+    expect(valueCalls).toBeLessThanOrEqual(4 * N);
+  });
+});
+
+describe('<Autocomplete> async + perf interaction', () => {
+  it('debounces loadOptions so 5 rapid keystrokes ⇒ 1 fetch', async () => {
+    const calls: string[] = [];
+    const load = (q: string) => {
+      calls.push(q);
+      return Promise.resolve<AutocompleteOption[]>([]);
+    };
+    render(
+      <Autocomplete
+        name="x"
+        options={[]}
+        loadOptions={load}
+        loadDebounceMs={50}
+      />
+    );
+    const input = screen.getByRole('combobox') as HTMLInputElement;
+    // Type 5 chars in quick succession (synchronous).
+    for (let i = 0; i < 5; i++) {
+      fireEvent.change(input, { target: { value: 'abcde'.slice(0, i + 1) } });
+    }
+    // Before debounce expires, no call yet.
+    expect(calls.length).toBe(0);
+    // Wait past debounce window.
+    await new Promise((r) => setTimeout(r, 80));
+    // Exactly ONE call lands, with the LAST typed value.
+    expect(calls).toEqual(['abcde']);
+  });
+});
+
+/**
+ * Module-level useEffect import sanity (suppresses "useRef declared but
+ * not used" if a test runner tree-shake removes some perf tests in CI).
+ */
+void useRef;
+void useEffect;