@dashforge/tw 1.1.0 → 1.2.0

package/src/components/TopBar/TopBar.test.tsx

@@ -1,129 +0,0 @@
-// @vitest-environment jsdom
-import * as React from 'react';
-import { describe, it, expect, afterEach } from 'vitest';
-import { render, screen, cleanup } from '@testing-library/react';
-import { TopBar } from './TopBar.js';
-
-void React;
-afterEach(() => cleanup());
-
-describe('<TopBar>', () => {
-  it('renders as a banner landmark by default (<header>)', () => {
-    render(<TopBar end={<span>x</span>} />);
-    expect(screen.getByRole('banner')).toBeTruthy();
-  });
-
-  it('renders as a plain <div> when asDiv is true', () => {
-    const { container } = render(<TopBar end={<span>x</span>} asDiv />);
-    expect(container.querySelector('header')).toBeNull();
-    expect(container.querySelector('div')).toBeTruthy();
-  });
-
-  it('renders the start slot', () => {
-    render(<TopBar start={<button>menu</button>} />);
-    expect(screen.getByRole('button', { name: 'menu' })).toBeTruthy();
-  });
-
-  it('renders the center slot', () => {
-    render(<TopBar center={<span data-testid="c">page</span>} />);
-    expect(screen.getByTestId('c')).toBeTruthy();
-  });
-
-  it('renders the end slot', () => {
-    render(<TopBar end={<button>user</button>} />);
-    expect(screen.getByRole('button', { name: 'user' })).toBeTruthy();
-  });
-
-  it('renders children as the center slot when `center` is not provided', () => {
-    render(
-      <TopBar>
-        <span data-testid="child">title</span>
-      </TopBar>
-    );
-    expect(screen.getByTestId('child')).toBeTruthy();
-  });
-
-  it('prefers explicit `center` over children', () => {
-    render(
-      <TopBar center={<span data-testid="explicit-center">c</span>}>
-        <span data-testid="child">should-not-render</span>
-      </TopBar>
-    );
-    expect(screen.getByTestId('explicit-center')).toBeTruthy();
-    expect(screen.queryByTestId('child')).toBeNull();
-  });
-
-  it('does not render start / end wrappers when those props are absent', () => {
-    const { container } = render(<TopBar center={<span>c</span>} />);
-    // Inner divs: only the center div is rendered when start/end are
-    // both undefined (we render `<div>{center ?? children}</div>` always).
-    expect(container.querySelectorAll('header > div')).toHaveLength(1);
-  });
-
-  it('applies the sx className to the root', () => {
-    const { container } = render(
-      <TopBar center={<span>c</span>} sx="custom-class" />
-    );
-    expect(container.querySelector('header.custom-class')).toBeTruthy();
-  });
-
-  it('renders height variants without throwing', () => {
-    (['sm', 'md', 'lg'] as const).forEach((h) => {
-      const { unmount } = render(<TopBar center={<span>c</span>} height={h} />);
-      expect(screen.getByRole('banner')).toBeTruthy();
-      unmount();
-    });
-  });
-});
-
-describe('<TopBar> performance', () => {
-  it('mounts in under 20ms', () => {
-    const t0 = performance.now();
-    render(
-      <TopBar
-        start={<button>start</button>}
-        center={<span>center</span>}
-        end={<button>end</button>}
-      />
-    );
-    const t1 = performance.now();
-    expect(t1 - t0).toBeLessThan(20);
-  });
-
-  it('renders at most 2 times on mount', () => {
-    let count = 0;
-    const Counted = (props: React.ComponentProps<typeof TopBar>) => {
-      count++;
-      return <TopBar {...props} />;
-    };
-    render(
-      <Counted
-        start={<button>s</button>}
-        center={<span>c</span>}
-        end={<button>e</button>}
-      />
-    );
-    expect(count).toBeLessThanOrEqual(2);
-  });
-
-  it('does NOT re-render an unrelated sibling on prop change', () => {
-    const sibCount = { count: 0 };
-    const Sibling = () => {
-      sibCount.count++;
-      return <div data-testid="sib" />;
-    };
-    const Tree = ({ label }: { label: string }) => (
-      <div>
-        <TopBar center={<span>{label}</span>} />
-        <Sibling />
-      </div>
-    );
-    const { rerender } = render(<Tree label="A" />);
-    const before = sibCount.count;
-    rerender(<Tree label="B" />);
-    rerender(<Tree label="C" />);
-    // Each parent rerender is expected to also re-render the sibling.
-    // 2 parent rerenders ⇒ ≤ 2 extra sibling renders (+1 tolerance).
-    expect(sibCount.count - before).toBeLessThanOrEqual(3);
-  });
-});

package/src/components/TopBar/TopBar.tsx

@@ -1,66 +0,0 @@
-import { cn } from '../../utils/cn.js';
-import { topBarVariants } from './topBar.variants.js';
-import type { TopBarProps } from './topBar.types.js';
-
-/**
- * Dashforge TW TopBar — sticky header with 3 named slots.
- *
- * Pure composition. Three regions arranged horizontally:
- *
- *   ┌──────────────────────────────────────────────────────────┐
- *   │ start   │           center                  │      end   │
- *   └──────────────────────────────────────────────────────────┘
- *
- * - `start` and `end` shrink to content.
- * - `center` grows to fill remaining space.
- * - If you pass `children` instead of `center`, those children render
- *   in the center region — handy for terse JSX:
- *
- *   ```tsx
- *   <TopBar start={<Logo />} end={<UserMenu />}>
- *     <Breadcrumbs items={trail} />
- *   </TopBar>
- *   ```
- *
- * Default renders as `<header role="banner">` (implicit from
- * `<header>` as a top-level landmark). Pass `asDiv` for cases where
- * you don't want the banner role (e.g., nested inside another header).
- *
- * **A11y**:
- *   - `<header>` is a banner landmark — only one per page; if you put
- *     multiple TopBars on a page, use `asDiv` on the secondary ones.
- *   - Slots are agnostic about ARIA — wrap your slot content with
- *     appropriate roles (`<nav>`, `<search>`, etc.) where needed.
- */
-export function TopBar(props: TopBarProps) {
-  const {
-    start,
-    center,
-    end,
-    children,
-    height,
-    sticky,
-    asDiv,
-    sx,
-    slotProps,
-  } = props;
-
-  const v = topBarVariants({ height, sticky });
-  const Tag = (asDiv ? 'div' : 'header') as 'header';
-
-  return (
-    <Tag className={cn(v.root(), sx, slotProps?.root?.className)}>
-      {(start != null) && (
-        <div className={cn(v.start(), slotProps?.start?.className)}>
-          {start}
-        </div>
-      )}
-      <div className={cn(v.center(), slotProps?.center?.className)}>
-        {center ?? children}
-      </div>
-      {(end != null) && (
-        <div className={cn(v.end(), slotProps?.end?.className)}>{end}</div>
-      )}
-    </Tag>
-  );
-}

package/src/components/TopBar/topBar.types.ts

@@ -1,42 +0,0 @@
-import type { ReactNode } from 'react';
-import type { TopBarVariants } from './topBar.variants.js';
-
-export interface TopBarSlotProps {
-  root?: { className?: string };
-  start?: { className?: string };
-  center?: { className?: string };
-  end?: { className?: string };
-}
-
-/**
- * Props for `<TopBar>`.
- *
- * Pure composition container with 3 named slots — `start`, `center`,
- * `end` — that fill a sticky horizontal bar.
- *
- * Typical patterns:
- *
- *   - **start**: mobile menu toggle, brand/logo
- *   - **center**: Breadcrumbs, page title, global search
- *   - **end**: notifications icon, user menu, theme toggle
- *
- * The component is intentionally minimal: it just lays out the three
- * regions. All semantics (e.g., `<header role="banner">`) come for
- * free from rendering as an HTML `<header>` element.
- */
-export interface TopBarProps extends TopBarVariants {
-  /** Left-aligned slot (mobile menu, brand). */
-  start?: ReactNode;
-  /** Center slot (breadcrumbs, title). Grows to fill remaining space. */
-  center?: ReactNode;
-  /** Right-aligned slot (actions, user menu). */
-  end?: ReactNode;
-  /** Convenience: render the bar as a plain `<div>` (no banner role). */
-  asDiv?: boolean;
-  /** Root className shortcut. */
-  sx?: string;
-  /** Per-slot className overrides. */
-  slotProps?: TopBarSlotProps;
-  /** Children render between `start` and `end` when no `center` is set. */
-  children?: ReactNode;
-}

package/src/components/TopBar/topBar.variants.ts

@@ -1,38 +0,0 @@
-import { tv, type VariantProps } from 'tailwind-variants';
-
-/**
- * Tailwind-variants recipe for `<TopBar>`.
- *
- * Slots:
- *   - `root`   — outer `<header>` (or `<div>` with `asDiv`)
- *   - `start`  — left region (shrink-to-content)
- *   - `center` — middle region (grows to fill)
- *   - `end`    — right region (shrink-to-content)
- */
-export const topBarVariants = tv({
-  slots: {
-    root: [
-      'flex items-center gap-3 w-full px-4 shrink-0',
-      'bg-neutral-50 border-b border-neutral-200',
-    ],
-    start: 'flex items-center gap-2 min-w-0 shrink-0',
-    center: 'flex items-center gap-2 min-w-0 flex-1',
-    end: 'flex items-center gap-2 shrink-0',
-  },
-  variants: {
-    height: {
-      sm: { root: 'h-12 text-sm' },
-      md: { root: 'h-14' },
-      lg: { root: 'h-16' },
-    },
-    sticky: {
-      true: { root: 'sticky top-0 z-30' },
-    },
-  },
-  defaultVariants: {
-    height: 'md',
-    sticky: true,
-  },
-});
-
-export type TopBarVariants = VariantProps<typeof topBarVariants>;

package/src/components/Typography/Typography.test.tsx

@@ -1,247 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { render } from '@testing-library/react';
-import { Typography } from './Typography.js';
-
-/**
- * Suite mirrors the Button.test.tsx shape (rendering · variants · color ·
- * override · polymorphism) so the test surface is uniform across the
- * package.
- *
- * Strategy: render → query → assert on `tagName` (for HTML-element
- * resolution) and `className` (for variant resolution). We deliberately
- * DON'T snapshot: snapshots churn on every variant-class edit and offer
- * no signal on the actual contract — the contract is "this variant
- * emits THESE specific Tailwind utility classes", which we assert
- * positively below.
- */
-describe('<Typography>', () => {
-  // ─── Rendering / default tag mapping ────────────────────────────────
-  describe('default tag mapping', () => {
-    it('renders <p> for body1 by default', () => {
-      const { container } = render(<Typography>hello</Typography>);
-      expect(container.firstElementChild?.tagName).toBe('P');
-    });
-
-    it('renders <h1> for variant="h1"', () => {
-      const { container } = render(<Typography variant="h1">title</Typography>);
-      expect(container.firstElementChild?.tagName).toBe('H1');
-    });
-
-    it('renders <h3> for variant="h3"', () => {
-      const { container } = render(<Typography variant="h3">title</Typography>);
-      expect(container.firstElementChild?.tagName).toBe('H3');
-    });
-
-    it('renders <span> for variant="caption"', () => {
-      const { container } = render(<Typography variant="caption">note</Typography>);
-      expect(container.firstElementChild?.tagName).toBe('SPAN');
-    });
-
-    it('renders <span> for variant="overline"', () => {
-      const { container } = render(<Typography variant="overline">label</Typography>);
-      expect(container.firstElementChild?.tagName).toBe('SPAN');
-    });
-  });
-
-  // ─── Variant classes ────────────────────────────────────────────────
-  describe('variant → utility chain', () => {
-    it('h1 has text-5xl + font-bold', () => {
-      const { container } = render(<Typography variant="h1">x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('text-5xl');
-      expect(cls).toContain('font-bold');
-    });
-
-    it('body2 has text-sm', () => {
-      const { container } = render(<Typography variant="body2">x</Typography>);
-      expect(container.firstElementChild?.className).toContain('text-sm');
-    });
-
-    it('overline has uppercase + tracking', () => {
-      const { container } = render(<Typography variant="overline">x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('uppercase');
-      expect(cls).toMatch(/tracking-\[/);
-    });
-  });
-
-  // ─── Color intent ───────────────────────────────────────────────────
-  describe('color', () => {
-    it('color="primary" emits text-primary-* with dark variant', () => {
-      const { container } = render(<Typography color="primary">x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('text-primary-700');
-      expect(cls).toContain('dark:text-primary-400');
-    });
-
-    it('color="danger" emits text-danger-*', () => {
-      const { container } = render(<Typography color="danger">x</Typography>);
-      expect(container.firstElementChild?.className).toContain('text-danger-700');
-    });
-
-    it('color="inherit" emits text-inherit', () => {
-      const { container } = render(<Typography color="inherit">x</Typography>);
-      expect(container.firstElementChild?.className).toContain('text-inherit');
-    });
-
-    it('defaults to color="neutral" (text-neutral-900, NOT text-inherit)', () => {
-      // Sprint 6 P5 fix — a bare <Typography> must emit the
-      // auto-inverting neutral token, not inherit the consumer's
-      // arbitrary root colour (which broke dark-mode consistency).
-      const { container } = render(<Typography>x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('text-neutral-900');
-      expect(cls).not.toContain('text-inherit');
-    });
-
-    it('color="muted" emits text-neutral-600', () => {
-      const { container } = render(<Typography color="muted">x</Typography>);
-      expect(container.firstElementChild?.className).toContain('text-neutral-600');
-    });
-  });
-
-  // ─── Override semantics ─────────────────────────────────────────────
-  describe('override', () => {
-    it('sx wins over variant defaults via tailwind-merge', () => {
-      const { container } = render(
-        <Typography variant="h1" color="primary" sx="text-pink-500">x</Typography>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      // tailwind-merge collapses the conflicting `text-*` colour to the last one
-      expect(cls).toContain('text-pink-500');
-      expect(cls).not.toContain('text-primary-700');
-    });
-
-    it('weight prop overrides variant default weight', () => {
-      const { container } = render(<Typography variant="h1" weight="normal">x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      // h1's default `font-bold` is dropped by tailwind-merge, replaced by font-normal
-      expect(cls).toContain('font-normal');
-      expect(cls).not.toContain('font-bold');
-    });
-
-    it('truncate adds the truncate utility', () => {
-      const { container } = render(<Typography truncate>x</Typography>);
-      expect(container.firstElementChild?.className).toContain('truncate');
-    });
-
-    it('gutterBottom adds mb-3', () => {
-      const { container } = render(<Typography gutterBottom>x</Typography>);
-      expect(container.firstElementChild?.className).toContain('mb-3');
-    });
-  });
-
-  // ─── Polymorphism — `as` and `asChild` ───────────────────────────────
-  describe('polymorphism', () => {
-    it('as="section" overrides the variant-default tag', () => {
-      const { container } = render(
-        <Typography variant="h1" as="section">x</Typography>,
-      );
-      expect(container.firstElementChild?.tagName).toBe('SECTION');
-    });
-
-    it('asChild renders the single child element with merged className', () => {
-      const { container } = render(
-        <Typography variant="h2" color="primary" asChild>
-          <a href="#">link</a>
-        </Typography>,
-      );
-      const el = container.firstElementChild;
-      expect(el?.tagName).toBe('A');
-      expect(el?.className).toContain('text-4xl');
-      expect(el?.className).toContain('text-primary-700');
-      expect(el?.getAttribute('href')).toBe('#');
-    });
-
-    it('asChild wins over `as` when both are passed', () => {
-      const { container } = render(
-        <Typography variant="h1" as="section" asChild>
-          <article>x</article>
-        </Typography>,
-      );
-      // Slot renders the child element, ignoring `as`
-      expect(container.firstElementChild?.tagName).toBe('ARTICLE');
-    });
-  });
-
-  // ─── Pass-through ────────────────────────────────────────────────────
-  describe('pass-through props', () => {
-    it('forwards data-* attributes', () => {
-      const { container } = render(
-        <Typography data-testid="typo">x</Typography>,
-      );
-      expect(container.firstElementChild?.getAttribute('data-testid')).toBe('typo');
-    });
-
-    it('forwards aria-label', () => {
-      const { container } = render(
-        <Typography aria-label="heading">x</Typography>,
-      );
-      expect(container.firstElementChild?.getAttribute('aria-label')).toBe('heading');
-    });
-  });
-
-  // ─── F11-bis edge cases ─────────────────────────────────────────────
-  describe('multi-axis combinations', () => {
-    it('variant=h2 + color=primary + weight=normal + align=center + truncate + gutterBottom', () => {
-      const { container } = render(
-        <Typography
-          variant="h2"
-          color="primary"
-          weight="normal"
-          align="center"
-          truncate
-          gutterBottom
-        >
-          x
-        </Typography>,
-      );
-      const cls = container.firstElementChild?.className ?? '';
-      expect(cls).toContain('text-4xl');           // h2 size
-      expect(cls).toContain('text-primary-700');   // color intent
-      expect(cls).toContain('font-normal');        // weight override (vs h2 default font-bold)
-      expect(cls).not.toContain('font-bold');      // overridden
-      expect(cls).toContain('text-center');        // align
-      expect(cls).toContain('truncate');           // truncate
-      expect(cls).toContain('mb-3');               // gutterBottom
-    });
-
-    it('noWrap + truncate: truncate wins (later in chain, tailwind-merge collapses whitespace-nowrap)', () => {
-      const { container } = render(<Typography noWrap truncate>x</Typography>);
-      // truncate utility already includes whitespace-nowrap — tailwind-merge
-      // collapses the redundant nowrap from noWrap
-      expect(container.firstElementChild?.className).toContain('truncate');
-    });
-
-    it('every variant maps to its expected default tag', () => {
-      const cases: Array<[Parameters<typeof Typography>[0]['variant'], string]> = [
-        ['h1', 'H1'], ['h2', 'H2'], ['h3', 'H3'], ['h4', 'H4'], ['h5', 'H5'], ['h6', 'H6'],
-        ['subtitle1', 'P'], ['subtitle2', 'P'],
-        ['body1', 'P'], ['body2', 'P'],
-        ['caption', 'SPAN'], ['overline', 'SPAN'],
-      ];
-      cases.forEach(([variant, tag]) => {
-        const { container } = render(<Typography variant={variant}>x</Typography>);
-        expect(container.firstElementChild?.tagName).toBe(tag);
-      });
-    });
-  });
-
-  describe('color edge cases', () => {
-    const INTENTS = ['primary', 'secondary', 'success', 'warning', 'danger', 'info', 'muted'] as const;
-    it.each(INTENTS)('color="%s" emits the right text-* + dark pair', (color) => {
-      const { container } = render(<Typography color={color}>x</Typography>);
-      const cls = container.firstElementChild?.className ?? '';
-      if (color === 'muted') {
-        // Sprint 4.3 identity sweep: neutral palette auto-inverts via
-        // CSS-var swap — no `dark:` variant needed.
-        expect(cls).toContain('text-neutral-600');
-        expect(cls).not.toContain('dark:text-neutral-');
-      } else {
-        expect(cls).toContain(`text-${color}-700`);
-        expect(cls).toContain(`dark:text-${color}-400`);
-      }
-    });
-  });
-});

package/src/components/Typography/Typography.tsx

@@ -1,112 +0,0 @@
-import { forwardRef, type ElementType, type ReactElement } from 'react';
-import { Slot } from '@radix-ui/react-slot';
-import { cn } from '../../utils/cn.js';
-import { typographyVariants } from './typography.variants.js';
-import type { TypographyProps } from './typography.types.js';
-
-/**
- * Default HTML tag per variant. Headings get their semantic level (h1→h1
- * etc.); subtitle/body get `<p>` (block, paragraph semantics);
- * caption/overline get `<span>` (inline, no implicit block break).
- *
- * Override per-instance via the `as` prop — useful when the semantic
- * heading level should differ from the visual scale (e.g. a hero
- * rendered as `<h2>` but visually styled `h1`).
- */
-const VARIANT_TO_TAG: Record<NonNullable<TypographyProps['variant']>, ElementType> = {
-  h1:        'h1',
-  h2:        'h2',
-  h3:        'h3',
-  h4:        'h4',
-  h5:        'h5',
-  h6:        'h6',
-  subtitle1: 'p',
-  subtitle2: 'p',
-  body1:     'p',
-  body2:     'p',
-  caption:   'span',
-  overline:  'span',
-};
-
-/**
- * `<Typography>` — semantic typed text, the foundation of every readable
- * surface in @dashforge/tw.
- *
- * Why this exists:
- *   Tailwind ships a typographic scale (`text-xl`, `font-bold`,
- *   `leading-relaxed`) but leaves the SEMANTIC HTML tag and the
- *   intent-coloured palette to the consumer. That's fine for one-off
- *   marketing surfaces, but at app scale it means every `<h2>` and every
- *   body paragraph re-derives its own utility chain — and they drift.
- *
- *   Typography moves that decision into a typed prop set: the visual
- *   scale, the intent colour, the alignment, the truncation all live in
- *   `tailwind-variants` and resolve to the same utility chain everywhere
- *   in the app. The default HTML tag is inferred from `variant` so the
- *   semantic layer follows the visual layer; `as` and `asChild` are the
- *   two escape hatches when you need something else.
- *
- * Layering:
- *   • Sits BENEATH every component that renders text — `<Button>`'s
- *     label, `<TextField>`'s helper text, MDX prose in our own docs.
- *   • Composes ON TOP of `@dashforge/tw-tokens` colour scales (so
- *     `color="primary"` paints `text-primary-700` in light, `-400` in dark,
- *     reactive to `setMode()`).
- *   • Polymorphic via Radix Slot — pairs cleanly with router `<Link>`,
- *     `<button>`, or `<a>` without injecting an extra wrapper element.
- *
- * Polymorphism rules — `as` vs `asChild`:
- *   • `as` swaps the rendered tag (we still render the element ourselves).
- *   • `asChild` removes our element entirely — the single React child
- *     becomes the rendered tag, with our className/ref merged onto it.
- *     This is the Radix Slot pattern; use when you need a router Link
- *     to style as a heading.
- *   When BOTH are passed, `asChild` wins. We considered making this a
- *   compile-time error via discriminated unions, but the API surface
- *   already has 8 axes and adding one more dimension to the props type
- *   would inflate IntelliSense suggestions for marginal benefit. The
- *   runtime preference is documented; the test asserts it.
- */
-export const Typography = forwardRef<HTMLElement, TypographyProps>(
-  function Typography(props, ref) {
-    const {
-      variant = 'body1',
-      color,
-      weight,
-      align,
-      truncate,
-      noWrap,
-      gutterBottom,
-      as,
-      asChild = false,
-      sx,
-      children,
-      ...rest
-    } = props;
-
-    const classes = cn(
-      typographyVariants({ variant, color, weight, align, truncate, noWrap, gutterBottom }),
-      sx,
-    );
-
-    // asChild wins over `as` when both are passed (see component header).
-    if (asChild) {
-      return (
-        <Slot ref={ref} className={classes} {...rest}>
-          {children as ReactElement}
-        </Slot>
-      );
-    }
-
-    // Resolve the rendered tag: explicit `as` > variant default > fallback.
-    const Tag = (as ?? VARIANT_TO_TAG[variant] ?? 'span') as ElementType;
-
-    return (
-      <Tag ref={ref as never} className={classes} {...rest}>
-        {children}
-      </Tag>
-    );
-  },
-);
-
-Typography.displayName = 'Typography';