@dashforge/tw 1.0.0 → 1.1.1

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

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

@@ -1,130 +0,0 @@
-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` is the explicit escape hatch — use it on a
-      // `<Typography>` inside a coloured surface (e.g.
-      // `<Box variant="solid" color="primary">` paints white text)
-      // so the text picks up the surface colour. It is NO LONGER the
-      // default: a bare `<Typography>` would otherwise inherit the
-      // consuming app's arbitrary root colour (often OS-`prefers-
-      // color-scheme` driven), which diverges from the Dashforge
-      // `data-dash-tw-theme` mode and breaks colour consistency in
-      // dark mode. The default is now `neutral` — see `defaultVariants`.
-      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 palette auto-inverts via the dashforgePreset() CSS-var
-      // swap — no `dark:` variants. `text-neutral-900` resolves to
-      // dark text in light mode and light text in dark mode; same
-      // applies to `text-neutral-600` (muted).
-      neutral:   'text-neutral-900',
-      muted:     'text-neutral-600',
-    },
-
-    /*
-     * `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',
-    // `neutral` (not `inherit`): a bare `<Typography>` emits
-    // `text-neutral-900`, which auto-inverts via the dashforgePreset()
-    // CSS-var swap and follows the Dashforge mode. Pass
-    // `color="inherit"` explicitly inside a coloured surface.
-    color:   'neutral',
-    align:   'left',
-  },
-});
-
-export type TypographyVariants = VariantProps<typeof typographyVariants>;

package/src/components/VisuallyHidden/VisuallyHidden.test.tsx

@@ -1,86 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { render } from '@testing-library/react';
-import { VisuallyHidden } from './VisuallyHidden.js';
-
-describe('<VisuallyHidden>', () => {
-  it('renders a <span> by default', () => {
-    const { container } = render(<VisuallyHidden>label</VisuallyHidden>);
-    expect(container.firstElementChild?.tagName).toBe('SPAN');
-  });
-
-  it('has the sr-only class', () => {
-    const { container } = render(<VisuallyHidden>label</VisuallyHidden>);
-    expect(container.firstElementChild?.className).toContain('sr-only');
-  });
-
-  it('preserves the text content (so screen readers can read it)', () => {
-    const { container } = render(<VisuallyHidden>Close dialog</VisuallyHidden>);
-    expect(container.firstElementChild?.textContent).toBe('Close dialog');
-  });
-
-  it('as="div" renders <div>', () => {
-    const { container } = render(<VisuallyHidden as="div">label</VisuallyHidden>);
-    expect(container.firstElementChild?.tagName).toBe('DIV');
-  });
-
-  it('sx adds utilities (merged with sr-only)', () => {
-    const { container } = render(
-      <VisuallyHidden sx="text-xs">label</VisuallyHidden>,
-    );
-    const cls = container.firstElementChild?.className ?? '';
-    expect(cls).toContain('sr-only');
-    expect(cls).toContain('text-xs');
-  });
-
-  it('forwards data-* + aria-*', () => {
-    const { container } = render(
-      <VisuallyHidden data-testid="vh" aria-live="polite">x</VisuallyHidden>,
-    );
-    const el = container.firstElementChild;
-    expect(el?.getAttribute('data-testid')).toBe('vh');
-    expect(el?.getAttribute('aria-live')).toBe('polite');
-  });
-
-  it('typical pattern — icon button label', () => {
-    const { container } = render(
-      <button type="button">
-        <span aria-hidden="true">✕</span>
-        <VisuallyHidden>Close</VisuallyHidden>
-      </button>,
-    );
-    const btn = container.querySelector('button');
-    // textContent includes the hidden label so AT can read it
-    expect(btn?.textContent).toBe('✕Close');
-    // visually, the Close span has sr-only
-    const hidden = btn?.querySelector('.sr-only');
-    expect(hidden?.textContent).toBe('Close');
-  });
-
-  // ─── F11-bis edge cases ─────────────────────────────────────────────
-  it('empty children renders empty element with sr-only', () => {
-    const { container } = render(<VisuallyHidden>{''}</VisuallyHidden>);
-    const el = container.firstElementChild;
-    expect(el?.className).toContain('sr-only');
-    expect(el?.textContent).toBe('');
-  });
-
-  it('aria-live="polite" pattern for status announcements', () => {
-    const { container } = render(
-      <VisuallyHidden aria-live="polite">Saved successfully</VisuallyHidden>,
-    );
-    const el = container.firstElementChild;
-    expect(el?.getAttribute('aria-live')).toBe('polite');
-    expect(el?.textContent).toBe('Saved successfully');
-  });
-
-  it('as="div" renders block element (consumer choice for block hidden content)', () => {
-    const { container } = render(
-      <VisuallyHidden as="div">
-        Block content hidden from sight but readable by AT
-      </VisuallyHidden>,
-    );
-    expect(container.firstElementChild?.tagName).toBe('DIV');
-    expect(container.firstElementChild?.className).toContain('sr-only');
-  });
-});

package/src/components/VisuallyHidden/VisuallyHidden.tsx

@@ -1,59 +0,0 @@
-import { forwardRef, type ElementType } from 'react';
-import { cn } from '../../utils/cn.js';
-import type { VisuallyHiddenProps } from './visuallyHidden.types.js';
-
-/**
- * `<VisuallyHidden>` — the accessibility primitive.
- *
- * Hides children from sighted users (zero pixels rendered, no layout
- * impact) while keeping them in the accessibility tree. Screen readers
- * speak the content; voice control software uses it for click targets;
- * keyboard users see nothing — same as if it weren't there.
- *
- * Implementation: Tailwind's built-in `sr-only` utility, which expands to:
- *
- *   .sr-only {
- *     position: absolute;
- *     width: 1px;
- *     height: 1px;
- *     padding: 0;
- *     margin: -1px;
- *     overflow: hidden;
- *     clip: rect(0,0,0,0);
- *     white-space: nowrap;
- *     border-width: 0;
- *   }
- *
- * This is the canonical "visually-hidden but screen-reader-accessible"
- * pattern, also known as the WebAIM clip technique. Critically:
- *
- *   • NOT `display: none` (removes from a11y tree)
- *   • NOT `visibility: hidden` (also removes from a11y tree)
- *   • NOT `opacity: 0` (technically still rendered, doesn't help AT)
- *   • NOT `width/height: 0` (collapses, some AT skips it)
- *
- * Default tag is `<span>` (inline) — the 99% case is "label inside a
- * button or link". For block content, override with `as="div"`, but
- * be aware nesting block inside inline is invalid HTML.
- *
- * The component is intentionally tiny (~30 LoC total): one className,
- * one tag. The value is the COMPONENT NAME — `<VisuallyHidden>` reads
- * as an intentional a11y decision in code review, while
- * `className="sr-only"` looks like a typo or a forgotten utility.
- */
-export const VisuallyHidden = forwardRef<HTMLElement, VisuallyHiddenProps>(
-  function VisuallyHidden(props, ref) {
-    const { as, sx, children, ...rest } = props;
-
-    const Tag = (as ?? 'span') as ElementType;
-    const classes = cn('sr-only', sx);
-
-    return (
-      <Tag ref={ref as never} className={classes} {...rest}>
-        {children}
-      </Tag>
-    );
-  },
-);
-
-VisuallyHidden.displayName = 'VisuallyHidden';

package/src/components/VisuallyHidden/visuallyHidden.types.ts

@@ -1,45 +0,0 @@
-import type { ElementType, HTMLAttributes, ReactElement } from 'react';
-
-/**
- * Props for `<VisuallyHidden>` — the a11y primitive.
- *
- * Hides content visually (zero pixels rendered) while keeping it
- * accessible to assistive technology (screen readers, voice control).
- * The canonical use case: icon-only buttons that need an audible label
- * for non-visual users.
- *
- *   <button>
- *     <CloseIcon />
- *     <VisuallyHidden>Close dialog</VisuallyHidden>
- *   </button>
- *
- * Implementation uses Tailwind's `sr-only` utility, which sets
- * `position: absolute; width: 1px; height: 1px; padding: 0;
- * margin: -1px; overflow: hidden; clip: rect(0,0,0,0);
- * white-space: nowrap; border-width: 0;` — the canonical
- * "visually-hidden but screen-reader-accessible" pattern. Better
- * than `display: none` (removes from a11y tree) and better than
- * `visibility: hidden` (also removes from a11y tree).
- */
-export interface VisuallyHiddenProps
-  extends Omit<HTMLAttributes<HTMLElement>, 'className'> {
-  /**
-   * The text or markup hidden from sighted users but read by AT.
-   * Most often a string label.
-   */
-  children?: ReactElement | string | number;
-
-  /**
-   * Override the rendered HTML tag. Defaults to `'span'` — inline
-   * placement is the most common case (label inside a button or link).
-   * Use `as="div"` when the hidden content is block-level, but be
-   * aware: nesting a block inside an inline parent is invalid HTML.
-   */
-  as?: ElementType;
-
-  /**
-   * Utility classes appended to `sr-only`. RARELY needed for this
-   * primitive (it's just hidden text) — kept for API parity.
-   */
-  sx?: string;
-}

package/src/components/_shared/data/getNestedValue.test.ts

@@ -1,50 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { getNestedValue } from './getNestedValue.js';
-
-describe('getNestedValue', () => {
-  it('returns top-level value', () => {
-    expect(getNestedValue({ a: 1 }, 'a')).toBe(1);
-  });
-
-  it('returns nested value (1 level)', () => {
-    expect(getNestedValue({ user: { name: 'Jane' } }, 'user.name')).toBe('Jane');
-  });
-
-  it('returns nested value (3 levels)', () => {
-    expect(
-      getNestedValue({ a: { b: { c: { d: 42 } } } }, 'a.b.c.d'),
-    ).toBe(42);
-  });
-
-  it('returns undefined when path is empty', () => {
-    expect(getNestedValue({ a: 1 }, '')).toBeUndefined();
-  });
-
-  it('returns undefined when intermediate segment is null', () => {
-    expect(getNestedValue({ user: null as never }, 'user.name')).toBeUndefined();
-  });
-
-  it('returns undefined when intermediate segment is undefined', () => {
-    expect(getNestedValue({} as { a?: { b?: number } }, 'a.b')).toBeUndefined();
-  });
-
-  it('returns undefined when intermediate segment is a primitive', () => {
-    expect(getNestedValue({ a: 'hello' }, 'a.b')).toBeUndefined();
-  });
-
-  it('preserves zero value (not coerced to undefined)', () => {
-    expect(getNestedValue({ a: { b: 0 } }, 'a.b')).toBe(0);
-  });
-
-  it('preserves false value', () => {
-    expect(getNestedValue({ a: { b: false } }, 'a.b')).toBe(false);
-  });
-
-  it('preserves empty string value', () => {
-    expect(getNestedValue({ a: { b: '' } }, 'a.b')).toBe('');
-  });
-
-  it('returns the full sub-object when path stops mid-tree', () => {
-    expect(getNestedValue({ a: { b: { c: 1 } } }, 'a.b')).toEqual({ c: 1 });
-  });
-});

package/src/components/_shared/data/getNestedValue.ts

@@ -1,32 +0,0 @@
-/**
- * Walk a dotted path through an object and return the value, or
- * `undefined` if any segment is missing / nullish.
- *
- * Bug fix from the MUI-side Table (Sprint 4.1 motivation): the
- * existing wrapper typed `field: NestedKeyOf<T>` but performed a
- * flat `row[col.field]` lookup at runtime — nested keys silently
- * returned `undefined`. This helper makes the runtime match the
- * type contract.
- *
- * @example
- * ```ts
- * getNestedValue({ user: { name: 'Jane' } }, 'user.name')  // 'Jane'
- * getNestedValue({ user: null }, 'user.name')              // undefined
- * getNestedValue({}, 'a.b.c')                              // undefined
- * getNestedValue({ a: { b: 0 } }, 'a.b')                   // 0 (NOT undefined)
- * ```
- */
-export function getNestedValue<T extends object>(
-  row: T,
-  path: string,
-): unknown {
-  if (!path) return undefined;
-  const segments = path.split('.');
-  let current: unknown = row;
-  for (const segment of segments) {
-    if (current == null) return undefined;
-    if (typeof current !== 'object') return undefined;
-    current = (current as Record<string, unknown>)[segment];
-  }
-  return current;
-}

package/src/components/_shared/data/useColumnAutoDetect.test.ts

@@ -1,123 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import {
-  useColumnAutoDetect,
-  resolveAlign,
-  resolveMonospace,
-  resolveTabularNums,
-} from './useColumnAutoDetect.js';
-import type { TableColumn } from '../../Table/table.types.js';
-
-interface Row {
-  name: string;
-  age: number;
-  active: boolean;
-  joinedAt: Date;
-  isoDate: string;
-  meta: { count: number };
-  unknownField?: never;
-}
-
-const cols: TableColumn<Row>[] = [
-  { field: 'name',     header: 'Name' },
-  { field: 'age',      header: 'Age' },
-  { field: 'active',   header: 'Active' },
-  { field: 'joinedAt' as never, header: 'JoinedAt' },
-  { field: 'isoDate' as never,  header: 'ISO Date' },
-  { field: 'meta.count' as never, header: 'Count' },
-  { field: 'unknownField' as never, header: 'Unknown' },
-];
-
-const rows: Row[] = [
-  {
-    name: 'Jane', age: 30, active: true,
-    joinedAt: new Date('2024-01-15'),
-    isoDate: '2024-01-15T00:00:00Z',
-    meta: { count: 5 },
-  },
-];
-
-describe('useColumnAutoDetect', () => {
-  it('infers number / boolean / string / date / nested-number', () => {
-    const { result } = renderHook(() => useColumnAutoDetect(rows, cols));
-    expect(result.current.get('name')).toBe('string');
-    expect(result.current.get('age')).toBe('number');
-    expect(result.current.get('active')).toBe('boolean');
-    expect(result.current.get('joinedAt')).toBe('date');
-    expect(result.current.get('isoDate')).toBe('date');
-    expect(result.current.get('meta.count')).toBe('number');
-    expect(result.current.get('unknownField')).toBe('unknown');
-  });
-
-  it('returns unknown for empty rows array', () => {
-    const { result } = renderHook(() => useColumnAutoDetect([], cols));
-    for (const col of cols) {
-      expect(result.current.get(col.field as string)).toBe('unknown');
-    }
-  });
-
-  it('skips null values to find the first non-null sample', () => {
-    const colsAge: TableColumn<{ age: number | null }>[] = [{ field: 'age', header: 'Age' }];
-    const sparseRows = [{ age: null }, { age: null }, { age: 42 }];
-    const { result } = renderHook(() => useColumnAutoDetect(sparseRows, colsAge));
-    expect(result.current.get('age')).toBe('number');
-  });
-});
-
-describe('resolveAlign', () => {
-  it('explicit align wins', () => {
-    expect(resolveAlign({ align: 'center' }, 'number')).toBe('center');
-  });
-  it('number → right', () => {
-    expect(resolveAlign({}, 'number')).toBe('right');
-  });
-  it('boolean → center', () => {
-    expect(resolveAlign({}, 'boolean')).toBe('center');
-  });
-  it('string → left (default)', () => {
-    expect(resolveAlign({}, 'string')).toBe('left');
-  });
-  it('date → left', () => {
-    expect(resolveAlign({}, 'date')).toBe('left');
-  });
-  it('unknown → left', () => {
-    expect(resolveAlign({}, 'unknown')).toBe('left');
-  });
-});
-
-describe('resolveMonospace', () => {
-  // Library MUST NOT auto-pick a font family — it would override
-  // the consumer's theme font. Only explicit opt-in turns it on.
-  it('explicit monospace=true wins', () => {
-    expect(resolveMonospace({ monospace: true })).toBe(true);
-  });
-  it('explicit monospace=false → false', () => {
-    expect(resolveMonospace({ monospace: false })).toBe(false);
-  });
-  it('omitted → false (never auto-applies)', () => {
-    expect(resolveMonospace({})).toBe(false);
-  });
-});
-
-describe('resolveTabularNums', () => {
-  // tabular-nums is a font-feature-setting (digit alignment) — does
-  // NOT change the font family. Safe to auto-apply for number/date.
-  it('explicit tabularNums=true wins', () => {
-    expect(resolveTabularNums({ tabularNums: true }, 'string')).toBe(true);
-  });
-  it('explicit tabularNums=false wins (opt-out)', () => {
-    expect(resolveTabularNums({ tabularNums: false }, 'number')).toBe(false);
-  });
-  it('number → true (auto)', () => {
-    expect(resolveTabularNums({}, 'number')).toBe(true);
-  });
-  it('date → true (auto, ISO digits align)', () => {
-    expect(resolveTabularNums({}, 'date')).toBe(true);
-  });
-  it('string / boolean / unknown → false', () => {
-    expect(resolveTabularNums({}, 'string')).toBe(false);
-    expect(resolveTabularNums({}, 'boolean')).toBe(false);
-    expect(resolveTabularNums({}, 'unknown')).toBe(false);
-  });
-});