@dashforge/tw 1.0.0 → 1.1.1

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

@@ -1,309 +0,0 @@
-// @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

@@ -1,115 +0,0 @@
-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

@@ -1,68 +0,0 @@
-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;
-}

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

@@ -1,80 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * `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.
- */
-export 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',
-  },
-});
-
-export type StackVariants = VariantProps<typeof stackVariants>;