@dashforge/tw 0.2.1-beta → 0.4.0-beta

package/src/components/Accordion/accordion.variants.ts

@@ -0,0 +1,30 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+export const accordionVariants = tv({
+  slots: {
+    root: 'w-full',
+    item: 'border-b border-neutral-200 dark:border-neutral-800',
+    header: 'flex',
+    trigger: [
+      'flex flex-1 items-center justify-between py-3 text-left',
+      'text-sm font-medium text-neutral-900 dark:text-neutral-50',
+      'transition-all hover:underline',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:rounded',
+      '[&[data-state=open]>svg]:rotate-180',
+      'disabled:opacity-50 disabled:pointer-events-none',
+      'motion-reduce:transition-none',
+    ],
+    content: [
+      'overflow-hidden text-sm text-neutral-700 dark:text-neutral-300',
+      'data-[state=open]:animate-accordion-down',
+      'data-[state=closed]:animate-accordion-up',
+      'motion-reduce:animate-none',
+    ],
+    chevron: [
+      'h-4 w-4 shrink-0 text-neutral-500 transition-transform duration-200',
+      'motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+  },
+});
+
+export type AccordionVariants = VariantProps<typeof accordionVariants>;

package/src/components/AppShell/AppShell.tsx

@@ -1,8 +1,32 @@
-import { useEffect } from 'react';
+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.
  *
@@ -31,6 +55,20 @@ import type { AppShellProps } from './appShell.types.js';
  *   - 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 {
@@ -66,6 +104,86 @@ export function AppShell(props: AppShellProps) {
     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 && (
@@ -81,8 +199,15 @@ export function AppShell(props: AppShellProps) {
               {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

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

@@ -21,14 +21,20 @@ export const appShellVariants = tv({
     nav: 'hidden md:flex shrink-0',
     navMobile: [
       'flex md:hidden fixed inset-y-0 left-0 z-40',
-      'transition-transform duration-200 ease-out',
+      // Drawer slide-in is the most prominent motion in AppShell and
+      // a clear WCAG 2.3.3 candidate. Gate the transition on
+      // `prefers-reduced-motion: no-preference`; the data-driven
+      // `-translate-x-full` / `translate-x-0` still applies, just
+      // without the smooth slide.
+      'transition-transform duration-200 ease-out motion-reduce:transition-none motion-reduce:duration-0',
       '-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',
+      // Backdrop opacity fade — micro motion, gated for consistency.
+      'transition-opacity duration-200 motion-reduce:transition-none motion-reduce:duration-0',
       'opacity-0 pointer-events-none',
     ],
   },

package/src/components/Autocomplete/Autocomplete.tsx

@@ -23,6 +23,61 @@ import type {
   AutocompleteValue,
 } from './autocomplete.types.js';
 
+/**
+ * Inline SVG icons used by the Autocomplete chrome (chip remove, clear,
+ * dropdown caret). Stroke uses `currentColor` so the parent's `text-*`
+ * propagates — same pattern as Checkbox's CheckIcon.
+ *
+ * Why inline SVG (not lucide / heroicons / unicode glyphs):
+ *  - Zero icon-library dependency: keeps `@dashforge/tw` self-contained.
+ *  - Crisp at every size (the unicode `×` / `▾` glyphs we shipped pre-
+ *    0.2.2 rendered as chunky font characters that looked unpolished
+ *    next to the rest of the design system).
+ *  - SVG scales with parent font-size cleanly via `width="1em" height="1em"`.
+ *
+ * @internal
+ */
+function CloseIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 16 16"
+      width="1em"
+      height="1em"
+      fill="none"
+      className={className}
+    >
+      <path
+        d="M4 4l8 8M12 4l-8 8"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+function ChevronDownIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 16 16"
+      width="1em"
+      height="1em"
+      fill="none"
+      className={className}
+    >
+      <path
+        d="M4 6l4 4 4-4"
+        stroke="currentColor"
+        strokeWidth="1.75"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
 /**
  * Coerce a raw value (from bridge / props) into a canonical shape:
  *
@@ -402,7 +457,17 @@ export function Autocomplete<TOption = AutocompleteOption>(
         if (next == null) {
           setInputValue('');
         } else {
-          const found = options.find((opt) => getOptionValue(opt) === next);
+          // Look up the label in the EFFECTIVE option pool (static
+          // `options` + async `asyncOptions` when `loadOptions` is
+          // configured). Looking only at the static `options` here
+          // means async-loaded picks never update the input — the
+          // user sees their search query stick instead of the
+          // selected label after click. Same lookup logic mirrored in
+          // `displayInputValue` so the two paths can't drift.
+          const pool = loadOptions && asyncOptions !== null
+            ? asyncOptions
+            : options;
+          const found = pool.find((opt) => getOptionValue(opt) === next);
           const found_label = found ? labelAsString(found) : undefined;
           if (found_label !== undefined) {
             setInputValue(found_label);
@@ -434,6 +499,8 @@ export function Autocomplete<TOption = AutocompleteOption>(
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
       options,
+      asyncOptions,
+      loadOptions,
       isFormMode,
       bridge,
       name,
@@ -837,7 +904,7 @@ export function Autocomplete<TOption = AutocompleteOption>(
                         slotProps?.chipRemove?.className
                       )}
                     >
-                      ×
+                      <CloseIcon />
                     </button>
                   )}
                 </span>
@@ -893,7 +960,7 @@ export function Autocomplete<TOption = AutocompleteOption>(
             tabIndex={-1}
             className={cn(v.clearButton(), slotProps?.clearButton?.className)}
           >
-            ×
+            <CloseIcon />
           </button>
         )}
 
@@ -908,7 +975,13 @@ export function Autocomplete<TOption = AutocompleteOption>(
           disabled={effectiveDisabled}
           className={cn(v.trigger(), slotProps?.trigger?.className)}
         >
-          ▾
+          {/*
+           * Chevron flips up when popover is open (CSS-only, driven by
+           * the `aria-expanded` attribute selector on the parent
+           * `<button>`). See autocomplete.variants.ts → `trigger` slot
+           * for the `aria-expanded:rotate-180` rule.
+           */}
+          <ChevronDownIcon />
         </button>
 
         {isOpen && (

package/src/components/Autocomplete/autocomplete.variants.ts

@@ -44,6 +44,12 @@ export const autocompleteVariants = tv({
       'text-neutral-600 hover:text-neutral-900',
       'disabled:cursor-not-allowed disabled:opacity-40',
       'transition-colors',
+      // Chevron flip on open — targets the SVG child via the aria-
+      // expanded state on the button itself (set by React). Smooth
+      // rotate gated on prefers-reduced-motion (WCAG 2.3.3); the
+      // 180° state still applies, just without the animated tween.
+      '[&[aria-expanded=true]>svg]:rotate-180',
+      '[&>svg]:transition-transform [&>svg]:duration-150 motion-reduce:[&>svg]:transition-none',
     ],
     clearButton: [
       'flex items-center justify-center shrink-0 px-2',

package/src/components/Breadcrumbs/breadcrumbs.variants.ts

@@ -23,6 +23,11 @@ export const breadcrumbsVariants = tv({
       'rounded-sm outline-none',
       'focus-visible:ring-2 focus-visible:ring-primary-500/50',
       'transition-colors',
+      // Defensive `no-underline` — see the matching comment in
+      // LeftNav itemLink slot. The Breadcrumbs root cause covers
+      // TopBar too because Breadcrumbs is typically rendered in
+      // TopBar's center slot.
+      'no-underline hover:no-underline',
     ],
     current: [
       'inline-flex items-center gap-1 truncate',

package/src/components/Checkbox/Checkbox.tsx

@@ -10,8 +10,8 @@ import { checkboxVariants } from './checkbox.variants.js';
 import type { CheckboxProps } from './checkbox.types.js';
 
 /**
- * Inline checkmark SVG used by `Radix.Indicator`. Stroke uses
- * `currentColor` so the parent's `text-white` propagates correctly.
+ * Inline checkmark SVG used by `Radix.Indicator` when fully checked.
+ * Stroke uses `currentColor` so the parent's `text-white` propagates.
  *
  * @internal
  */
@@ -34,6 +34,37 @@ function CheckIcon({ className }: { className?: string }) {
   );
 }
 
+/**
+ * Inline dash SVG used by `Radix.Indicator` when the checkbox is in
+ * the `indeterminate` tri-state ("some, but not all, children
+ * selected" — the canonical "select all" partial state).
+ *
+ * Pre-0.2.2-beta the indicator rendered the CheckIcon for BOTH
+ * checked and indeterminate (Radix mounts the Indicator for either
+ * state). We now discriminate via the `data-state` attribute Radix
+ * sets on the Indicator element itself — see the parent `Indicator`
+ * rendering below for the CSS toggle.
+ *
+ * @internal
+ */
+function DashIcon({ className }: { className?: string }) {
+  return (
+    <svg
+      aria-hidden="true"
+      viewBox="0 0 16 16"
+      fill="none"
+      className={className}
+    >
+      <path
+        d="M3 8h10"
+        stroke="currentColor"
+        strokeWidth="2.5"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
 /**
  * Dashforge TW Checkbox — bridge-integrated form control.
  *
@@ -212,16 +243,19 @@ export function Checkbox(props: CheckboxProps) {
          * modes — controlled, uncontrolled, bridge). Indicator mounts
          * exactly when the checkbox is checked OR indeterminate.
          *
-         * Indeterminate caveat: this renders the check glyph for
-         * BOTH checked AND indeterminate states. Previously
-         * indeterminate rendered nothing inside the blue square
-         * (same level of broken). A future improvement would render
-         * a dash for indeterminate — out of scope here.
+         * Per-state glyph (Sprint 2 P4): when Indicator is mounted we
+         * render BOTH glyphs and toggle visibility via the Indicator's
+         * own `data-state` attribute. The `group` class on Indicator
+         * lets the SVG children target the parent's state with
+         * `group-data-[state=checked]:hidden` / `…:indeterminate:hidden`.
+         * No React state required — Radix's data-state attribute is
+         * the single source of truth.
          */}
         <RadixCheckbox.Indicator
-          className={cn(v.indicator(), slotProps?.indicator?.className)}
+          className={cn(v.indicator(), 'group', slotProps?.indicator?.className)}
         >
-          <CheckIcon className="h-full w-full" />
+          <CheckIcon className="h-full w-full group-data-[state=indeterminate]:hidden" />
+          <DashIcon className="h-full w-full group-data-[state=checked]:hidden" />
         </RadixCheckbox.Indicator>
       </RadixCheckbox.Root>
 

package/src/components/Dialog/Dialog.test.tsx

@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { Dialog } from './Dialog.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('Dialog — rendering', () => {
+  it('renders nothing when open=false', () => {
+    render(
+      <Dialog open={false} onOpenChange={() => {}}>
+        <p>body</p>
+      </Dialog>
+    );
+    expect(screen.queryByText('body')).toBeNull();
+  });
+
+  it('renders title + body + close button when open', () => {
+    render(
+      <Dialog open onOpenChange={() => {}} title="Confirm action">
+        <p>body content</p>
+      </Dialog>
+    );
+    expect(screen.queryByText('Confirm action')).not.toBeNull();
+    expect(screen.queryByText('body content')).not.toBeNull();
+    expect(screen.queryByLabelText('Close')).not.toBeNull();
+  });
+
+  it('honors showCloseButton={false}', () => {
+    render(
+      <Dialog open onOpenChange={() => {}} showCloseButton={false}>
+        <p>body</p>
+      </Dialog>
+    );
+    expect(screen.queryByLabelText('Close')).toBeNull();
+  });
+
+  it('emits onOpenChange(false) when close button is clicked', () => {
+    let lastOpen: boolean | null = null;
+    render(
+      <Dialog open onOpenChange={(o) => (lastOpen = o)}>
+        <p>body</p>
+      </Dialog>
+    );
+    fireEvent.click(screen.getByLabelText('Close'));
+    expect(lastOpen).toBe(false);
+  });
+
+  it('renders description when provided', () => {
+    render(
+      <Dialog open onOpenChange={() => {}} title="Title" description="Hint text">
+        <p>body</p>
+      </Dialog>
+    );
+    expect(screen.queryByText('Hint text')).not.toBeNull();
+  });
+});
+
+describe('Dialog — size variants', () => {
+  it.each(['sm', 'md', 'lg'] as const)('renders size=%s without crashing', (size) => {
+    render(
+      <Dialog open onOpenChange={() => {}} size={size}>
+        <p>body</p>
+      </Dialog>
+    );
+    expect(screen.queryByText('body')).not.toBeNull();
+  });
+});
+
+describe('Dialog — sx + slotProps', () => {
+  it('appends sx to the content element', () => {
+    render(
+      <Dialog open onOpenChange={() => {}} sx="custom-sx-class">
+        <p>body</p>
+      </Dialog>
+    );
+    const content = screen.getByText('body').closest('[role="dialog"]');
+    expect(content?.className).toContain('custom-sx-class');
+  });
+
+  it('applies slotProps.title.className', () => {
+    render(
+      <Dialog
+        open
+        onOpenChange={() => {}}
+        title="T"
+        slotProps={{ title: { className: 'tw-title-override' } }}
+      >
+        <p>body</p>
+      </Dialog>
+    );
+    expect(screen.getByText('T').className).toContain('tw-title-override');
+  });
+});

package/src/components/Dialog/Dialog.tsx

@@ -0,0 +1,93 @@
+import * as RadixDialog from '@radix-ui/react-dialog';
+import { cn } from '../../utils/cn.js';
+import { dialogVariants } from './dialog.variants.js';
+import type { DialogProps } from './dialog.types.js';
+
+/**
+ * Dashforge TW `<Dialog>` — declarative modal dialog.
+ *
+ * Built on `@radix-ui/react-dialog`:
+ *  - APG dialog pattern out of the box (focus trap, restore focus on
+ *    close, Esc-to-close, `aria-modal`, `aria-labelledby`).
+ *  - Renders into a portal (no z-index hell).
+ *  - Scroll lock on `<body>` while open.
+ *
+ * Use the imperative `useDialog()` (export from this same module) if
+ * you want a `confirm()`-style return value pattern (similar to
+ * `useConfirm()` from `ConfirmDialog`). Use `<Dialog>` when you want
+ * the control flow living in your component tree.
+ */
+export function Dialog(props: DialogProps) {
+  const {
+    open,
+    onOpenChange,
+    children,
+    title,
+    description,
+    showCloseButton = true,
+    disableBackdropClose = false,
+    disableEscapeClose = false,
+    size = 'md',
+    sx,
+    slotProps,
+  } = props;
+
+  const v = dialogVariants({ size });
+
+  return (
+    <RadixDialog.Root open={open} onOpenChange={onOpenChange}>
+      <RadixDialog.Portal>
+        <RadixDialog.Overlay
+          className={cn(v.overlay(), slotProps?.overlay?.className)}
+        />
+        <RadixDialog.Content
+          className={cn(v.content(), sx, slotProps?.content?.className)}
+          onPointerDownOutside={(event) => {
+            if (disableBackdropClose) event.preventDefault();
+          }}
+          onEscapeKeyDown={(event) => {
+            if (disableEscapeClose) event.preventDefault();
+          }}
+        >
+          {title != null && (
+            <RadixDialog.Title
+              className={cn(v.title(), slotProps?.title?.className)}
+            >
+              {title}
+            </RadixDialog.Title>
+          )}
+          {description != null && (
+            <RadixDialog.Description
+              className={cn(v.description(), slotProps?.description?.className)}
+            >
+              {description}
+            </RadixDialog.Description>
+          )}
+          <div className={cn(v.body(), slotProps?.body?.className)}>
+            {children}
+          </div>
+          {showCloseButton && (
+            <RadixDialog.Close
+              aria-label="Close"
+              className={cn(v.closeButton(), slotProps?.closeButton?.className)}
+            >
+              <svg
+                width="1em"
+                height="1em"
+                viewBox="0 0 16 16"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M4 4l8 8M12 4l-8 8" />
+              </svg>
+            </RadixDialog.Close>
+          )}
+        </RadixDialog.Content>
+      </RadixDialog.Portal>
+    </RadixDialog.Root>
+  );
+}