@dashforge/tw 0.1.0-beta → 0.2.1-beta

package/dist/index.esm.js

@@ -1,5 +1,5 @@
 import { jsx, jsxs, Fragment as Fragment$1 } from 'react/jsx-runtime';
-import { useMemo, forwardRef, useContext, useId, useRef, useEffect, useCallback, useState, Fragment, createContext } from 'react';
+import { useMemo, forwardRef, useContext, useId, useRef, useEffect, useCallback, useState, Fragment, createContext, Children, isValidElement, cloneElement } from 'react';
 import { Slot } from '@radix-ui/react-slot';
 import clsx from 'clsx';
 import { twMerge } from 'tailwind-merge';
@@ -403,6 +403,13 @@ function _object_without_properties_loose(source, excluded) {
         fullWidth,
         loading
     }), sx);
+    /*
+     * `aria-busy` announces the loading state to assistive tech.
+     * `disabled` alone hides the reason (perm-denied vs loading vs
+     * intrinsic), so SR users only hear "dimmed/inactive" without
+     * knowing why. Adding `aria-busy={true}` while loading distinguishes
+     * "wait for the action to finish" from "you can't do this".
+     */ const ariaBusy = loading ? true : undefined;
     // `asChild` renders through Radix Slot: the immediate child element
     // gets the resolved className, no extra Button DOM is emitted.
     if (asChild) {
@@ -411,6 +418,7 @@ function _object_without_properties_loose(source, excluded) {
             className: classes,
             "data-disabled": effectiveDisabled || undefined,
             "aria-disabled": effectiveDisabled || undefined,
+            "aria-busy": ariaBusy,
             children: children
         });
     }
@@ -418,6 +426,7 @@ function _object_without_properties_loose(source, excluded) {
         ref: ref,
         type: (_rest_type = rest.type) != null ? _rest_type : 'button',
         disabled: effectiveDisabled,
+        "aria-busy": ariaBusy,
         className: classes
     }, rest, {
         children: [
@@ -968,10 +977,9 @@ function _object_without_properties_loose(source, excluded) {
                 className: cn(v.control(), slotProps == null ? void 0 : (_slotProps_control = slotProps.control) == null ? void 0 : _slotProps_control.className),
                 children: jsx(RadixCheckbox.Indicator, {
                     className: cn(v.indicator(), slotProps == null ? void 0 : (_slotProps_indicator = slotProps.indicator) == null ? void 0 : _slotProps_indicator.className),
-                    forceMount: true,
-                    children: resolvedChecked === true ? jsx(CheckIcon, {
+                    children: jsx(CheckIcon, {
                         className: "h-full w-full"
-                    }) : null
+                    })
                 })
             })),
             jsxs("div", {
@@ -1430,9 +1438,13 @@ function _object_without_properties_loose(source, excluded) {
                     })
                 ]
             }),
-            jsx(RadixRadioGroup.Root, {
-                name: name,
-                value: resolvedValue,
+            jsx(RadixRadioGroup.Root, _extends({
+                name: name
+            }, isFormMode || explicitValue !== undefined ? {
+                value: resolvedValue
+            } : {
+                defaultValue: defaultValue != null ? defaultValue : undefined
+            }, {
                 onValueChange: handleValueChange,
                 onBlur: handleBlur,
                 disabled: groupEffectiveDisabled,
@@ -1463,7 +1475,7 @@ function _object_without_properties_loose(source, excluded) {
                         ]
                     }, option.value);
                 })
-            }),
+            })),
             resolvedHelperText && jsx("p", {
                 id: helperId,
                 className: cn(resolvedError ? v.errorText() : v.helperText(), resolvedError ? slotProps == null ? void 0 : (_slotProps_errorText = slotProps.errorText) == null ? void 0 : _slotProps_errorText.className : slotProps == null ? void 0 : (_slotProps_helperText = slotProps.helperText) == null ? void 0 : _slotProps_helperText.className),
@@ -1905,6 +1917,18 @@ function _object_without_properties_loose(source, excluded) {
     useDashFieldMeta(name);
     const accessState = useAccessState(access);
     const inputId = useId();
+    /*
+     * Local state for the STANDALONE UNCONTROLLED case (no bridge, no
+     * `value` prop, only `defaultValue`). Mirrors OTPField. Without this,
+     * `resolvedDisplayValue` would be a snapshot computed ONCE from
+     * `defaultValue` and the controlled `<input value={...}>` would
+     * snap user input back on every keystroke / stepper click — same
+     * trap that hit Checkbox + RadioGroup in this package.
+     *
+     * In form mode the bridge owns state. In standalone CONTROLLED mode
+     * (consumer passes `value`) the consumer owns state. Only this
+     * branch needs the local hook.
+     */ const [uncontrolledValue, setUncontrolledValue] = useState(()=>formatForDisplay(defaultValue));
     const helperId = `${inputId}-help`;
     // StrictMode-safe unregister-on-unmount
     const unregisterRef = useRef({
@@ -1942,7 +1966,7 @@ function _object_without_properties_loose(source, excluded) {
         resolvedHelperText = validation.helperText;
         resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : formatForDisplay(bridge.getValue(name));
     } else {
-        resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : formatForDisplay(defaultValue);
+        resolvedDisplayValue = userValue !== undefined ? formatForDisplay(userValue) : uncontrolledValue;
     }
     const writeToBridge = (parsed)=>{
         if (!isFormMode || !bridge) return;
@@ -1957,6 +1981,13 @@ function _object_without_properties_loose(source, excluded) {
             // internal logic still sees the raw string change.
             void registration.onChange(e);
         }
+        // Standalone uncontrolled mode: mirror the raw input string so the
+        // controlled `<input value={...}>` reflects what the user typed.
+        // Partial states (e.g. "-", "1.") are kept verbatim — `parseFromInput`
+        // returns `undefined` for them so `writeToBridge` is a no-op above.
+        if (!isFormMode && userValue === undefined) {
+            setUncontrolledValue(e.target.value);
+        }
         userOnChange == null ? void 0 : userOnChange(e);
     };
     const handleBlur = (e)=>{
@@ -1972,6 +2003,11 @@ function _object_without_properties_loose(source, excluded) {
         if (typeof min === 'number') next = Math.max(min, next);
         if (typeof max === 'number') next = Math.min(max, next);
         writeToBridge(next);
+        // Standalone uncontrolled: also persist the new value to local
+        // state so the visible display tracks the stepper click.
+        if (!isFormMode && userValue === undefined) {
+            setUncontrolledValue(formatForDisplay(next));
+        }
     };
     const canIncrement = !effectiveDisabled && (typeof max !== 'number' || ((_parseFromInput = parseFromInput(resolvedDisplayValue)) != null ? _parseFromInput : -Infinity) < max);
     const canDecrement = !effectiveDisabled && (typeof min !== 'number' || ((_parseFromInput1 = parseFromInput(resolvedDisplayValue)) != null ? _parseFromInput1 : Infinity) > min);
@@ -4926,6 +4962,1567 @@ const SnackbarContext = /*#__PURE__*/ createContext(null);
     });
 }
 
+/**
+ * `typographyVariants` — the full type scale for the @dashforge/tw library.
+ *
+ * Mirrors the MUI Typography variant set (h1–h6 · subtitle1/2 · body1/2 ·
+ * caption · overline) so the mental model carries over for developers
+ * moving between the two ecosystems. Each variant baseline maps to a
+ * Tailwind utility chain that resolves through the @dashforge/tw-tokens
+ * scale (so the visual stays in sync with the rest of the system when the
+ * token theme is patched).
+ *
+ * Variant axes are intentionally ORTHOGONAL — `variant` chooses the type
+ * scale, `weight` overrides the variant's default weight (useful for "h2
+ * but lighter"), `color` picks the intent, `align` picks the axis. They
+ * never collide, so consumers can mix them freely.
+ *
+ * Two boolean flags (`truncate`, `noWrap`) encode the most common one-line
+ * patterns; `gutterBottom` adds the conventional bottom margin used when a
+ * heading precedes a paragraph block (mirror of MUI's same flag).
+ */ const typographyVariants = tv({
+    base: 'text-inherit',
+    variants: {
+        /*
+         * `variant` is the type-scale axis.
+         *
+         * The default font-weight is baked into each variant (headings come
+         * with semibold/bold by default). Consumers override per-instance via
+         * the `weight` axis below — when set, `weight` wins because it's
+         * declared later in the cn() chain and tailwind-merge resolves the
+         * last `font-*` to win.
+         */ variant: {
+            h1: 'text-5xl font-bold leading-[1.05] tracking-[-0.025em]',
+            h2: 'text-4xl font-bold leading-[1.1] tracking-[-0.022em]',
+            h3: 'text-3xl font-semibold leading-[1.15] tracking-[-0.02em]',
+            h4: 'text-2xl font-semibold leading-snug tracking-[-0.015em]',
+            h5: 'text-xl font-semibold leading-snug',
+            h6: 'text-lg font-semibold leading-normal',
+            subtitle1: 'text-base font-medium leading-relaxed',
+            subtitle2: 'text-sm font-medium leading-relaxed',
+            body1: 'text-base font-normal leading-relaxed',
+            body2: 'text-sm font-normal leading-relaxed',
+            caption: 'text-xs font-normal leading-normal',
+            overline: 'text-xs font-semibold uppercase tracking-[0.12em] leading-normal'
+        },
+        /*
+         * `color` is the intent axis. Pairs with the @dashforge/tw-theme
+         * reactive colour vars so the choice survives theme patches and dark
+         * mode flips. `inherit` is the escape hatch — used inside a Box that
+         * has set its own color (e.g. `<Box variant="solid" color="primary">`
+         * paints white text).
+         */ color: {
+            inherit: 'text-inherit',
+            primary: 'text-primary-700 dark:text-primary-400',
+            secondary: 'text-secondary-700 dark:text-secondary-400',
+            success: 'text-success-700 dark:text-success-400',
+            warning: 'text-warning-700 dark:text-warning-400',
+            danger: 'text-danger-700 dark:text-danger-400',
+            info: 'text-info-700 dark:text-info-400',
+            neutral: 'text-neutral-900 dark:text-neutral-100',
+            muted: 'text-neutral-600 dark:text-neutral-400'
+        },
+        /*
+         * `weight` overrides the variant's default weight. When unset, the
+         * variant's own weight wins. When set, this axis appears LATER in the
+         * cn() chain so tailwind-merge resolves to this value.
+         */ weight: {
+            normal: 'font-normal',
+            medium: 'font-medium',
+            semibold: 'font-semibold',
+            bold: 'font-bold',
+            extrabold: 'font-extrabold'
+        },
+        align: {
+            left: 'text-left',
+            center: 'text-center',
+            right: 'text-right',
+            justify: 'text-justify'
+        },
+        /*
+         * `truncate` collapses to a one-line ellipsis. `noWrap` is the looser
+         * sibling — keeps the text on one line but lets it overflow without
+         * the `…`. Mutually-exclusive intent-wise; if both are passed,
+         * `truncate` wins (later in the cn() chain).
+         */ truncate: {
+            true: 'truncate'
+        },
+        noWrap: {
+            true: 'whitespace-nowrap'
+        },
+        /*
+         * `gutterBottom` adds the conventional bottom margin used when a
+         * heading precedes a paragraph block. Mirror of MUI's same prop —
+         * familiar to developers crossing from the MUI side.
+         */ gutterBottom: {
+            true: 'mb-3'
+        }
+    },
+    defaultVariants: {
+        variant: 'body1',
+        color: 'inherit',
+        align: 'left'
+    }
+});
+
+/**
+ * Default HTML tag per variant. Headings get their semantic level (h1→h1
+ * etc.); subtitle/body get `<p>` (block, paragraph semantics);
+ * caption/overline get `<span>` (inline, no implicit block break).
+ *
+ * Override per-instance via the `as` prop — useful when the semantic
+ * heading level should differ from the visual scale (e.g. a hero
+ * rendered as `<h2>` but visually styled `h1`).
+ */ const VARIANT_TO_TAG = {
+    h1: 'h1',
+    h2: 'h2',
+    h3: 'h3',
+    h4: 'h4',
+    h5: 'h5',
+    h6: 'h6',
+    subtitle1: 'p',
+    subtitle2: 'p',
+    body1: 'p',
+    body2: 'p',
+    caption: 'span',
+    overline: 'span'
+};
+/**
+ * `<Typography>` — semantic typed text, the foundation of every readable
+ * surface in @dashforge/tw.
+ *
+ * Why this exists:
+ *   Tailwind ships a typographic scale (`text-xl`, `font-bold`,
+ *   `leading-relaxed`) but leaves the SEMANTIC HTML tag and the
+ *   intent-coloured palette to the consumer. That's fine for one-off
+ *   marketing surfaces, but at app scale it means every `<h2>` and every
+ *   body paragraph re-derives its own utility chain — and they drift.
+ *
+ *   Typography moves that decision into a typed prop set: the visual
+ *   scale, the intent colour, the alignment, the truncation all live in
+ *   `tailwind-variants` and resolve to the same utility chain everywhere
+ *   in the app. The default HTML tag is inferred from `variant` so the
+ *   semantic layer follows the visual layer; `as` and `asChild` are the
+ *   two escape hatches when you need something else.
+ *
+ * Layering:
+ *   • Sits BENEATH every component that renders text — `<Button>`'s
+ *     label, `<TextField>`'s helper text, MDX prose in our own docs.
+ *   • Composes ON TOP of `@dashforge/tw-tokens` colour scales (so
+ *     `color="primary"` paints `text-primary-700` in light, `-400` in dark,
+ *     reactive to `setMode()`).
+ *   • Polymorphic via Radix Slot — pairs cleanly with router `<Link>`,
+ *     `<button>`, or `<a>` without injecting an extra wrapper element.
+ *
+ * Polymorphism rules — `as` vs `asChild`:
+ *   • `as` swaps the rendered tag (we still render the element ourselves).
+ *   • `asChild` removes our element entirely — the single React child
+ *     becomes the rendered tag, with our className/ref merged onto it.
+ *     This is the Radix Slot pattern; use when you need a router Link
+ *     to style as a heading.
+ *   When BOTH are passed, `asChild` wins. We considered making this a
+ *   compile-time error via discriminated unions, but the API surface
+ *   already has 8 axes and adding one more dimension to the props type
+ *   would inflate IntelliSense suggestions for marginal benefit. The
+ *   runtime preference is documented; the test asserts it.
+ */ const Typography = /*#__PURE__*/ forwardRef(function Typography(props, ref) {
+    var _ref;
+    const { variant = 'body1', color, weight, align, truncate, noWrap, gutterBottom, as, asChild = false, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "variant",
+        "color",
+        "weight",
+        "align",
+        "truncate",
+        "noWrap",
+        "gutterBottom",
+        "as",
+        "asChild",
+        "sx",
+        "children"
+    ]);
+    const classes = cn(typographyVariants({
+        variant,
+        color,
+        weight,
+        align,
+        truncate,
+        noWrap,
+        gutterBottom
+    }), sx);
+    // asChild wins over `as` when both are passed (see component header).
+    if (asChild) {
+        return jsx(Slot, _extends({
+            ref: ref,
+            className: classes
+        }, rest, {
+            children: children
+        }));
+    }
+    // Resolve the rendered tag: explicit `as` > variant default > fallback.
+    const Tag = (_ref = as != null ? as : VARIANT_TO_TAG[variant]) != null ? _ref : 'span';
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, rest, {
+        children: children
+    }));
+});
+Typography.displayName = 'Typography';
+
+/**
+ * `boxVariants` — the surface primitive for @dashforge/tw.
+ *
+ * Architectural choice (planned with the user — F9 deep dive):
+ *
+ *   Box replaces FOUR overlapping concepts from MUI in one component:
+ *     • Box        (typed div)
+ *     • Paper      (surface with elevation)
+ *     • Card       (Paper specialisation)
+ *     • Surface    (Joy UI's outlined / soft / solid / plain variants)
+ *
+ *   The reason for the consolidation: in MUI you have to compose two or
+ *   three of these to express even basic intent ("an outlined card with
+ *   warning tone"). Here, one `<Box variant="outlined" color="warning">`
+ *   says exactly that.
+ *
+ * Variant taxonomy (5 axes, intentionally non-overlapping with Stack/Grid):
+ *
+ *   • plain     — bare div + padding + radius. The escape hatch.
+ *   • outlined  — 1px border + subtle bg tint. The "card lite".
+ *   • elevated  — bg surface + shadow scale (0-5). The "floating panel".
+ *   • soft      — semi-transparent intent bg + intent text. The "callout".
+ *   • solid     — solid intent bg + contrasting text. The "CTA banner".
+ *
+ *   `color` applies to outlined/soft/solid (each gets the 7 intent
+ *   variants). `elevated` is color-agnostic (always neutral surface +
+ *   shadow scale). `plain` is everything-agnostic.
+ *
+ * Spacing axes (p/px/py/m/mx/my): mapped explicitly to the 11 token
+ * steps from @dashforge/tw-tokens (0, 0.5, 1, 2, 3, 4, 6, 8, 12, 16, 24).
+ * Tailwind JIT requires literal class strings — building them dynamically
+ * with template literals would purge them. The verbosity below is the
+ * cost of keeping the bundle CSS-pure and rebuild-free.
+ *
+ * What this does NOT do (deliberate, see component docs):
+ *   • No display / flex / grid props      → use Stack or Grid
+ *   • No position / overflow / z-index    → use `sx`
+ *   • No animation / transition           → use `sx`
+ *
+ * The "Box is not flex" rule is the spine of the layout layer. Without
+ * it, every `<div>` in an app gravitates back to Box and the surface
+ * vs layout distinction collapses — exactly the failure mode this
+ * primitive exists to prevent.
+ */ const boxVariants = tv({
+    base: 'block',
+    variants: {
+        /*
+         * Surface variant. Compound with `color` for outlined / soft / solid;
+         * standalone for plain / elevated.
+         */ variant: {
+            plain: '',
+            outlined: 'border',
+            elevated: 'bg-white dark:bg-neutral-900',
+            soft: '',
+            solid: ''
+        },
+        /*
+         * Intent color. Only meaningful when variant is outlined / soft /
+         * solid (resolved via compoundVariants below). For plain / elevated
+         * this axis is ignored at the visual level — but kept in the type
+         * so the prop is always available without conditional typing.
+         */ color: {
+            primary: '',
+            secondary: '',
+            success: '',
+            warning: '',
+            danger: '',
+            info: '',
+            neutral: ''
+        },
+        /*
+         * Shadow scale — relevant for `variant='elevated'`. We keep elevation
+         * as a separate axis (not folded into `variant`) so consumers can
+         * dial it up/down without changing the variant. Default `0` = no
+         * shadow (consistent with MUI's elevation=0).
+         */ elevation: {
+            0: 'shadow-none',
+            1: 'shadow-sm',
+            2: 'shadow',
+            3: 'shadow-md',
+            4: 'shadow-lg',
+            5: 'shadow-xl'
+        },
+        rounded: {
+            none: 'rounded-none',
+            sm: 'rounded-sm',
+            md: 'rounded-md',
+            lg: 'rounded-lg',
+            xl: 'rounded-xl',
+            '2xl': 'rounded-2xl',
+            full: 'rounded-full'
+        },
+        /*
+         * Spacing — six axes (p/px/py/m/mx/my), 11 token steps each.
+         * Literals enumerated explicitly so Tailwind's JIT scanner finds
+         * every class. Token steps mirror @dashforge/tw-tokens spacing scale.
+         */ p: {
+            0: 'p-0',
+            '0.5': 'p-0.5',
+            1: 'p-1',
+            2: 'p-2',
+            3: 'p-3',
+            4: 'p-4',
+            6: 'p-6',
+            8: 'p-8',
+            12: 'p-12',
+            16: 'p-16',
+            24: 'p-24'
+        },
+        px: {
+            0: 'px-0',
+            '0.5': 'px-0.5',
+            1: 'px-1',
+            2: 'px-2',
+            3: 'px-3',
+            4: 'px-4',
+            6: 'px-6',
+            8: 'px-8',
+            12: 'px-12',
+            16: 'px-16',
+            24: 'px-24'
+        },
+        py: {
+            0: 'py-0',
+            '0.5': 'py-0.5',
+            1: 'py-1',
+            2: 'py-2',
+            3: 'py-3',
+            4: 'py-4',
+            6: 'py-6',
+            8: 'py-8',
+            12: 'py-12',
+            16: 'py-16',
+            24: 'py-24'
+        },
+        m: {
+            0: 'm-0',
+            '0.5': 'm-0.5',
+            1: 'm-1',
+            2: 'm-2',
+            3: 'm-3',
+            4: 'm-4',
+            6: 'm-6',
+            8: 'm-8',
+            12: 'm-12',
+            16: 'm-16',
+            24: 'm-24'
+        },
+        mx: {
+            0: 'mx-0',
+            '0.5': 'mx-0.5',
+            1: 'mx-1',
+            2: 'mx-2',
+            3: 'mx-3',
+            4: 'mx-4',
+            6: 'mx-6',
+            8: 'mx-8',
+            12: 'mx-12',
+            16: 'mx-16',
+            24: 'mx-24'
+        },
+        my: {
+            0: 'my-0',
+            '0.5': 'my-0.5',
+            1: 'my-1',
+            2: 'my-2',
+            3: 'my-3',
+            4: 'my-4',
+            6: 'my-6',
+            8: 'my-8',
+            12: 'my-12',
+            16: 'my-16',
+            24: 'my-24'
+        },
+        fullWidth: {
+            true: 'w-full'
+        },
+        fullHeight: {
+            true: 'h-full'
+        }
+    },
+    /*
+     * Compound variants — where surface × color get their actual visual.
+     * Twenty-one entries: 7 (outlined) + 7 (soft) + 7 (solid).
+     * `plain` and `elevated` don't appear here (no color contribution).
+     *
+     * Dark-mode pair is baked in: light-mode picks the 50-300 steps,
+     * dark-mode picks the 800-950 steps — both reactive to setMode()
+     * via the @dashforge/tw-theme CSS variables.
+     */ compoundVariants: [
+        // ─── outlined × color ─────────────────────────────────────────────
+        {
+            variant: 'outlined',
+            color: 'primary',
+            class: 'border-primary-300 bg-primary-50/40 dark:border-primary-800 dark:bg-primary-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'secondary',
+            class: 'border-secondary-300 bg-secondary-50/40 dark:border-secondary-800 dark:bg-secondary-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'success',
+            class: 'border-success-300 bg-success-50/40 dark:border-success-800 dark:bg-success-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'warning',
+            class: 'border-warning-300 bg-warning-50/40 dark:border-warning-800 dark:bg-warning-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'danger',
+            class: 'border-danger-300 bg-danger-50/40 dark:border-danger-800 dark:bg-danger-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'info',
+            class: 'border-info-300 bg-info-50/40 dark:border-info-800 dark:bg-info-950/30'
+        },
+        {
+            variant: 'outlined',
+            color: 'neutral',
+            class: 'border-neutral-200 bg-white dark:border-neutral-700 dark:bg-neutral-900'
+        },
+        // ─── soft × color ─────────────────────────────────────────────────
+        {
+            variant: 'soft',
+            color: 'primary',
+            class: 'bg-primary-100 text-primary-900 dark:bg-primary-950/50 dark:text-primary-100'
+        },
+        {
+            variant: 'soft',
+            color: 'secondary',
+            class: 'bg-secondary-100 text-secondary-900 dark:bg-secondary-950/50 dark:text-secondary-100'
+        },
+        {
+            variant: 'soft',
+            color: 'success',
+            class: 'bg-success-100 text-success-900 dark:bg-success-950/50 dark:text-success-100'
+        },
+        {
+            variant: 'soft',
+            color: 'warning',
+            class: 'bg-warning-100 text-warning-900 dark:bg-warning-950/50 dark:text-warning-100'
+        },
+        {
+            variant: 'soft',
+            color: 'danger',
+            class: 'bg-danger-100 text-danger-900 dark:bg-danger-950/50 dark:text-danger-100'
+        },
+        {
+            variant: 'soft',
+            color: 'info',
+            class: 'bg-info-100 text-info-900 dark:bg-info-950/50 dark:text-info-100'
+        },
+        {
+            variant: 'soft',
+            color: 'neutral',
+            class: 'bg-neutral-100 text-neutral-900 dark:bg-neutral-800 dark:text-neutral-100'
+        },
+        // ─── solid × color ────────────────────────────────────────────────
+        {
+            variant: 'solid',
+            color: 'primary',
+            class: 'bg-primary-600 text-white dark:bg-primary-500'
+        },
+        {
+            variant: 'solid',
+            color: 'secondary',
+            class: 'bg-secondary-600 text-white dark:bg-secondary-500'
+        },
+        {
+            variant: 'solid',
+            color: 'success',
+            class: 'bg-success-600 text-white dark:bg-success-500'
+        },
+        {
+            variant: 'solid',
+            color: 'warning',
+            class: 'bg-warning-500 text-white dark:bg-warning-600'
+        },
+        {
+            variant: 'solid',
+            color: 'danger',
+            class: 'bg-danger-600 text-white dark:bg-danger-500'
+        },
+        {
+            variant: 'solid',
+            color: 'info',
+            class: 'bg-info-600 text-white dark:bg-info-500'
+        },
+        {
+            variant: 'solid',
+            color: 'neutral',
+            class: 'bg-neutral-900 text-white dark:bg-neutral-100 dark:text-neutral-900'
+        }
+    ],
+    defaultVariants: {
+        variant: 'plain',
+        color: 'neutral',
+        elevation: 0,
+        rounded: 'none'
+    }
+});
+
+/**
+ * `<Box>` — the surface primitive of @dashforge/tw.
+ *
+ * What it IS:
+ *   A polymorphic container with typed surface variants (plain /
+ *   outlined / elevated / soft / solid) × 7 intent colours, plus
+ *   spacing / sizing / rounded / elevation as enumerated token-scale
+ *   props. Replaces MUI's Box + Paper + Card + Surface in one component.
+ *
+ * What it is NOT (deliberate, enforced by the prop set):
+ *   • Not a flex container         → use <Stack>
+ *   • Not a grid container         → use <Grid>
+ *   • Not a paragraph              → use <Typography>
+ *   • Not a button                 → use <Button>
+ *
+ * The "Box is not flex" rule is the spine of the layout layer. Without
+ * it, every `<div>` in an app gravitates back to Box and the surface
+ * vs layout distinction collapses. Box's job is the SURFACE around
+ * content; Stack/Grid's job is the ARRANGEMENT of content. Two
+ * primitives, two responsibilities.
+ *
+ * When BOTH `as` and `asChild` are passed, `asChild` wins. Same rule
+ * as Typography — documented to avoid the dimension-bloat of a
+ * discriminated union over an 11-axis props type.
+ *
+ * Layering:
+ *   • Sits BENEATH every visual chrome — every card, every panel,
+ *     every section background.
+ *   • Composes ON TOP of @dashforge/tw-tokens (color + spacing + radius
+ *     + shadow scales) via the dashforgePreset CSS variables.
+ *   • Pairs with Typography for text content, Stack/Grid for layout
+ *     children inside it.
+ */ const Box = /*#__PURE__*/ forwardRef(function Box(props, ref) {
+    const { variant, color, elevation, rounded, p, px, py, m, mx, my, fullWidth, fullHeight, as, asChild = false, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "variant",
+        "color",
+        "elevation",
+        "rounded",
+        "p",
+        "px",
+        "py",
+        "m",
+        "mx",
+        "my",
+        "fullWidth",
+        "fullHeight",
+        "as",
+        "asChild",
+        "sx",
+        "children"
+    ]);
+    const classes = cn(boxVariants({
+        variant,
+        color,
+        elevation,
+        rounded,
+        p,
+        px,
+        py,
+        m,
+        mx,
+        my,
+        fullWidth,
+        fullHeight
+    }), sx);
+    if (asChild) {
+        return jsx(Slot, _extends({
+            ref: ref,
+            className: classes
+        }, rest, {
+            children: children
+        }));
+    }
+    const Tag = as != null ? as : 'div';
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, rest, {
+        children: children
+    }));
+});
+Box.displayName = 'Box';
+
+/**
+ * `stackVariants` — flex container 1D, the layout primitive of @dashforge/tw.
+ *
+ * Architectural role (planned with the user — F9 deep dive):
+ *
+ *   Stack is the ONLY way to do flex in this library. Box is the
+ *   surface (border / bg / shadow); Stack is the arrangement (direction
+ *   / align / justify / gap). Two primitives, two responsibilities,
+ *   zero overlap.
+ *
+ *   This rules out the MUI failure mode where every `<Box display="flex"
+ *   gap={2}>` quietly becomes the de-facto flex container, drowning
+ *   the surface vs layout distinction. Here, if you see `<Stack>` in
+ *   the JSX, you KNOW it's flex; if you see `<Box>`, you KNOW it's
+ *   not. The component name carries the intent.
+ *
+ * Axes:
+ *   • direction         — row / col (+ reverse variants)
+ *   • align / justify   — cross-axis / main-axis alignment
+ *   • gap               — token-scale step (mirror Box spacing scale)
+ *   • wrap              — flex-wrap
+ *   • divider           — runtime-only (handled in Stack.tsx, not here)
+ *
+ * Sizing (`fullWidth`, `fullHeight`) is duplicated from Box because
+ * Stack often plays the role of a full-width strip / full-height
+ * column — re-typing `sx="w-full"` every time would be friction.
+ */ const stackVariants = tv({
+    base: 'flex',
+    variants: {
+        direction: {
+            row: 'flex-row',
+            col: 'flex-col',
+            'row-reverse': 'flex-row-reverse',
+            'col-reverse': 'flex-col-reverse'
+        },
+        align: {
+            start: 'items-start',
+            center: 'items-center',
+            end: 'items-end',
+            stretch: 'items-stretch',
+            baseline: 'items-baseline'
+        },
+        justify: {
+            start: 'justify-start',
+            center: 'justify-center',
+            end: 'justify-end',
+            between: 'justify-between',
+            around: 'justify-around',
+            evenly: 'justify-evenly'
+        },
+        /*
+         * `gap` — explicit literal mapping for the 11 token-scale steps.
+         * Same set as Box's spacing axes (p, m, etc.) so muscle memory
+         * carries over: `<Stack gap={4}>` aligns visually with `<Box p={4}>`.
+         */ gap: {
+            0: 'gap-0',
+            '0.5': 'gap-0.5',
+            1: 'gap-1',
+            2: 'gap-2',
+            3: 'gap-3',
+            4: 'gap-4',
+            6: 'gap-6',
+            8: 'gap-8',
+            12: 'gap-12',
+            16: 'gap-16',
+            24: 'gap-24'
+        },
+        wrap: {
+            true: 'flex-wrap'
+        },
+        fullWidth: {
+            true: 'w-full'
+        },
+        fullHeight: {
+            true: 'h-full'
+        }
+    },
+    defaultVariants: {
+        direction: 'col'
+    }
+});
+
+/**
+ * Walk the children, inserting `divider` BETWEEN every consecutive pair.
+ *
+ * Implementation notes:
+ *   • `React.Children.toArray` assigns auto-keys but does NOT recursively
+ *     flatten Fragments — it treats them as opaque single children. So
+ *     `<Stack><><a/><b/></><c/></Stack>` is 2 boundaries (fragment + c),
+ *     yielding ONE divider. Hoist items out of the fragment when you
+ *     need a divider between them. Documented + asserted in the tests.
+ *   • Dividers are wrapped in `<Fragment>` with a deterministic key
+ *     derived from the boundary index — stable across re-renders so
+ *     React reconciles correctly when children re-order.
+ *   • 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) {
+    const items = Children.toArray(children);
+    if (items.length <= 1) return items;
+    const result = [];
+    items.forEach((child, i)=>{
+        result.push(child);
+        if (i < items.length - 1) {
+            const key = `df-stack-divider-${i}`;
+            if (/*#__PURE__*/ isValidElement(divider)) {
+                result.push(/*#__PURE__*/ cloneElement(divider, {
+                    key
+                }));
+            } else {
+                result.push(jsx(Fragment, {
+                    children: divider
+                }, key));
+            }
+        }
+    });
+    return result;
+}
+/**
+ * `<Stack>` — flex container 1D, the layout primitive.
+ *
+ * This is the ONLY component in @dashforge/tw that does flex. Box
+ * doesn't, Grid does CSS Grid (not flex). The strict naming → engine
+ * mapping is the whole point: when you read `<Stack>` in a JSX tree,
+ * you instantly know it's flex. No `<Box display="flex" ...>` traps.
+ *
+ * Direction defaults to `'col'` (vertical stack) — the most common
+ * case for forms, sidebars, settings panels. Pass `direction="row"`
+ * for horizontal layouts (toolbars, button rows, breadcrumbs).
+ *
+ * The `divider` prop is the runtime-only piece: TV can't encode the
+ * "render this between each child" logic as a class, so we walk the
+ * children at render time. The walk is O(n); for n ≤ ~10 (typical
+ * Stack content) the cost is negligible. For very long Stacks (1000+
+ * items), prefer to render dividers as part of each child instead.
+ *
+ * When `asChild` is true, the divider prop is silently ignored — Slot
+ * requires a single child, and the N-1 insertion has nowhere to act.
+ */ const Stack = /*#__PURE__*/ forwardRef(function Stack(props, ref) {
+    const { direction, align, justify, gap, wrap, fullWidth, fullHeight, divider, as, asChild = false, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "direction",
+        "align",
+        "justify",
+        "gap",
+        "wrap",
+        "fullWidth",
+        "fullHeight",
+        "divider",
+        "as",
+        "asChild",
+        "sx",
+        "children"
+    ]);
+    const classes = cn(stackVariants({
+        direction,
+        align,
+        justify,
+        gap,
+        wrap,
+        fullWidth,
+        fullHeight
+    }), sx);
+    if (asChild) {
+        // Slot expects a single child; divider has no place here.
+        return jsx(Slot, _extends({
+            ref: ref,
+            className: classes
+        }, rest, {
+            children: children
+        }));
+    }
+    const Tag = as != null ? as : 'div';
+    const content = divider != null ? interleaveDividers(children, divider) : children;
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, rest, {
+        children: content
+    }));
+});
+Stack.displayName = 'Stack';
+
+/**
+ * `gridVariants` — CSS Grid container + item, polymorphic in role.
+ *
+ * Architectural choice (planned with the user — F9 deep dive):
+ *
+ *   Pattern is MUI Grid v2 from the API side (`<Grid container>` +
+ *   `<Grid xs={6}>`), but engine is REAL CSS Grid under the hood
+ *   (`display: grid` + `grid-template-columns: repeat(N, 1fr)` +
+ *   `col-span-*`). MUI v2 uses flexbox + basis percentages — historical
+ *   IE11 reasons. In 2026, CSS Grid is universally supported AND
+ *   Tailwind ships `grid-cols-*` / `col-span-*` natively, so flexbox
+ *   would be a downgrade.
+ *
+ * Two distinct shapes coexist in the same TV recipe:
+ *
+ *   • container=true   — display:grid + cols + gap + autoFlow
+ *   • container=false  — col-span at each breakpoint (xs/sm/md/lg/xl)
+ *
+ *   The discriminated union lives in grid.types.ts (TypeScript-level);
+ *   here the TV catalogue exposes every axis so the consumer's choice
+ *   triggers the right classes regardless of which role the component
+ *   is playing. Unused axes produce no classes (TV silently drops
+ *   undefined variants), so a container Grid never accidentally emits
+ *   `col-span-6` and an item Grid never accidentally emits `grid`.
+ *
+ * Mapping table size:
+ *   • cols                  : 6 entries (12, 6, 4, 3, 2, 1)
+ *   • autoFlow              : 5 entries
+ *   • span axes (5×14)      : 70 entries (xs/sm/md/lg/xl × {1..12, auto, full})
+ *   • gap / gapX / gapY     : 33 entries (11 steps × 3 axes)
+ *
+ *   Total: ~115 literal class names. All explicit, all Tailwind-scannable.
+ *   Bundle CSS impact when fully exercised: ~3 KB gz (mostly the
+ *   responsive col-span set).
+ */ const gridVariants = tv({
+    base: '',
+    variants: {
+        // ─── CONTAINER role ────────────────────────────────────────────────
+        container: {
+            true: 'grid'
+        },
+        cols: {
+            1: 'grid-cols-1',
+            2: 'grid-cols-2',
+            3: 'grid-cols-3',
+            4: 'grid-cols-4',
+            6: 'grid-cols-6',
+            12: 'grid-cols-12'
+        },
+        autoFlow: {
+            row: 'grid-flow-row',
+            col: 'grid-flow-col',
+            dense: 'grid-flow-dense',
+            'row-dense': 'grid-flow-row-dense',
+            'col-dense': 'grid-flow-col-dense'
+        },
+        /*
+         * Container gap — token-scale step. Same set as Box/Stack so muscle
+         * memory carries across primitives.
+         */ spacing: {
+            0: 'gap-0',
+            '0.5': 'gap-0.5',
+            1: 'gap-1',
+            2: 'gap-2',
+            3: 'gap-3',
+            4: 'gap-4',
+            6: 'gap-6',
+            8: 'gap-8',
+            12: 'gap-12',
+            16: 'gap-16',
+            24: 'gap-24'
+        },
+        spacingX: {
+            0: 'gap-x-0',
+            '0.5': 'gap-x-0.5',
+            1: 'gap-x-1',
+            2: 'gap-x-2',
+            3: 'gap-x-3',
+            4: 'gap-x-4',
+            6: 'gap-x-6',
+            8: 'gap-x-8',
+            12: 'gap-x-12',
+            16: 'gap-x-16',
+            24: 'gap-x-24'
+        },
+        spacingY: {
+            0: 'gap-y-0',
+            '0.5': 'gap-y-0.5',
+            1: 'gap-y-1',
+            2: 'gap-y-2',
+            3: 'gap-y-3',
+            4: 'gap-y-4',
+            6: 'gap-y-6',
+            8: 'gap-y-8',
+            12: 'gap-y-12',
+            16: 'gap-y-16',
+            24: 'gap-y-24'
+        },
+        // ─── ITEM role — col-span at each breakpoint ──────────────────────
+        /*
+         * `xs` is the base breakpoint (no prefix) — Tailwind's mobile-first
+         * convention. `sm/md/lg/xl` cascade up from there.
+         *
+         * Special values:
+         *   • 'auto' → col-auto (content-sized)
+         *   • 'full' → col-span-full (span all columns regardless of count)
+         */ xs: {
+            1: 'col-span-1',
+            2: 'col-span-2',
+            3: 'col-span-3',
+            4: 'col-span-4',
+            5: 'col-span-5',
+            6: 'col-span-6',
+            7: 'col-span-7',
+            8: 'col-span-8',
+            9: 'col-span-9',
+            10: 'col-span-10',
+            11: 'col-span-11',
+            12: 'col-span-12',
+            auto: 'col-auto',
+            full: 'col-span-full'
+        },
+        sm: {
+            1: 'sm:col-span-1',
+            2: 'sm:col-span-2',
+            3: 'sm:col-span-3',
+            4: 'sm:col-span-4',
+            5: 'sm:col-span-5',
+            6: 'sm:col-span-6',
+            7: 'sm:col-span-7',
+            8: 'sm:col-span-8',
+            9: 'sm:col-span-9',
+            10: 'sm:col-span-10',
+            11: 'sm:col-span-11',
+            12: 'sm:col-span-12',
+            auto: 'sm:col-auto',
+            full: 'sm:col-span-full'
+        },
+        md: {
+            1: 'md:col-span-1',
+            2: 'md:col-span-2',
+            3: 'md:col-span-3',
+            4: 'md:col-span-4',
+            5: 'md:col-span-5',
+            6: 'md:col-span-6',
+            7: 'md:col-span-7',
+            8: 'md:col-span-8',
+            9: 'md:col-span-9',
+            10: 'md:col-span-10',
+            11: 'md:col-span-11',
+            12: 'md:col-span-12',
+            auto: 'md:col-auto',
+            full: 'md:col-span-full'
+        },
+        lg: {
+            1: 'lg:col-span-1',
+            2: 'lg:col-span-2',
+            3: 'lg:col-span-3',
+            4: 'lg:col-span-4',
+            5: 'lg:col-span-5',
+            6: 'lg:col-span-6',
+            7: 'lg:col-span-7',
+            8: 'lg:col-span-8',
+            9: 'lg:col-span-9',
+            10: 'lg:col-span-10',
+            11: 'lg:col-span-11',
+            12: 'lg:col-span-12',
+            auto: 'lg:col-auto',
+            full: 'lg:col-span-full'
+        },
+        xl: {
+            1: 'xl:col-span-1',
+            2: 'xl:col-span-2',
+            3: 'xl:col-span-3',
+            4: 'xl:col-span-4',
+            5: 'xl:col-span-5',
+            6: 'xl:col-span-6',
+            7: 'xl:col-span-7',
+            8: 'xl:col-span-8',
+            9: 'xl:col-span-9',
+            10: 'xl:col-span-10',
+            11: 'xl:col-span-11',
+            12: 'xl:col-span-12',
+            auto: 'xl:col-auto',
+            full: 'xl:col-span-full'
+        }
+    }
+});
+
+/**
+ * `<Grid>` — CSS Grid container + item, polymorphic in role.
+ *
+ * API surface mirrors MUI Grid v2:
+ *   • <Grid container spacing={4} cols={12}>          ← container
+ *   • <Grid xs={12} md={6}>                           ← item
+ *
+ * Engine is REAL CSS Grid (not flexbox, unlike MUI v2 internals).
+ * Benefits over flexbox-based implementation:
+ *   • Native `gap` (no negative-margin tricks)
+ *   • `col-span-N` maps directly to `grid-column: span N`
+ *   • Vertical alignment without manual `align-items` per item
+ *   • Auto-flow for dense packing without DOM gymnastics
+ *
+ * TypeScript discriminated union (see grid.types.ts) makes mixing
+ * impossible: `<Grid container xs={6}>` won't compile. Same for the
+ * inverse. IntelliSense filters by role.
+ *
+ * Defaults at the component level (not at the TV level — see the
+ * variants file for the rationale):
+ *   • container: cols defaults to 12 (MUI convention)
+ *   • item:      xs defaults to 'full' so a forgotten prop doesn't
+ *                collapse the cell to 1/12th of a row
+ *
+ * `asChild` on a CONTAINER is technically allowed but rarely useful:
+ * `display:grid` only applies to direct children, so the slotted
+ * element has to already be a viable container parent. Use sparingly;
+ * test asserts the wrapping still emits the right class chain.
+ */ const Grid = /*#__PURE__*/ forwardRef(function Grid(props, ref) {
+    const { as, asChild = false, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "as",
+        "asChild",
+        "sx",
+        "children"
+    ]);
+    /*
+     * Discriminated union runtime branch.
+     *
+     * TS narrows GridProps to ONE of the two shapes (container or item)
+     * at the call site, but inside this function body we receive the
+     * union — so we manually narrow via a single cast per branch.
+     * `as GridContainerProps` / `as GridItemProps` is sound because
+     * `container === true` is the literal discriminator declared in
+     * the types file; the cast just makes TS read the right branch.
+     */ const isContainer = props.container === true;
+    let classes;
+    let containerPayload = null;
+    let itemPayload = null;
+    if (isContainer) {
+        var _containerPayload_cols;
+        containerPayload = props;
+        /*
+         * Container branch — pass ONLY container axes to TV. Default cols
+         * to 12 (MUI v2 convention) so a forgotten prop doesn't collapse
+         * to grid-cols-1. The spacing axes are passed straight through;
+         * TV silently drops undefined values.
+         */ classes = cn(gridVariants({
+            container: true,
+            cols: (_containerPayload_cols = containerPayload.cols) != null ? _containerPayload_cols : 12,
+            spacing: containerPayload.spacing,
+            spacingX: containerPayload.spacingX,
+            spacingY: containerPayload.spacingY,
+            autoFlow: containerPayload.autoFlow
+        }), sx);
+    } else {
+        var _itemPayload_xs;
+        itemPayload = props;
+        /*
+         * Item branch — default `xs` to 'full' so a forgotten breakpoint
+         * prop doesn't collapse the cell to grid-auto's minimum width.
+         */ classes = cn(gridVariants({
+            xs: (_itemPayload_xs = itemPayload.xs) != null ? _itemPayload_xs : 'full',
+            sm: itemPayload.sm,
+            md: itemPayload.md,
+            lg: itemPayload.lg,
+            xl: itemPayload.xl
+        }), sx);
+    }
+    /*
+     * Strip role-specific props from `rest` before spreading on the DOM
+     * element. Without this, React warns:
+     *   "React does not recognize the `cols` prop on a DOM element"
+     */ const domRest = _extends({}, rest);
+    if (containerPayload) {
+        delete domRest.cols;
+        delete domRest.spacing;
+        delete domRest.spacingX;
+        delete domRest.spacingY;
+        delete domRest.autoFlow;
+    }
+    if (itemPayload) {
+        delete domRest.xs;
+        delete domRest.sm;
+        delete domRest.md;
+        delete domRest.lg;
+        delete domRest.xl;
+    }
+    // `container` discriminator itself must never reach the DOM.
+    delete domRest.container;
+    if (asChild) {
+        return jsx(Slot, _extends({
+            ref: ref,
+            className: classes
+        }, domRest, {
+            children: children
+        }));
+    }
+    const Tag = as != null ? as : 'div';
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, domRest, {
+        children: children
+    }));
+});
+Grid.displayName = 'Grid';
+
+/**
+ * `containerVariants` — centered max-width wrapper for page layouts.
+ *
+ * Architectural role:
+ *
+ *   Every web app has the same pattern at the page-root level: a div
+ *   that's `mx-auto`, capped at some `max-w-*`, with responsive
+ *   horizontal padding. Without Container, every page rewrites:
+ *
+ *     <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+ *
+ *   Container collapses that into one typed prop set, with size names
+ *   that mirror Tailwind's breakpoint vocabulary so the muscle memory
+ *   carries over (`size="lg"` ↔ `max-w-screen-lg`).
+ *
+ * Size axis — maps to Tailwind's `max-w-screen-*` aliases:
+ *   • sm     → max-w-screen-sm     (640px)
+ *   • md     → max-w-screen-md     (768px)
+ *   • lg     → max-w-screen-lg     (1024px) — most common doc/content cap
+ *   • xl     → max-w-screen-xl     (1280px) — default; comfortable for full apps
+ *   • 2xl    → max-w-screen-2xl    (1536px) — wide dashboards
+ *   • fluid  → no max-width at all (full bleed, padding still applies)
+ *
+ * Padding axis (`px`):
+ *   • true (default) — responsive horizontal padding (px-4 sm:px-6 lg:px-8)
+ *     The canonical Tailwind responsive padding ramp. Designed to keep
+ *     edges from kissing the viewport on mobile and breathing more on
+ *     larger screens.
+ *   • false — no padding. Use when the consumer wants full bleed AND
+ *     handles edge padding inside (e.g. a hero section with its own
+ *     internal spacing scale).
+ *
+ * Center content axis (`centerContent`):
+ *   • true  — turns the Container into a flex column with items-center
+ *     so the page content stacks centered horizontally. Common for
+ *     marketing pages, sign-in flows, "single artifact" layouts.
+ *   • false (default) — children flow normally (block stacking).
+ */ const containerVariants = tv({
+    base: 'mx-auto w-full',
+    variants: {
+        size: {
+            sm: 'max-w-screen-sm',
+            md: 'max-w-screen-md',
+            lg: 'max-w-screen-lg',
+            xl: 'max-w-screen-xl',
+            '2xl': 'max-w-screen-2xl',
+            fluid: ''
+        },
+        /*
+         * Responsive padding ramp. `false` skips it entirely so the
+         * consumer can supply custom padding via `sx` when needed.
+         */ px: {
+            true: 'px-4 sm:px-6 lg:px-8',
+            false: ''
+        },
+        /*
+         * Stacks children centered. Mutually compatible with all sizes —
+         * a fluid container with centerContent is the canonical "marketing
+         * hero" layout.
+         */ centerContent: {
+            true: 'flex flex-col items-center',
+            false: ''
+        }
+    },
+    defaultVariants: {
+        size: 'xl',
+        px: true,
+        centerContent: false
+    }
+});
+
+/**
+ * `<Container>` — centered max-width wrapper for page-level layouts.
+ *
+ * The pattern is universal: every page-root `<div>` in a non-trivial
+ * web app boils down to "mx-auto + max-w-X + responsive horizontal
+ * padding". Container collapses that into a typed prop set so the
+ * decision lives in ONE place per app section (the Container size),
+ * not scattered as utility chains across every page file.
+ *
+ * Default size is `'xl'` (1280px) — comfortable for full app shells
+ * with a left nav + main + optional right rail. Drop to `'lg'` (1024px)
+ * for content-heavy docs/marketing, jump to `'2xl'` (1536px) for wide
+ * dashboards.
+ *
+ * Composition pattern — Container at the page root, Stack/Grid inside:
+ *
+ *   <Container size="lg" as="main">
+ *     <Stack gap={8}>
+ *       <Typography variant="h1">Page title</Typography>
+ *       <Grid container spacing={6}>
+ *         <Grid xs={12} md={6}>...</Grid>
+ *       </Grid>
+ *     </Stack>
+ *   </Container>
+ *
+ * Container handles the page chrome (centered, padded, capped width);
+ * Stack/Grid handle the actual layout of children. Two concerns, two
+ * primitives.
+ *
+ * Polymorphism rule (same as Typography/Box/Stack/Grid): when both
+ * `as` and `asChild` are passed, `asChild` wins.
+ */ const Container = /*#__PURE__*/ forwardRef(function Container(props, ref) {
+    const { size, px, centerContent, as, asChild = false, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "size",
+        "px",
+        "centerContent",
+        "as",
+        "asChild",
+        "sx",
+        "children"
+    ]);
+    const classes = cn(containerVariants({
+        size,
+        px,
+        centerContent
+    }), sx);
+    if (asChild) {
+        return jsx(Slot, _extends({
+            ref: ref,
+            className: classes
+        }, rest, {
+            children: children
+        }));
+    }
+    const Tag = as != null ? as : 'div';
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, rest, {
+        children: children
+    }));
+});
+Container.displayName = 'Container';
+
+/**
+ * `dividerVariants` — visual separator with two rendering modes (line-only
+ * vs labeled). Two interconnected TV recipes:
+ *
+ *   • `dividerVariants`      — root container (block layout, alignment)
+ *   • `dividerLineVariants`  — the actual line segments (border style,
+ *                              color, orientation)
+ *
+ * Two recipes (not one with slots) because the labeled mode renders
+ * THREE elements (left line · label · right line) while the line-only
+ * mode is ONE element. Splitting keeps each TV catalogue small and
+ * the type unions narrow.
+ *
+ * Mental model:
+ *   • Without `children` → renders an `<hr>` (or a div if vertical)
+ *     with the line styles applied directly.
+ *   • With `children`    → renders a flex row with two `<span>` line
+ *     segments either side of the label. The label's flex-shrink keeps
+ *     it from being squashed; the line segments share the remaining
+ *     space according to `align`.
+ *
+ * a11y: the root always carries `role="separator"` + `aria-orientation`
+ * — handled in Divider.tsx, not in TV (it's a prop, not a class).
+ */ /*
+ * Root container — only relevant when label is present (flex layout).
+ * For line-only, the root IS the line.
+ */ const dividerVariants = tv({
+    base: 'flex items-center',
+    variants: {
+        orientation: {
+            horizontal: 'w-full',
+            vertical: 'h-full flex-col'
+        },
+        /*
+         * Label alignment along the divider's main axis. Implemented by
+         * setting the flex-basis of the two line segments asymmetrically
+         * — handled in the variants for `dividerLineVariants` below via
+         * compound logic. The root just needs the flex layout.
+         */ align: {
+            start: '',
+            center: '',
+            end: ''
+        }
+    },
+    defaultVariants: {
+        orientation: 'horizontal',
+        align: 'center'
+    }
+});
+/*
+ * Line segment(s).
+ *
+ * Border styles (solid/dashed/dotted) are applied as `border-t-{style}`
+ * for horizontal, `border-l-{style}` for vertical. Color drives the
+ * 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).
+ */ const dividerLineVariants = tv({
+    base: '',
+    variants: {
+        orientation: {
+            horizontal: 'h-0 border-t',
+            vertical: 'w-0 border-l self-stretch'
+        },
+        variant: {
+            solid: 'border-solid',
+            dashed: 'border-dashed',
+            dotted: 'border-dotted'
+        },
+        color: {
+            neutral: 'border-neutral-200 dark:border-neutral-800',
+            primary: 'border-primary-300 dark:border-primary-700',
+            secondary: 'border-secondary-300 dark:border-secondary-700',
+            success: 'border-success-300 dark:border-success-700',
+            warning: 'border-warning-300 dark:border-warning-700',
+            danger: 'border-danger-300 dark:border-danger-700',
+            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: {
+            full: 'w-full',
+            grow: 'flex-1'
+        }
+    },
+    defaultVariants: {
+        orientation: 'horizontal',
+        variant: 'solid',
+        color: 'neutral',
+        segment: 'full'
+    }
+});
+
+/**
+ * `<Divider>` — visual separator. Two modes:
+ *
+ *   1. Line-only (no children):
+ *
+ *        <Divider />
+ *      →  <hr role="separator" aria-orientation="horizontal" />
+ *
+ *      Renders a single horizontal line via `border-t-*` on an `<hr>`
+ *      (which by default has no `display`, no margin in our reset, just
+ *      acts as the border carrier).
+ *
+ *   2. Labeled (with children):
+ *
+ *        <Divider><Typography variant="overline">OR</Typography></Divider>
+ *      →  <div role="separator" aria-orientation="horizontal">
+ *           <span aria-hidden className="flex-1 border-t" />
+ *           <span className="px-3">OR</span>
+ *           <span aria-hidden className="flex-1 border-t" />
+ *         </div>
+ *
+ *      Two line segments share the available space; the label sits
+ *      between them with horizontal padding for breathing room. Each
+ *      line segment is `aria-hidden` (the role="separator" on the root
+ *      conveys the separator semantics — duplicating it would confuse
+ *      screen readers).
+ *
+ * Alignment:
+ *   • align="start"  → label hugs the left, right segment grows
+ *   • align="center" (default) → both segments equal
+ *   • align="end"    → label hugs the right, left segment grows
+ *
+ *   Implemented by setting `flex-basis: 0` to either segment to keep
+ *   it minimal. We use `basis-[2rem]` (32px short stub) rather than
+ *   `basis-0` so a tiny line still hints at the divider on the squashed
+ *   side — pure flex-1 vs basis-0 would collapse it invisibly.
+ *
+ * Vertical orientation:
+ *   The line orientation flips (border-l instead of border-t). Vertical
+ *   labeled dividers are RARE in practice — supported for parity but
+ *   the typical use is line-only between flex row items.
+ *
+ * a11y:
+ *   • Root element gets `role="separator"` (or implicit via `<hr>`)
+ *   • `aria-orientation` is set explicitly so AT knows the axis
+ *   • Labeled mode: label has no extra role; the visual layout speaks
+ */ const Divider = /*#__PURE__*/ forwardRef(function Divider(props, ref) {
+    const { orientation = 'horizontal', align = 'center', variant = 'solid', color = 'neutral', children, flexItem, sx } = props, rest = _object_without_properties_loose(props, [
+        "orientation",
+        "align",
+        "variant",
+        "color",
+        "children",
+        "flexItem",
+        "sx"
+    ]);
+    // ─── Mode 1: line-only (no children) ─────────────────────────────
+    if (children == null) {
+        const lineClasses = cn(dividerLineVariants({
+            orientation,
+            variant,
+            color,
+            segment: 'full'
+        }), sx);
+        // Horizontal → <hr>: zero default styling once we strip the UA
+        // default `<hr>` border via `border-0` (in `dividerLineVariants`
+        // base) and apply our own `border-t-*`. Vertical → <div> because
+        // <hr> can't be vertical cross-browser-consistently.
+        if (orientation === 'horizontal') {
+            return jsx("hr", _extends({
+                ref: ref,
+                role: "separator",
+                "aria-orientation": "horizontal",
+                className: cn('border-0', lineClasses)
+            }, rest));
+        }
+        return jsx("div", _extends({
+            ref: ref,
+            role: "separator",
+            "aria-orientation": "vertical",
+            className: lineClasses
+        }, rest));
+    }
+    // ─── Mode 2: labeled (with children) ─────────────────────────────
+    const rootClasses = cn(dividerVariants({
+        orientation,
+        align
+    }), sx);
+    /*
+     * Segment widths per `align`:
+     *   • center → both flex-1 (equal share)
+     *   • start  → left short stub, right grows
+     *   • end    → left grows, right short stub
+     *
+     * "Short stub" = 2rem so the divider visually exists on the squashed
+     * side without dominating the label.
+     */ const isHorizontal = orientation === 'horizontal';
+    const leftStubClass = align === 'start' ? isHorizontal ? 'basis-8 grow-0' : 'basis-8 grow-0' : 'flex-1';
+    const rightStubClass = align === 'end' ? isHorizontal ? 'basis-8 grow-0' : 'basis-8 grow-0' : 'flex-1';
+    const lineCommon = dividerLineVariants({
+        orientation,
+        variant,
+        color,
+        segment: 'grow'
+    });
+    const labelPadding = isHorizontal ? 'px-3' : 'py-3';
+    return jsxs("div", _extends({
+        ref: ref,
+        role: "separator",
+        "aria-orientation": orientation,
+        className: rootClasses
+    }, rest, {
+        children: [
+            jsx("span", {
+                "aria-hidden": "true",
+                className: cn(lineCommon, leftStubClass)
+            }),
+            jsx("span", {
+                className: cn('shrink-0 text-sm text-neutral-500 dark:text-neutral-400', labelPadding),
+                children: children
+            }),
+            jsx("span", {
+                "aria-hidden": "true",
+                className: cn(lineCommon, rightStubClass)
+            })
+        ]
+    }));
+});
+Divider.displayName = 'Divider';
+
+/**
+ * `<AspectRatio>` — locks the aspect ratio of its child container,
+ * regardless of width. The classic use is responsive images and
+ * embedded media: an `<img>` that takes 100% of the available width
+ * but always renders at 16:9 (or 1:1, or whatever the source ratio is)
+ * — no jumping layouts during image load, no whitespace below the
+ * media, no JS measurement.
+ *
+ * Implementation: native CSS `aspect-ratio` property. Supported in
+ * every browser shipped from 2021 onward (Chrome 88, Firefox 89,
+ * Safari 15, Edge 88). No padding-bottom hack — that workaround
+ * predates the native property and brings ugly absolute-positioning
+ * requirements on the child.
+ *
+ * Why a component if it's "just one CSS property"?
+ *   Two reasons:
+ *     1. Discoverability — `<AspectRatio ratio={16/9}>` documents the
+ *        intent at the call site. `style={{ aspectRatio: '16/9' }}` is
+ *        the same thing functionally, but harder to spot in a 200-line
+ *        component file.
+ *     2. Composition — pairs naturally with `sx="rounded-xl overflow-hidden"`
+ *        for the canonical "rounded clipped media" pattern. Forgetting
+ *        the `overflow-hidden` is the #1 mistake we want to prevent
+ *        through documentation (it's in this component's MDX, at the
+ *        top of the Notes).
+ *
+ * Child contract:
+ *   The single child is expected to fill the container — typically
+ *   `<img>` / `<video>` with `className="w-full h-full object-cover"`.
+ *   We don't force this via CSS (the consumer might want a centered
+ *   icon instead of a filling image) — but it's the 99% case, and the
+ *   docs show it first.
+ */ const AspectRatio = /*#__PURE__*/ forwardRef(function AspectRatio(props, ref) {
+    const { ratio = 1, as, sx, style, children } = props, rest = _object_without_properties_loose(props, [
+        "ratio",
+        "as",
+        "sx",
+        "style",
+        "children"
+    ]);
+    /*
+     * Normalise to a CSS `aspect-ratio` string. The CSS property
+     * accepts both `16/9` and `16 / 9` (with spaces), but for safety
+     * we convert numbers to the canonical `N / 1` form — `aspectRatio: 1.7777`
+     * works too, but produces an arbitrary-looking value in DevTools.
+     */ const aspectRatioValue = typeof ratio === 'number' ? `${ratio} / 1` : ratio;
+    const mergedStyle = _extends({
+        aspectRatio: aspectRatioValue
+    }, style);
+    const classes = cn('w-full', sx);
+    const Tag = as != null ? as : 'div';
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes,
+        style: mergedStyle
+    }, rest, {
+        children: children
+    }));
+});
+AspectRatio.displayName = 'AspectRatio';
+
+/**
+ * `<VisuallyHidden>` — the accessibility primitive.
+ *
+ * Hides children from sighted users (zero pixels rendered, no layout
+ * impact) while keeping them in the accessibility tree. Screen readers
+ * speak the content; voice control software uses it for click targets;
+ * keyboard users see nothing — same as if it weren't there.
+ *
+ * Implementation: Tailwind's built-in `sr-only` utility, which expands to:
+ *
+ *   .sr-only {
+ *     position: absolute;
+ *     width: 1px;
+ *     height: 1px;
+ *     padding: 0;
+ *     margin: -1px;
+ *     overflow: hidden;
+ *     clip: rect(0,0,0,0);
+ *     white-space: nowrap;
+ *     border-width: 0;
+ *   }
+ *
+ * This is the canonical "visually-hidden but screen-reader-accessible"
+ * pattern, also known as the WebAIM clip technique. Critically:
+ *
+ *   • NOT `display: none` (removes from a11y tree)
+ *   • NOT `visibility: hidden` (also removes from a11y tree)
+ *   • NOT `opacity: 0` (technically still rendered, doesn't help AT)
+ *   • NOT `width/height: 0` (collapses, some AT skips it)
+ *
+ * Default tag is `<span>` (inline) — the 99% case is "label inside a
+ * button or link". For block content, override with `as="div"`, but
+ * be aware nesting block inside inline is invalid HTML.
+ *
+ * The component is intentionally tiny (~30 LoC total): one className,
+ * one tag. The value is the COMPONENT NAME — `<VisuallyHidden>` reads
+ * as an intentional a11y decision in code review, while
+ * `className="sr-only"` looks like a typo or a forgotten utility.
+ */ const VisuallyHidden = /*#__PURE__*/ forwardRef(function VisuallyHidden(props, ref) {
+    const { as, sx, children } = props, rest = _object_without_properties_loose(props, [
+        "as",
+        "sx",
+        "children"
+    ]);
+    const Tag = as != null ? as : 'span';
+    const classes = cn('sr-only', sx);
+    return jsx(Tag, _extends({
+        ref: ref,
+        className: classes
+    }, rest, {
+        children: children
+    }));
+});
+VisuallyHidden.displayName = 'VisuallyHidden';
+
 /**
  * @dashforge/tw
  *
@@ -4953,6 +6550,6 @@ const SnackbarContext = /*#__PURE__*/ createContext(null);
  */ // ───── Components ─────
 /**
  * Package version (synced with `package.json` at publish time).
- */ const VERSION = '0.1.0-beta';
+ */ const VERSION = '0.2.1-beta';
 
-export { AppShell, Autocomplete, Breadcrumbs, Button, Checkbox, ConfirmDialogProvider, DateTimePicker, LeftNav, NumberField, OTPField, RadioGroup, SnackbarProvider, Switch, TextField, Textarea, TopBar, VERSION, appShellVariants, autocompleteVariants, breadcrumbsVariants, buttonVariants, checkboxVariants, cn, confirmDialogVariants, dateTimePickerVariants, isoToInputValue, leftNavVariants, numberFieldVariants, otpFieldVariants, radioGroupVariants, snackbarVariants, switchVariants, textFieldVariants, textareaVariants, topBarVariants, useAccessState, useConfirm, useSnackbar };
+export { AppShell, AspectRatio, Autocomplete, Box, Breadcrumbs, Button, Checkbox, ConfirmDialogProvider, Container, DateTimePicker, Divider, Grid, LeftNav, NumberField, OTPField, RadioGroup, SnackbarProvider, Stack, Switch, TextField, Textarea, TopBar, Typography, VERSION, VisuallyHidden, appShellVariants, autocompleteVariants, boxVariants, breadcrumbsVariants, buttonVariants, checkboxVariants, cn, confirmDialogVariants, containerVariants, dateTimePickerVariants, dividerLineVariants, dividerVariants, gridVariants, isoToInputValue, leftNavVariants, numberFieldVariants, otpFieldVariants, radioGroupVariants, snackbarVariants, stackVariants, switchVariants, textFieldVariants, textareaVariants, topBarVariants, typographyVariants, useAccessState, useConfirm, useSnackbar };