@dashforge/tw 0.1.0-beta → 0.2.1-beta

package/src/components/Divider/divider.variants.ts

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

package/src/components/Grid/Grid.test.tsx

@@ -0,0 +1,321 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Grid } from './Grid.js';
+
+/**
+ * Suite covers:
+ *   • Container role  — display:grid + cols + spacing + autoFlow
+ *   • Item role        — col-span at xs/sm/md/lg/xl breakpoints
+ *   • Default semantics — container without cols → 12; item without xs → 'full'
+ *   • Polymorphism     — as / asChild on both roles
+ *   • Override          — sx wins over variant defaults
+ *
+ * We don't enumerate every breakpoint × span (5 × 14 = 70 combos);
+ * spot-checks across xs/md/xl with span 6/auto/full cover the
+ * cascade. If those work, the rest works.
+ */
+describe('<Grid>', () => {
+  // ─── Container role ─────────────────────────────────────────────────
+  describe('container', () => {
+    it('renders display:grid + default cols=12', () => {
+      const { container } = render(<Grid container>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('grid');
+      expect(cls).toContain('grid-cols-12');
+    });
+
+    it('container with cols={6}', () => {
+      const { container } = render(<Grid container cols={6}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain('grid-cols-6');
+    });
+
+    it('spacing={4} emits gap-4', () => {
+      const { container } = render(<Grid container spacing={4}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain('gap-4');
+    });
+
+    it('spacingX + spacingY emit gap-x / gap-y', () => {
+      const { container } = render(
+        <Grid container spacingX={6} spacingY={2}>x</Grid>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('gap-x-6');
+      expect(cls).toContain('gap-y-2');
+    });
+
+    it('autoFlow="dense"', () => {
+      const { container } = render(<Grid container autoFlow="dense">x</Grid>);
+      expect(container.firstElementChild?.className).toContain('grid-flow-dense');
+    });
+  });
+
+  // ─── Item role ──────────────────────────────────────────────────────
+  describe('item', () => {
+    it('item without props defaults to col-span-full (xs="full")', () => {
+      const { container } = render(<Grid>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('col-span-full');
+      // never accidentally a container
+      expect(cls).not.toContain('grid-cols-12');
+      // confirm it's NOT display:grid (no `grid` class)
+      expect(cls.split(' ')).not.toContain('grid');
+    });
+
+    it('item xs={6}', () => {
+      const { container } = render(<Grid xs={6}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain('col-span-6');
+    });
+
+    it('item with responsive cascade xs={12} md={6} lg={4}', () => {
+      const { container } = render(<Grid xs={12} md={6} lg={4}>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('col-span-12');
+      expect(cls).toContain('md:col-span-6');
+      expect(cls).toContain('lg:col-span-4');
+    });
+
+    it('item xs="auto"', () => {
+      const { container } = render(<Grid xs="auto">x</Grid>);
+      expect(container.firstElementChild?.className).toContain('col-auto');
+    });
+
+    it('item sm="full" xl={3}', () => {
+      const { container } = render(<Grid sm="full" xl={3}>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('sm:col-span-full');
+      expect(cls).toContain('xl:col-span-3');
+    });
+  });
+
+  // ─── Composition: container > item ──────────────────────────────────
+  describe('container > item composition', () => {
+    it('container with item children produces the canonical class chain', () => {
+      const { container } = render(
+        <Grid container spacing={4}>
+          <Grid xs={12} md={6}>a</Grid>
+          <Grid xs={12} md={6}>b</Grid>
+        </Grid>,
+      );
+      const root = container.firstElementChild;
+      expect(root?.className).toContain('grid');
+      expect(root?.className).toContain('gap-4');
+      const items = root?.querySelectorAll(':scope > div') ?? [];
+      expect(items.length).toBe(2);
+      items.forEach((item) => {
+        expect(item.className).toContain('col-span-12');
+        expect(item.className).toContain('md:col-span-6');
+      });
+    });
+  });
+
+  // ─── Override + sx ──────────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over default cols on container', () => {
+      const { container } = render(
+        <Grid container sx="grid-cols-4">x</Grid>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('grid-cols-4');
+      // tailwind-merge collapses the default 12 → 4
+      expect(cls).not.toContain('grid-cols-12');
+    });
+
+    it('sx adds utilities Grid does not expose', () => {
+      const { container } = render(<Grid container sx="min-h-screen">x</Grid>);
+      expect(container.firstElementChild?.className).toContain('min-h-screen');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('container as="section" renders <section> + grid classes', () => {
+      const { container } = render(<Grid container as="section">x</Grid>);
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('SECTION');
+      expect(el?.className).toContain('grid');
+    });
+
+    it('item asChild paints onto child element', () => {
+      const { container } = render(
+        <Grid xs={6} asChild>
+          <article>x</article>
+        </Grid>,
+      );
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('ARTICLE');
+      expect(el?.className).toContain('col-span-6');
+    });
+  });
+
+  // ─── DOM cleanliness (no role-specific props leak as HTML attrs) ────
+  describe('DOM cleanliness', () => {
+    it('container props (cols/spacing/autoFlow) do not leak to DOM', () => {
+      const { container } = render(
+        <Grid container cols={4} spacing={2} autoFlow="dense">x</Grid>,
+      );
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.hasAttribute('cols')).toBe(false);
+      expect(el.hasAttribute('spacing')).toBe(false);
+      expect(el.hasAttribute('autoflow')).toBe(false);
+    });
+
+    it('item props (xs/sm/md/lg/xl) do not leak to DOM', () => {
+      const { container } = render(
+        <Grid xs={12} md={6} lg={4}>x</Grid>,
+      );
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.hasAttribute('xs')).toBe(false);
+      expect(el.hasAttribute('md')).toBe(false);
+      expect(el.hasAttribute('lg')).toBe(false);
+    });
+  });
+
+  // ─── F11-bis edge cases: responsive cascade across ALL breakpoints ──
+  // The original suite spot-checked xs/md/lg/sm/xl with a couple of
+  // values each. The publish-validation pass enumerates each breakpoint
+  // for the high-traffic span values (1, 6, 12, auto, full) so a future
+  // mapping-table edit can't silently drop one.
+  describe('responsive cascade — every breakpoint × representative span', () => {
+    const BREAKPOINTS = ['sm', 'md', 'lg', 'xl'] as const;
+
+    it.each(BREAKPOINTS)('breakpoint %s × span=1', (bp) => {
+      const props = { [bp]: 1 as const };
+      const { container } = render(<Grid {...props}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`${bp}:col-span-1`);
+    });
+
+    it.each(BREAKPOINTS)('breakpoint %s × span=6', (bp) => {
+      const props = { [bp]: 6 as const };
+      const { container } = render(<Grid {...props}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`${bp}:col-span-6`);
+    });
+
+    it.each(BREAKPOINTS)('breakpoint %s × span=12', (bp) => {
+      const props = { [bp]: 12 as const };
+      const { container } = render(<Grid {...props}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`${bp}:col-span-12`);
+    });
+
+    it.each(BREAKPOINTS)('breakpoint %s × auto', (bp) => {
+      const props = { [bp]: 'auto' as const };
+      const { container } = render(<Grid {...props}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`${bp}:col-auto`);
+    });
+
+    it.each(BREAKPOINTS)('breakpoint %s × full', (bp) => {
+      const props = { [bp]: 'full' as const };
+      const { container } = render(<Grid {...props}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`${bp}:col-span-full`);
+    });
+
+    it('full cascade xs=12 sm=6 md=4 lg=3 xl=2 emits all five', () => {
+      const { container } = render(
+        <Grid xs={12} sm={6} md={4} lg={3} xl={2}>x</Grid>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('col-span-12');
+      expect(cls).toContain('sm:col-span-6');
+      expect(cls).toContain('md:col-span-4');
+      expect(cls).toContain('lg:col-span-3');
+      expect(cls).toContain('xl:col-span-2');
+    });
+  });
+
+  // ─── F11-bis edge cases: autoFlow all five varianti ─────────────────
+  describe('autoFlow — every value', () => {
+    const FLOWS = ['row', 'col', 'dense', 'row-dense', 'col-dense'] as const;
+    const EXPECTED: Record<typeof FLOWS[number], string> = {
+      row:         'grid-flow-row',
+      col:         'grid-flow-col',
+      dense:       'grid-flow-dense',
+      'row-dense': 'grid-flow-row-dense',
+      'col-dense': 'grid-flow-col-dense',
+    };
+
+    it.each(FLOWS)('autoFlow="%s" emits the right grid-flow-* class', (flow) => {
+      const { container } = render(<Grid container autoFlow={flow}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(EXPECTED[flow]);
+    });
+  });
+
+  // ─── F11-bis edge cases: container cols all valid values ────────────
+  describe('cols — every valid value', () => {
+    const COLS = [1, 2, 3, 4, 6, 12] as const;
+    it.each(COLS)('container cols=%s emits grid-cols-%s', (n) => {
+      const { container } = render(<Grid container cols={n}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain(`grid-cols-${n}`);
+    });
+  });
+
+  // ─── F11-bis edge cases: spacingX vs spacingY independence ──────────
+  describe('spacingX / spacingY independence', () => {
+    it('spacingX without spacingY emits only gap-x', () => {
+      const { container } = render(<Grid container spacingX={4}>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('gap-x-4');
+      expect(cls).not.toMatch(/gap-y-/);
+      // standalone `gap-` shouldn't appear unless spacing was passed
+      expect(cls).not.toMatch(/gap-\d/);
+    });
+
+    it('spacingY without spacingX emits only gap-y', () => {
+      const { container } = render(<Grid container spacingY={2}>x</Grid>);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('gap-y-2');
+      expect(cls).not.toMatch(/gap-x-/);
+    });
+
+    it('spacing + spacingX: spacing applies symmetrically, spacingX overrides on X', () => {
+      const { container } = render(
+        <Grid container spacing={4} spacingX={8}>x</Grid>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('gap-4');
+      expect(cls).toContain('gap-x-8');
+    });
+  });
+
+  // ─── F11-bis edge cases: empty container / orphan item ──────────────
+  describe('empty children + orphan item', () => {
+    it('container with NO children emits grid + cols, renders empty div', () => {
+      const { container } = render(<Grid container />);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.className).toContain('grid');
+      expect(el.className).toContain('grid-cols-12');
+      expect(el.children.length).toBe(0);
+    });
+
+    it('orphan item (no container parent) still emits col-span-* (consumer mistake)', () => {
+      // Doesn't crash — produces a col-span-* class that has no effect
+      // outside a CSS Grid parent. Documented behaviour: the consumer
+      // owns the composition.
+      const { container } = render(<Grid xs={6}>x</Grid>);
+      expect(container.firstElementChild?.className).toContain('col-span-6');
+    });
+  });
+
+  // ─── F11-bis edge cases: composition deep nesting ───────────────────
+  describe('deep nesting — Grid inside Grid item', () => {
+    it('nested Grid container inside an item works (12-col inside a 6-span)', () => {
+      const { container } = render(
+        <Grid container spacing={4}>
+          <Grid xs={6}>
+            <Grid container spacing={2}>
+              <Grid xs={6}>inner-a</Grid>
+              <Grid xs={6}>inner-b</Grid>
+            </Grid>
+          </Grid>
+          <Grid xs={6}>outer-b</Grid>
+        </Grid>,
+      );
+      // Outer: grid + 12-col + gap-4
+      const outer = container.firstElementChild;
+      expect(outer?.className).toContain('grid');
+      expect(outer?.className).toContain('grid-cols-12');
+      expect(outer?.className).toContain('gap-4');
+      // Inner items count: outer has 2 direct children
+      expect(outer?.children.length).toBe(2);
+    });
+  });
+});

package/src/components/Grid/Grid.tsx

@@ -0,0 +1,148 @@
+import { forwardRef, type ElementType, type ReactElement } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { gridVariants } from './grid.variants.js';
+import type {
+  GridProps,
+  GridContainerProps,
+  GridItemProps,
+  ColSpan,
+  GridSpacingStep,
+} from './grid.types.js';
+
+/**
+ * `<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.
+ */
+export const Grid = forwardRef<HTMLElement, GridProps>(
+  function Grid(props, ref) {
+    const { as, asChild = false, sx, children, ...rest } = props as GridProps & {
+      as?: ElementType;
+      asChild?: boolean;
+      sx?: string;
+      children?: React.ReactNode;
+    };
+    /*
+     * 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 as { container?: boolean }).container === true;
+
+    let classes: string;
+    let containerPayload: GridContainerProps | null = null;
+    let itemPayload: GridItemProps | null = null;
+
+    if (isContainer) {
+      containerPayload = props as GridContainerProps;
+      /*
+       * 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 ?? 12) as 1 | 2 | 3 | 4 | 6 | 12,
+          spacing:  containerPayload.spacing,
+          spacingX: containerPayload.spacingX,
+          spacingY: containerPayload.spacingY,
+          autoFlow: containerPayload.autoFlow,
+        }),
+        sx,
+      );
+    } else {
+      itemPayload = props as GridItemProps;
+      /*
+       * 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 ?? 'full') as ColSpan,
+          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: Record<string, unknown> = { ...(rest as Record<string, unknown>) };
+    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;
+    // Silence unused vars that the union typings require us to receive.
+    void itemPayload; void containerPayload;
+    // The unused-vars helper from grid.types is a type-only import,
+    // referenced here to keep ESM tree-shake clean — TS handles imports.
+    void ({} as GridSpacingStep);
+
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={classes} {...domRest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    const Tag = (as ?? 'div') as ElementType;
+    return (
+      <Tag ref={ref as never} className={classes} {...domRest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+Grid.displayName = 'Grid';