@dashforge/tw 0.1.0-beta → 0.2.0-beta

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;
+}

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

@@ -0,0 +1,115 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `dividerVariants` — visual separator with two rendering modes (line-only
+ * vs labeled). Two interconnected TV recipes:
+ *
+ *   • `dividerVariants`      — root container (block layout, alignment)
+ *   • `dividerLineVariants`  — the actual line segments (border style,
+ *                              color, orientation)
+ *
+ * Two recipes (not one with slots) because the labeled mode renders
+ * THREE elements (left line · label · right line) while the line-only
+ * mode is ONE element. Splitting keeps each TV catalogue small and
+ * the type unions narrow.
+ *
+ * Mental model:
+ *   • Without `children` → renders an `<hr>` (or a div if vertical)
+ *     with the line styles applied directly.
+ *   • With `children`    → renders a flex row with two `<span>` line
+ *     segments either side of the label. The label's flex-shrink keeps
+ *     it from being squashed; the line segments share the remaining
+ *     space according to `align`.
+ *
+ * a11y: the root always carries `role="separator"` + `aria-orientation`
+ * — handled in Divider.tsx, not in TV (it's a prop, not a class).
+ */
+
+/*
+ * Root container — only relevant when label is present (flex layout).
+ * For line-only, the root IS the line.
+ */
+export const dividerVariants = tv({
+  base: 'flex items-center',
+
+  variants: {
+    orientation: {
+      horizontal: 'w-full',
+      vertical:   'h-full flex-col',
+    },
+
+    /*
+     * Label alignment along the divider's main axis. Implemented by
+     * setting the flex-basis of the two line segments asymmetrically
+     * — handled in the variants for `dividerLineVariants` below via
+     * compound logic. The root just needs the flex layout.
+     */
+    align: {
+      start:  '',
+      center: '',
+      end:    '',
+    },
+  },
+
+  defaultVariants: {
+    orientation: 'horizontal',
+    align:       'center',
+  },
+});
+
+export type DividerVariants = VariantProps<typeof dividerVariants>;
+
+/*
+ * Line segment(s).
+ *
+ * Border styles (solid/dashed/dotted) are applied as `border-t-{style}`
+ * for horizontal, `border-l-{style}` for vertical. Color drives the
+ * border-* color token to the intent.
+ *
+ * The `segment` axis distinguishes whether this is a line-only render
+ * (full width) vs a labeled-mode segment (flex-1 grows to share space).
+ */
+export const dividerLineVariants = tv({
+  base: '',
+
+  variants: {
+    orientation: {
+      horizontal: 'h-0 border-t',
+      vertical:   'w-0 border-l self-stretch',
+    },
+
+    variant: {
+      solid:  'border-solid',
+      dashed: 'border-dashed',
+      dotted: 'border-dotted',
+    },
+
+    color: {
+      neutral:   'border-neutral-200 dark:border-neutral-800',
+      primary:   'border-primary-300 dark:border-primary-700',
+      secondary: 'border-secondary-300 dark:border-secondary-700',
+      success:   'border-success-300 dark:border-success-700',
+      warning:   'border-warning-300 dark:border-warning-700',
+      danger:    'border-danger-300 dark:border-danger-700',
+      info:      'border-info-300 dark:border-info-700',
+    },
+
+    /*
+     * `segment` controls whether the line spans full width (line-only
+     * mode) or grows to fill space (labeled-mode flex segment).
+     */
+    segment: {
+      full:  'w-full',
+      grow:  'flex-1',
+    },
+  },
+
+  defaultVariants: {
+    orientation: 'horizontal',
+    variant:     'solid',
+    color:       'neutral',
+    segment:     'full',
+  },
+});
+
+export type DividerLineVariants = VariantProps<typeof dividerLineVariants>;