@dashforge/tw 0.1.0-beta → 0.2.1-beta

package/src/components/Container/Container.tsx

@@ -0,0 +1,74 @@
+import { forwardRef, type ElementType, type ReactElement } from 'react';
+import { Slot } from '@radix-ui/react-slot';
+import { cn } from '../../utils/cn.js';
+import { containerVariants } from './container.variants.js';
+import type { ContainerProps } from './container.types.js';
+
+/**
+ * `<Container>` — centered max-width wrapper for page-level layouts.
+ *
+ * The pattern is universal: every page-root `<div>` in a non-trivial
+ * web app boils down to "mx-auto + max-w-X + responsive horizontal
+ * padding". Container collapses that into a typed prop set so the
+ * decision lives in ONE place per app section (the Container size),
+ * not scattered as utility chains across every page file.
+ *
+ * Default size is `'xl'` (1280px) — comfortable for full app shells
+ * with a left nav + main + optional right rail. Drop to `'lg'` (1024px)
+ * for content-heavy docs/marketing, jump to `'2xl'` (1536px) for wide
+ * dashboards.
+ *
+ * Composition pattern — Container at the page root, Stack/Grid inside:
+ *
+ *   <Container size="lg" as="main">
+ *     <Stack gap={8}>
+ *       <Typography variant="h1">Page title</Typography>
+ *       <Grid container spacing={6}>
+ *         <Grid xs={12} md={6}>...</Grid>
+ *       </Grid>
+ *     </Stack>
+ *   </Container>
+ *
+ * Container handles the page chrome (centered, padded, capped width);
+ * Stack/Grid handle the actual layout of children. Two concerns, two
+ * primitives.
+ *
+ * Polymorphism rule (same as Typography/Box/Stack/Grid): when both
+ * `as` and `asChild` are passed, `asChild` wins.
+ */
+export const Container = forwardRef<HTMLElement, ContainerProps>(
+  function Container(props, ref) {
+    const {
+      size,
+      px,
+      centerContent,
+      as,
+      asChild = false,
+      sx,
+      children,
+      ...rest
+    } = props;
+
+    const classes = cn(
+      containerVariants({ size, px, centerContent }),
+      sx,
+    );
+
+    if (asChild) {
+      return (
+        <Slot ref={ref} className={classes} {...rest}>
+          {children as ReactElement}
+        </Slot>
+      );
+    }
+
+    const Tag = (as ?? 'div') as ElementType;
+    return (
+      <Tag ref={ref as never} className={classes} {...rest}>
+        {children}
+      </Tag>
+    );
+  },
+);
+
+Container.displayName = 'Container';

package/src/components/Container/container.types.ts

@@ -0,0 +1,45 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { ContainerVariants } from './container.variants.js';
+
+/**
+ * Props for `<Container>` — page-level centered max-width wrapper.
+ *
+ * Use at the page-root level (or section-root) to constrain content
+ * width and apply the canonical responsive horizontal padding ramp.
+ * Compose Stack/Grid INSIDE Container for the actual layout work.
+ *
+ * Native attribute overrides:
+ *   • `className` omitted in favour of `sx` (utility string, merged
+ *     via tailwind-merge — same convention as Box/Stack/Grid/Typography).
+ */
+export interface ContainerProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'className'>,
+          Pick<ContainerVariants, 'size' | 'px' | 'centerContent'> {
+  /**
+   * Override the rendered HTML tag. Defaults to `'div'`. Use
+   * `as="main"` for the primary content region of a page,
+   * `as="section"` for a named section, `as="article"` for a
+   * self-contained article shell.
+   *
+   * Ignored when `asChild` is true.
+   */
+  as?: ElementType;
+
+  /**
+   * Render via Radix `Slot` — the Container styles paint onto the
+   * single React child instead of wrapping it. Useful for letting a
+   * router `<main>` element receive the Container chrome without
+   * adding an intermediate `<div>` in the tree.
+   *
+   * Mutually exclusive with `as` (when both are passed, `asChild` wins).
+   */
+  asChild?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge` so the consumer's classes always win over the
+   * variant defaults — useful for one-off vertical padding (`sx="py-8"`),
+   * custom max-width (`sx="max-w-3xl"`), etc.
+   */
+  sx?: string;
+}

package/src/components/Container/container.variants.ts

@@ -0,0 +1,81 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `containerVariants` — centered max-width wrapper for page layouts.
+ *
+ * Architectural role:
+ *
+ *   Every web app has the same pattern at the page-root level: a div
+ *   that's `mx-auto`, capped at some `max-w-*`, with responsive
+ *   horizontal padding. Without Container, every page rewrites:
+ *
+ *     <div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
+ *
+ *   Container collapses that into one typed prop set, with size names
+ *   that mirror Tailwind's breakpoint vocabulary so the muscle memory
+ *   carries over (`size="lg"` ↔ `max-w-screen-lg`).
+ *
+ * Size axis — maps to Tailwind's `max-w-screen-*` aliases:
+ *   • sm     → max-w-screen-sm     (640px)
+ *   • md     → max-w-screen-md     (768px)
+ *   • lg     → max-w-screen-lg     (1024px) — most common doc/content cap
+ *   • xl     → max-w-screen-xl     (1280px) — default; comfortable for full apps
+ *   • 2xl    → max-w-screen-2xl    (1536px) — wide dashboards
+ *   • fluid  → no max-width at all (full bleed, padding still applies)
+ *
+ * Padding axis (`px`):
+ *   • true (default) — responsive horizontal padding (px-4 sm:px-6 lg:px-8)
+ *     The canonical Tailwind responsive padding ramp. Designed to keep
+ *     edges from kissing the viewport on mobile and breathing more on
+ *     larger screens.
+ *   • false — no padding. Use when the consumer wants full bleed AND
+ *     handles edge padding inside (e.g. a hero section with its own
+ *     internal spacing scale).
+ *
+ * Center content axis (`centerContent`):
+ *   • true  — turns the Container into a flex column with items-center
+ *     so the page content stacks centered horizontally. Common for
+ *     marketing pages, sign-in flows, "single artifact" layouts.
+ *   • false (default) — children flow normally (block stacking).
+ */
+export const containerVariants = tv({
+  base: 'mx-auto w-full',
+
+  variants: {
+    size: {
+      sm:    'max-w-screen-sm',
+      md:    'max-w-screen-md',
+      lg:    'max-w-screen-lg',
+      xl:    'max-w-screen-xl',
+      '2xl': 'max-w-screen-2xl',
+      fluid: '',
+    },
+
+    /*
+     * Responsive padding ramp. `false` skips it entirely so the
+     * consumer can supply custom padding via `sx` when needed.
+     */
+    px: {
+      true:  'px-4 sm:px-6 lg:px-8',
+      false: '',
+    },
+
+    /*
+     * Stacks children centered. Mutually compatible with all sizes —
+     * a fluid container with centerContent is the canonical "marketing
+     * hero" layout.
+     */
+    centerContent: {
+      true:  'flex flex-col items-center',
+      false: '',
+    },
+  },
+
+  defaultVariants: {
+    size: 'xl',
+    px: true,
+    centerContent: false,
+  },
+});
+
+export type ContainerVariants = VariantProps<typeof containerVariants>;

package/src/components/Divider/Divider.test.tsx

@@ -0,0 +1,241 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { Divider } from './Divider.js';
+
+describe('<Divider>', () => {
+  // ─── Line-only mode ─────────────────────────────────────────────────
+  describe('line-only (no children)', () => {
+    it('renders <hr> for horizontal', () => {
+      const { container } = render(<Divider />);
+      expect(container.firstElementChild?.tagName).toBe('HR');
+    });
+
+    it('renders <div role="separator"> for vertical', () => {
+      const { container } = render(<Divider orientation="vertical" />);
+      const el = container.firstElementChild;
+      expect(el?.tagName).toBe('DIV');
+      expect(el?.getAttribute('role')).toBe('separator');
+    });
+
+    it('sets aria-orientation correctly', () => {
+      const { container: ch } = render(<Divider />);
+      expect(ch.firstElementChild?.getAttribute('aria-orientation')).toBe('horizontal');
+
+      const { container: cv } = render(<Divider orientation="vertical" />);
+      expect(cv.firstElementChild?.getAttribute('aria-orientation')).toBe('vertical');
+    });
+
+    it('horizontal applies border-t (line carrier)', () => {
+      const { container } = render(<Divider />);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('border-t');
+    });
+
+    it('vertical applies border-l', () => {
+      const { container } = render(<Divider orientation="vertical" />);
+      expect(container.firstElementChild?.className).toContain('border-l');
+    });
+
+    it('strips <hr> UA default via border-0', () => {
+      const { container } = render(<Divider />);
+      expect(container.firstElementChild?.className).toContain('border-0');
+    });
+  });
+
+  // ─── Variants — line style ──────────────────────────────────────────
+  describe('variant', () => {
+    it('default solid', () => {
+      const { container } = render(<Divider />);
+      expect(container.firstElementChild?.className).toContain('border-solid');
+    });
+
+    it('dashed', () => {
+      const { container } = render(<Divider variant="dashed" />);
+      expect(container.firstElementChild?.className).toContain('border-dashed');
+    });
+
+    it('dotted', () => {
+      const { container } = render(<Divider variant="dotted" />);
+      expect(container.firstElementChild?.className).toContain('border-dotted');
+    });
+  });
+
+  // ─── Color intent ───────────────────────────────────────────────────
+  describe('color', () => {
+    it('default neutral', () => {
+      const { container } = render(<Divider />);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('border-neutral-200');
+      expect(cls).toContain('dark:border-neutral-800');
+    });
+
+    it('color="primary"', () => {
+      const { container } = render(<Divider color="primary" />);
+      expect(container.firstElementChild?.className).toContain('border-primary-300');
+    });
+
+    it('color="danger"', () => {
+      const { container } = render(<Divider color="danger" />);
+      expect(container.firstElementChild?.className).toContain('border-danger-300');
+    });
+  });
+
+  // ─── Labeled mode ───────────────────────────────────────────────────
+  describe('labeled (with children)', () => {
+    it('renders 3 children: line, label, line', () => {
+      const { container } = render(<Divider>OR</Divider>);
+      const root = container.firstElementChild;
+      expect(root?.children.length).toBe(3);
+    });
+
+    it('label text is preserved', () => {
+      const { container } = render(<Divider>OR</Divider>);
+      expect(container.firstElementChild?.textContent).toBe('OR');
+    });
+
+    it('root has role="separator" + aria-orientation', () => {
+      const { container } = render(<Divider>OR</Divider>);
+      const root = container.firstElementChild;
+      expect(root?.getAttribute('role')).toBe('separator');
+      expect(root?.getAttribute('aria-orientation')).toBe('horizontal');
+    });
+
+    it('line segments are aria-hidden (separator role is on the root)', () => {
+      const { container } = render(<Divider>OR</Divider>);
+      const lines = container.firstElementChild?.querySelectorAll('span[aria-hidden]');
+      expect(lines?.length).toBe(2);
+    });
+
+    it('center alignment: both segments flex-1', () => {
+      const { container } = render(<Divider align="center">OR</Divider>);
+      const lines = container.firstElementChild?.querySelectorAll('span[aria-hidden]');
+      lines?.forEach((line) => {
+        expect(line.className).toContain('flex-1');
+      });
+    });
+
+    it('start alignment: left segment is short stub', () => {
+      const { container } = render(<Divider align="start">OR</Divider>);
+      const lines = container.firstElementChild?.querySelectorAll('span[aria-hidden]');
+      expect(lines?.[0].className).toContain('basis-8');
+      expect(lines?.[1].className).toContain('flex-1');
+    });
+
+    it('end alignment: right segment is short stub', () => {
+      const { container } = render(<Divider align="end">OR</Divider>);
+      const lines = container.firstElementChild?.querySelectorAll('span[aria-hidden]');
+      expect(lines?.[0].className).toContain('flex-1');
+      expect(lines?.[1].className).toContain('basis-8');
+    });
+
+    it('label gets shrink-0 + padding so it does not collapse', () => {
+      const { container } = render(<Divider>Hello</Divider>);
+      const label = container.firstElementChild?.children[1] as HTMLElement;
+      expect(label.className).toContain('shrink-0');
+      expect(label.className).toContain('px-3');
+    });
+
+    it('color applies to both segments in labeled mode', () => {
+      const { container } = render(<Divider color="primary">OR</Divider>);
+      const lines = container.firstElementChild?.querySelectorAll('span[aria-hidden]');
+      lines?.forEach((line) => {
+        expect(line.className).toContain('border-primary-300');
+      });
+    });
+
+    it('renders complex children (JSX)', () => {
+      const { container } = render(
+        <Divider>
+          <strong>Section title</strong>
+        </Divider>,
+      );
+      const label = container.firstElementChild?.children[1];
+      expect(label?.querySelector('strong')?.textContent).toBe('Section title');
+    });
+  });
+
+  // ─── Override ───────────────────────────────────────────────────────
+  describe('override', () => {
+    it('sx wins over variant defaults', () => {
+      const { container } = render(<Divider sx="border-t-4" />);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('border-t-4');
+      // tailwind-merge collapses border-t → border-t-4
+      expect(cls).not.toMatch(/border-t (?!-)/);
+    });
+
+    it('sx applies on root in labeled mode', () => {
+      const { container } = render(<Divider sx="my-8">OR</Divider>);
+      expect(container.firstElementChild?.className).toContain('my-8');
+    });
+  });
+
+  // ─── Pass-through ───────────────────────────────────────────────────
+  describe('pass-through', () => {
+    it('forwards data-* on root', () => {
+      const { container } = render(<Divider data-testid="d" />);
+      expect(container.firstElementChild?.getAttribute('data-testid')).toBe('d');
+    });
+
+    it('forwards data-* in labeled mode too', () => {
+      const { container } = render(<Divider data-testid="d">OR</Divider>);
+      expect(container.firstElementChild?.getAttribute('data-testid')).toBe('d');
+    });
+  });
+
+  // ─── F11-bis edge cases ─────────────────────────────────────────────
+  describe('color — every intent', () => {
+    const INTENTS = ['secondary', 'success', 'warning', 'danger', 'info'] as const;
+    it.each(INTENTS)('color="%s" emits border-%s-300 with dark pair', (color) => {
+      const { container } = render(<Divider color={color} />);
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain(`border-${color}-300`);
+      expect(cls).toContain(`dark:border-${color}-700`);
+    });
+  });
+
+  describe('vertical labeled mode', () => {
+    it('vertical + label renders all 3 children with vertical layout', () => {
+      const { container } = render(
+        <Divider orientation="vertical">section</Divider>,
+      );
+      const root = container.firstElementChild;
+      expect(root?.tagName).toBe('DIV');
+      expect(root?.getAttribute('aria-orientation')).toBe('vertical');
+      expect(root?.className).toContain('flex-col');
+      expect(root?.children.length).toBe(3);
+    });
+  });
+
+  describe('label edge values', () => {
+    it('numeric label (0) renders correctly', () => {
+      const { container } = render(<Divider>{0}</Divider>);
+      // 0 is a valid React child, should render as "0"
+      expect(container.firstElementChild?.textContent).toBe('0');
+    });
+
+    it('JSX with multiple elements as label', () => {
+      const { container } = render(
+        <Divider>
+          <strong>bold</strong>
+          <em> italic</em>
+        </Divider>,
+      );
+      const root = container.firstElementChild;
+      // root has 3 children (line + label-span + line); label-span has 2 nested
+      expect(root?.children.length).toBe(3);
+      expect(root?.querySelector('strong')?.textContent).toBe('bold');
+      expect(root?.querySelector('em')?.textContent).toBe(' italic');
+    });
+  });
+
+  describe('flexItem (no-op forward-compat hook)', () => {
+    it('flexItem prop does not crash or leak as attribute', () => {
+      const { container } = render(<Divider flexItem />);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.hasAttribute('flexitem')).toBe(false);
+      expect(el.hasAttribute('flexItem')).toBe(false);
+    });
+  });
+});

package/src/components/Divider/Divider.tsx

@@ -0,0 +1,140 @@
+import { forwardRef } from 'react';
+import { cn } from '../../utils/cn.js';
+import { dividerVariants, dividerLineVariants } from './divider.variants.js';
+import type { DividerProps } from './divider.types.js';
+
+/**
+ * `<Divider>` — visual separator. Two modes:
+ *
+ *   1. Line-only (no children):
+ *
+ *        <Divider />
+ *      →  <hr role="separator" aria-orientation="horizontal" />
+ *
+ *      Renders a single horizontal line via `border-t-*` on an `<hr>`
+ *      (which by default has no `display`, no margin in our reset, just
+ *      acts as the border carrier).
+ *
+ *   2. Labeled (with children):
+ *
+ *        <Divider><Typography variant="overline">OR</Typography></Divider>
+ *      →  <div role="separator" aria-orientation="horizontal">
+ *           <span aria-hidden className="flex-1 border-t" />
+ *           <span className="px-3">OR</span>
+ *           <span aria-hidden className="flex-1 border-t" />
+ *         </div>
+ *
+ *      Two line segments share the available space; the label sits
+ *      between them with horizontal padding for breathing room. Each
+ *      line segment is `aria-hidden` (the role="separator" on the root
+ *      conveys the separator semantics — duplicating it would confuse
+ *      screen readers).
+ *
+ * Alignment:
+ *   • align="start"  → label hugs the left, right segment grows
+ *   • align="center" (default) → both segments equal
+ *   • align="end"    → label hugs the right, left segment grows
+ *
+ *   Implemented by setting `flex-basis: 0` to either segment to keep
+ *   it minimal. We use `basis-[2rem]` (32px short stub) rather than
+ *   `basis-0` so a tiny line still hints at the divider on the squashed
+ *   side — pure flex-1 vs basis-0 would collapse it invisibly.
+ *
+ * Vertical orientation:
+ *   The line orientation flips (border-l instead of border-t). Vertical
+ *   labeled dividers are RARE in practice — supported for parity but
+ *   the typical use is line-only between flex row items.
+ *
+ * a11y:
+ *   • Root element gets `role="separator"` (or implicit via `<hr>`)
+ *   • `aria-orientation` is set explicitly so AT knows the axis
+ *   • Labeled mode: label has no extra role; the visual layout speaks
+ */
+export const Divider = forwardRef<HTMLElement, DividerProps>(
+  function Divider(props, ref) {
+    const {
+      orientation = 'horizontal',
+      align = 'center',
+      variant = 'solid',
+      color = 'neutral',
+      children,
+      flexItem,  // currently a no-op (see types) — `self-stretch` is in TV base
+      sx,
+      ...rest
+    } = props;
+
+    // Reference flexItem to silence unused-var lint while keeping it in the
+    // public API for parity with MUI Divider. Forward-compat hook.
+    void flexItem;
+
+    // ─── Mode 1: line-only (no children) ─────────────────────────────
+    if (children == null) {
+      const lineClasses = cn(
+        dividerLineVariants({ orientation, variant, color, segment: 'full' }),
+        sx,
+      );
+
+      // Horizontal → <hr>: zero default styling once we strip the UA
+      // default `<hr>` border via `border-0` (in `dividerLineVariants`
+      // base) and apply our own `border-t-*`. Vertical → <div> because
+      // <hr> can't be vertical cross-browser-consistently.
+      if (orientation === 'horizontal') {
+        return (
+          <hr
+            ref={ref as never}
+            role="separator"
+            aria-orientation="horizontal"
+            className={cn('border-0', lineClasses)}
+            {...rest}
+          />
+        );
+      }
+      return (
+        <div
+          ref={ref as never}
+          role="separator"
+          aria-orientation="vertical"
+          className={lineClasses}
+          {...rest}
+        />
+      );
+    }
+
+    // ─── Mode 2: labeled (with children) ─────────────────────────────
+    const rootClasses = cn(dividerVariants({ orientation, align }), sx);
+
+    /*
+     * Segment widths per `align`:
+     *   • center → both flex-1 (equal share)
+     *   • start  → left short stub, right grows
+     *   • end    → left grows, right short stub
+     *
+     * "Short stub" = 2rem so the divider visually exists on the squashed
+     * side without dominating the label.
+     */
+    const isHorizontal = orientation === 'horizontal';
+    const leftStubClass  = align === 'start' ? (isHorizontal ? 'basis-8 grow-0' : 'basis-8 grow-0') : 'flex-1';
+    const rightStubClass = align === 'end'   ? (isHorizontal ? 'basis-8 grow-0' : 'basis-8 grow-0') : 'flex-1';
+
+    const lineCommon = dividerLineVariants({ orientation, variant, color, segment: 'grow' });
+    const labelPadding = isHorizontal ? 'px-3' : 'py-3';
+
+    return (
+      <div
+        ref={ref as never}
+        role="separator"
+        aria-orientation={orientation}
+        className={rootClasses}
+        {...rest}
+      >
+        <span aria-hidden="true" className={cn(lineCommon, leftStubClass)} />
+        <span className={cn('shrink-0 text-sm text-neutral-500 dark:text-neutral-400', labelPadding)}>
+          {children}
+        </span>
+        <span aria-hidden="true" className={cn(lineCommon, rightStubClass)} />
+      </div>
+    );
+  },
+);
+
+Divider.displayName = 'Divider';

package/src/components/Divider/divider.types.ts

@@ -0,0 +1,52 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import type { DividerVariants, DividerLineVariants } from './divider.variants.js';
+
+/**
+ * Props for `<Divider>` — visual separator with optional inline label.
+ *
+ * Two rendering modes:
+ *   • Line-only (no `children`)   — renders an `<hr>` (horizontal) or
+ *                                   `<div role="separator">` (vertical).
+ *   • Labeled    (with `children`) — renders a flex row: two line
+ *                                    segments around the centered label.
+ *                                    Canonical "OR" separator pattern.
+ *
+ * The user passes ONE consistent prop set; the implementation chooses
+ * the mode based on whether `children` is provided.
+ */
+export interface DividerProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'className' | 'color' | 'children'>,
+          Pick<DividerVariants, 'orientation' | 'align'>,
+          Pick<DividerLineVariants, 'variant' | 'color'> {
+  /**
+   * Optional inline label. When present, the divider switches from
+   * "single line" to "two segments + label" layout — the canonical
+   * "OR" separator pattern between sign-in methods, section titled
+   * separators, etc.
+   *
+   * Accepts any node (string, Typography element, Stack with icon,
+   * etc.). Recommended: `<Typography variant="overline">OR</Typography>`
+   * for short uppercase labels.
+   */
+  children?: ReactNode;
+
+  /**
+   * In a flex Stack `direction="row"`, a `<Divider orientation="vertical">`
+   * with `flexItem` stretches to the row's cross-axis height (via
+   * `self-stretch`). Without it, vertical dividers may collapse to
+   * 0 height because there's nothing to anchor them.
+   *
+   * Implementation note: `self-stretch` is already applied on the
+   * vertical line segment by default in the TV — this prop is a
+   * no-op for now, kept for API parity with MUI's same flag (and as
+   * a forward-compatibility hook if we ever change the default).
+   */
+  flexItem?: boolean;
+
+  /**
+   * Utility classes appended to the variant chain. Resolved via
+   * `tailwind-merge`. Useful for one-off margin (`sx="my-8"`) or
+   * a custom border weight (`sx="border-t-2"`).
+   */
+  sx?: string;
+}