@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/src/components/Stack/stack.variants.ts

@@ -0,0 +1,80 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `stackVariants` — flex container 1D, the layout primitive of @dashforge/tw.
+ *
+ * Architectural role (planned with the user — F9 deep dive):
+ *
+ *   Stack is the ONLY way to do flex in this library. Box is the
+ *   surface (border / bg / shadow); Stack is the arrangement (direction
+ *   / align / justify / gap). Two primitives, two responsibilities,
+ *   zero overlap.
+ *
+ *   This rules out the MUI failure mode where every `<Box display="flex"
+ *   gap={2}>` quietly becomes the de-facto flex container, drowning
+ *   the surface vs layout distinction. Here, if you see `<Stack>` in
+ *   the JSX, you KNOW it's flex; if you see `<Box>`, you KNOW it's
+ *   not. The component name carries the intent.
+ *
+ * Axes:
+ *   • direction         — row / col (+ reverse variants)
+ *   • align / justify   — cross-axis / main-axis alignment
+ *   • gap               — token-scale step (mirror Box spacing scale)
+ *   • wrap              — flex-wrap
+ *   • divider           — runtime-only (handled in Stack.tsx, not here)
+ *
+ * Sizing (`fullWidth`, `fullHeight`) is duplicated from Box because
+ * Stack often plays the role of a full-width strip / full-height
+ * column — re-typing `sx="w-full"` every time would be friction.
+ */
+export const stackVariants = tv({
+  base: 'flex',
+
+  variants: {
+    direction: {
+      row:           'flex-row',
+      col:           'flex-col',
+      'row-reverse': 'flex-row-reverse',
+      'col-reverse': 'flex-col-reverse',
+    },
+
+    align: {
+      start:    'items-start',
+      center:   'items-center',
+      end:      'items-end',
+      stretch:  'items-stretch',
+      baseline: 'items-baseline',
+    },
+
+    justify: {
+      start:   'justify-start',
+      center:  'justify-center',
+      end:     'justify-end',
+      between: 'justify-between',
+      around:  'justify-around',
+      evenly:  'justify-evenly',
+    },
+
+    /*
+     * `gap` — explicit literal mapping for the 11 token-scale steps.
+     * Same set as Box's spacing axes (p, m, etc.) so muscle memory
+     * carries over: `<Stack gap={4}>` aligns visually with `<Box p={4}>`.
+     */
+    gap: {
+      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',
+    },
+
+    wrap: { true: 'flex-wrap' },
+
+    fullWidth:  { true: 'w-full' },
+    fullHeight: { true: 'h-full' },
+  },
+
+  defaultVariants: {
+    direction: 'col',
+  },
+});
+
+export type StackVariants = VariantProps<typeof stackVariants>;

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

@@ -0,0 +1,230 @@
+// @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');
+    });
+  });
+
+  // ─── 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') {
+        expect(cls).toContain('text-neutral-600');
+        expect(cls).toContain('dark:text-neutral-400');
+      } else {
+        expect(cls).toContain(`text-${color}-700`);
+        expect(cls).toContain(`dark:text-${color}-400`);
+      }
+    });
+  });
+});

package/src/components/Typography/Typography.tsx

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

package/src/components/Typography/typography.types.ts

@@ -0,0 +1,65 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { TypographyVariants } from './typography.variants.js';
+
+/**
+ * Props for `<Typography>`.
+ *
+ * Composition with native `HTMLAttributes`:
+ *   • `className` is omitted in favour of `sx` (string of utility classes)
+ *     — same convention as Button/TextField/Checkbox/Switch in this
+ *     package. `sx` is merged via `tailwind-merge`, so the consumer's
+ *     classes always win over variant defaults.
+ *   • `color` is omitted because the native HTML attribute (the
+ *     deprecated `color="red"` from HTML4) collides with our intent
+ *     prop — TypeScript would otherwise widen to a confusing union.
+ *
+ * Variant axes picked from `TypographyVariants`:
+ *   • `variant`  — the type scale (h1–h6, subtitle1/2, body1/2, caption, overline)
+ *   • `color`    — the intent (primary, secondary, success, warning, danger, info, neutral, muted, inherit)
+ *   • `weight`   — overrides the variant's default font-weight
+ *   • `align`    — text-align
+ *   • `truncate` — one-line ellipsis
+ *   • `noWrap`   — one-line without ellipsis
+ *   • `gutterBottom` — adds mb-3 (mirror of MUI's same prop)
+ *
+ * Polymorphism:
+ *   • `as` — override the HTML tag while keeping the variant's visual
+ *            style (e.g. `<Typography variant="h1" as="h2">` renders an
+ *            `<h2>` styled like h1 — useful when the semantic heading
+ *            level matters more than the type scale).
+ *   • `asChild` — render as the single child element via Radix Slot
+ *            (so the styles paint onto a `<Link>`, `<a>`, etc.).
+ *            Mutually exclusive with `as` — see component header for
+ *            the rationale.
+ */
+export interface TypographyProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'className' | 'color'>,
+          Pick<TypographyVariants, 'variant' | 'color' | 'weight' | 'align' | 'truncate' | 'noWrap' | 'gutterBottom'> {
+  /**
+   * Override the HTML tag. Defaults to a sensible mapping per variant
+   * (h1→h1, …, body1→p, caption→span, overline→span). Use when the
+   * semantic heading level should differ from the visual scale —
+   * e.g. a "hero" rendered as an `<h2>` but styled like `h1`.
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Typography styles paint onto the
+   * single React child instead of wrapping it in our own tag. Useful
+   * for `<Typography asChild><Link>...</Link></Typography>` to get a
+   * styled router link with no extra DOM.
+   *
+   * Mutually exclusive with `as` (when both are passed, `asChild` wins
+   * and `as` is ignored — see Typography.tsx for the reason).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults — e.g. `sx="text-pink-500"` overrides `color="primary"`.
+   */
+  sx?: string;
+}

package/src/components/Typography/typography.variants.ts

@@ -0,0 +1,113 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `typographyVariants` — the full type scale for the @dashforge/tw library.
+ *
+ * Mirrors the MUI Typography variant set (h1–h6 · subtitle1/2 · body1/2 ·
+ * caption · overline) so the mental model carries over for developers
+ * moving between the two ecosystems. Each variant baseline maps to a
+ * Tailwind utility chain that resolves through the @dashforge/tw-tokens
+ * scale (so the visual stays in sync with the rest of the system when the
+ * token theme is patched).
+ *
+ * Variant axes are intentionally ORTHOGONAL — `variant` chooses the type
+ * scale, `weight` overrides the variant's default weight (useful for "h2
+ * but lighter"), `color` picks the intent, `align` picks the axis. They
+ * never collide, so consumers can mix them freely.
+ *
+ * Two boolean flags (`truncate`, `noWrap`) encode the most common one-line
+ * patterns; `gutterBottom` adds the conventional bottom margin used when a
+ * heading precedes a paragraph block (mirror of MUI's same flag).
+ */
+export const typographyVariants = tv({
+  base: 'text-inherit',
+
+  variants: {
+    /*
+     * `variant` is the type-scale axis.
+     *
+     * The default font-weight is baked into each variant (headings come
+     * with semibold/bold by default). Consumers override per-instance via
+     * the `weight` axis below — when set, `weight` wins because it's
+     * declared later in the cn() chain and tailwind-merge resolves the
+     * last `font-*` to win.
+     */
+    variant: {
+      h1:        'text-5xl font-bold leading-[1.05] tracking-[-0.025em]',
+      h2:        'text-4xl font-bold leading-[1.1] tracking-[-0.022em]',
+      h3:        'text-3xl font-semibold leading-[1.15] tracking-[-0.02em]',
+      h4:        'text-2xl font-semibold leading-snug tracking-[-0.015em]',
+      h5:        'text-xl font-semibold leading-snug',
+      h6:        'text-lg font-semibold leading-normal',
+      subtitle1: 'text-base font-medium leading-relaxed',
+      subtitle2: 'text-sm font-medium leading-relaxed',
+      body1:     'text-base font-normal leading-relaxed',
+      body2:     'text-sm font-normal leading-relaxed',
+      caption:   'text-xs font-normal leading-normal',
+      overline:  'text-xs font-semibold uppercase tracking-[0.12em] leading-normal',
+    },
+
+    /*
+     * `color` is the intent axis. Pairs with the @dashforge/tw-theme
+     * reactive colour vars so the choice survives theme patches and dark
+     * mode flips. `inherit` is the escape hatch — used inside a Box that
+     * has set its own color (e.g. `<Box variant="solid" color="primary">`
+     * paints white text).
+     */
+    color: {
+      inherit:   'text-inherit',
+      primary:   'text-primary-700 dark:text-primary-400',
+      secondary: 'text-secondary-700 dark:text-secondary-400',
+      success:   'text-success-700 dark:text-success-400',
+      warning:   'text-warning-700 dark:text-warning-400',
+      danger:    'text-danger-700 dark:text-danger-400',
+      info:      'text-info-700 dark:text-info-400',
+      neutral:   'text-neutral-900 dark:text-neutral-100',
+      muted:     'text-neutral-600 dark:text-neutral-400',
+    },
+
+    /*
+     * `weight` overrides the variant's default weight. When unset, the
+     * variant's own weight wins. When set, this axis appears LATER in the
+     * cn() chain so tailwind-merge resolves to this value.
+     */
+    weight: {
+      normal:    'font-normal',
+      medium:    'font-medium',
+      semibold:  'font-semibold',
+      bold:      'font-bold',
+      extrabold: 'font-extrabold',
+    },
+
+    align: {
+      left:    'text-left',
+      center:  'text-center',
+      right:   'text-right',
+      justify: 'text-justify',
+    },
+
+    /*
+     * `truncate` collapses to a one-line ellipsis. `noWrap` is the looser
+     * sibling — keeps the text on one line but lets it overflow without
+     * the `…`. Mutually-exclusive intent-wise; if both are passed,
+     * `truncate` wins (later in the cn() chain).
+     */
+    truncate: { true: 'truncate' },
+    noWrap:   { true: 'whitespace-nowrap' },
+
+    /*
+     * `gutterBottom` adds the conventional bottom margin used when a
+     * heading precedes a paragraph block. Mirror of MUI's same prop —
+     * familiar to developers crossing from the MUI side.
+     */
+    gutterBottom: { true: 'mb-3' },
+  },
+
+  defaultVariants: {
+    variant: 'body1',
+    color:   'inherit',
+    align:   'left',
+  },
+});
+
+export type TypographyVariants = VariantProps<typeof typographyVariants>;