@dashforge/tw 1.7.0 → 2.0.0

package/dist/index.esm.js

@@ -373,7 +373,13 @@ Spinner.displayName = 'Spinner';
             secondary: '',
             success: '',
             warning: '',
-            danger: ''
+            danger: '',
+            /**
+             * For a surface that is dark regardless of the theme: a dark hero,
+             * an ink footer, an inverted panel. Reads the theme-invariant
+             * `inverse` token role, so it does NOT flip with light/dark the way
+             * a `neutral`-based treatment would. See kensaadi/dashforge#140.
+             */ inverse: ''
         },
         size: {
             sm: 'h-8 px-3 text-sm',
@@ -385,6 +391,18 @@ Spinner.displayName = 'Spinner';
         },
         loading: {
             true: 'cursor-wait'
+        },
+        /**
+         * Toggle state. Styling lives in `compoundVariants` because "on" reads
+         * differently on a filled button than on a quiet one: the quiet
+         * variants gain a surface, `solid` deepens the one it already has.
+         *
+         * The treatment is not invented. It is LeftNav's `itemActive`
+         * (`bg-*-100 text-*-900 font-medium`), the catalog's existing way of
+         * saying "this is the current thing". kensaadi/dashforge#63 gap C.
+         */ pressed: {
+            true: '',
+            false: ''
         }
     },
     compoundVariants: [
@@ -491,6 +509,136 @@ Spinner.displayName = 'Spinner';
             variant: 'link',
             color: 'danger',
             class: 'text-danger-700 hover:text-danger-800'
+        },
+        // ───── × inverse ─────
+        //
+        // `focus-visible:ring-offset-transparent` on every row is load-bearing.
+        // The base sets `focus-visible:ring-offset-2`, and neither the preset
+        // nor the base declares a ring-offset COLOUR, so it falls through to
+        // Tailwind v4's default of `#fff`. On a dark surface that paints a
+        // white halo around the button the moment it takes keyboard focus.
+        {
+            variant: 'solid',
+            color: 'inverse',
+            class: 'bg-inverse-50 text-inverse-900 hover:bg-inverse-200 active:bg-inverse-300 ' + 'focus-visible:ring-inverse-50 focus-visible:ring-offset-transparent'
+        },
+        {
+            variant: 'outline',
+            color: 'inverse',
+            class: 'border-inverse-50/40 text-inverse-50 hover:bg-inverse-50/10 ' + 'focus-visible:ring-inverse-50 focus-visible:ring-offset-transparent'
+        },
+        {
+            variant: 'ghost',
+            color: 'inverse',
+            class: 'text-inverse-50 hover:bg-inverse-50/10 ' + 'focus-visible:ring-inverse-50 focus-visible:ring-offset-transparent'
+        },
+        {
+            variant: 'link',
+            color: 'inverse',
+            class: 'text-inverse-50 hover:text-inverse-200'
+        },
+        // ───── pressed × color, on the quiet variants ─────
+        //
+        // `outline` and `ghost` have no surface of their own, so an "on" toggle
+        // gains one. Shape borrowed from LeftNav's `itemActive` rather than
+        // invented, so a pressed Button and an active nav row read the same.
+        {
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'primary',
+            class: 'bg-primary-100 text-primary-900 font-medium hover:bg-primary-200'
+        },
+        {
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'secondary',
+            class: 'bg-secondary-100 text-secondary-900 font-medium hover:bg-secondary-200'
+        },
+        {
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'success',
+            class: 'bg-success-100 text-success-900 font-medium hover:bg-success-200'
+        },
+        {
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'warning',
+            class: 'bg-warning-100 text-warning-900 font-medium hover:bg-warning-200'
+        },
+        {
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'danger',
+            class: 'bg-danger-100 text-danger-900 font-medium hover:bg-danger-200'
+        },
+        {
+            // `inverse` keeps its own idiom: a wash over the dark surface rather
+            // than a tint from a scale that does not follow the theme. The hover
+            // rows above use `/10`, so "on" sits one step up at `/20`.
+            variant: [
+                'outline',
+                'ghost'
+            ],
+            pressed: true,
+            color: 'inverse',
+            class: 'bg-inverse-50/20 text-inverse-50 font-medium hover:bg-inverse-50/25 ' + 'focus-visible:ring-offset-transparent'
+        },
+        // ───── pressed × color, on solid ─────
+        //
+        // Already filled, so "on" deepens instead of tinting: it reuses each
+        // row's own `active:` tier, the shade that already means "being pressed
+        // right now".
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'primary',
+            class: 'bg-primary-700 hover:bg-primary-800'
+        },
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'secondary',
+            class: 'bg-secondary-700 hover:bg-secondary-800'
+        },
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'success',
+            class: 'bg-success-700 hover:bg-success-800'
+        },
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'warning',
+            class: 'bg-warning-700 hover:bg-warning-800'
+        },
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'danger',
+            class: 'bg-danger-700 hover:bg-danger-800'
+        },
+        {
+            variant: 'solid',
+            pressed: true,
+            color: 'inverse',
+            class: 'bg-inverse-300 hover:bg-inverse-400'
         }
     ],
     defaultVariants: {
@@ -563,7 +711,7 @@ Spinner.displayName = 'Spinner';
     // omit a field, TV picks its `defaultVariants` value (step 1).
     const themeDefaults = useComponentDefaults('Button');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
-    const { access, visibleWhen, disabled, variant, color, size, fullWidth, loading, asChild, sx, children } = merged, rest = _object_without_properties_loose(merged, [
+    const { access, visibleWhen, disabled, variant, color, size, fullWidth, loading, pressed, asChild, sx, children } = merged, rest = _object_without_properties_loose(merged, [
         "access",
         "visibleWhen",
         "disabled",
@@ -572,6 +720,7 @@ Spinner.displayName = 'Spinner';
         "size",
         "fullWidth",
         "loading",
+        "pressed",
         "asChild",
         "sx",
         "children"
@@ -596,7 +745,8 @@ Spinner.displayName = 'Spinner';
         color,
         size,
         fullWidth,
-        loading
+        loading,
+        pressed
     }), sx);
     /*
      * `aria-busy` announces the loading state to assistive tech.
@@ -614,6 +764,7 @@ Spinner.displayName = 'Spinner';
             "data-disabled": effectiveDisabled || undefined,
             "aria-disabled": effectiveDisabled || undefined,
             "aria-busy": ariaBusy,
+            "aria-pressed": pressed,
             children: children
         });
     }
@@ -622,6 +773,7 @@ Spinner.displayName = 'Spinner';
         type: (_rest_type = rest.type) != null ? _rest_type : 'button',
         disabled: effectiveDisabled,
         "aria-busy": ariaBusy,
+        "aria-pressed": pressed,
         className: classes
     }, rest, {
         children: [
@@ -859,7 +1011,6 @@ const tooltipVariants = tv({
         if (onChange !== undefined) return;
         hasWarnedRef.current = true;
         const nameSegment = typeof name === 'string' && name.length > 0 ? ` name="${name}"` : '';
-        // eslint-disable-next-line no-console -- dev-only guard, guarded by NODE_ENV above.
         console.warn(`[@dashforge/tw] <${componentName}${nameSegment}> is not inside a ` + `DashFormProvider and no value/onChange were provided. Did you ` + `forget the provider, or intend controlled mode? The widget will ` + `render but never emit changes upward. See the "Controlled vs ` + `bridge mode" docs.`);
     // The check runs once on mount; the ref guards re-runs even if React
     // Strict Mode double-invokes the effect in development.
@@ -870,23 +1021,33 @@ const tooltipVariants = tv({
 /**
  * Compute `error` + `helperText` for a bridge-managed field.
  *
- * **Renderer-agnostic** — copy of the MUI-side
- * `textField.validation.ts`. Promoted to a `_shared/` directory inside
- * `@dashforge/tw` so all form components (TextField + Checkbox +
- * Switch) reuse the same precedence logic without depending on a
+ * **Renderer-agnostic.** Mirrors the MUI-side
+ * `ui/src/components/TextField/textField.validation.ts`. Promoted to a
+ * `_shared/` directory inside `@dashforge/tw` so all 14 bridge-managed
+ * form components reuse the same precedence without depending on a
  * specific component folder.
  *
- * Precedence rules (matches MUI side byte-for-byte):
- *
- *  1. **Explicit props win.** If the user passed `error` / `helperText`
- *     explicitly, those values are used as-is.
- *  2. **Auto values are gated by interaction.** The bridge's error is
+ * ⚠️ This file is a COPY, not an import. The two sides have to be kept
+ * in step by hand, and once already were not: BUG 17 (2026-09-15)
+ * inverted the `helperText` precedence on the MUI side only, and this
+ * copy kept the broken order for ten days until BUG 32 caught it. The
+ * verification that missed it was a grep for imports of the MUI file,
+ * which by construction cannot reach a copy. **When you change the
+ * precedence here, change it there too — and vice versa.**
+ *
+ * Precedence rules:
+ *
+ *  1. **`error`: the explicit prop wins.** An author who passes `error`
+ *     is forcing the visual state, so it overrides the auto-gate.
+ *  2. **`helperText`: the validation message wins while it is showing;
+ *     the explicit prop is the fallback for the no-error state.** A
+ *     constant hint ("Unique, uppercase") must not swallow the reason a
+ *     required field was rejected — that leaves the user looking at a
+ *     red field with no explanation. See README-BUG.md § BUG 17 / § BUG 32.
+ *  3. **Auto values are gated by interaction.** The bridge's error is
  *     surfaced only when the field is `touched` OR the form has been
  *     submitted at least once (`submitCount > 0`). This prevents the
  *     "error spam while typing" anti-pattern.
- *  3. **`error === false` explicitly clears the bridge's error message
- *     text.** Useful for forcing a "valid" visual state regardless of
- *     bridge state.
  *
  * @param name         field name registered with the bridge
  * @param bridge       active `DashFormBridge` (guaranteed non-null at
@@ -899,8 +1060,16 @@ const tooltipVariants = tv({
     const autoTouched = (_bridge_isTouched = bridge.isTouched(name)) != null ? _bridge_isTouched : false;
     const submitCount = (_bridge_submitCount = bridge.submitCount) != null ? _bridge_submitCount : 0;
     const allowAutoError = autoTouched || submitCount > 0;
+    // `error` still lets an explicit prop force the visual state.
     const error = explicitError != null ? explicitError : Boolean(autoErr) && allowAutoError;
-    const helperText = explicitHelperText != null ? explicitHelperText : allowAutoError ? autoErr == null ? void 0 : autoErr.message : undefined;
+    // BUG 32: the validation message wins over the explicit hint while it
+    // is showing. The previous order (`explicitHelperText ?? autoMessage`)
+    // short-circuited on the hint, so any field carrying one painted the
+    // danger state and `aria-invalid="true"` while still rendering the
+    // hint text — a red field with no stated reason. Identical inversion
+    // to the one BUG 17 landed on the MUI side.
+    const autoMessage = allowAutoError ? autoErr == null ? void 0 : autoErr.message : undefined;
+    const helperText = autoMessage != null ? autoMessage : explicitHelperText;
     return {
         error,
         helperText
@@ -1242,11 +1411,25 @@ const tooltipVariants = tv({
  *   - `error` : bool — swaps borders + helper-text color to danger tones
  */ const checkboxVariants = tv({
     slots: {
-        root: 'inline-flex items-start gap-2',
+        /*
+         * `relative` is load-bearing, not cosmetic. Radix renders a hidden
+         * native input for form participation with inline
+         * `position: absolute; opacity: 0; transform: translateX(-100%)`.
+         * Without a positioned ancestor it anchors to the BODY, so it escapes
+         * any `overflow: hidden` ancestor and extends the document's
+         * scrollable area down to wherever the field happens to sit.
+         *
+         * Measured on `learn/dash` with a checkbox ~1870px down the page:
+         * `document.documentElement.scrollHeight` 1891 against a 768px
+         * viewport, and the window scrolled 800px inside an AppShell that had
+         * just been given `h-dvh overflow-hidden`. Adding this one declaration
+         * dropped scrollHeight to 768 and the window scroll to 0.
+         * See README-BUG § BUG 36.
+         */ root: 'relative inline-flex items-start gap-2',
         control: [
             'inline-flex items-center justify-center shrink-0',
             // bg-neutral-50 inverts — dark-mode aware via the dashforge preset.
-            'rounded border bg-neutral-50',
+            'rounded-sm border bg-neutral-50',
             'border-neutral-300',
             'transition-colors',
             // Radix.Checkbox.Root renders a `<button>`, whose UA cursor is
@@ -1595,7 +1778,21 @@ const tooltipVariants = tv({
  *   - `helperText` / `errorText` — informational lines below
  */ const switchVariants = tv({
     slots: {
-        root: 'inline-flex items-start gap-3',
+        /*
+         * `relative` is load-bearing, not cosmetic. Radix renders a hidden
+         * native input for form participation with inline
+         * `position: absolute; opacity: 0; transform: translateX(-100%)`.
+         * Without a positioned ancestor it anchors to the BODY, so it escapes
+         * any `overflow: hidden` ancestor and extends the document's
+         * scrollable area down to wherever the field happens to sit.
+         *
+         * Measured on `learn/dash` with a checkbox ~1870px down the page:
+         * `document.documentElement.scrollHeight` 1891 against a 768px
+         * viewport, and the window scrolled 800px inside an AppShell that had
+         * just been given `h-dvh overflow-hidden`. Adding this one declaration
+         * dropped scrollHeight to 768 and the window scroll to 0.
+         * See README-BUG § BUG 36.
+         */ root: 'relative inline-flex items-start gap-3',
         control: [
             'relative inline-flex shrink-0 cursor-pointer items-center',
             'rounded-full border-2 border-transparent',
@@ -1864,7 +2061,21 @@ const tooltipVariants = tv({
  *   - `error`  : bool — swaps borders + helperText color to danger tones
  */ const radioGroupVariants = tv({
     slots: {
-        root: 'flex flex-col gap-1.5',
+        /*
+         * `relative` is load-bearing, not cosmetic. Radix renders a hidden
+         * native input for form participation with inline
+         * `position: absolute; opacity: 0; transform: translateX(-100%)`.
+         * Without a positioned ancestor it anchors to the BODY, so it escapes
+         * any `overflow: hidden` ancestor and extends the document's
+         * scrollable area down to wherever the field happens to sit.
+         *
+         * Measured on `learn/dash` with a checkbox ~1870px down the page:
+         * `document.documentElement.scrollHeight` 1891 against a 768px
+         * viewport, and the window scrolled 800px inside an AppShell that had
+         * just been given `h-dvh overflow-hidden`. Adding this one declaration
+         * dropped scrollHeight to 768 and the window scroll to 0.
+         * See README-BUG § BUG 36.
+         */ root: 'relative flex flex-col gap-1.5',
         label: 'block text-sm font-medium text-neutral-900',
         requiredMark: 'text-danger-500 ml-0.5',
         optionList: 'flex gap-3',
@@ -4276,7 +4487,7 @@ function Autocomplete(props) {
     slots: {
         root: 'inline-flex w-fit flex-col gap-2 rounded-lg border border-neutral-200 bg-neutral-50 p-3 select-none',
         header: 'flex items-center justify-between gap-1',
-        navButton: 'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[1rem] text-neutral-600 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 disabled:pointer-events-none disabled:opacity-40',
+        navButton: 'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-base text-neutral-600 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 disabled:pointer-events-none disabled:opacity-40',
         monthLabel: 'flex-1 text-center text-sm font-semibold text-neutral-900',
         grid: 'flex flex-col gap-1 focus:outline-none',
         weekdayRow: 'grid grid-cols-7 gap-1',
@@ -4301,7 +4512,26 @@ function Autocomplete(props) {
     base: 'flex h-9 w-9 items-center justify-center rounded-md text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500',
     variants: {
         siblingMonth: {
-            true: 'text-neutral-400'
+            /*
+             * `neutral-600`, not `neutral-400`, and not `neutral-500` either.
+             *
+             * A sibling-month cell is ACTIVE: it is selectable, so its label is
+             * subject to WCAG 1.4.3, and at 14px / weight 400 the threshold is
+             * 4.5:1. Measured on the running app, `neutral-400` gave **2.42:1**
+             * in light and **2.53:1** in dark. Both fail. (The disabled cells sit
+             * at 1.23:1 and are fine: WCAG exempts the text of inactive
+             * components.)
+             *
+             * `neutral-500` is the pivot of the scale — it stays rgb(115,115,115)
+             * in both themes — so it clears light at 4.54:1 but **fails dark at
+             * 4.18:1**. `neutral-600` is the first tier that passes both:
+             * 7.49:1 light, 7.85:1 dark, while still reading clearly muted
+             * against the current month's 17:1.
+             *
+             * See README-BUG § BUG 31. Do not soften this without re-measuring
+             * BOTH themes: the neutral scale inverts, so one number proves
+             * nothing.
+             */ true: 'text-neutral-600'
         },
         today: {
             true: 'font-bold ring-1 ring-inset ring-primary-400'
@@ -4377,7 +4607,7 @@ function ChevronRightIcon$2() {
     const themeDefaults = useComponentDefaults('Calendar');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
-    const { value, defaultValue, onChange, month, year, defaultMonth, defaultYear, onMonthChange, minDate, maxDate, disabledDates, isDateDisabled, weekStartDay, locale, today, disabled = false, autoFocus = false, sx, slotProps, testId, 'aria-label': ariaLabel = 'Calendar' } = merged;
+    const { value, defaultValue, onChange, month, year, defaultMonth, defaultYear, onMonthChange, minDate, maxDate, disabledDates, isDateDisabled, weekStartDay, locale, today, disabled = false, showSiblingDays = true, autoFocus = false, sx, slotProps, testId, 'aria-label': ariaLabel = 'Calendar' } = merged;
     const isValueControlled = value !== undefined;
     const [internalValue, setInternalValue] = useState(defaultValue != null ? defaultValue : null);
     const selectedValue = isValueControlled ? value : internalValue;
@@ -4450,6 +4680,14 @@ function ChevronRightIcon$2() {
         calendar
     ]);
     const resolvedLocale = locale != null ? locale : 'en-US';
+    /**
+     * `slotProps.day` may be a flat object or a function of the cell state.
+     * Resolving it here keeps the call site in the grid readable and means
+     * the theme-level and instance-level slots go through the same path.
+     */ const resolveDaySlot = (slot, state)=>{
+        var _this;
+        return (_this = typeof slot === 'function' ? slot(state) : slot) == null ? void 0 : _this.className;
+    };
     const v = calendarVariants({
         disabled
     });
@@ -4506,8 +4744,26 @@ function ChevronRightIcon$2() {
                             role: "row",
                             className: v.weekRow(),
                             children: week.days.map((day)=>{
-                                var _themeSlotProps_day, _slotProps_day;
                                 const isActiveCell = day.iso === calendar.focusedDate;
+                                // `showSiblingDays={false}` keeps the 7-column geometry with
+                                // an empty cell rather than dropping the element, so the grid
+                                // does not reflow and the row stays a row.
+                                if (day.isSiblingMonth && !showSiblingDays) {
+                                    return jsx("span", {
+                                        role: "gridcell",
+                                        "aria-hidden": "true",
+                                        className: "flex",
+                                        children: jsx("span", {
+                                            className: "h-9 w-9"
+                                        })
+                                    }, day.iso);
+                                }
+                                const dayState = {
+                                    siblingMonth: day.isSiblingMonth,
+                                    today: day.isToday,
+                                    selected: day.isSelected,
+                                    disabled: day.isDisabled
+                                };
                                 return jsx("span", {
                                     role: "gridcell",
                                     className: "flex",
@@ -4527,12 +4783,7 @@ function ChevronRightIcon$2() {
                                         onClick: ()=>{
                                             calendar.selectDate(day.iso);
                                         },
-                                        className: cn(calendarDayVariants({
-                                            siblingMonth: day.isSiblingMonth,
-                                            today: day.isToday,
-                                            selected: day.isSelected,
-                                            disabled: day.isDisabled
-                                        }), themeSlotProps == null ? void 0 : (_themeSlotProps_day = themeSlotProps.day) == null ? void 0 : _themeSlotProps_day.className, slotProps == null ? void 0 : (_slotProps_day = slotProps.day) == null ? void 0 : _slotProps_day.className),
+                                        className: cn(calendarDayVariants(dayState), resolveDaySlot(themeSlotProps == null ? void 0 : themeSlotProps.day, dayState), resolveDaySlot(slotProps == null ? void 0 : slotProps.day, dayState)),
                                         children: day.day
                                     })
                                 }, day.iso);
@@ -4628,7 +4879,7 @@ const popoverVariants = tv({
         trigger: 'flex items-center gap-2 h-10 min-w-[12rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
         value: 'flex-1 truncate text-left',
         placeholder: 'flex-1 truncate text-left text-neutral-400',
-        icon: 'shrink-0 text-[1rem] text-neutral-500',
+        icon: 'shrink-0 text-base text-neutral-500',
         helperText: 'mt-1 text-sm text-neutral-600',
         errorText: 'mt-1 text-sm text-danger-600'
     },
@@ -4935,9 +5186,9 @@ function CalendarIcon$2() {
         trigger: 'flex items-center gap-2 h-10 min-w-[10rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
         value: 'flex-1 truncate text-left',
         placeholder: 'flex-1 truncate text-left text-neutral-400',
-        icon: 'shrink-0 text-[1rem] text-neutral-500',
+        icon: 'shrink-0 text-base text-neutral-500',
         list: 'flex max-h-64 min-w-[8rem] flex-col gap-0.5 overflow-y-auto p-1',
-        option: 'flex w-full cursor-pointer items-center rounded px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600 aria-disabled:cursor-default aria-disabled:text-neutral-300 aria-disabled:opacity-60 aria-disabled:hover:bg-transparent',
+        option: 'flex w-full cursor-pointer items-center rounded-md px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600 aria-disabled:cursor-default aria-disabled:text-neutral-300 aria-disabled:opacity-60 aria-disabled:hover:bg-transparent',
         helperText: 'mt-1 text-sm text-neutral-600',
         errorText: 'mt-1 text-sm text-danger-600'
     },
@@ -5231,10 +5482,10 @@ function ClockIcon() {
         trigger: 'flex items-center gap-2 h-10 min-w-[13rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
         value: 'flex-1 truncate text-left',
         placeholder: 'flex-1 truncate text-left text-neutral-400',
-        icon: 'shrink-0 text-[1rem] text-neutral-500',
+        icon: 'shrink-0 text-base text-neutral-500',
         panel: 'flex items-stretch',
         list: 'flex max-h-[19rem] min-w-[6.5rem] flex-col gap-0.5 overflow-y-auto border-l border-neutral-200 p-1',
-        option: 'flex w-full cursor-pointer items-center rounded px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600',
+        option: 'flex w-full cursor-pointer items-center rounded-md px-2.5 py-1.5 text-sm text-neutral-900 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 aria-selected:bg-primary-600 aria-selected:text-white aria-selected:hover:bg-primary-600',
         helperText: 'mt-1 text-sm text-neutral-600',
         errorText: 'mt-1 text-sm text-danger-600'
     },
@@ -5581,11 +5832,11 @@ const DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})/;
         trigger: 'flex items-center gap-2 h-10 min-w-[15rem] rounded-md border border-neutral-300 bg-neutral-50 px-3 text-base text-neutral-900 cursor-pointer transition-colors hover:border-neutral-400 focus-visible:outline-none focus-visible:border-primary-500 focus-visible:ring-2 focus-visible:ring-primary-500/30 disabled:cursor-not-allowed disabled:opacity-60 disabled:bg-neutral-200',
         value: 'flex-1 truncate text-left',
         placeholder: 'flex-1 truncate text-left text-neutral-400',
-        icon: 'shrink-0 text-[1rem] text-neutral-500',
+        icon: 'shrink-0 text-base text-neutral-500',
         panel: 'flex gap-3 p-3 select-none',
         month: 'flex flex-col gap-2',
         header: 'flex items-center justify-between gap-1',
-        navButton: 'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-[1rem] text-neutral-600 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+        navButton: 'inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-md text-base text-neutral-600 transition-colors hover:bg-neutral-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
         navSpacer: 'h-7 w-7 shrink-0',
         monthLabel: 'flex-1 text-center text-sm font-semibold text-neutral-900',
         grid: 'flex flex-col gap-1',
@@ -6364,7 +6615,7 @@ function formatRange(range, locale) {
         itemLabel: 'truncate flex-1 min-w-0 text-left',
         itemBadge: [
             'shrink-0 inline-flex items-center justify-center',
-            'px-1.5 h-5 rounded-full text-[10px] font-medium',
+            'px-1.5 h-5 rounded-full text-2xs font-medium',
             'bg-neutral-200 text-neutral-800'
         ],
         group: 'flex flex-col gap-0.5',
@@ -6666,7 +6917,16 @@ function formatRange(range, locale) {
             'flex items-center gap-3 w-full px-4 shrink-0',
             'bg-neutral-50 border-b border-neutral-200'
         ],
-        start: 'flex items-center gap-2 min-w-0 shrink-0',
+        /*
+         * `shrink-0` removed (README-BUG § BUG 42): it sat next to `min-w-0`,
+         * which only has an effect on an item that is allowed to shrink, so the
+         * two contradicted each other and `shrink-0` won. The slot kept its
+         * content width whatever happened, which meant a long brand pushed
+         * `center` and `end` out of the bar instead of ellipsing.
+         *
+         * Only the already-broken case changes: where there is room, a
+         * shrinkable item and a non-shrinkable one lay out identically.
+         */ start: 'flex items-center gap-2 min-w-0',
         center: 'flex items-center gap-2 min-w-0 flex-1',
         end: 'flex items-center gap-2 shrink-0'
     },
@@ -6693,6 +6953,22 @@ function formatRange(range, locale) {
         sticky: true
     }
 });
+/**
+ * Recipe for `<TopBarBrand>`.
+ *
+ * `min-w-0` plus `truncate` on both lines is the load-bearing part: a bar
+ * is a fixed-height row, and a long subtitle (a file path, which is the
+ * case this exists for) would otherwise push the `center` and `end` slots
+ * out of the bar rather than ellipsing.
+ */ const topBarBrandVariants = tv({
+    slots: {
+        root: 'flex items-center gap-2 min-w-0',
+        logo: 'shrink-0 flex items-center',
+        text: 'flex flex-col justify-center min-w-0 leading-tight',
+        title: 'truncate text-sm font-semibold text-neutral-900',
+        subtitle: 'truncate text-xs text-neutral-500'
+    }
+});
 
 /**
  * Dashforge TW TopBar — sticky header with 3 named slots.
@@ -6752,22 +7028,70 @@ function formatRange(range, locale) {
         ]
     });
 }
+/**
+ * `<TopBarBrand>` — the mark-plus-text block for a `<TopBar>`'s `start`
+ * slot.
+ *
+ * ```tsx
+ * <TopBar
+ *   start={<TopBarBrand logo={<Logo />} title="Dashforge" subtitle="src/App.tsx" />}
+ *   end={<UserMenu />}
+ * />
+ * ```
+ *
+ * See {@link TopBarBrandProps} for why it is a sibling export rather than
+ * `TopBar.Brand`, and why it stays layout-only.
+ */ const TopBarBrand = /*#__PURE__*/ forwardRef(function TopBarBrand({ logo, title, subtitle, sx, slotProps }, ref) {
+    var _slotProps_root, _slotProps_logo, _slotProps_text, _slotProps_title, _slotProps_subtitle;
+    const v = topBarBrandVariants();
+    return jsxs("div", {
+        ref: ref,
+        className: cn(v.root(), slotProps == null ? void 0 : (_slotProps_root = slotProps.root) == null ? void 0 : _slotProps_root.className, sx),
+        children: [
+            logo != null && jsx("span", {
+                className: cn(v.logo(), slotProps == null ? void 0 : (_slotProps_logo = slotProps.logo) == null ? void 0 : _slotProps_logo.className),
+                children: logo
+            }),
+            jsxs("span", {
+                className: cn(v.text(), slotProps == null ? void 0 : (_slotProps_text = slotProps.text) == null ? void 0 : _slotProps_text.className),
+                children: [
+                    jsx("span", {
+                        className: cn(v.title(), slotProps == null ? void 0 : (_slotProps_title = slotProps.title) == null ? void 0 : _slotProps_title.className),
+                        children: title
+                    }),
+                    subtitle != null && jsx("span", {
+                        className: cn(v.subtitle(), slotProps == null ? void 0 : (_slotProps_subtitle = slotProps.subtitle) == null ? void 0 : _slotProps_subtitle.className),
+                        children: subtitle
+                    })
+                ]
+            })
+        ]
+    });
+});
+TopBarBrand.displayName = 'TopBarBrand';
 
 /**
  * Tailwind-variants recipe for `<AppShell>`.
  *
  * Slots:
- *   - `root`      — outer flex column (full viewport)
+ *   - `root`      — outer flex column
  *   - `header`    — top region
  *   - `body`      — flex row holding nav + main
  *   - `nav`       — desktop nav rail (md+)
  *   - `navMobile` — mobile drawer (slide-in)
- *   - `main`      — scrollable content area
+ *   - `main`      — content area
  *   - `footer`    — bottom region
  *   - `backdrop`  — semi-opaque overlay behind the mobile drawer
+ *
+ * Which element scrolls is decided by the `layout` axis, NOT by the
+ * slots. Before BUG 27 it was decided by neither: `root` carried
+ * `min-h-screen` while `main` carried `overflow-y-auto`, which describe
+ * two different layouts, and `min-h-screen` won. The root grew with the
+ * content, the window scrolled, and `main` never overflowed, so its
+ * `overflow-y-auto` was dead on every page long enough to need it.
  */ const appShellVariants = tv({
     slots: {
-        root: 'flex flex-col min-h-screen bg-neutral-100',
+        root: 'flex flex-col bg-neutral-100',
         header: 'shrink-0',
         body: 'flex flex-1 min-h-0',
         nav: 'hidden md:flex shrink-0',
@@ -6781,7 +7105,7 @@ function formatRange(range, locale) {
             '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',
+        main: 'flex-1 min-w-0',
         footer: 'shrink-0',
         backdrop: [
             'md:hidden fixed inset-0 z-30 bg-black/40',
@@ -6791,6 +7115,36 @@ function formatRange(range, locale) {
         ]
     },
     variants: {
+        /*
+         * Both shells are legitimate, so this is an axis rather than a
+         * decision baked into the slots. See README-BUG § BUG 27.
+         *
+         * `viewport` — the shell fills the window and `main` scrolls inside
+         *   it, so header, nav and footer stay put. This is the layout the
+         *   component's own header diagram draws and the one
+         *   `main: overflow-y-auto` was written for, so it is the default.
+         *
+         * `page` — the window scrolls and the whole shell moves with it,
+         *   which is what a marketing-style shell wants. `main` gets no
+         *   overflow here: it could never be the scroller in this mode, and
+         *   advertising one is how the two ended up contradicting.
+         */ layout: {
+            viewport: {
+                /*
+                 * `h-dvh`, never `h-screen`. `100vh` is the height the screen
+                 * has only while a phone's address bar is hidden, so `h-screen`
+                 * yields a shell taller than the window and the page scrolls
+                 * again, on exactly the devices where that is worst.
+                 */ root: 'h-dvh overflow-hidden',
+                // Fixed must not mean clipped: on a short screen the last nav
+                // items have to stay reachable.
+                nav: 'overflow-y-auto',
+                main: 'overflow-y-auto'
+            },
+            page: {
+                root: 'min-h-screen'
+            }
+        },
         navOpen: {
             true: {
                 navMobile: 'translate-x-0',
@@ -6799,6 +7153,7 @@ function formatRange(range, locale) {
         }
     },
     defaultVariants: {
+        layout: 'viewport',
         navOpen: false
     }
 });
@@ -6870,10 +7225,14 @@ function formatRange(range, locale) {
  */ function AppShell(props) {
     var _themeSlotProps_root, _slotProps_root, _themeSlotProps_header, _slotProps_header, _themeSlotProps_nav, _slotProps_nav, _themeSlotProps_navMobile, _slotProps_navMobile, _themeSlotProps_backdrop, _slotProps_backdrop, _themeSlotProps_main, _slotProps_main, _themeSlotProps_footer, _slotProps_footer;
     const themeDefaults = useComponentDefaults('AppShell');
-    const { header, nav, footer, children, navOpen = false, onNavOpenChange, sx, slotProps } = props;
+    // Instance props win over the theme, same precedence as every other
+    // component that supports `theme.components.<Name>.defaults`.
+    const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
+    const { header, nav, footer, children, layout = 'viewport', navOpen = false, onNavOpenChange, sx, slotProps } = merged;
     // Theme-level slotProps (Option C Track B).
     const themeSlotProps = themeDefaults == null ? void 0 : themeDefaults.slotProps;
     const v = appShellVariants({
+        layout,
         navOpen
     });
     // Lock body scroll while the mobile drawer is open.
@@ -7875,7 +8234,7 @@ const SnackbarContext = /*#__PURE__*/ createContext(null);
                 root: 'px-4 py-3'
             },
             compact: {
-                root: 'px-3 py-2 text-[13px]'
+                root: 'px-3 py-2 text-xs'
             }
         }
     },
@@ -8521,6 +8880,21 @@ Progress.displayName = 'Progress';
  *
  * Motion is gated by `prefers-reduced-motion`: slide animations collapse
  * to instantaneous appear/disappear for users who opt out.
+ */ /*
+ * Layering: the Drawer sits on the catalog's `z-50` overlay tier, like
+ * Dialog, Menu, Popover, Tooltip, Snackbar and the two comboboxes. It used
+ * to carry `z-[1400]` / `z-[1410]`, MUI's ladder, which is a different
+ * scale entirely — and authored alone it looked fine.
+ *
+ * What it broke, which only shows when two overlays meet: a Dialog raised
+ * from inside a Drawer rendered BEHIND it (50 against 1410), so the user
+ * got a drawer with an invisible modal holding their focus, and a Snackbar
+ * confirming an action taken in the drawer was invisible too.
+ *
+ * Overlay and content are both `z-50` on purpose, matching Dialog: within
+ * one component DOM order settles it (content renders after the overlay),
+ * and between components the one mounted later wins, which is what
+ * "opened on top" means.
  */ const drawerVariants = tv({
     slots: {
         overlay: [
@@ -8528,7 +8902,7 @@ Progress.displayName = 'Progress';
             // z-1300; Chakra AppShell uses ~1000). z-[1400] sits above them
             // without touching the reserved "topmost" (~9999) tier for host
             // error overlays / dev tools. Matches Chakra Drawer's own default.
-            'fixed inset-0 z-[1400] bg-neutral-950/60 backdrop-blur-sm',
+            'fixed inset-0 z-50 bg-neutral-950/60 backdrop-blur-sm',
             // Fade the backdrop in/out via a pure CSS keyframe (defined in
             // Drawer.tsx's module-level style injection).
             'data-[state=open]:animate-[df-drawer-fade-in_300ms_ease-out]',
@@ -8538,7 +8912,7 @@ Progress.displayName = 'Progress';
         content: [
             // Same z-tier as the overlay (see note above) plus 10 so the
             // drawer panel stacks above its own backdrop reliably.
-            'fixed z-[1410] flex flex-col',
+            'fixed z-50 flex flex-col',
             // bg-white hardcoded (doesn't auto-invert) so `dark:` is needed.
             // Same pattern as Dialog for cross-primitive consistency.
             'bg-white dark:bg-neutral-100 shadow-xl',
@@ -8570,7 +8944,11 @@ Progress.displayName = 'Progress';
             // mode without a `dark:` variant.
             'rounded-md border border-neutral-200',
             'text-neutral-500 hover:text-neutral-900 hover:bg-neutral-100 hover:border-neutral-300',
-            'focus:outline-none focus:ring-2 focus:ring-primary-500 focus:ring-offset-1',
+            // `focus-visible:`, not `focus:` — see BUG 28. Radix focuses the
+            // panel on open and this is its first focusable child, so a plain
+            // `focus:ring` framed the × on every mouse-opened drawer. The
+            // `resizeHandle` slot below already had it right.
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-1',
             'transition-colors motion-reduce:transition-none'
         ],
         body: 'flex-1 min-h-0 overflow-y-auto p-4',
@@ -8834,7 +9212,6 @@ injectDrawerKeyframes();
         if (hasWarnedRef.current) return;
         if (process.env.NODE_ENV === 'production') return;
         hasWarnedRef.current = true;
-        // eslint-disable-next-line no-console -- dev-only, guarded above.
         console.warn('[@dashforge/tw] <Drawer resize> was used without a `resizeKey`. ' + 'The resized dimension will not persist across sessions. Pass a ' + 'string identifier to `resizeKey` (e.g. `resizeKey="inspector"`) ' + 'to enable localStorage persistence.');
     }, [
         resize,
@@ -9150,7 +9527,7 @@ if (process.env.NODE_ENV !== 'production') {
             'group-data-[state=invalid]/step:text-danger-700'
         ],
         helperText: 'text-xs text-neutral-600 truncate',
-        optionalTag: 'text-[10px] italic text-neutral-500',
+        optionalTag: 'text-2xs italic text-neutral-500',
         connector: 'bg-neutral-200',
         content: 'w-full',
         footer: 'flex items-center justify-between mt-4'
@@ -9209,7 +9586,7 @@ if (process.env.NODE_ENV !== 'production') {
             sm: {
                 indicator: 'w-6 h-6 text-xs',
                 label: 'text-xs',
-                helperText: 'text-[10px]'
+                helperText: 'text-2xs'
             },
             md: {
                 indicator: 'w-7 h-7 text-sm',
@@ -9341,7 +9718,6 @@ if (process.env.NODE_ENV !== 'production') {
             }, `stepper-passthrough-${i}`));
         });
         if (sawStrayDom && process.env.NODE_ENV !== 'production') {
-            // eslint-disable-next-line no-console -- dev-only, guarded by NODE_ENV.
             console.warn('[@dashforge/tw] <Stepper> received bare DOM children (text or ' + 'intrinsic elements like <div>). Only <Step> configs and ' + 'component children (e.g. a footer reading useStep()) are ' + 'recognized; stray DOM was ignored.');
         }
         return {
@@ -9380,7 +9756,6 @@ if (process.env.NODE_ENV !== 'production') {
             return initialStep;
         }
         if (initialStep && process.env.NODE_ENV !== 'production') {
-            // eslint-disable-next-line no-console -- dev-only warning.
             console.warn(`[@dashforge/tw] <Stepper initialStep="${initialStep}"> did not ` + `match any visible step. Falling back to the first visible step.`);
         }
         return (_visibleStepNames_ = visibleStepNames[0]) != null ? _visibleStepNames_ : '';
@@ -9471,7 +9846,6 @@ if (process.env.NODE_ENV !== 'production') {
                     return false;
                 }
             } else if (process.env.NODE_ENV !== 'production') {
-                // eslint-disable-next-line no-console -- dev-only guard.
                 console.warn(`[@dashforge/tw] <Step name="${step.name}" fields={[...]}> was ` + `used outside a <DashForm> (or with a bridge that does not ` + `implement trigger). The fields validation is skipped.`);
             }
         }
@@ -9882,7 +10256,7 @@ Stepper.displayName = 'Stepper';
         ],
         valueLabel: [
             'absolute -translate-x-1/2 -translate-y-full',
-            'px-1.5 py-0.5 rounded text-xs font-medium text-neutral-50',
+            'px-1.5 py-0.5 rounded-md text-xs font-medium text-neutral-50',
             'pointer-events-none whitespace-nowrap',
             'shadow-sm',
             // background color applied via variant below
@@ -9931,7 +10305,7 @@ Stepper.displayName = 'Stepper';
                 track: 'h-1',
                 thumb: 'w-3.5 h-3.5',
                 mark: 'w-0.5 h-0.5',
-                valueLabel: 'text-[10px] px-1'
+                valueLabel: 'text-2xs px-1'
             },
             md: {
                 controlWrapper: 'py-2 h-8',
@@ -10280,6 +10654,7 @@ const DEFAULT_STEP = 1;
         return v <= displayValueArr[0];
     };
     return jsxs("div", {
+        ref: ref,
         className: rootClasses,
         "data-testid": testId,
         children: [
@@ -10600,7 +10975,8 @@ Slider.displayName = 'Slider';
  *
  * `V` inference — TypeScript narrows the union from the `options`
  * array so `onChange` gets the precise literal type.
- */ function SelectInner(props, ref) {
+ */ function SelectInner(props, // The trigger is a `<div role="combobox">`, not a `<button>` — see BUG 23.
+ref) {
     var _ref;
     var _themeDefaults_defaults, _themeSlotProps_root, _slotProps_root, _themeSlotProps_label, _slotProps_label, _themeSlotProps_requiredMark, _slotProps_requiredMark, _themeSlotProps_trigger, _slotProps_trigger, _themeSlotProps_triggerText, _slotProps_triggerText, _themeSlotProps_triggerPlaceholder, _slotProps_triggerPlaceholder, _themeSlotProps_chevron, _slotProps_chevron, _themeSlotProps_popover, _slotProps_popover, _themeSlotProps_listBox, _slotProps_listBox, _themeSlotProps_emptyState, _slotProps_emptyState, _themeSlotProps_helperText, _slotProps_helperText, _themeSlotProps_errorText, _slotProps_errorText, _themeSlotProps_chipsList, _slotProps_chipsList, _themeSlotProps_chip, _slotProps_chip, _themeSlotProps_chipRemove, _slotProps_chipRemove, _triggerRef_current;
     const themeDefaults = useComponentDefaults('Select');
@@ -10617,6 +10993,7 @@ Slider.displayName = 'Slider';
     const controlId = useId();
     const listboxId = `${controlId}-listbox`;
     const helperId = `${controlId}-help`;
+    const labelId = `${controlId}-label`;
     const isFormMode = Boolean(bridge == null ? void 0 : bridge.register);
     useStandaloneFieldWarning('Select', name, isFormMode, userValue, onChange);
     // Mirror of useStandaloneFieldWarning: warn when running under a
@@ -10981,8 +11358,18 @@ Slider.displayName = 'Slider';
         "data-testid": testId,
         children: [
             label != null && jsx("label", {
+                id: labelId,
                 htmlFor: controlId,
                 className: labelClasses,
+                // `htmlFor` no longer associates anything: the trigger is a div,
+                // and `<label for>` only binds to a labelable element. It is kept
+                // because it is harmless and consumers may key CSS off it, but
+                // the real name comes from `aria-labelledby` on the trigger and
+                // the focus-on-click has to be done by hand. BUG 23.
+                onClick: ()=>{
+                    var _triggerRef_current;
+                    return (_triggerRef_current = triggerRef.current) == null ? void 0 : _triggerRef_current.focus();
+                },
                 children: renderLabelWithTooltip(label, tooltipConfig, required && jsx("span", {
                     className: requiredMarkClasses,
                     children: "*"
@@ -10994,24 +11381,27 @@ Slider.displayName = 'Slider';
                 children: [
                     jsx(RadixPopover.Trigger, {
                         asChild: true,
-                        children: jsxs("button", {
+                        children: jsxs("div", _extends({
                             ref: (node)=>{
                                 triggerRef.current = node;
                                 if (typeof ref === 'function') ref(node);
                                 else if (ref) ref.current = node;
                             },
-                            id: controlId,
-                            type: "button",
+                            id: controlId
+                        }, {
+                            type: undefined
+                        }, {
                             role: "combobox",
+                            tabIndex: effectiveDisabled ? -1 : 0,
                             "aria-haspopup": "listbox",
                             "aria-expanded": isOpen,
                             "aria-controls": listboxId,
+                            "aria-labelledby": label != null ? labelId : undefined,
                             "aria-required": required || undefined,
                             "aria-invalid": hasError || undefined,
                             "aria-describedby": resolvedHelperText != null ? helperId : undefined,
                             "aria-disabled": effectiveDisabled || undefined,
-                            disabled: effectiveDisabled,
-                            name: name,
+                            "data-name": name,
                             className: triggerClasses,
                             onKeyDown: handleTriggerKeyDown,
                             children: [
@@ -11020,7 +11410,7 @@ Slider.displayName = 'Slider';
                                     className: cn(chevronClasses)
                                 })
                             ]
-                        })
+                        }))
                     }),
                     jsx(RadixPopover.Portal, {
                         children: jsx(RadixPopover.Content, {
@@ -11147,7 +11537,7 @@ Select.displayName = 'Select';
         'inline-flex items-center gap-1',
         // Anchor semantics — cursor + focus-visible ring using primary token.
         'cursor-pointer',
-        'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2 focus-visible:rounded',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2 focus-visible:rounded-sm',
         // Motion-reduce safe transition on color / decoration.
         'transition-colors',
         'motion-reduce:transition-none'
@@ -11246,7 +11636,6 @@ Select.displayName = 'Select';
         // the Slot pattern paints classes onto a foreign child, and there is
         // no seam for us to inject start/end icon wrappers.
         if (process.env.NODE_ENV !== 'production' && (startIcon != null || endIcon != null)) {
-            // eslint-disable-next-line no-console -- dev-only nudge.
             console.warn('[@dashforge/tw] <Link asChild> ignores startIcon / endIcon — the ' + 'child element renders its own content. Move the icons inside the ' + 'child instead.');
         }
         return jsx(Slot, _extends({
@@ -11688,7 +12077,7 @@ MenuItem.displayName = 'MenuItem';
             // dimensions below.
             'inline-flex items-center justify-center',
             'rounded-full',
-            'text-[10px] font-medium leading-none',
+            'text-2xs font-medium leading-none',
             'pointer-events-none select-none',
             // Smooth show/hide for `invisible` toggle (consumer-side
             // animation hook). Gated on motion-reduce per WCAG 2.3.3.
@@ -11938,6 +12327,78 @@ MenuItem.displayName = 'MenuItem';
 });
 Badge.displayName = 'Badge';
 
+/**
+ * Tailwind-variants recipe for `<Kbd>`.
+ *
+ * One axis, `size`, because a keycap has no intent: it is chrome around a
+ * literal key, not a status or an action. Colour is fixed to the neutral
+ * ramp, which auto-inverts through the preset's CSS vars, so the cap reads
+ * as a raised surface in light and a recessed one in dark with no `dark:`
+ * variant to keep in sync.
+ *
+ * The border is what makes the cap read as a cap, and it is at `-500`
+ * rather than the `-300` a hairline invites. Measured on `learn/dash`
+ * against both surfaces a keycap realistically sits on:
+ *
+ *   surface neutral-100 ... 1.09 vs page, 1.04 vs card
+ *   surface neutral-200 ... 1.26 / 1.21
+ *   border  neutral-300 ... 1.48 / 1.42
+ *   border  neutral-400 ... 2.52 / 2.42
+ *   border  neutral-500 ... 4.74 / 4.54   <- the first that clears 3:1
+ *
+ * The first draft assumed the `bg-neutral-100` surface would do the
+ * separating and left the border at `-300`. It does not: a neutral surface
+ * one step off the page is ~1.1:1 by construction, and in dark mode it
+ * lands on exactly the same colour as a card, so the cap disappeared into
+ * the panel and only the hairline was left. That is the same shape that
+ * failed on the outline Chip (README-BUG § BUG 40), and it reached the
+ * same tier for the same reason.
+ *
+ * The surface stays as a faint lift, not as the separator.
+ *
+ * `rounded-md` rather than a bare `rounded`, which is hard-coded at
+ * 0.25rem and immune to the radius tokens (README-BUG § BUG 26).
+ */ const kbdVariants = tv({
+    base: [
+        'inline-flex items-center justify-center',
+        'font-mono font-medium leading-none whitespace-nowrap select-none',
+        'bg-neutral-100 text-neutral-700',
+        'border border-neutral-500 rounded-md shadow-sm'
+    ],
+    variants: {
+        size: {
+            sm: 'h-5 min-w-5 px-1 text-2xs',
+            md: 'h-6 min-w-6 px-1.5 text-xs',
+            lg: 'h-7 min-w-7 px-2 text-sm'
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});
+
+/**
+ * `<Kbd>` — a single keycap.
+ *
+ * ```tsx
+ * Press <Kbd>Esc</Kbd> to close
+ * ```
+ *
+ * See {@link KbdProps} for the full API surface, including why chords are
+ * composed rather than passed as an array.
+ */ const Kbd = /*#__PURE__*/ forwardRef(function Kbd(rawProps, ref) {
+    const themeDefaults = useComponentDefaults('Kbd');
+    const { size, sx, className, children } = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, rawProps);
+    return jsx("kbd", {
+        ref: ref,
+        className: cn(kbdVariants({
+            size
+        }), className, sx),
+        children: children
+    });
+});
+Kbd.displayName = 'Kbd';
+
 /**
  * Tailwind-variants recipe for `<Avatar>`.
  *
@@ -11972,7 +12433,7 @@ Badge.displayName = 'Badge';
     variants: {
         size: {
             xs: {
-                root: 'w-5 h-5 text-[10px]',
+                root: 'w-5 h-5 text-2xs',
                 initials: ''
             },
             sm: {
@@ -12412,7 +12873,7 @@ AvatarGroup.displayName = 'AvatarGroup';
     variants: {
         variant: {
             text: {
-                root: 'rounded h-[1em] w-full'
+                root: 'rounded-sm h-[1em] w-full'
             },
             rectangle: {
                 root: 'rounded-md w-full h-[100px]'
@@ -13118,6 +13579,18 @@ Video.displayName = 'Video';
             4: 'shadow-lg',
             5: 'shadow-xl'
         },
+        /*
+         * Border style. Only visible where a border-width is already set:
+         * `variant="outlined"` sets one, and a consumer can bring their own
+         * through `sx`. Declared as its own axis rather than folded into
+         * `variant` because the two are orthogonal — a dashed placeholder
+         * can be outlined, soft or solid. kensaadi/dashforge#63 gap I.
+         */ borderStyle: {
+            solid: 'border-solid',
+            dashed: 'border-dashed',
+            dotted: 'border-dotted',
+            double: 'border-double'
+        },
         rounded: {
             none: 'rounded-none',
             sm: 'rounded-sm',
@@ -13394,11 +13867,12 @@ Video.displayName = 'Video';
     // theme < instance; `sx` layers last via `cn()` + tailwind-merge.
     const themeDefaults = useComponentDefaults('Box');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
-    const { variant, color, elevation, rounded, p, px, py, m, mx, my, fullWidth, fullHeight, as, asChild = false, sx, visibleWhen, access, children } = merged, rest = _object_without_properties_loose(merged, [
+    const { variant, color, elevation, rounded, borderStyle, p, px, py, m, mx, my, fullWidth, fullHeight, as, asChild = false, sx, visibleWhen, access, children } = merged, rest = _object_without_properties_loose(merged, [
         "variant",
         "color",
         "elevation",
         "rounded",
+        "borderStyle",
         "p",
         "px",
         "py",
@@ -13436,6 +13910,7 @@ Video.displayName = 'Video';
         color,
         elevation,
         rounded,
+        borderStyle,
         p,
         px,
         py,
@@ -13726,7 +14201,18 @@ CardActionArea.displayName = 'CardActionArea';
          * (one step up the elevation ladder of its current variant).
          * Compound rules below apply the actual shift per (variant, color)
          * cell.
-         */ selected: {
+         */ /*
+         * Pointer affordance for a chip used as a drag source, e.g. a palette
+         * of items dragged onto a canvas. Native HTML5 drag-and-drop, so the
+         * library takes on no dnd dependency and the consumer keeps ownership
+         * of the transfer payload. kensaadi/dashforge#63 gap D.
+         *
+         * `active:cursor-grabbing` rather than a `:hover` swap: the closed
+         * hand belongs to the moment the pointer is down, not to hovering.
+         */ draggable: {
+            true: 'cursor-grab active:cursor-grabbing'
+        },
+        selected: {
             true: 'ring-2 ring-offset-1'
         },
         /** Disabled state for clickable chips. */ disabled: {
@@ -13820,7 +14306,7 @@ CardActionArea.displayName = 'CardActionArea';
         {
             variant: 'outline',
             color: 'neutral',
-            class: 'border border-neutral-300 text-neutral-700'
+            class: 'border border-neutral-500 text-neutral-700'
         },
         {
             variant: 'outline',
@@ -14154,7 +14640,7 @@ CardActionArea.displayName = 'CardActionArea';
  */ const Chip = /*#__PURE__*/ forwardRef(function Chip(props, ref) {
     const themeDefaults = useComponentDefaults('Chip');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
-    const { label, icon, avatar, variant, color, size, clickable: clickableProp, onClick, onDelete, deleteIcon, deleteLabel = 'Remove', selected, disabled: disabledProp, visibleWhen, access, sx, className } = merged;
+    const { label, icon, avatar, variant, color, size, clickable: clickableProp, onClick, onDelete, deleteIcon, deleteLabel = 'Remove', selected, disabled: disabledProp, draggable, onDragStart, onDragEnd, visibleWhen, access, sx, className } = merged;
     // Bridge — both hooks called unconditionally (rules-of-hooks).
     // Inside a `<DashForm>`, `useEngineVisibility` subscribes to engine
     // state and re-evaluates the predicate on changes; outside a form,
@@ -14173,7 +14659,8 @@ CardActionArea.displayName = 'CardActionArea';
         size,
         clickable: isClickable || undefined,
         selected: selected || undefined,
-        disabled: isDisabled || undefined
+        disabled: isDisabled || undefined,
+        draggable: draggable || undefined
     }), sx, className);
     // ─── Inner content — leading slot + label + delete ────────────
     // Avatar wins over icon when both provided (MUI parity).
@@ -14183,6 +14670,46 @@ CardActionArea.displayName = 'CardActionArea';
     // `inline-flex items-center` provides vertical alignment with
     // any leading / trailing slots.
     const leading = avatar != null ? avatar : icon;
+    const deleteClasses = cn('ml-0.5 -mr-1 inline-flex items-center justify-center', 'h-4 w-4 rounded-full opacity-70 hover:opacity-100', 'transition-opacity');
+    /*
+     * The delete affordance has TWO shapes, and which one is legal depends
+     * on what the root turned out to be. See README-BUG § BUG 35.
+     *
+     * Static root (`<span>`): a real `<button>`. A span is not a widget, so
+     * a focusable button inside it is valid HTML and is the only keyboard
+     * path to delete. Unchanged.
+     *
+     * Clickable root (`role="button"`): NOT a button, and not focusable.
+     * Both `<button>` and `role="button"` forbid interactive descendants —
+     * HTML by its content model, ARIA by the presentational-children rule,
+     * which strips the semantics of everything inside a `button` role. So a
+     * nested control is either invalid markup or invisible to AT, depending
+     * on which spelling you pick. The keyboard path moves to Backspace /
+     * Delete on the chip itself, which is what MUI does and what this
+     * component's own `onKeyDown` comment already anticipated.
+     */ const deleteNode = onDelete == null ? null : isClickable ? jsx("span", {
+        "data-chip-delete": "",
+        "aria-hidden": "true",
+        onClick: (e)=>{
+            // Stop propagation so the chip's own onClick doesn't fire when
+            // the user clicks the × — MUI matches this behaviour.
+            e.stopPropagation();
+            if (!isDisabled) onDelete(e);
+        },
+        className: cn(deleteClasses, !isDisabled && 'cursor-pointer'),
+        children: deleteIcon != null ? deleteIcon : jsx(DefaultDeleteIcon, {})
+    }) : jsx("button", {
+        "data-chip-delete": "",
+        type: "button",
+        "aria-label": deleteLabel,
+        onClick: (e)=>{
+            e.stopPropagation();
+            if (!isDisabled) onDelete(e);
+        },
+        disabled: isDisabled,
+        className: cn(deleteClasses, 'outline-none focus-visible:ring-2 focus-visible:ring-current'),
+        children: deleteIcon != null ? deleteIcon : jsx(DefaultDeleteIcon, {})
+    });
     const innerContent = jsxs(Fragment, {
         children: [
             leading != null && jsx("span", {
@@ -14190,45 +14717,70 @@ CardActionArea.displayName = 'CardActionArea';
                 children: leading
             }),
             label,
-            onDelete != null && jsx("button", {
-                type: "button",
-                "aria-label": deleteLabel,
-                onClick: (e)=>{
-                    // Stop propagation so the chip's own onClick doesn't fire
-                    // when the user clicks the × — MUI matches this behaviour.
-                    e.stopPropagation();
-                    if (!isDisabled) onDelete(e);
-                },
-                disabled: isDisabled,
-                className: cn('ml-0.5 -mr-1 inline-flex items-center justify-center', 'h-4 w-4 rounded-full opacity-70 hover:opacity-100', 'outline-none focus-visible:ring-2 focus-visible:ring-current', 'transition-opacity'),
-                children: deleteIcon != null ? deleteIcon : jsx(DefaultDeleteIcon, {})
-            })
+            deleteNode
         ]
     });
     // ─── Interactive root (clickable) ─────────────────────────────
+    /*
+     * A `<div role="button">`, not a `<button>`. With `onDelete` also set,
+     * the native element nested a `<button>` inside a `<button>`, which is
+     * invalid HTML: React reported a hydration error and the parser hoisted
+     * the inner control out. BUG 35.
+     *
+     * Everything the native element gave away is re-supplied below, because
+     * a div gives none of it: focusability, Enter / Space activation, and
+     * inertness while disabled.
+     */ // A disabled chip must not be a drag source either: `pointer-events-none`
+    // already blocks the pointer, but the attribute would still advertise it.
+    const dragProps = {
+        draggable: draggable && !isDisabled ? true : undefined,
+        onDragStart: draggable && !isDisabled ? onDragStart : undefined,
+        onDragEnd: draggable && !isDisabled ? onDragEnd : undefined
+    };
     if (isClickable) {
-        return jsx("button", {
+        return jsx("div", _extends({
             ref: ref,
-            type: "button",
-            className: classes,
-            disabled: isDisabled,
+            role: "button",
+            tabIndex: isDisabled ? -1 : 0,
+            className: classes
+        }, dragProps, {
+            "aria-disabled": isDisabled || undefined,
             "aria-pressed": selected ? true : undefined,
             onClick: (e)=>{
                 if (isDisabled) return;
                 onClick == null ? void 0 : onClick(e);
             },
             onKeyDown: (e)=>{
+                if (isDisabled) return;
+                // Ignore anything bubbling up from a child, so a focusable slot
+                // (an interactive avatar, say) keeps its own keys. Mirrors
+                // MUI's `event.currentTarget === event.target` guard.
+                if (e.currentTarget !== e.target) return;
+                // A div has no implicit activation. Space is prevented first so
+                // the page does not scroll under the chip.
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    onClick == null ? void 0 : onClick(e);
+                    return;
+                }
+                // The keyboard path to the delete affordance, which is not
+                // focusable in this branch. Same keys as MUI.
+                if (onDelete != null && (e.key === 'Backspace' || e.key === 'Delete')) {
+                    e.preventDefault();
+                    onDelete(e);
+                }
             },
             children: innerContent
-        });
+        }));
     }
     // ─── Static root (display only) ───────────────────────────────
-    return jsx("span", {
+    return jsx("span", _extends({
         ref: ref,
         className: classes,
-        "aria-disabled": isDisabled || undefined,
+        "aria-disabled": isDisabled || undefined
+    }, dragProps, {
         children: innerContent
-    });
+    }));
 });
 
 /**
@@ -14548,7 +15100,19 @@ Typography.displayName = 'Typography';
  * Runtime allow-list, for the dev-warn to check against a passed
  * `gap` value at render time. Same set as {@link StackGap}. Frozen
  * so callers can't mutate the source of truth.
- */ const STACK_GAP_VALUES = Object.freeze([
+ */ /**
+ * The accepted `direction` values, for the dev-time guard in `Stack.tsx`.
+ *
+ * Frozen and exported rather than inlined so the warning cannot drift from
+ * the variant recipe: adding an axis value without adding it here would
+ * make the guard warn about something that works.
+ */ const STACK_DIRECTION_VALUES = Object.freeze([
+    'row',
+    'col',
+    'row-reverse',
+    'col-reverse'
+]);
+const STACK_GAP_VALUES = Object.freeze([
     0,
     0.5,
     1,
@@ -14568,6 +15132,25 @@ Typography.displayName = 'Typography';
  * useStandaloneFieldWarning "warn once" ergonomic. `Set<unknown>` so
  * `null` / arbitrary strings share the same bucket as `NaN`.
  */ const warnedGapValues = new Set();
+/** Same "warn once per value" bucket, for `direction`. */ const warnedDirectionValues = new Set();
+/** Whether the `spacing`-instead-of-`gap` warning has already fired. */ let warnedSpacingAlias = false;
+/**
+ * Names people reach for instead of the ones this component uses, mapped to
+ * what they meant. kensaadi/dashforge#63 gap K reported the surprise;
+ * accepting both spellings was the alternative and was not taken, because a
+ * second name for one axis is a fork every consumer, every theme default
+ * and every doc example then has to pick a side of, forever.
+ *
+ * TypeScript already rejects these. The guard is for the consumers TS does
+ * not reach: JS callers, `{...anyProps}` spreads, values read from config.
+ * Left alone the value is simply dropped and the Stack renders its default
+ * axis, which is the silent failure the report described as "surprising".
+ */ const DIRECTION_ALIASES = {
+    column: 'col',
+    'column-reverse': 'col-reverse',
+    vertical: 'col',
+    horizontal: 'row'
+};
 /**
  * Walk the children, inserting `divider` BETWEEN every consecutive pair.
  *
@@ -14583,7 +15166,28 @@ Typography.displayName = 'Typography';
  *   • If `divider` is a valid element, we `cloneElement` once per
  *     boundary (cheaper than re-rendering the JSX expression N-1 times).
  *     For string/number dividers we wrap in a span automatically.
- */ function interleaveDividers(children, divider) {
+ */ /**
+ * The divider orientation that separates items along each axis. A row is
+ * separated by vertical rules and a column by horizontal ones, which is the
+ * opposite of what the names suggest and the reason this was worth deriving
+ * rather than leaving to the caller. kensaadi/dashforge#63 gap F.
+ */ const DIVIDER_ORIENTATION_FOR = {
+    row: 'vertical',
+    'row-reverse': 'vertical',
+    col: 'horizontal',
+    'col-reverse': 'horizontal'
+};
+/**
+ * True for our own `<Divider>`, read off `displayName` rather than by
+ * importing the component: Stack has no business depending on Divider, and
+ * the check has to fail safely for anything else. Injecting an
+ * `orientation` prop into a foreign element is how `tooltip` once landed on
+ * the DOM as an unknown attribute (README-BUG § BUG 9).
+ */ function isDashforgeDivider(node) {
+    var _node_type;
+    return ((_node_type = node.type) == null ? void 0 : _node_type.displayName) === 'Divider';
+}
+function interleaveDividers(children, divider, direction) {
     const items = Children.toArray(children);
     if (items.length <= 1) return items;
     const result = [];
@@ -14592,9 +15196,20 @@ Typography.displayName = 'Typography';
         if (i < items.length - 1) {
             const key = `df-stack-divider-${i}`;
             if (/*#__PURE__*/ isValidElement(divider)) {
-                result.push(/*#__PURE__*/ cloneElement(divider, {
+                var _DIVIDER_ORIENTATION_FOR_direction;
+                // A `<Divider>` defaults to `horizontal`, so dropping one into a
+                // row Stack gave a zero-height rule at `w-full`: it did not
+                // separate anything, it demanded the whole width and squeezed the
+                // items instead. The Stack knows its own axis, so it supplies the
+                // orientation the caller did not choose. An explicit `orientation`
+                // always wins, and a non-Divider node is passed through untouched.
+                const props = divider.props;
+                const shouldDerive = isDashforgeDivider(divider) && props.orientation === undefined;
+                result.push(/*#__PURE__*/ cloneElement(divider, _extends({
                     key
-                }));
+                }, shouldDerive ? {
+                    orientation: (_DIVIDER_ORIENTATION_FOR_direction = DIVIDER_ORIENTATION_FOR[direction]) != null ? _DIVIDER_ORIENTATION_FOR_direction : 'horizontal'
+                } : {})));
             } else {
                 result.push(jsx(Fragment$1, {
                     children: divider
@@ -14627,7 +15242,7 @@ Typography.displayName = 'Typography';
  */ const Stack = /*#__PURE__*/ forwardRef(function Stack(props, ref) {
     const themeDefaults = useComponentDefaults('Stack');
     const merged = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, props);
-    const { direction, align, justify, gap, wrap, fullWidth, fullHeight, divider, as, asChild = false, sx, children } = merged, rest = _object_without_properties_loose(merged, [
+    const { direction, align, justify, gap, wrap, fullWidth, fullHeight, divider, as, asChild = false, sx, visibleWhen, access, children } = merged, rest = _object_without_properties_loose(merged, [
         "direction",
         "align",
         "justify",
@@ -14639,6 +15254,8 @@ Typography.displayName = 'Typography';
         "as",
         "asChild",
         "sx",
+        "visibleWhen",
+        "access",
         "children"
     ]);
     // Dev-only guard for #111 (G-27): `<Stack gap>` is typed to the
@@ -14648,9 +15265,18 @@ Typography.displayName = 'Typography';
     // consumers get a real signal instead of silent `rowGap: normal`.
     if (process.env.NODE_ENV !== 'production' && gap !== undefined && !STACK_GAP_VALUES.includes(gap) && !warnedGapValues.has(gap)) {
         warnedGapValues.add(gap);
-        // eslint-disable-next-line no-console -- dev-only guard, guarded by NODE_ENV above.
         console.warn(`[@dashforge/tw] <Stack gap={${JSON.stringify(gap)}}> is not on the ` + `token-scale set (${STACK_GAP_VALUES.join(', ')}). The variant ` + `mapping silently falls back to no gap. Use a numeric literal ` + `from the accepted set — token strings like "sm" / "md" / "lg" ` + `are not supported.`);
     }
+    // Same shape of guard for `direction`, which fails the same silent way:
+    // an unrecognised value is dropped by the variant recipe and the Stack
+    // falls back to `defaultVariants.direction`, so a column Stack asked
+    // for as "column" quietly lays out as a column anyway and a "vertical"
+    // row does not. See kensaadi/dashforge#63 gap K.
+    if (process.env.NODE_ENV !== 'production' && direction !== undefined && !STACK_DIRECTION_VALUES.includes(direction) && !warnedDirectionValues.has(direction)) {
+        warnedDirectionValues.add(direction);
+        const meant = DIRECTION_ALIASES[String(direction)];
+        console.warn(`[@dashforge/tw] <Stack direction={${JSON.stringify(direction)}}> is ` + `not an accepted value (${STACK_DIRECTION_VALUES.join(', ')}). ` + `The variant mapping drops it and the Stack falls back to ` + `"${'col'}".` + (meant ? ` Did you mean "${meant}"?` : ''));
+    }
     // Runtime safety-net for #112 (G-28): the `StackProps` interface
     // Omit-excludes `className`, forcing typed consumers to use `sx`. But
     // TS-loose consumers (unchecked casts, `{...anyProps}` spreads) can
@@ -14661,9 +15287,40 @@ Typography.displayName = 'Typography';
     // Extract it, feed it through `cn` so tailwind-merge preserves the
     // non-conflicting utility (e.g. consumer's `min-h-0` + variant
     // `flex flex-col gap-3`), and drop it from the DOM spread.
-    const { className: consumerClassName } = rest, safeRest = _object_without_properties_loose(rest, [
-        "className"
+    // Bridge — hooks called unconditionally, ABOVE the early return
+    // (rules-of-hooks; see README-BUG § BUG 33 for what happens when a
+    // subscription is made conditional instead). `useEngineVisibility`
+    // re-evaluates the predicate reactively inside a `<DashForm>` and
+    // watches nothing when `visibleWhen` is omitted; `useAccessState`
+    // consults the @dashforge/rbac policy engine. Both are no-ops when
+    // their prop is absent, so a consumer passing neither renders
+    // exactly as before.
+    const bridge = useContext(DashFormContext);
+    const isVisible = useEngineVisibility(bridge == null ? void 0 : bridge.engine, visibleWhen);
+    const accessState = useAccessState(access);
+    // Early return — predicate false OR RBAC denies visibility.
+    if (!isVisible || !accessState.visible) return null;
+    const ariaProps = {
+        'aria-disabled': accessState.disabled || undefined,
+        'aria-readonly': accessState.readonly || undefined,
+        'data-disabled': accessState.disabled || undefined,
+        'data-readonly': accessState.readonly || undefined
+    };
+    const { className: consumerClassName, // `spacing` is MUI's name for this axis and the one consumers reach
+    // for first (kensaadi/dashforge#63 gap K). Pulled out of the spread
+    // rather than passed through: React 19 writes an unknown lowercase
+    // attribute to the DOM without a word, so `spacing={2}` would ship as
+    // `spacing="2"` on the element while doing nothing to the layout.
+    // That is BUG 9's failure mode, and the warning below is the signal
+    // the consumer would otherwise never get.
+    spacing: spacingAlias } = rest, safeRest = _object_without_properties_loose(rest, [
+        "className",
+        "spacing"
     ]);
+    if (process.env.NODE_ENV !== 'production' && spacingAlias !== undefined && !warnedSpacingAlias) {
+        warnedSpacingAlias = true;
+        console.warn(`[@dashforge/tw] <Stack spacing={${JSON.stringify(spacingAlias)}}> ` + `has no effect: this component calls the axis \`gap\`. The value ` + `is dropped rather than forwarded, so it does not reach the DOM ` + `either. Use gap={${JSON.stringify(spacingAlias)}}.`);
+    }
     const classes = cn(stackVariants({
         direction,
         align,
@@ -14680,22 +15337,24 @@ Typography.displayName = 'Typography';
         wrap,
         fullWidth,
         fullHeight
-    }), consumerClassName, sx);
+    }), // RBAC-denied surfaces dim and carry the ARIA attributes assigned
+    // below, so descendants and assistive tech can react.
+    accessState.disabled && 'opacity-60', accessState.readonly && 'opacity-80', consumerClassName, sx);
     if (asChild) {
         // Slot expects a single child; divider has no place here.
         return jsx(Slot, _extends({
             ref: ref,
             className: classes
-        }, safeRest, {
+        }, ariaProps, safeRest, {
             children: children
         }));
     }
     const Tag = as != null ? as : 'div';
-    const content = divider != null ? interleaveDividers(children, divider) : children;
+    const content = divider != null ? interleaveDividers(children, divider, direction != null ? direction : 'col') : children;
     return jsx(Tag, _extends({
         ref: ref,
         className: classes
-    }, safeRest, {
+    }, ariaProps, safeRest, {
         children: content
     }));
 });
@@ -14925,13 +15584,34 @@ Stack.displayName = 'Stack';
     // branches of the discriminated union.
     const themeDefaults = useComponentDefaults('Grid');
     const props = _extends({}, themeDefaults == null ? void 0 : themeDefaults.defaults, _props);
-    const { as, asChild = false, sx, children, className: consumerClassName } = props, rest = _object_without_properties_loose(props, [
+    const { as, asChild = false, sx, visibleWhen, access, children, className: consumerClassName } = props, rest = _object_without_properties_loose(props, [
         "as",
         "asChild",
         "sx",
+        "visibleWhen",
+        "access",
         "children",
         "className"
     ]);
+    // Bridge — hooks called unconditionally, ABOVE the early return and
+    // above the union branching (rules-of-hooks; see README-BUG § BUG 33
+    // for what a conditional subscription costs). Both are no-ops when
+    // their prop is absent, so a consumer passing neither renders exactly
+    // as before. Destructured out of `rest` so neither can reach the DOM.
+    const bridge = useContext(DashFormContext);
+    const isVisible = useEngineVisibility(bridge == null ? void 0 : bridge.engine, visibleWhen);
+    const accessState = useAccessState(access);
+    // Early return — predicate false OR RBAC denies visibility.
+    if (!isVisible || !accessState.visible) return null;
+    // RBAC-denied surfaces dim and carry the ARIA attributes below, so
+    // descendants and assistive tech can react.
+    const accessClasses = cn(accessState.disabled && 'opacity-60', accessState.readonly && 'opacity-80');
+    const ariaProps = {
+        'aria-disabled': accessState.disabled || undefined,
+        'aria-readonly': accessState.readonly || undefined,
+        'data-disabled': accessState.disabled || undefined,
+        'data-readonly': accessState.readonly || undefined
+    };
     // #112 (G-28): salvage a stray untyped `className` that snuck in via
     // spread props so the JSX spread doesn't clobber the variant chain
     // via last-wins prop override. Merged through `cn` in both branches
@@ -14964,7 +15644,7 @@ Stack.displayName = 'Stack';
             spacingX: containerPayload.spacingX,
             spacingY: containerPayload.spacingY,
             autoFlow: containerPayload.autoFlow
-        }), consumerClassName, sx);
+        }), accessClasses, consumerClassName, sx);
     } else {
         var _itemPayload_xs;
         itemPayload = props;
@@ -14977,7 +15657,7 @@ Stack.displayName = 'Stack';
             md: itemPayload.md,
             lg: itemPayload.lg,
             xl: itemPayload.xl
-        }), consumerClassName, sx);
+        }), accessClasses, consumerClassName, sx);
     }
     /*
      * Strip role-specific props from `rest` before spreading on the DOM
@@ -15004,7 +15684,7 @@ Stack.displayName = 'Stack';
         return jsx(Slot, _extends({
             ref: ref,
             className: classes
-        }, domRest, {
+        }, ariaProps, domRest, {
             children: children
         }));
     }
@@ -15012,7 +15692,7 @@ Stack.displayName = 'Stack';
     return jsx(Tag, _extends({
         ref: ref,
         className: classes
-    }, domRest, {
+    }, ariaProps, domRest, {
         children: children
     }));
 });
@@ -15218,13 +15898,29 @@ Container.displayName = 'Container';
  * border-* color token to the intent.
  *
  * The `segment` axis distinguishes whether this is a line-only render
- * (full width) vs a labeled-mode segment (flex-1 grows to share space).
+ * (spans its own main axis) vs a labeled-mode segment (flex-1 grows to
+ * share space).
+ *
+ * `full` means "span the divider's OWN main axis", which is the width
+ * for a horizontal rule and the HEIGHT for a vertical one. It is
+ * therefore orientation-dependent and lives in `compoundVariants`, not
+ * on the plain axis. See README-BUG § BUG 25: an unconditional
+ * `w-full` here fought the `w-0` from the orientation axis, tailwind-
+ * merge kept the later `w-full`, and every vertical line-only divider
+ * came out as a full-width bar with a left border.
  */ const dividerLineVariants = tv({
     base: '',
     variants: {
         orientation: {
             horizontal: 'h-0 border-t',
-            vertical: 'w-0 border-l self-stretch'
+            /*
+             * `w-0` does double duty and must NOT be dropped:
+             *   - in a `flex-row` parent it is the main-axis size, so the
+             *     visible width is exactly the 1px `border-l`;
+             *   - in a `flex-col` parent (labeled vertical mode) it is the
+             *     CROSS size, and being definite it stops `self-stretch` from
+             *     stretching the rule to the full width.
+             */ vertical: 'w-0 border-l self-stretch'
         },
         variant: {
             solid: 'border-solid',
@@ -15242,13 +15938,30 @@ Container.displayName = 'Container';
             info: 'border-info-300 dark:border-info-700'
         },
         /*
-         * `segment` controls whether the line spans full width (line-only
-         * mode) or grows to fill space (labeled-mode flex segment).
+         * `segment` controls whether the line spans its own main axis
+         * (line-only mode) or grows to fill space (labeled-mode flex
+         * segment).
+         *
+         * `full` is empty here on purpose: what "full" resolves to depends
+         * on the orientation, so it is emitted from `compoundVariants`.
+         * `grow` is genuinely orientation-agnostic — `flex-1` grows along
+         * whichever main axis the parent sets — so it stays on the axis.
          */ segment: {
-            full: 'w-full',
+            full: '',
             grow: 'flex-1'
         }
     },
+    compoundVariants: [
+        /*
+         * Horizontal: `w-full` is load-bearing. A block child does NOT fill
+         * the width once it is a flex item, which is exactly the toolbar
+         * case, so the rule would collapse without this.
+         */ {
+            orientation: 'horizontal',
+            segment: 'full',
+            class: 'w-full'
+        }
+    ],
     defaultVariants: {
         orientation: 'horizontal',
         variant: 'solid',
@@ -15556,7 +16269,11 @@ VisuallyHidden.displayName = 'VisuallyHidden';
             'absolute top-4 right-4 inline-flex items-center justify-center',
             'h-8 w-8 rounded-md text-neutral-500 hover:text-neutral-900',
             'hover:bg-neutral-100',
-            'focus:outline-none focus:ring-2 focus:ring-primary-500',
+            // `focus-visible:`, not `focus:` — Radix moves focus into the panel
+            // on open and this button is the first focusable thing in it, so a
+            // plain `focus:ring` painted a ring on every mouse-opened dialog.
+            // BUG 28. Matches the catalog's dominant form (9 other slots).
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
             'transition-colors'
         ],
         body: 'flex-1 overflow-y-auto',
@@ -15911,8 +16628,12 @@ const accordionVariants = tv({
         trigger: [
             'flex flex-1 items-center justify-between py-3 text-left',
             'text-sm font-medium text-neutral-900',
-            'transition-all hover:underline',
-            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:rounded',
+            // `transition-all` covers transform-able properties, so it is
+            // motion under WCAG 2.3.3 and needs the gate. Every other
+            // `transition-transform` in the catalog has one; this was the
+            // only movement left ungated.
+            'transition-all hover:underline motion-reduce:transition-none',
+            'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:rounded-sm',
             '[&[data-state=open]>svg]:rotate-180',
             'disabled:opacity-50 disabled:pointer-events-none',
             'motion-reduce:transition-none'
@@ -17580,7 +18301,7 @@ function Row(props) {
                             "aria-label": isExpanded ? labels.ariaCollapseRow : labels.ariaExpandRow,
                             "aria-expanded": isExpanded,
                             disabled: !isInteractive,
-                            className: cn('inline-flex items-center justify-center h-6 w-6 rounded', // text-neutral-500 + hover bump; both auto-invert via CSS-var preset.
+                            className: cn('inline-flex items-center justify-center h-6 w-6 rounded-md', // text-neutral-500 + hover bump; both auto-invert via CSS-var preset.
                             'text-neutral-500 hover:text-neutral-900', 'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500', 'transition-transform motion-reduce:transition-none', isExpanded && 'rotate-90'),
                             children: jsx(ChevronRightIcon, {})
                         })
@@ -18327,7 +19048,7 @@ function ColumnFilterTrigger(props) {
             "aria-label": labels.filterColumn,
             "aria-pressed": active,
             disabled: disabled,
-            className: cn('inline-flex items-center justify-center h-6 w-6 rounded', 'text-neutral-500 hover:text-neutral-900', active && 'text-primary-700', 'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500', 'transition-colors motion-reduce:transition-none', 'disabled:opacity-50 disabled:cursor-not-allowed'),
+            className: cn('inline-flex items-center justify-center h-6 w-6 rounded-md', 'text-neutral-500 hover:text-neutral-900', active && 'text-primary-700', 'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500', 'transition-colors motion-reduce:transition-none', 'disabled:opacity-50 disabled:cursor-not-allowed'),
             children: jsx(FilterIcon, {})
         })
     });
@@ -18709,7 +19430,7 @@ function ColumnVisibilityTrigger(props) {
                         const header = typeof col.header === 'function' ? col.header() : col.header;
                         return jsx("li", {
                             children: jsxs("label", {
-                                className: "flex items-center gap-2 cursor-pointer py-1 px-1 rounded hover:bg-neutral-100",
+                                className: "flex items-center gap-2 cursor-pointer py-1 px-1 rounded-md hover:bg-neutral-100",
                                 children: [
                                     jsx("input", {
                                         type: "checkbox",
@@ -19803,4 +20524,4 @@ function SearchIcon(props) {
  * Package version (synced with `package.json` at publish time).
  */ const VERSION = '1.5.2';
 
-export { AVATAR_SOFT_FALLBACK, AVATAR_TONE_FALLBACK, Accordion, Alert, AlertTitle, AppShell, AspectRatio, Autocomplete, Avatar, AvatarGroup, Badge, Box, Breadcrumbs, Button, Calendar, Card, CardActionArea, CardContent, Checkbox, Chip, ConfirmDialogProvider, Container, DRAWER_SIZE_PRESETS, DataGrid, DatePicker, DateRangePicker, DateTimePicker, Dialog, Divider, Drawer, Grid, ICON_BUTTON_BASE, ICON_BUTTON_SIZE_OVERRIDES, IconButton, Image, LeftNav, Link, Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuSkeleton, MenuTrigger, NumberField, OTPField, Pagination, Popover, Progress, RadioGroup, RenderButton, RenderChip, RenderText, RenderTwoLine, RowActionsMenu, SPINNER_COLORS, SPINNER_STROKE_WIDTH, SPINNER_TRACK_OPACITY, Select, Skeleton, Slider, SnackbarProvider, Spinner, Stack, Step, Stepper, Switch, Table, Tabs, TextField, Textarea, TimePicker, Tooltip, TopBar, Typography, VERSION, Video, VisuallyHidden, accordionVariants, alertVariants, appShellVariants, autocompleteVariants, avatarVariants, badgeVariants, boxVariants, breadcrumbsVariants, buttonVariants, calendarDayVariants, calendarVariants, checkboxVariants, chipVariants, cn, confirmDialogVariants, containerVariants, dataGridVariants, datePickerVariants, dateRangeDayVariants, dateRangePickerVariants, dateTimePickerVariants, dialogVariants, dividerLineVariants, dividerVariants, drawerVariants, getNestedValue, gridVariants, imageVariants, leftNavVariants, linkVariants, menuVariants, numberFieldVariants, otpFieldVariants, paginationVariants, popoverVariants, progressVariants, radioGroupVariants, selectVariants, skeletonVariants, sliderVariants, snackbarVariants, spinnerVariants, stackVariants, stepperVariants, switchVariants, tableVariants, tabsVariants, textFieldVariants, textareaVariants, timePickerVariants, tooltipVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar, useStep, videoVariants };
+export { AVATAR_SOFT_FALLBACK, AVATAR_TONE_FALLBACK, Accordion, Alert, AlertTitle, AppShell, AspectRatio, Autocomplete, Avatar, AvatarGroup, Badge, Box, Breadcrumbs, Button, Calendar, Card, CardActionArea, CardContent, Checkbox, Chip, ConfirmDialogProvider, Container, DRAWER_SIZE_PRESETS, DataGrid, DatePicker, DateRangePicker, DateTimePicker, Dialog, Divider, Drawer, Grid, ICON_BUTTON_BASE, ICON_BUTTON_SIZE_OVERRIDES, IconButton, Image, Kbd, LeftNav, Link, Menu, MenuContent, MenuItem, MenuLabel, MenuSeparator, MenuSkeleton, MenuTrigger, NumberField, OTPField, Pagination, Popover, Progress, RadioGroup, RenderButton, RenderChip, RenderText, RenderTwoLine, RowActionsMenu, SPINNER_COLORS, SPINNER_STROKE_WIDTH, SPINNER_TRACK_OPACITY, Select, Skeleton, Slider, SnackbarProvider, Spinner, Stack, Step, Stepper, Switch, Table, Tabs, TextField, Textarea, TimePicker, Tooltip, TopBar, TopBarBrand, Typography, VERSION, Video, VisuallyHidden, accordionVariants, alertVariants, appShellVariants, autocompleteVariants, avatarVariants, badgeVariants, boxVariants, breadcrumbsVariants, buttonVariants, calendarDayVariants, calendarVariants, checkboxVariants, chipVariants, cn, confirmDialogVariants, containerVariants, dataGridVariants, datePickerVariants, dateRangeDayVariants, dateRangePickerVariants, dateTimePickerVariants, dialogVariants, dividerLineVariants, dividerVariants, drawerVariants, getNestedValue, gridVariants, imageVariants, kbdVariants, leftNavVariants, linkVariants, menuVariants, numberFieldVariants, otpFieldVariants, paginationVariants, popoverVariants, progressVariants, radioGroupVariants, selectVariants, skeletonVariants, sliderVariants, snackbarVariants, spinnerVariants, stackVariants, stepperVariants, switchVariants, tableVariants, tabsVariants, textFieldVariants, textareaVariants, timePickerVariants, tooltipVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar, useStep, videoVariants };