@dashforge/tw 0.2.1-beta → 0.4.0-beta

package/dist/index.esm.js

@@ -11,6 +11,11 @@ import { useDashFieldMeta } from '@dashforge/forms';
 import * as RadixCheckbox from '@radix-ui/react-checkbox';
 import * as RadixSwitch from '@radix-ui/react-switch';
 import * as RadixRadioGroup from '@radix-ui/react-radio-group';
+import * as RadixDialog from '@radix-ui/react-dialog';
+import * as RadixTabs from '@radix-ui/react-tabs';
+import * as RadixTooltip from '@radix-ui/react-tooltip';
+import * as RadixPopover from '@radix-ui/react-popover';
+import * as RadixAccordion from '@radix-ui/react-accordion';
 
 function _extends() {
     _extends = Object.assign || function assign(target) {
@@ -510,7 +515,24 @@ function _object_without_properties_loose(source, excluded) {
             'read-only:cursor-default'
         ],
         helperText: 'mt-1 text-sm text-neutral-600',
-        errorText: 'mt-1 text-sm text-danger-600'
+        errorText: 'mt-1 text-sm text-danger-600',
+        /*
+         * `prefix` / `suffix` slot — inline adornment rendered before /
+         * after the input INSIDE the inputWrapper. `shrink-0` keeps the
+         * adornment width fixed so it doesn't compete for space with the
+         * input; `select-none` + `pointer-events-none` avoids
+         * accidentally stealing focus from the input on click (the
+         * inputWrapper handles focus via `focus-within`).
+         */ prefix: [
+            'shrink-0 inline-flex items-center select-none pointer-events-none',
+            'text-neutral-500',
+            'mr-2'
+        ],
+        suffix: [
+            'shrink-0 inline-flex items-center select-none pointer-events-none',
+            'text-neutral-500',
+            'ml-2'
+        ]
     },
     variants: {
         size: {
@@ -587,7 +609,7 @@ function _object_without_properties_loose(source, excluded) {
  *   - `aria-describedby` links the input to the helper/error text node.
  *   - Required fields get the native `required` attribute + a visual `*`.
  */ function TextField(props) {
-    var _slotProps_root, _slotProps_label, _slotProps_requiredMark, _slotProps_inputWrapper, _slotProps_input, _slotProps_errorText, _slotProps_helperText;
+    var _slotProps_root, _slotProps_label, _slotProps_requiredMark, _slotProps_inputWrapper, _slotProps_prefix, _slotProps_input, _slotProps_suffix, _slotProps_errorText, _slotProps_helperText;
     const { name, rules, visibleWhen, layout = 'stacked', size, label, helperText, required, error, disabled, fullWidth, access, sx, slotProps, placeholder, type, onChange: userOnChange, onBlur: userOnBlur, value: userValue, defaultValue } = props, rest = _object_without_properties_loose(props, [
         "name",
         "rules",
@@ -717,25 +739,37 @@ function _object_without_properties_loose(source, excluded) {
                     })
                 ]
             }),
-            jsx("div", {
+            jsxs("div", {
                 className: cn(v.inputWrapper(), slotProps == null ? void 0 : (_slotProps_inputWrapper = slotProps.inputWrapper) == null ? void 0 : _slotProps_inputWrapper.className),
-                children: jsx("input", _extends({}, rest, {
-                    id: inputId,
-                    name: name,
-                    type: type != null ? type : 'text',
-                    placeholder: placeholder,
-                    value: isFormMode ? resolvedValue != null ? resolvedValue : '' : userValue,
-                    defaultValue: !isFormMode && userValue === undefined ? defaultValue : undefined,
-                    disabled: effectiveDisabled,
-                    readOnly: effectiveReadOnly,
-                    required: required,
-                    "aria-invalid": resolvedError || undefined,
-                    "aria-describedby": resolvedHelperText ? helperId : undefined,
-                    onChange: handleChange,
-                    onBlur: handleBlur,
-                    ref: inputRef,
-                    className: cn(v.input(), slotProps == null ? void 0 : (_slotProps_input = slotProps.input) == null ? void 0 : _slotProps_input.className)
-                }))
+                children: [
+                    (slotProps == null ? void 0 : (_slotProps_prefix = slotProps.prefix) == null ? void 0 : _slotProps_prefix.children) !== undefined && jsx("span", {
+                        "aria-hidden": "true",
+                        className: cn(v.prefix(), slotProps.prefix.className),
+                        children: slotProps.prefix.children
+                    }),
+                    jsx("input", _extends({}, rest, {
+                        id: inputId,
+                        name: name,
+                        type: type != null ? type : 'text',
+                        placeholder: placeholder,
+                        value: isFormMode ? resolvedValue != null ? resolvedValue : '' : userValue,
+                        defaultValue: !isFormMode && userValue === undefined ? defaultValue : undefined,
+                        disabled: effectiveDisabled,
+                        readOnly: effectiveReadOnly,
+                        required: required,
+                        "aria-invalid": resolvedError || undefined,
+                        "aria-describedby": resolvedHelperText ? helperId : undefined,
+                        onChange: handleChange,
+                        onBlur: handleBlur,
+                        ref: inputRef,
+                        className: cn(v.input(), slotProps == null ? void 0 : (_slotProps_input = slotProps.input) == null ? void 0 : _slotProps_input.className)
+                    })),
+                    (slotProps == null ? void 0 : (_slotProps_suffix = slotProps.suffix) == null ? void 0 : _slotProps_suffix.children) !== undefined && jsx("span", {
+                        "aria-hidden": "true",
+                        className: cn(v.suffix(), slotProps.suffix.className),
+                        children: slotProps.suffix.children
+                    })
+                ]
             }),
             resolvedHelperText && jsx("p", {
                 id: helperId,
@@ -811,8 +845,8 @@ function _object_without_properties_loose(source, excluded) {
 });
 
 /**
- * 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
  */ function CheckIcon({ className }) {
@@ -830,6 +864,32 @@ function _object_without_properties_loose(source, excluded) {
         })
     });
 }
+/**
+ * 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 }) {
+    return jsx("svg", {
+        "aria-hidden": "true",
+        viewBox: "0 0 16 16",
+        fill: "none",
+        className: className,
+        children: jsx("path", {
+            d: "M3 8h10",
+            stroke: "currentColor",
+            strokeWidth: "2.5",
+            strokeLinecap: "round"
+        })
+    });
+}
 /**
  * Dashforge TW Checkbox — bridge-integrated form control.
  *
@@ -975,11 +1035,16 @@ function _object_without_properties_loose(source, excluded) {
                 onBlur: handleBlur,
                 ref: registration == null ? void 0 : registration.ref,
                 className: cn(v.control(), slotProps == null ? void 0 : (_slotProps_control = slotProps.control) == null ? void 0 : _slotProps_control.className),
-                children: jsx(RadixCheckbox.Indicator, {
-                    className: cn(v.indicator(), slotProps == null ? void 0 : (_slotProps_indicator = slotProps.indicator) == null ? void 0 : _slotProps_indicator.className),
-                    children: jsx(CheckIcon, {
-                        className: "h-full w-full"
-                    })
+                children: jsxs(RadixCheckbox.Indicator, {
+                    className: cn(v.indicator(), 'group', slotProps == null ? void 0 : (_slotProps_indicator = slotProps.indicator) == null ? void 0 : _slotProps_indicator.className),
+                    children: [
+                        jsx(CheckIcon, {
+                            className: "h-full w-full group-data-[state=indeterminate]:hidden"
+                        }),
+                        jsx(DashIcon, {
+                            className: "h-full w-full group-data-[state=checked]:hidden"
+                        })
+                    ]
                 })
             })),
             jsxs("div", {
@@ -1024,7 +1089,12 @@ function _object_without_properties_loose(source, excluded) {
         ],
         thumb: [
             'pointer-events-none inline-block rounded-full bg-white shadow ring-0',
-            'transition-transform',
+            // Slide animation gated on `prefers-reduced-motion: no-preference`
+            // (WCAG 2.3.3). The thumb still moves between positions instantly
+            // for users who request reduced motion — the data-state change
+            // applies the translate-x rule unconditionally, only the smooth
+            // transition between the two is suppressed.
+            'transition-transform motion-reduce:transition-none',
             'data-[state=unchecked]:translate-x-0'
         ],
         label: 'select-none cursor-pointer text-neutral-900',
@@ -2414,7 +2484,13 @@ function _object_without_properties_loose(source, excluded) {
             'flex items-center justify-center shrink-0 px-2',
             'text-neutral-600 hover:text-neutral-900',
             'disabled:cursor-not-allowed disabled:opacity-40',
-            'transition-colors'
+            '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',
@@ -2507,6 +2583,52 @@ function _object_without_properties_loose(source, excluded) {
     }
 });
 
+/**
+ * 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 }) {
+    return jsx("svg", {
+        "aria-hidden": "true",
+        viewBox: "0 0 16 16",
+        width: "1em",
+        height: "1em",
+        fill: "none",
+        className: className,
+        children: jsx("path", {
+            d: "M4 4l8 8M12 4l-8 8",
+            stroke: "currentColor",
+            strokeWidth: "1.75",
+            strokeLinecap: "round"
+        })
+    });
+}
+function ChevronDownIcon({ className }) {
+    return jsx("svg", {
+        "aria-hidden": "true",
+        viewBox: "0 0 16 16",
+        width: "1em",
+        height: "1em",
+        fill: "none",
+        className: className,
+        children: jsx("path", {
+            d: "M4 6l4 4 4-4",
+            stroke: "currentColor",
+            strokeWidth: "1.75",
+            strokeLinecap: "round",
+            strokeLinejoin: "round"
+        })
+    });
+}
 /**
  * Coerce a raw value (from bridge / props) into a canonical shape:
  *
@@ -2813,7 +2935,15 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
             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);
@@ -2843,6 +2973,8 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
         options,
+        asyncOptions,
+        loadOptions,
         isFormMode,
         bridge,
         name,
@@ -3189,7 +3321,7 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
                                         "aria-label": `Remove ${labelText}`,
                                         tabIndex: -1,
                                         className: cn(v.chipRemove(), slotProps == null ? void 0 : (_slotProps_chipRemove = slotProps.chipRemove) == null ? void 0 : _slotProps_chipRemove.className),
-                                        children: "\u00D7"
+                                        children: jsx(CloseIcon, {})
                                     })
                                 ]
                             }, key);
@@ -3233,7 +3365,7 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
                         "aria-label": "Clear selection",
                         tabIndex: -1,
                         className: cn(v.clearButton(), slotProps == null ? void 0 : (_slotProps_clearButton = slotProps.clearButton) == null ? void 0 : _slotProps_clearButton.className),
-                        children: "\u00D7"
+                        children: jsx(CloseIcon, {})
                     }),
                     jsx("button", {
                         type: "button",
@@ -3245,7 +3377,7 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
                         tabIndex: -1,
                         disabled: effectiveDisabled,
                         className: cn(v.trigger(), slotProps == null ? void 0 : (_slotProps_trigger = slotProps.trigger) == null ? void 0 : _slotProps_trigger.className),
-                        children: "\u25BE"
+                        children: jsx(ChevronDownIcon, {})
                     }),
                     isOpen && jsx("ul", {
                         ref: listboxRef,
@@ -3643,7 +3775,12 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
             'text-neutral-600 hover:text-primary-700',
             'rounded-sm outline-none',
             'focus-visible:ring-2 focus-visible:ring-primary-500/50',
-            'transition-colors'
+            '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',
@@ -3837,7 +3974,10 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
         root: [
             'flex flex-col h-full',
             'bg-neutral-50 border-r border-neutral-200',
-            'transition-[width] duration-200'
+            // Width transition (rail-mode toggle) — gated on
+            // prefers-reduced-motion (WCAG 2.3.3). The new width still
+            // applies, just without the animated tween.
+            'transition-[width] duration-200 motion-reduce:transition-none motion-reduce:duration-0'
         ],
         brand: [
             'flex items-center gap-2 px-3 h-14 shrink-0',
@@ -3851,7 +3991,15 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
             'outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50',
             'transition-colors w-full',
             'aria-disabled:opacity-50 aria-disabled:cursor-not-allowed',
-            'aria-disabled:hover:bg-transparent'
+            'aria-disabled:hover:bg-transparent',
+            // Defensive `no-underline` — Tailwind's preflight removes the
+            // default browser anchor underline globally, but environments
+            // that DISABLE preflight (e.g. our docs-lab, where the tw
+            // section coexists with MUI's chrome) get raw browser defaults
+            // back. Without this, `<a>` items in the nav render underlined
+            // in those contexts. Explicit `no-underline` + `hover:no-underline`
+            // keeps the appearance consistent regardless of preflight state.
+            'no-underline hover:no-underline'
         ],
         itemActive: 'bg-primary-100 text-primary-900 font-medium',
         itemIcon: 'shrink-0 w-5 h-5 flex items-center justify-center',
@@ -4259,14 +4407,20 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
         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'
         ]
     },
@@ -4283,6 +4437,28 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
     }
 });
 
+/**
+ * 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.
  *
@@ -4311,6 +4487,20 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
  *   - 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.
  */ function AppShell(props) {
     var _slotProps_root, _slotProps_header, _slotProps_nav, _slotProps_navMobile, _slotProps_backdrop, _slotProps_main, _slotProps_footer;
     const { header, nav, footer, children, navOpen = false, onNavOpenChange, sx, slotProps } = props;
@@ -4340,6 +4530,80 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
         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(null);
+    const restoreFocusRef = useRef(null);
+    useEffect(()=>{
+        if (!navOpen) return;
+        // 1) Capture the element that had focus before the drawer opened.
+        restoreFocusRef.current = document.activeElement;
+        // 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(FOCUSABLE_SELECTOR);
+            first == null ? void 0 : first.focus();
+        });
+        // 3) Trap Tab / Shift+Tab inside the drawer.
+        const onKeyDown = (event)=>{
+            if (event.key !== 'Tab') return;
+            const drawer = drawerRef.current;
+            if (!drawer) return;
+            const focusables = Array.from(drawer.querySelectorAll(FOCUSABLE_SELECTOR));
+            if (focusables.length === 0) {
+                event.preventDefault();
+                return;
+            }
+            const first = focusables[0];
+            const last = focusables[focusables.length - 1];
+            const active = document.activeElement;
+            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 jsxs("div", {
         className: cn(v.root(), sx, slotProps == null ? void 0 : (_slotProps_root = slotProps.root) == null ? void 0 : _slotProps_root.className),
         children: [
@@ -4357,8 +4621,15 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
                                 children: nav
                             }),
                             jsx("aside", {
+                                ref: drawerRef,
                                 className: cn(v.navMobile(), slotProps == null ? void 0 : (_slotProps_navMobile = slotProps.navMobile) == null ? void 0 : _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,
                                 children: nav
                             }),
                             jsx("div", {
@@ -4663,8 +4934,10 @@ const ConfirmContext = /*#__PURE__*/ createContext(null);
             'rounded-lg border shadow-lg',
             'text-sm bg-neutral-50 text-neutral-900',
             // Subtle enter transition — opacity + translate, kept short so a
-            // burst of snackbars feels snappy.
-            'transition-all duration-200',
+            // burst of snackbars feels snappy. Gated on motion-reduce
+            // (WCAG 2.3.3) — users who request reduced motion see snackbars
+            // pop in instantly without the slide animation.
+            'transition-all duration-200 motion-reduce:transition-none motion-reduce:duration-0',
             'data-[state=entered]:opacity-100 data-[state=exited]:opacity-0'
         ],
         icon: 'shrink-0 mt-0.5 w-5 h-5 inline-flex items-center justify-center',
@@ -6523,6 +6796,492 @@ AspectRatio.displayName = 'AspectRatio';
 });
 VisuallyHidden.displayName = 'VisuallyHidden';
 
+/**
+ * `<Dialog>` variant recipe.
+ *
+ * Slots:
+ *  - `overlay`  — backdrop (Radix's `DialogOverlay`)
+ *  - `content`  — the dialog box itself
+ *  - `title`    — heading at the top
+ *  - `description` — secondary text under the title
+ *  - `closeButton` — top-right `×` button
+ *  - `body`     — main scrollable area
+ *  - `actions`  — footer action bar
+ *
+ * Three sizes (`sm` / `md` / `lg`) drive the content max-width.
+ * Motion is gated by `prefers-reduced-motion` so the slide-in
+ * animation collapses to an instant appear on users that opt out.
+ */ const dialogVariants = tv({
+    slots: {
+        overlay: [
+            'fixed inset-0 z-50 bg-neutral-950/60 backdrop-blur-sm',
+            'data-[state=open]:animate-in data-[state=open]:fade-in-0',
+            'data-[state=closed]:animate-out data-[state=closed]:fade-out-0',
+            'motion-reduce:transition-none motion-reduce:duration-0'
+        ],
+        content: [
+            'fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2',
+            'w-full bg-white dark:bg-neutral-900 rounded-lg shadow-xl',
+            'border border-neutral-200 dark:border-neutral-800',
+            'p-6 flex flex-col gap-4 max-h-[90vh]',
+            'focus:outline-none',
+            'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+            'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+            'motion-reduce:transition-none motion-reduce:duration-0'
+        ],
+        title: 'text-lg font-semibold leading-tight text-neutral-900 dark:text-neutral-50',
+        description: 'text-sm text-neutral-600 dark:text-neutral-400',
+        closeButton: [
+            'absolute top-4 right-4 inline-flex items-center justify-center',
+            'h-8 w-8 rounded-md text-neutral-500 hover:text-neutral-900',
+            'dark:text-neutral-400 dark:hover:text-neutral-50',
+            'hover:bg-neutral-100 dark:hover:bg-neutral-800',
+            'focus:outline-none focus:ring-2 focus:ring-primary-500',
+            'transition-colors'
+        ],
+        body: 'flex-1 overflow-y-auto',
+        actions: 'flex justify-end gap-2 pt-2'
+    },
+    variants: {
+        size: {
+            sm: {
+                content: 'max-w-sm'
+            },
+            md: {
+                content: 'max-w-md'
+            },
+            lg: {
+                content: 'max-w-2xl'
+            }
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});
+
+/**
+ * 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.
+ */ function Dialog(props) {
+    var _slotProps_overlay, _slotProps_content, _slotProps_title, _slotProps_description, _slotProps_body, _slotProps_closeButton;
+    const { open, onOpenChange, children, title, description, showCloseButton = true, disableBackdropClose = false, disableEscapeClose = false, size = 'md', sx, slotProps } = props;
+    const v = dialogVariants({
+        size
+    });
+    return jsx(RadixDialog.Root, {
+        open: open,
+        onOpenChange: onOpenChange,
+        children: jsxs(RadixDialog.Portal, {
+            children: [
+                jsx(RadixDialog.Overlay, {
+                    className: cn(v.overlay(), slotProps == null ? void 0 : (_slotProps_overlay = slotProps.overlay) == null ? void 0 : _slotProps_overlay.className)
+                }),
+                jsxs(RadixDialog.Content, {
+                    className: cn(v.content(), sx, slotProps == null ? void 0 : (_slotProps_content = slotProps.content) == null ? void 0 : _slotProps_content.className),
+                    onPointerDownOutside: (event)=>{
+                        if (disableBackdropClose) event.preventDefault();
+                    },
+                    onEscapeKeyDown: (event)=>{
+                        if (disableEscapeClose) event.preventDefault();
+                    },
+                    children: [
+                        title != null && jsx(RadixDialog.Title, {
+                            className: cn(v.title(), slotProps == null ? void 0 : (_slotProps_title = slotProps.title) == null ? void 0 : _slotProps_title.className),
+                            children: title
+                        }),
+                        description != null && jsx(RadixDialog.Description, {
+                            className: cn(v.description(), slotProps == null ? void 0 : (_slotProps_description = slotProps.description) == null ? void 0 : _slotProps_description.className),
+                            children: description
+                        }),
+                        jsx("div", {
+                            className: cn(v.body(), slotProps == null ? void 0 : (_slotProps_body = slotProps.body) == null ? void 0 : _slotProps_body.className),
+                            children: children
+                        }),
+                        showCloseButton && jsx(RadixDialog.Close, {
+                            "aria-label": "Close",
+                            className: cn(v.closeButton(), slotProps == null ? void 0 : (_slotProps_closeButton = slotProps.closeButton) == null ? void 0 : _slotProps_closeButton.className),
+                            children: jsx("svg", {
+                                width: "1em",
+                                height: "1em",
+                                viewBox: "0 0 16 16",
+                                fill: "none",
+                                stroke: "currentColor",
+                                strokeWidth: "1.5",
+                                strokeLinecap: "round",
+                                strokeLinejoin: "round",
+                                "aria-hidden": "true",
+                                children: jsx("path", {
+                                    d: "M4 4l8 8M12 4l-8 8"
+                                })
+                            })
+                        })
+                    ]
+                })
+            ]
+        })
+    });
+}
+
+const tabsVariants = tv({
+    slots: {
+        root: 'flex',
+        list: 'inline-flex items-center gap-1',
+        trigger: [
+            'inline-flex items-center justify-center whitespace-nowrap',
+            'text-sm font-medium transition-colors',
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+            'disabled:opacity-50 disabled:pointer-events-none',
+            'motion-reduce:transition-none'
+        ],
+        content: [
+            'mt-3 focus:outline-none',
+            'data-[state=inactive]:hidden'
+        ]
+    },
+    variants: {
+        variant: {
+            underline: {
+                list: 'border-b border-neutral-200 dark:border-neutral-800',
+                trigger: [
+                    'px-3 py-2 border-b-2 border-transparent text-neutral-600 dark:text-neutral-400',
+                    'hover:text-neutral-900 dark:hover:text-neutral-50',
+                    'data-[state=active]:border-primary-500 data-[state=active]:text-primary-700',
+                    'dark:data-[state=active]:text-primary-400'
+                ]
+            },
+            pill: {
+                list: 'rounded-lg bg-neutral-100 dark:bg-neutral-800 p-1',
+                trigger: [
+                    'px-3 py-1.5 rounded-md text-neutral-600 dark:text-neutral-400',
+                    'hover:text-neutral-900 dark:hover:text-neutral-50',
+                    'data-[state=active]:bg-white dark:data-[state=active]:bg-neutral-900',
+                    'data-[state=active]:text-neutral-900 dark:data-[state=active]:text-neutral-50',
+                    'data-[state=active]:shadow-sm'
+                ]
+            }
+        },
+        orientation: {
+            horizontal: {
+                root: 'flex-col',
+                list: 'flex-row'
+            },
+            vertical: {
+                root: 'flex-row gap-4',
+                list: 'flex-col items-stretch'
+            }
+        }
+    },
+    defaultVariants: {
+        variant: 'underline',
+        orientation: 'horizontal'
+    }
+});
+
+/**
+ * Dashforge TW `<Tabs>` — declarative tab navigation.
+ *
+ * Built on `@radix-ui/react-tabs`:
+ *  - APG tabs pattern (arrow-key navigation, automatic activation,
+ *    `role="tablist"` + `role="tab"` + `role="tabpanel"`).
+ *  - Controlled / uncontrolled (`value` / `defaultValue`).
+ *
+ * Two variant axes:
+ *  - `variant` — `underline` (default) | `pill`
+ *  - `orientation` — `horizontal` (default) | `vertical`
+ */ function Tabs(props) {
+    var _items_, _slotProps_root, _slotProps_list;
+    const { items, value, defaultValue, onValueChange, variant = 'underline', orientation = 'horizontal', sx, slotProps } = props;
+    const v = tabsVariants({
+        variant,
+        orientation
+    });
+    const resolvedDefault = defaultValue != null ? defaultValue : (_items_ = items[0]) == null ? void 0 : _items_.value;
+    return jsxs(RadixTabs.Root, {
+        value: value,
+        defaultValue: resolvedDefault,
+        onValueChange: onValueChange,
+        orientation: orientation,
+        className: cn(v.root(), sx, slotProps == null ? void 0 : (_slotProps_root = slotProps.root) == null ? void 0 : _slotProps_root.className),
+        children: [
+            jsx(RadixTabs.List, {
+                className: cn(v.list(), slotProps == null ? void 0 : (_slotProps_list = slotProps.list) == null ? void 0 : _slotProps_list.className),
+                children: items.map((item)=>{
+                    var _slotProps_trigger;
+                    return jsx(RadixTabs.Trigger, {
+                        value: item.value,
+                        disabled: item.disabled,
+                        className: cn(v.trigger(), slotProps == null ? void 0 : (_slotProps_trigger = slotProps.trigger) == null ? void 0 : _slotProps_trigger.className),
+                        children: item.label
+                    }, item.value);
+                })
+            }),
+            items.map((item)=>{
+                var _slotProps_content;
+                return jsx(RadixTabs.Content, {
+                    value: item.value,
+                    className: cn(v.content(), slotProps == null ? void 0 : (_slotProps_content = slotProps.content) == null ? void 0 : _slotProps_content.className),
+                    children: item.content
+                }, item.value);
+            })
+        ]
+    });
+}
+
+const tooltipVariants = tv({
+    slots: {
+        content: [
+            'z-50 max-w-xs rounded-md px-3 py-1.5 text-xs font-medium',
+            'bg-neutral-900 text-neutral-50',
+            'dark:bg-neutral-50 dark:text-neutral-900',
+            'shadow-md',
+            'data-[state=delayed-open]:animate-in data-[state=delayed-open]:fade-in-0 data-[state=delayed-open]:zoom-in-95',
+            'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+            'motion-reduce:transition-none motion-reduce:duration-0'
+        ],
+        arrow: 'fill-neutral-900 dark:fill-neutral-50'
+    }
+});
+
+/**
+ * Dashforge TW `<Tooltip>` — hoverable / focusable tooltip.
+ *
+ * Built on `@radix-ui/react-tooltip`:
+ *  - APG tooltip pattern: `role="tooltip"`, `aria-describedby` wired
+ *    to the trigger automatically (Radix manages the id linkage).
+ *  - Shows on hover OR keyboard focus.
+ *  - Dismissed on Escape or pointer leave.
+ *
+ * Wrap any single React node — it becomes the trigger via Radix's
+ * `asChild` slot. The trigger inherits `aria-describedby` so screen
+ * readers announce the tooltip content along with the trigger.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip content="Delete this item">
+ *   <Button variant="ghost">
+ *     <TrashIcon />
+ *   </Button>
+ * </Tooltip>
+ * ```
+ *
+ * Each consumer can also wrap the entire app once in
+ * `<RadixTooltip.Provider>` to share delay/skip configuration; we
+ * include a per-component provider here for ease-of-use.
+ */ function Tooltip(props) {
+    var _slotProps_content, _slotProps_arrow;
+    const { children, content, side = 'top', align = 'center', hideArrow = false, delayDuration = 200, open, onOpenChange, sideOffset = 4, slotProps } = props;
+    const v = tooltipVariants();
+    return jsx(RadixTooltip.Provider, {
+        delayDuration: delayDuration,
+        children: jsxs(RadixTooltip.Root, {
+            open: open,
+            onOpenChange: onOpenChange,
+            children: [
+                jsx(RadixTooltip.Trigger, {
+                    asChild: true,
+                    children: children
+                }),
+                jsx(RadixTooltip.Portal, {
+                    children: jsxs(RadixTooltip.Content, {
+                        side: side,
+                        align: align,
+                        sideOffset: sideOffset,
+                        className: cn(v.content(), slotProps == null ? void 0 : (_slotProps_content = slotProps.content) == null ? void 0 : _slotProps_content.className),
+                        children: [
+                            content,
+                            !hideArrow && jsx(RadixTooltip.Arrow, {
+                                className: cn(v.arrow(), slotProps == null ? void 0 : (_slotProps_arrow = slotProps.arrow) == null ? void 0 : _slotProps_arrow.className)
+                            })
+                        ]
+                    })
+                })
+            ]
+        })
+    });
+}
+
+const popoverVariants = tv({
+    slots: {
+        content: [
+            'z-50 rounded-md border border-neutral-200 dark:border-neutral-800',
+            'bg-white dark:bg-neutral-900 p-4 shadow-lg',
+            'text-sm text-neutral-900 dark:text-neutral-50',
+            'focus:outline-none',
+            'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+            'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+            'motion-reduce:transition-none motion-reduce:duration-0'
+        ],
+        arrow: 'fill-white dark:fill-neutral-900'
+    }
+});
+
+/**
+ * Dashforge TW `<Popover>` — clickable floating content panel.
+ *
+ * Built on `@radix-ui/react-popover`:
+ *  - Focus trap inside the popover (Tab cycles within).
+ *  - Outside-click + Escape dismiss.
+ *  - APG dialog-like semantics (`role="dialog"` on content).
+ *  - Portal-rendered.
+ *
+ * Use `<Popover>` for menus / pickers / settings panels with
+ * interactive children. Use `<Tooltip>` for read-only hints.
+ */ function Popover(props) {
+    var _slotProps_content, _slotProps_arrow;
+    const { children, content, side = 'bottom', align = 'center', showArrow = false, open, onOpenChange, sideOffset = 8, width, slotProps } = props;
+    const v = popoverVariants();
+    return jsxs(RadixPopover.Root, {
+        open: open,
+        onOpenChange: onOpenChange,
+        children: [
+            jsx(RadixPopover.Trigger, {
+                asChild: true,
+                children: children
+            }),
+            jsx(RadixPopover.Portal, {
+                children: jsxs(RadixPopover.Content, {
+                    side: side,
+                    align: align,
+                    sideOffset: sideOffset,
+                    style: width != null ? {
+                        width
+                    } : undefined,
+                    className: cn(v.content(), slotProps == null ? void 0 : (_slotProps_content = slotProps.content) == null ? void 0 : _slotProps_content.className),
+                    children: [
+                        content,
+                        showArrow && jsx(RadixPopover.Arrow, {
+                            className: cn(v.arrow(), slotProps == null ? void 0 : (_slotProps_arrow = slotProps.arrow) == null ? void 0 : _slotProps_arrow.className)
+                        })
+                    ]
+                })
+            })
+        ]
+    });
+}
+
+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'
+        ]
+    }
+});
+
+/**
+ * Dashforge TW `<Accordion>` — collapsible section list.
+ *
+ * Built on `@radix-ui/react-accordion`:
+ *  - APG accordion pattern: `role="region"` on content, header
+ *    button with `aria-expanded` and `aria-controls` linked to
+ *    the panel.
+ *  - Keyboard support: Space / Enter toggle, ArrowDown / ArrowUp
+ *    move focus between triggers, Home / End to extremes.
+ *  - Two modes:
+ *    - `type="single"` — at most one section open at a time;
+ *      `collapsible` allows clicking the open section to close it
+ *      (default true).
+ *    - `type="multiple"` — multiple sections open simultaneously.
+ *
+ * The trigger renders a chevron that flips 180° via CSS
+ * (`data-state=open` selector) — no React state, no JS animation.
+ */ function Accordion(props) {
+    var _props_collapsible;
+    var _slotProps_root;
+    const v = accordionVariants();
+    const { items, sx, slotProps } = props;
+    const renderItems = (items, slotProps)=>items.map((item)=>{
+            var _slotProps_item, _slotProps_header, _slotProps_trigger, _slotProps_chevron, _slotProps_content;
+            return jsxs(RadixAccordion.Item, {
+                value: item.value,
+                disabled: item.disabled,
+                className: cn(v.item(), slotProps == null ? void 0 : (_slotProps_item = slotProps.item) == null ? void 0 : _slotProps_item.className),
+                children: [
+                    jsx(RadixAccordion.Header, {
+                        className: cn(v.header(), slotProps == null ? void 0 : (_slotProps_header = slotProps.header) == null ? void 0 : _slotProps_header.className),
+                        children: jsxs(RadixAccordion.Trigger, {
+                            className: cn(v.trigger(), slotProps == null ? void 0 : (_slotProps_trigger = slotProps.trigger) == null ? void 0 : _slotProps_trigger.className),
+                            children: [
+                                item.header,
+                                jsx("svg", {
+                                    className: cn(v.chevron(), slotProps == null ? void 0 : (_slotProps_chevron = slotProps.chevron) == null ? void 0 : _slotProps_chevron.className),
+                                    width: "1em",
+                                    height: "1em",
+                                    viewBox: "0 0 16 16",
+                                    fill: "none",
+                                    stroke: "currentColor",
+                                    strokeWidth: "1.5",
+                                    strokeLinecap: "round",
+                                    strokeLinejoin: "round",
+                                    "aria-hidden": "true",
+                                    children: jsx("path", {
+                                        d: "M4 6l4 4 4-4"
+                                    })
+                                })
+                            ]
+                        })
+                    }),
+                    jsx(RadixAccordion.Content, {
+                        className: cn(v.content(), slotProps == null ? void 0 : (_slotProps_content = slotProps.content) == null ? void 0 : _slotProps_content.className),
+                        children: jsx("div", {
+                            className: "pb-3 pt-0",
+                            children: item.content
+                        })
+                    })
+                ]
+            }, item.value);
+        });
+    if (props.type === 'multiple') {
+        var _slotProps_root1;
+        return jsx(RadixAccordion.Root, {
+            type: "multiple",
+            value: props.value,
+            defaultValue: props.defaultValue,
+            onValueChange: props.onValueChange,
+            className: cn(v.root(), sx, slotProps == null ? void 0 : (_slotProps_root1 = slotProps.root) == null ? void 0 : _slotProps_root1.className),
+            children: renderItems(items, slotProps)
+        });
+    }
+    return jsx(RadixAccordion.Root, {
+        type: "single",
+        collapsible: (_props_collapsible = props.collapsible) != null ? _props_collapsible : true,
+        value: props.value,
+        defaultValue: props.defaultValue,
+        onValueChange: props.onValueChange,
+        className: cn(v.root(), sx, slotProps == null ? void 0 : (_slotProps_root = slotProps.root) == null ? void 0 : _slotProps_root.className),
+        children: renderItems(items, slotProps)
+    });
+}
+
 /**
  * @dashforge/tw
  *
@@ -6550,6 +7309,6 @@ VisuallyHidden.displayName = 'VisuallyHidden';
  */ // ───── Components ─────
 /**
  * Package version (synced with `package.json` at publish time).
- */ const VERSION = '0.2.1-beta';
+ */ const VERSION = '0.4.0-beta';
 
-export { AppShell, AspectRatio, Autocomplete, Box, Breadcrumbs, Button, Checkbox, ConfirmDialogProvider, Container, DateTimePicker, Divider, Grid, LeftNav, NumberField, OTPField, RadioGroup, SnackbarProvider, Stack, Switch, TextField, Textarea, TopBar, Typography, VERSION, VisuallyHidden, appShellVariants, autocompleteVariants, boxVariants, breadcrumbsVariants, buttonVariants, checkboxVariants, cn, confirmDialogVariants, containerVariants, dateTimePickerVariants, dividerLineVariants, dividerVariants, gridVariants, isoToInputValue, leftNavVariants, numberFieldVariants, otpFieldVariants, radioGroupVariants, snackbarVariants, stackVariants, switchVariants, textFieldVariants, textareaVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar };
+export { Accordion, AppShell, AspectRatio, Autocomplete, Box, Breadcrumbs, Button, Checkbox, ConfirmDialogProvider, Container, DateTimePicker, Dialog, Divider, Grid, LeftNav, NumberField, OTPField, Popover, RadioGroup, SnackbarProvider, Stack, Switch, Tabs, TextField, Textarea, Tooltip, TopBar, Typography, VERSION, VisuallyHidden, accordionVariants, appShellVariants, autocompleteVariants, boxVariants, breadcrumbsVariants, buttonVariants, checkboxVariants, cn, confirmDialogVariants, containerVariants, dateTimePickerVariants, dialogVariants, dividerLineVariants, dividerVariants, gridVariants, isoToInputValue, leftNavVariants, numberFieldVariants, otpFieldVariants, popoverVariants, radioGroupVariants, snackbarVariants, stackVariants, switchVariants, tabsVariants, textFieldVariants, textareaVariants, tooltipVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar };