@dashforge/tw 1.1.0 → 1.2.0

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/IconButton/IconButton.test.tsx

@@ -1,367 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { render, screen, fireEvent, cleanup } from '@testing-library/react';
-import { RbacProvider } from '@dashforge/rbac';
-import type { RbacPolicy, Subject } from '@dashforge/rbac';
-import { IconButton } from './IconButton.js';
-
-void React;
-afterEach(() => cleanup());
-
-/**
- * `<IconButton>` unit tests. Covers:
- *   - icon rendering, required aria-label, base layout primitives
- *   - variant × color × size matrix (5 variants × 5 colors × 3 sizes)
- *     — sampled, not exhaustive (the full matrix is covered by
- *     `<Button>`'s tests since IconButton reuses `buttonVariants`)
- *   - square geometry via SIZE_OVERRIDES + aspect-square
- *   - asChild polymorphism via Radix Slot
- *   - loading state (spinner + aria-busy + disabled)
- *   - disabled state (explicit + access.disabled + access.readonly)
- *   - access RBAC: hide / disable
- *   - click handler firing semantics
- */
-
-const TestIcon = () => (
-  <svg data-testid="test-icon" width={20} height={20} viewBox="0 0 20 20">
-    <circle cx="10" cy="10" r="8" />
-  </svg>
-);
-
-const FULL_ACCESS_POLICY: RbacPolicy = {
-  roles: [
-    {
-      name: 'admin',
-      permissions: [{ resource: '*', action: '*', effect: 'allow' }],
-    },
-  ],
-};
-const NO_ACCESS_POLICY: RbacPolicy = {
-  roles: [
-    { name: 'guest', permissions: [] },
-  ],
-};
-const adminSubject: Subject = { id: 'a', roles: ['admin'] };
-const guestSubject: Subject = { id: 'g', roles: ['guest'] };
-
-describe('<IconButton>', () => {
-  describe('rendering', () => {
-    it('renders the icon child', () => {
-      render(
-        <IconButton aria-label="x">
-          <TestIcon />
-        </IconButton>
-      );
-      expect(screen.getByTestId('test-icon')).toBeTruthy();
-    });
-
-    it('applies the aria-label to the button element', () => {
-      render(
-        <IconButton aria-label="Open settings">
-          <TestIcon />
-        </IconButton>
-      );
-      expect(screen.getByRole('button', { name: /open settings/i })).toBeTruthy();
-    });
-
-    it('renders as type="button" by default', () => {
-      render(
-        <IconButton aria-label="x">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = screen.getByRole('button') as HTMLButtonElement;
-      expect(btn.type).toBe('button');
-    });
-
-    it('respects an explicit type prop', () => {
-      render(
-        <IconButton aria-label="x" type="submit">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = screen.getByRole('button') as HTMLButtonElement;
-      expect(btn.type).toBe('submit');
-    });
-  });
-
-  describe('layout primitives — square geometry', () => {
-    it('always applies aspect-square + inline-flex (layout base)', () => {
-      const { container } = render(
-        <IconButton aria-label="x">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('aspect-square');
-      expect(btn.className).toContain('inline-flex');
-      expect(btn.className).toContain('items-center');
-      expect(btn.className).toContain('justify-center');
-    });
-
-    it('applies SIZE_OVERRIDES (w-N + px-0) for sm', () => {
-      const { container } = render(
-        <IconButton aria-label="x" size="sm">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('w-8');
-      expect(btn.className).toContain('px-0');
-    });
-
-    it('applies SIZE_OVERRIDES for md (default)', () => {
-      const { container } = render(
-        <IconButton aria-label="x">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('w-10');
-    });
-
-    it('applies SIZE_OVERRIDES for lg', () => {
-      const { container } = render(
-        <IconButton aria-label="x" size="lg">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('w-12');
-    });
-  });
-
-  describe('variant × color (inherits buttonVariants)', () => {
-    it('renders solid + primary (token-driven, no hardcoded hex)', () => {
-      const { container } = render(
-        <IconButton aria-label="x" variant="solid" color="primary">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('bg-primary-500');
-      expect(btn.className).not.toMatch(/#[0-9a-fA-F]{3,8}/);
-      expect(btn.className).not.toMatch(/\bdark:/);
-    });
-
-    it('renders outline + danger (border color comes through)', () => {
-      const { container } = render(
-        <IconButton aria-label="x" variant="outline" color="danger">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('border');
-      expect(btn.className).toContain('danger');
-    });
-
-    it('ghost variant uses bg-transparent', () => {
-      const { container } = render(
-        <IconButton aria-label="x" variant="ghost">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('bg-transparent');
-    });
-  });
-
-  describe('asChild polymorphism', () => {
-    it('renders the child via Radix Slot when asChild=true', () => {
-      const { container } = render(
-        <IconButton asChild aria-label="Open">
-          <a href="/open" data-testid="anchor-child">
-            <TestIcon />
-          </a>
-        </IconButton>
-      );
-      // Should be an <a>, not a <button>
-      const anchor = container.querySelector('a[data-testid="anchor-child"]');
-      expect(anchor).toBeTruthy();
-      expect(container.querySelector('button')).toBeNull();
-      // Anchor carries the IconButton className
-      expect(anchor!.className).toContain('aspect-square');
-    });
-  });
-
-  describe('loading state', () => {
-    it('swaps the icon with a spinner', () => {
-      const { container } = render(
-        <IconButton aria-label="x" loading>
-          <TestIcon />
-        </IconButton>
-      );
-      // Icon child gone, replaced by Spinner (animate-spin is on the
-      // Spinner's outer <span> wrapper now, since Sprint 4.4 refactor
-      // delegated to the public <Spinner> component).
-      expect(screen.queryByTestId('test-icon')).toBeNull();
-      const spinner = container.querySelector('[class*="animate-spin"]');
-      expect(spinner).toBeTruthy();
-    });
-
-    it('sets aria-busy=true while loading', () => {
-      render(
-        <IconButton aria-label="x" loading>
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = screen.getByRole('button');
-      expect(btn.getAttribute('aria-busy')).toBe('true');
-    });
-
-    it('is disabled while loading', () => {
-      render(
-        <IconButton aria-label="x" loading>
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = screen.getByRole('button') as HTMLButtonElement;
-      expect(btn.disabled).toBe(true);
-    });
-  });
-
-  describe('disabled state', () => {
-    it('respects the explicit disabled prop', () => {
-      render(
-        <IconButton aria-label="x" disabled>
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = screen.getByRole('button') as HTMLButtonElement;
-      expect(btn.disabled).toBe(true);
-    });
-
-    it('does not fire onClick when disabled', () => {
-      const onClick = vi.fn();
-      render(
-        <IconButton aria-label="x" disabled onClick={onClick}>
-          <TestIcon />
-        </IconButton>
-      );
-      fireEvent.click(screen.getByRole('button'));
-      expect(onClick).not.toHaveBeenCalled();
-    });
-  });
-
-  describe('access RBAC integration', () => {
-    it('hides the button when access.onUnauthorized=hide and subject lacks permission', () => {
-      const { container } = render(
-        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
-          <IconButton
-            aria-label="x"
-            access={{
-              resource: 'article',
-              action: 'publish',
-              onUnauthorized: 'hide',
-            }}
-          >
-            <TestIcon />
-          </IconButton>
-        </RbacProvider>
-      );
-      expect(container.querySelector('button')).toBeNull();
-    });
-
-    it('disables the button when access.onUnauthorized=disable and subject lacks permission', () => {
-      render(
-        <RbacProvider policy={NO_ACCESS_POLICY} subject={guestSubject}>
-          <IconButton
-            aria-label="x"
-            access={{
-              resource: 'article',
-              action: 'publish',
-              onUnauthorized: 'disable',
-            }}
-          >
-            <TestIcon />
-          </IconButton>
-        </RbacProvider>
-      );
-      const btn = screen.getByRole('button') as HTMLButtonElement;
-      expect(btn.disabled).toBe(true);
-    });
-
-    it('renders normally for an admin subject', () => {
-      render(
-        <RbacProvider policy={FULL_ACCESS_POLICY} subject={adminSubject}>
-          <IconButton
-            aria-label="x"
-            access={{
-              resource: 'article',
-              action: 'publish',
-              onUnauthorized: 'hide',
-            }}
-          >
-            <TestIcon />
-          </IconButton>
-        </RbacProvider>
-      );
-      expect(screen.getByRole('button')).toBeTruthy();
-    });
-  });
-
-  describe('click handler', () => {
-    it('fires onClick when clicked', () => {
-      const onClick = vi.fn();
-      render(
-        <IconButton aria-label="x" onClick={onClick}>
-          <TestIcon />
-        </IconButton>
-      );
-      fireEvent.click(screen.getByRole('button'));
-      expect(onClick).toHaveBeenCalledTimes(1);
-    });
-  });
-
-  describe('visibleWhen (engine-reactive, Sprint 4.4)', () => {
-    it('renders when visibleWhen returns true', () => {
-      const { container } = render(
-        <IconButton aria-label="x" visibleWhen={() => true}>
-          <TestIcon />
-        </IconButton>
-      );
-      expect(container.firstChild).toBeTruthy();
-    });
-
-    it('returns null when visibleWhen returns false', () => {
-      const { container } = render(
-        <IconButton aria-label="x" visibleWhen={() => false}>
-          <TestIcon />
-        </IconButton>
-      );
-      expect(container.firstChild).toBeNull();
-    });
-
-    it('renders normally when visibleWhen is omitted', () => {
-      const { container } = render(
-        <IconButton aria-label="x">
-          <TestIcon />
-        </IconButton>
-      );
-      expect(container.firstChild).toBeTruthy();
-    });
-  });
-
-  describe('overrides — sx + className', () => {
-    it('appends sx to the root className', () => {
-      const { container } = render(
-        <IconButton aria-label="x" sx="ring-2 ring-purple-500">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('ring-purple-500');
-    });
-
-    it('appends className to the root', () => {
-      const { container } = render(
-        <IconButton aria-label="x" className="my-custom-icon-btn">
-          <TestIcon />
-        </IconButton>
-      );
-      const btn = container.querySelector('button')!;
-      expect(btn.className).toContain('my-custom-icon-btn');
-    });
-  });
-});