@dashforge/tw 1.0.0 → 1.1.1

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

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

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

@@ -1,133 +0,0 @@
-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/LeftNav/LeftNav.perf.test.tsx

@@ -1,172 +0,0 @@
-// @vitest-environment jsdom
-/**
- * Performance + re-render budget tests for `<LeftNav>`.
- *
- * Layout sidebar is the most expensive layout primitive — it can
- * easily host 50+ rows, each with RBAC checks. Guardrails:
- *
- *  1. Mount cost bounded for realistic + worst-case row counts.
- *  2. `activeId` change only re-renders the rows that need re-styling
- *     (today: all rows re-render because we don't `React.memo` them,
- *     but the total time is still bounded).
- *  3. Group expand/collapse only re-renders THAT group.
- *  4. Toggling `collapsed` does not allocate per-item maps.
- */
-import * as React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
-import {
-  render,
-  screen,
-  fireEvent,
-  cleanup,
-} from '@testing-library/react';
-import { LeftNav } from './LeftNav.js';
-import type { LeftNavNode } from './leftNav.types.js';
-
-void React;
-afterEach(() => cleanup());
-
-function makeFlatNav(n: number): LeftNavNode[] {
-  return Array.from({ length: n }, (_, i) => ({
-    id: `r${i}`,
-    label: `Row ${i}`,
-    href: `/r${i}`,
-  }));
-}
-
-function makeNestedNav(groups: number, perGroup: number): LeftNavNode[] {
-  return Array.from({ length: groups }, (_, g) => ({
-    kind: 'group' as const,
-    id: `g${g}`,
-    label: `Group ${g}`,
-    children: Array.from({ length: perGroup }, (_, i) => ({
-      id: `g${g}-r${i}`,
-      label: `Row ${i}`,
-      href: `/g${g}/r${i}`,
-    })),
-  }));
-}
-
-function withRenderCounter<P>(
-  Component: React.ComponentType<P>,
-  counterRef: { count: number }
-): React.FC<P> {
-  return function Counted(props: P) {
-    counterRef.count++;
-    return <Component {...(props as P & object)} />;
-  };
-}
-
-describe('<LeftNav> performance', () => {
-  it('mounts a realistic 30-row flat nav in under 50ms', () => {
-    const items = makeFlatNav(30);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(50);
-  });
-
-  it('mounts a 300-row flat nav in under 250ms', () => {
-    const items = makeFlatNav(300);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(250);
-  });
-
-  it('mounts a 10×10 nested nav (100 leaf rows) in under 150ms', () => {
-    const items = makeNestedNav(10, 10);
-    const t0 = performance.now();
-    render(<LeftNav items={items} />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(150);
-  });
-
-  it('toggles `collapsed` in under 100ms (30 rows)', () => {
-    const items = makeFlatNav(30);
-    const { rerender } = render(<LeftNav items={items} />);
-    const t0 = performance.now();
-    rerender(<LeftNav items={items} collapsed />);
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(100);
-  });
-});
-
-describe('<LeftNav> re-render budget', () => {
-  it('renders at most 2 times on mount (top-level wrapper)', () => {
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(LeftNav, counter);
-    render(<Counted items={makeFlatNav(10)} />);
-    expect(counter.count).toBeLessThanOrEqual(2);
-  });
-
-  it('does NOT re-render the wrapper when a group expands locally', () => {
-    // Group state is local — flipping it must not bubble a re-render
-    // up to the LeftNav wrapper.
-    const counter = { count: 0 };
-    const Counted = withRenderCounter(LeftNav, counter);
-    render(<Counted items={makeNestedNav(2, 3)} />);
-    const baseline = counter.count;
-    const header = screen.getByRole('button', { name: /Group 0/ });
-    fireEvent.click(header);
-    fireEvent.click(header);
-    fireEvent.click(header);
-    expect(counter.count).toBe(baseline);
-  });
-
-  it('does NOT re-render an unrelated sibling when collapsing the nav', () => {
-    const sibCount = { count: 0 };
-    const Sibling = () => {
-      sibCount.count++;
-      return <div data-testid="sib" />;
-    };
-    const Shell = ({ collapsed }: { collapsed: boolean }) => (
-      <div>
-        <LeftNav items={makeFlatNav(20)} collapsed={collapsed} />
-        <Sibling />
-      </div>
-    );
-    const { rerender } = render(<Shell collapsed={false} />);
-    const baseline = sibCount.count;
-    rerender(<Shell collapsed={true} />);
-    // 1 parent re-render → 1 sibling re-render. Allow 1 extra for
-    // React strict-mode or commit-phase double-invocation in dev.
-    expect(sibCount.count - baseline).toBeLessThanOrEqual(2);
-  });
-
-  it('activeId change updates aria-current without throwing', () => {
-    const items = makeFlatNav(5);
-    const { rerender } = render(
-      <LeftNav items={items} activeId="r0" />
-    );
-    expect(
-      screen.getByRole('link', { name: 'Row 0' }).getAttribute('aria-current')
-    ).toBe('page');
-    rerender(<LeftNav items={items} activeId="r3" />);
-    expect(
-      screen.getByRole('link', { name: 'Row 0' }).getAttribute('aria-current')
-    ).toBeNull();
-    expect(
-      screen.getByRole('link', { name: 'Row 3' }).getAttribute('aria-current')
-    ).toBe('page');
-  });
-
-  it('group expanded state is preserved across parent re-renders', () => {
-    // Local state inside `<NavGroupRow>` must survive a parent
-    // re-render. Without this, every `activeId` change would reset
-    // every group to its `defaultExpanded`, which would be terrible UX.
-    const items = makeNestedNav(2, 3);
-    const { container, rerender } = render(
-      <LeftNav items={items} activeId="g0-r0" />
-    );
-    // Collapse Group 0 — Group 0's first child href becomes invisible.
-    fireEvent.click(screen.getByRole('button', { name: /Group 0/ }));
-    const g0Child = () =>
-      container.querySelector('a[href="/g0/r0"]');
-    expect(g0Child()).toBeNull();
-    // Now change activeId to a row in Group 1.
-    rerender(<LeftNav items={items} activeId="g1-r0" />);
-    // Group 0 must STAY collapsed (local state survived parent re-render).
-    expect(g0Child()).toBeNull();
-  });
-});