@dashforge/tw 0.2.0-beta → 0.3.0-beta

package/dist/index.esm.js

@@ -403,6 +403,13 @@ function _object_without_properties_loose(source, excluded) {
         fullWidth,
         loading
     }), sx);
+    /*
+     * `aria-busy` announces the loading state to assistive tech.
+     * `disabled` alone hides the reason (perm-denied vs loading vs
+     * intrinsic), so SR users only hear "dimmed/inactive" without
+     * knowing why. Adding `aria-busy={true}` while loading distinguishes
+     * "wait for the action to finish" from "you can't do this".
+     */ const ariaBusy = loading ? true : undefined;
     // `asChild` renders through Radix Slot: the immediate child element
     // gets the resolved className, no extra Button DOM is emitted.
     if (asChild) {
@@ -411,6 +418,7 @@ function _object_without_properties_loose(source, excluded) {
             className: classes,
             "data-disabled": effectiveDisabled || undefined,
             "aria-disabled": effectiveDisabled || undefined,
+            "aria-busy": ariaBusy,
             children: children
         });
     }
@@ -418,6 +426,7 @@ function _object_without_properties_loose(source, excluded) {
         ref: ref,
         type: (_rest_type = rest.type) != null ? _rest_type : 'button',
         disabled: effectiveDisabled,
+        "aria-busy": ariaBusy,
         className: classes
     }, rest, {
         children: [
@@ -501,7 +510,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: {
@@ -578,7 +604,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",
@@ -708,25 +734,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,
@@ -802,8 +840,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 }) {
@@ -821,6 +859,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.
  *
@@ -966,12 +1030,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),
-                    forceMount: true,
-                    children: resolvedChecked === true ? jsx(CheckIcon, {
-                        className: "h-full w-full"
-                    }) : null
+                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", {
@@ -1016,7 +1084,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',
@@ -1430,9 +1503,13 @@ function _object_without_properties_loose(source, excluded) {
                     })
                 ]
             }),
-            jsx(RadixRadioGroup.Root, {
-                name: name,
-                value: resolvedValue,
+            jsx(RadixRadioGroup.Root, _extends({
+                name: name
+            }, isFormMode || explicitValue !== undefined ? {
+                value: resolvedValue
+            } : {
+                defaultValue: defaultValue != null ? defaultValue : undefined
+            }, {
                 onValueChange: handleValueChange,
                 onBlur: handleBlur,
                 disabled: groupEffectiveDisabled,
@@ -1463,7 +1540,7 @@ function _object_without_properties_loose(source, excluded) {
                         ]
                     }, option.value);
                 })
-            }),
+            })),
             resolvedHelperText && jsx("p", {
                 id: helperId,
                 className: cn(resolvedError ? v.errorText() : v.helperText(), resolvedError ? slotProps == null ? void 0 : (_slotProps_errorText = slotProps.errorText) == null ? void 0 : _slotProps_errorText.className : slotProps == null ? void 0 : (_slotProps_helperText = slotProps.helperText) == null ? void 0 : _slotProps_helperText.className),
@@ -1905,6 +1982,18 @@ function _object_without_properties_loose(source, excluded) {
     useDashFieldMeta(name);
     const accessState = useAccessState(access);
     const inputId = useId();
+    /*
+     * Local state for the STANDALONE UNCONTROLLED case (no bridge, no
+     * `value` prop, only `defaultValue`). Mirrors OTPField. Without this,
+     * `resolvedDisplayValue` would be a snapshot computed ONCE from
+     * `defaultValue` and the controlled `<input value={...}>` would
+     * snap user input back on every keystroke / stepper click — same
+     * trap that hit Checkbox + RadioGroup in this package.
+     *
+     * In form mode the bridge owns state. In standalone CONTROLLED mode
+     * (consumer passes `value`) the consumer owns state. Only this
+     * branch needs the local hook.
+     */ const [uncontrolledValue, setUncontrolledValue] = useState(()=>formatForDisplay(defaultValue));
     const helperId = `${inputId}-help`;
     // StrictMode-safe unregister-on-unmount
     const unregisterRef = useRef({
@@ -1942,7 +2031,7 @@ function _object_without_properties_loose(source, excluded) {
         resolvedHelperText = validation.helperText;
         resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : formatForDisplay(bridge.getValue(name));
     } else {
-        resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : formatForDisplay(defaultValue);
+        resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : uncontrolledValue;
     }
     const writeToBridge = (parsed)=>{
         if (!isFormMode || !bridge) return;
@@ -1957,6 +2046,13 @@ function _object_without_properties_loose(source, excluded) {
             // internal logic still sees the raw string change.
             void registration.onChange(e);
         }
+        // Standalone uncontrolled mode: mirror the raw input string so the
+        // controlled `<input value={...}>` reflects what the user typed.
+        // Partial states (e.g. "-", "1.") are kept verbatim — `parseFromInput`
+        // returns `undefined` for them so `writeToBridge` is a no-op above.
+        if (!isFormMode && userValue === undefined) {
+            setUncontrolledValue(e.target.value);
+        }
         userOnChange == null ? void 0 : userOnChange(e);
     };
     const handleBlur = (e)=>{
@@ -1972,6 +2068,11 @@ function _object_without_properties_loose(source, excluded) {
         if (typeof min === 'number') next = Math.max(min, next);
         if (typeof max === 'number') next = Math.min(max, next);
         writeToBridge(next);
+        // Standalone uncontrolled: also persist the new value to local
+        // state so the visible display tracks the stepper click.
+        if (!isFormMode && userValue === undefined) {
+            setUncontrolledValue(formatForDisplay(next));
+        }
     };
     const canIncrement = !effectiveDisabled && (typeof max !== 'number' || ((_parseFromInput = parseFromInput(resolvedDisplayValue)) != null ? _parseFromInput : -Infinity) < max);
     const canDecrement = !effectiveDisabled && (typeof min !== 'number' || ((_parseFromInput1 = parseFromInput(resolvedDisplayValue)) != null ? _parseFromInput1 : Infinity) > min);
@@ -2378,7 +2479,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',
@@ -2471,6 +2578,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:
  *
@@ -2777,7 +2930,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);
@@ -2807,6 +2968,8 @@ const defaultGetOptionDisabled = (option)=>Boolean(option.disabled);
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [
         options,
+        asyncOptions,
+        loadOptions,
         isFormMode,
         bridge,
         name,
@@ -3153,7 +3316,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);
@@ -3197,7 +3360,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",
@@ -3209,7 +3372,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,
@@ -3607,7 +3770,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',
@@ -3801,7 +3969,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',
@@ -3815,7 +3986,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',
@@ -4223,14 +4402,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'
         ]
     },
@@ -4247,6 +4432,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.
  *
@@ -4275,6 +4482,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;
@@ -4304,6 +4525,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: [
@@ -4321,8 +4616,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", {
@@ -4627,8 +4929,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',
@@ -6514,6 +6818,6 @@ VisuallyHidden.displayName = 'VisuallyHidden';
  */ // ───── Components ─────
 /**
  * Package version (synced with `package.json` at publish time).
- */ const VERSION = '0.1.0-beta';
+ */ const VERSION = '0.3.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 };

package/dist/src/components/AppShell/AppShell.d.ts

@@ -27,6 +27,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 declare function AppShell(props: AppShellProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=AppShell.d.ts.map

package/dist/src/components/AppShell/AppShell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../../../src/components/AppShell/AppShell.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,2CA+E5C"}
+{"version":3,"file":"AppShell.d.ts","sourceRoot":"","sources":["../../../../src/components/AppShell/AppShell.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AA0BzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,2CAsK5C"}

package/dist/src/components/AppShell/appShell.variants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appShell.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/AppShell/appShell.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CA8B3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC"}
+{"version":3,"file":"appShell.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/AppShell/appShell.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2CAoC3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,YAAY,CAAC,OAAO,gBAAgB,CAAC,CAAC"}