@dashforge/tw 0.1.0-beta → 0.2.0-beta

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';

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

@@ -0,0 +1,112 @@
+import type { ElementType, HTMLAttributes } from 'react';
+
+/**
+ * Grid types — discriminated union for container vs item role.
+ *
+ * Pattern is MUI v2: a single `<Grid>` component that switches role
+ * based on the `container` prop. Container exposes layout axes
+ * (cols, spacing, autoFlow). Item exposes per-breakpoint span axes
+ * (xs/sm/md/lg/xl).
+ *
+ * TypeScript-level enforcement (the key win over MUI):
+ *   • `<Grid container xs={6}>` is a TYPE ERROR — `xs` doesn't exist
+ *     on the container shape.
+ *   • `<Grid xs={6} spacing={4}>` is a TYPE ERROR — `spacing` doesn't
+ *     exist on the item shape.
+ *   IntelliSense filters suggestions per role, so the developer never
+ *   sees props that don't apply.
+ *
+ * Type-only file (no runtime). Lives separate from the variants so the
+ * union doesn't widen with the variant catalogue's enum unions.
+ */
+
+/**
+ * Valid column-span values for a grid item, at any breakpoint.
+ *   • 1..12  — explicit span count
+ *   • 'auto' — content-sized (CSS Grid auto-track)
+ *   • 'full' — `col-span-full` (spans all columns regardless of count)
+ */
+export type ColSpan =
+  | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
+  | 'auto'
+  | 'full';
+
+/**
+ * Token-scale spacing step. Mirror of Box.p / Stack.gap so the value
+ * space across primitives is identical — `<Grid container spacing={4}>`
+ * and `<Stack gap={4}>` produce visually equivalent gaps.
+ */
+export type GridSpacingStep =
+  | 0 | '0.5' | 1 | 2 | 3 | 4 | 6 | 8 | 12 | 16 | 24;
+
+/**
+ * Container-role props. Discriminated on `container: true`.
+ *
+ * NOTE on `cols`: defaults to 12 in the component implementation
+ * (not in TV) — the MUI v2 convention. Override to 6/4/3/2/1 for
+ * dense dashboard layouts.
+ */
+export interface GridContainerProps {
+  /** Discriminator — `true` makes this a grid container. */
+  container: true;
+  /** Number of columns. Default 12. */
+  cols?: 1 | 2 | 3 | 4 | 6 | 12;
+  /** Gap between cells. Shorthand for spacingX + spacingY. */
+  spacing?: GridSpacingStep;
+  /** Horizontal gap override (wins over `spacing`). */
+  spacingX?: GridSpacingStep;
+  /** Vertical gap override (wins over `spacing`). */
+  spacingY?: GridSpacingStep;
+  /** `grid-auto-flow` — useful for dense or column-major packing. */
+  autoFlow?: 'row' | 'col' | 'dense' | 'row-dense' | 'col-dense';
+}
+
+/**
+ * Item-role props. Discriminated on `container: false | undefined`.
+ *
+ * Each breakpoint accepts a `ColSpan`. The cascade is Tailwind-native
+ * mobile-first: `xs` is the base (no media query), `sm/md/lg/xl`
+ * override at the corresponding min-width.
+ *
+ * Default behaviour when no breakpoint is set: spans `full` — the
+ * "comfortable default" so a forgotten prop doesn't collapse the cell
+ * to 1/12th of a row.
+ */
+export interface GridItemProps {
+  /** Discriminator — absent (or `false`) makes this a grid item. */
+  container?: false;
+  /** Base breakpoint (no media query). Default `'full'`. */
+  xs?: ColSpan;
+  /** Span at sm breakpoint and up. */
+  sm?: ColSpan;
+  /** Span at md breakpoint and up. */
+  md?: ColSpan;
+  /** Span at lg breakpoint and up. */
+  lg?: ColSpan;
+  /** Span at xl breakpoint and up. */
+  xl?: ColSpan;
+}
+
+/**
+ * Common props shared by both roles. Kept in a separate intersection
+ * so the discriminated union stays narrow and IntelliSense fast.
+ */
+interface GridCommonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'className'> {
+  /** Override the rendered HTML tag. Default `'div'`. Ignored under `asChild`. */
+  as?: ElementType;
+  /**
+   * Render via Radix Slot onto the single child. Wins over `as`.
+   * Note: container Grids using `asChild` don't make sense for most
+   * cases — the Slot pattern collapses our wrapper, but Grid's
+   * `display:grid` only applies to direct children, so the child
+   * needs to BE a container with the right children.
+   */
+  asChild?: boolean;
+  /** Utility-class override, merged via tailwind-merge. */
+  sx?: string;
+}
+
+/**
+ * `<Grid>` props — discriminated union: container OR item, never both.
+ */
+export type GridProps = (GridContainerProps | GridItemProps) & GridCommonProps;