@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/src/components/Grid/grid.variants.ts

@@ -0,0 +1,133 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `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).
+ */
+export 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',
+    },
+  },
+
+  /*
+   * No `defaultVariants`. The default semantics are role-dependent:
+   *   • container Grid defaults to cols=12 (set in Grid.tsx)
+   *   • item Grid defaults to xs="full" — full-width until a breakpoint
+   *     prop overrides (also set in Grid.tsx)
+   * Encoding these defaults at the TV level would emit them even when
+   * irrelevant (e.g. an item Grid never wants `grid grid-cols-12`).
+   */
+});
+
+export type GridVariants = VariantProps<typeof gridVariants>;

package/src/components/Stack/Stack.test.tsx

@@ -0,0 +1,309 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Stack } from './Stack.js';
+
+describe('<Stack>', () => {
+  // ─── Default rendering ──────────────────────────────────────────────
+  describe('default rendering', () => {
+    it('renders a <div> by default', () => {
+      const { container } = render(<Stack>x</Stack>);
+      expect(container.firstElementChild?.tagName).toBe('DIV');
+    });
+
+    it('has flex + flex-col by default', () => {
+      const { container } = render(<Stack>x</Stack>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('flex');
+      expect(cls).toContain('flex-col');
+    });
+  });
+
+  // ─── Direction ──────────────────────────────────────────────────────
+  describe('direction', () => {
+    it('row', () => {
+      const { container } = render(<Stack direction="row">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-row');
+    });
+
+    it('row-reverse', () => {
+      const { container } = render(<Stack direction="row-reverse">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-row-reverse');
+    });
+  });
+
+  // ─── Align + justify ────────────────────────────────────────────────
+  describe('align + justify', () => {
+    it('align="center" + justify="between"', () => {
+      const { container } = render(
+        <Stack align="center" justify="between">x</Stack>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('items-center');
+      expect(cls).toContain('justify-between');
+    });
+
+    it('align="baseline"', () => {
+      const { container } = render(<Stack align="baseline">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('items-baseline');
+    });
+  });
+
+  // ─── Gap + wrap + sizing ────────────────────────────────────────────
+  describe('gap + wrap + sizing', () => {
+    it('gap={4} emits gap-4', () => {
+      const { container } = render(<Stack gap={4}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain('gap-4');
+    });
+
+    it('gap={"0.5"} emits gap-0.5', () => {
+      const { container } = render(<Stack gap="0.5">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('gap-0.5');
+    });
+
+    it('wrap emits flex-wrap', () => {
+      const { container } = render(<Stack wrap>x</Stack>);
+      expect(container.firstElementChild?.className).toContain('flex-wrap');
+    });
+
+    it('fullWidth + fullHeight', () => {
+      const { container } = render(<Stack fullWidth fullHeight>x</Stack>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('w-full');
+      expect(cls).toContain('h-full');
+    });
+  });
+
+  // ─── Divider ─────────────────────────────────────────────────────────
+  describe('divider', () => {
+    it('inserts N-1 dividers between N children', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>a</span>
+          <span>b</span>
+          <span>c</span>
+        </Stack>,
+      );
+      // 3 children + 2 dividers
+      expect(container.firstElementChild?.children.length).toBe(5);
+      const dividers = container.querySelectorAll('[data-testid="div"]');
+      expect(dividers.length).toBe(2);
+    });
+
+    it('does NOT insert dividers when there is only one child', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>only</span>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.children.length).toBe(1);
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(0);
+    });
+
+    it('treats a Fragment as a single child for divider boundary counting', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <>
+            <span>a</span>
+            <span>b</span>
+          </>
+          <span>c</span>
+        </Stack>,
+      );
+      // React.Children.toArray does NOT recursively flatten fragments — it
+      // treats them as opaque single children. Documented behaviour: 2
+      // top-level children → 1 divider between them. If you need a divider
+      // BETWEEN the items inside the fragment, hoist them out of it.
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(1);
+    });
+
+    it('renders string/number divider correctly', () => {
+      const { container } = render(
+        <Stack divider=" · ">
+          <span>a</span>
+          <span>b</span>
+          <span>c</span>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.textContent).toBe('a · b · c');
+    });
+
+    it('asChild silently ignores divider', () => {
+      const { container } = render(
+        <Stack asChild divider={<hr data-testid="div" />}>
+          <nav>
+            <a href="#">link</a>
+          </nav>
+        </Stack>,
+      );
+      // Slot wraps a single child — divider has nowhere to go
+      expect(container.firstElementChild?.tagName).toBe('NAV');
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(0);
+    });
+  });
+
+  // ─── Override + sx ──────────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over variant defaults', () => {
+      const { container } = render(
+        <Stack direction="row" sx="flex-col">x</Stack>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('flex-col');
+      expect(cls).not.toContain('flex-row');
+    });
+
+    it('sx can add utilities Stack does not expose (overflow)', () => {
+      const { container } = render(<Stack sx="overflow-x-auto">x</Stack>);
+      expect(container.firstElementChild?.className).toContain('overflow-x-auto');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('as="nav" renders a <nav>', () => {
+      const { container } = render(<Stack as="nav">x</Stack>);
+      expect(container.firstElementChild?.tagName).toBe('NAV');
+    });
+
+    it('asChild wins over as', () => {
+      const { container } = render(
+        <Stack as="nav" asChild>
+          <header>x</header>
+        </Stack>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('HEADER');
+    });
+  });
+
+  // ─── Pass-through ────────────────────────────────────────────────────
+  it('forwards data-* + aria-*', () => {
+    const { container } = render(
+      <Stack data-testid="s" aria-label="settings">x</Stack>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.getAttribute('data-testid')).toBe('s');
+    expect(el?.getAttribute('aria-label')).toBe('settings');
+  });
+
+  // ─── F11-bis edge cases: divider with array / null / mixed children ─
+  describe('divider edge cases', () => {
+    it('children passed as an array still gets N-1 dividers', () => {
+      // Children.toArray handles arrays the same as iterated siblings —
+      // the divider count is items.length - 1 regardless of how the
+      // children were passed in.
+      const items = ['a', 'b', 'c', 'd'];
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          {items.map((t) => <span key={t}>{t}</span>)}
+        </Stack>,
+      );
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(3);
+    });
+
+    it('null children are stripped before divider insertion', () => {
+      // React's Children.toArray filters out null/undefined/false before
+      // returning the flat array — so a conditional child collapses to
+      // nothing and dividers are sized to the remaining set.
+      const showB = false;
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          <span>a</span>
+          {showB && <span>b</span>}
+          <span>c</span>
+        </Stack>,
+      );
+      // After stripping `false`: 2 effective children → 1 divider
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(1);
+    });
+
+    it('mixed text + element children — divider between EVERY pair', () => {
+      const { container } = render(
+        <Stack divider={<hr data-testid="div" />}>
+          {'plain string'}
+          <span>element child</span>
+          {42}
+          <span>last</span>
+        </Stack>,
+      );
+      // 4 effective children (Children.toArray wraps primitives) → 3 dividers
+      expect(container.querySelectorAll('[data-testid="div"]').length).toBe(3);
+    });
+
+    it('nested Stack inside Stack with divider — inner Stack counts as 1 child', () => {
+      const { container } = render(
+        <Stack gap={2} divider={<hr data-testid="outer-div" />}>
+          <span>top</span>
+          <Stack gap={1} direction="row">
+            <span>nested-a</span>
+            <span>nested-b</span>
+          </Stack>
+          <span>bottom</span>
+        </Stack>,
+      );
+      // Outer has 3 effective children → 2 outer dividers
+      expect(container.querySelectorAll('[data-testid="outer-div"]').length).toBe(2);
+    });
+
+    it('divider key is stable across re-renders (no key warning)', () => {
+      // Re-rendering with the same children + divider shouldn't produce
+      // React key warnings. We assert nothing throws + the structure is
+      // identical to a single render.
+      const { container, rerender } = render(
+        <Stack divider={<hr data-testid="d" />}>
+          <span>a</span>
+          <span>b</span>
+        </Stack>,
+      );
+      const firstRender = container.innerHTML;
+      rerender(
+        <Stack divider={<hr data-testid="d" />}>
+          <span>a</span>
+          <span>b</span>
+        </Stack>,
+      );
+      expect(container.innerHTML).toBe(firstRender);
+    });
+  });
+
+  // ─── F11-bis edge cases: gap value coverage ─────────────────────────
+  describe('gap — every token step', () => {
+    const GAPS = [0, '0.5', 1, 2, 3, 4, 6, 8, 12, 16, 24] as const;
+    it.each(GAPS)('gap=%s emits gap-%s', (g) => {
+      const { container } = render(<Stack gap={g}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`gap-${g}`);
+    });
+  });
+
+  // ─── F11-bis edge cases: align / justify all values ─────────────────
+  describe('align + justify — all valid values', () => {
+    const ALIGNS = ['start', 'center', 'end', 'stretch', 'baseline'] as const;
+    const JUSTIFIES = ['start', 'center', 'end', 'between', 'around', 'evenly'] as const;
+
+    it.each(ALIGNS)('align="%s"', (v) => {
+      const { container } = render(<Stack align={v}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`items-${v}`);
+    });
+
+    it.each(JUSTIFIES)('justify="%s"', (v) => {
+      const { container } = render(<Stack justify={v}>x</Stack>);
+      expect(container.firstElementChild?.className).toContain(`justify-${v}`);
+    });
+  });
+
+  // ─── F11-bis edge cases: empty Stack ────────────────────────────────
+  describe('empty Stack', () => {
+    it('renders an empty div with flex classes', () => {
+      const { container } = render(<Stack gap={4} />);
+      const el = container.firstElementChild;
+      expect(el?.children.length).toBe(0);
+      expect(el?.className).toContain('flex');
+      expect(el?.className).toContain('gap-4');
+    });
+
+    it('empty Stack with divider does NOT render the divider', () => {
+      const { container } = render(<Stack divider={<hr data-testid="d" />} />);
+      expect(container.querySelectorAll('[data-testid="d"]').length).toBe(0);
+    });
+  });
+});

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,115 @@
+import {
+  Children,
+  Fragment,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  type ElementType,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { stackVariants } from './stack.variants.js';
+import type { StackProps } from './stack.types.js';
+
+/**
+ * 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: ReactNode, divider: ReactNode): ReactNode[] {
+  const items = Children.toArray(children);
+  if (items.length <= 1) return items;
+
+  const result: ReactNode[] = [];
+  items.forEach((child, i) => {
+    result.push(child);
+    if (i < items.length - 1) {
+      const key = `df-stack-divider-${i}`;
+      if (isValidElement(divider)) {
+        result.push(cloneElement(divider as ReactElement<{ key?: string }>, { key }));
+      } else {
+        result.push(<Fragment key={key}>{divider}</Fragment>);
+      }
+    }
+  });
+  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.
+ */
+export const Stack = forwardRef<HTMLElement, StackProps>(
+  function Stack(props, ref) {
+    const {
+      direction,
+      align,
+      justify,
+      gap,
+      wrap,
+      fullWidth,
+      fullHeight,
+      divider,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    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 (
+        <Slot ref={ref} className={classes} {...rest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    const Tag = (as ?? 'div') as ElementType;
+    const content = divider != null ? interleaveDividers(children, divider) : children;
+
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {content}
+      </Tag>
+    );
+  },
+);
+
+Stack.displayName = 'Stack';

package/src/components/Stack/stack.types.ts

@@ -0,0 +1,68 @@
+import type { ElementType, HTMLAttributes, ReactNode } from 'react';
+import type { StackVariants } from './stack.variants.js';
+
+/**
+ * Props for `<Stack>` — flex container 1D, the layout primitive.
+ *
+ * Axes:
+ *   • direction              — flex-direction (default 'col')
+ *   • align                  — items-* (cross-axis)
+ *   • justify                — justify-* (main-axis)
+ *   • gap                    — token-scale spacing step
+ *   • wrap                   — flex-wrap
+ *   • fullWidth/fullHeight   — w-full / h-full
+ *   • divider                — node rendered N-1 times between children
+ *
+ * Polymorphism:
+ *   • as            — override the HTML tag (default 'div')
+ *   • asChild       — render via Radix Slot onto the single child
+ *
+ * What Stack does NOT do (route to other primitives):
+ *   • Surface chrome (border, bg, shadow)   → wrap in <Box>
+ *   • 2D layout (rows AND columns)          → use <Grid>
+ *   • Text styling                          → <Typography>
+ */
+export interface StackProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className'>,
+          Pick<StackVariants,
+            'direction' | 'align' | 'justify' | 'gap' | 'wrap'
+            | 'fullWidth' | 'fullHeight'> {
+  /**
+   * Node rendered N-1 times BETWEEN children — mirror of MUI Stack's
+   * divider prop. Useful for visual separators (a `<hr>`, a thin
+   * `<Box variant="outlined" sx="h-px border-0 border-t">`, an
+   * `<svg>` glyph) that need to follow the flex direction.
+   *
+   * The node is cloned for each insertion via `cloneElement`; pass a
+   * stable element (not a function) for best React reconciliation.
+   * `React.Children.toArray` flattens fragments before the walk, so
+   * `<Stack divider={...}><><...></></Stack>` works as expected.
+   */
+  divider?: ReactNode;
+
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`. Use when the
+   * Stack also has semantic meaning — `<Stack as="nav">` for a nav
+   * bar, `<Stack as="ul">` for a list (children become `<li>` via
+   * native HTML, not by us).
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Stack styles paint onto the single
+   * React child instead of wrapping it. Mutually exclusive with `as`
+   * (when both are passed, `asChild` wins). The `divider` prop is
+   * ignored when `asChild` is true (the Slot pattern wraps a single
+   * node, so the N-1 insertion logic has no place to act).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults.
+   */
+  sx?: string;
+}