@dashforge/tw 0.3.0-beta → 0.5.0-beta

package/src/components/Popover/Popover.tsx

@@ -0,0 +1,55 @@
+import * as RadixPopover from '@radix-ui/react-popover';
+import { cn } from '../../utils/cn.js';
+import { popoverVariants } from './popover.variants.js';
+import type { PopoverProps } from './popover.types.js';
+
+/**
+ * Dashforge TW `<Popover>` — clickable floating content panel.
+ *
+ * Built on `@radix-ui/react-popover`:
+ *  - Focus trap inside the popover (Tab cycles within).
+ *  - Outside-click + Escape dismiss.
+ *  - APG dialog-like semantics (`role="dialog"` on content).
+ *  - Portal-rendered.
+ *
+ * Use `<Popover>` for menus / pickers / settings panels with
+ * interactive children. Use `<Tooltip>` for read-only hints.
+ */
+export function Popover(props: PopoverProps) {
+  const {
+    children,
+    content,
+    side = 'bottom',
+    align = 'center',
+    showArrow = false,
+    open,
+    onOpenChange,
+    sideOffset = 8,
+    width,
+    slotProps,
+  } = props;
+
+  const v = popoverVariants();
+
+  return (
+    <RadixPopover.Root open={open} onOpenChange={onOpenChange}>
+      <RadixPopover.Trigger asChild>{children}</RadixPopover.Trigger>
+      <RadixPopover.Portal>
+        <RadixPopover.Content
+          side={side}
+          align={align}
+          sideOffset={sideOffset}
+          style={width != null ? { width } : undefined}
+          className={cn(v.content(), slotProps?.content?.className)}
+        >
+          {content}
+          {showArrow && (
+            <RadixPopover.Arrow
+              className={cn(v.arrow(), slotProps?.arrow?.className)}
+            />
+          )}
+        </RadixPopover.Content>
+      </RadixPopover.Portal>
+    </RadixPopover.Root>
+  );
+}

package/src/components/Popover/popover.types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+
+export interface PopoverSlotProps {
+  content?: { className?: string };
+  arrow?: { className?: string };
+}
+
+/**
+ * Props for `<Popover>`.
+ *
+ * Built on `@radix-ui/react-popover`. Use for richer floating UI
+ * than a tooltip — e.g. action menus, color pickers, settings
+ * panels.
+ *
+ * Differences vs `<Tooltip>`:
+ *  - Popover is **clickable** and captures focus inside (focus trap).
+ *  - Popover supports arbitrary interactive content (forms, buttons).
+ *  - Popover dismisses on outside-click / Escape (Radix-managed).
+ *  - No `role="tooltip"` — popovers are conceptually mini-dialogs.
+ */
+export interface PopoverProps {
+  /** The trigger element (wrapped in Radix's `asChild` slot). */
+  children: ReactNode;
+  /** Popover body content. */
+  content: ReactNode;
+  /** Side of the trigger to render on. @default 'bottom' */
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  /** Alignment along the perpendicular axis. @default 'center' */
+  align?: 'start' | 'center' | 'end';
+  /** Show an arrow indicator. @default false */
+  showArrow?: boolean;
+  /** Controlled open state. */
+  open?: boolean;
+  /** Called when open state changes. */
+  onOpenChange?: (open: boolean) => void;
+  /** Side offset in pixels. @default 8 */
+  sideOffset?: number;
+  /** Width of the popover content. CSS value. */
+  width?: string;
+  /** Per-slot overrides. */
+  slotProps?: PopoverSlotProps;
+}

package/src/components/Popover/popover.variants.ts

@@ -0,0 +1,18 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+export const popoverVariants = tv({
+  slots: {
+    content: [
+      'z-50 rounded-md border border-neutral-200 dark:border-neutral-800',
+      'bg-white dark:bg-neutral-900 p-4 shadow-lg',
+      'text-sm text-neutral-900 dark:text-neutral-50',
+      'focus:outline-none',
+      'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
+      'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+      'motion-reduce:transition-none motion-reduce:duration-0',
+    ],
+    arrow: 'fill-white dark:fill-neutral-900',
+  },
+});
+
+export type PopoverVariants = VariantProps<typeof popoverVariants>;

package/src/components/Skeleton/Skeleton.test.tsx

@@ -0,0 +1,127 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, cleanup } from '@testing-library/react';
+import { Skeleton } from './Skeleton.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('Skeleton — rendering', () => {
+  it('renders a span with aria-hidden', () => {
+    const { container } = render(<Skeleton />);
+    const el = container.querySelector('span');
+    expect(el).not.toBeNull();
+    expect(el?.getAttribute('aria-hidden')).toBe('true');
+    expect(el?.getAttribute('role')).toBe('presentation');
+  });
+
+  it('defaults to variant=text + animation=pulse', () => {
+    const { container } = render(<Skeleton />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('animate-pulse');
+    // text variant has a height of 1em
+    expect(cls).toContain('h-[1em]');
+  });
+});
+
+describe('Skeleton — variants', () => {
+  it.each(['text', 'rectangle', 'circle'] as const)(
+    'renders variant=%s without crashing',
+    (variant) => {
+      const { container } = render(<Skeleton variant={variant} />);
+      expect(container.querySelector('span')).not.toBeNull();
+    },
+  );
+
+  it('rectangle has rounded-md class', () => {
+    const { container } = render(<Skeleton variant="rectangle" />);
+    expect(container.querySelector('span')!.className).toContain('rounded-md');
+  });
+
+  it('circle has rounded-full class', () => {
+    const { container } = render(<Skeleton variant="circle" />);
+    expect(container.querySelector('span')!.className).toContain('rounded-full');
+  });
+});
+
+describe('Skeleton — animations', () => {
+  it('animation=pulse adds animate-pulse', () => {
+    const { container } = render(<Skeleton animation="pulse" />);
+    expect(container.querySelector('span')!.className).toContain('animate-pulse');
+  });
+
+  it('animation=none does NOT add animate-pulse', () => {
+    const { container } = render(<Skeleton animation="none" />);
+    expect(container.querySelector('span')!.className).not.toContain('animate-pulse');
+  });
+
+  it('animation=wave adds overflow-hidden + after gradient', () => {
+    const { container } = render(<Skeleton animation="wave" />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('overflow-hidden');
+    expect(cls).toContain('relative');
+  });
+
+  it('always carries motion-reduce safety regardless of animation', () => {
+    const { container } = render(<Skeleton animation="pulse" />);
+    expect(container.querySelector('span')!.className).toContain('motion-reduce:animate-none');
+  });
+});
+
+describe('Skeleton — dimensions', () => {
+  it('passes width as inline style', () => {
+    const { container } = render(<Skeleton width="200px" />);
+    expect((container.querySelector('span') as HTMLElement).style.width).toBe('200px');
+  });
+
+  it('passes height as inline style', () => {
+    const { container } = render(<Skeleton variant="rectangle" height="120px" />);
+    expect((container.querySelector('span') as HTMLElement).style.height).toBe('120px');
+  });
+
+  it('for circle, height defaults to width', () => {
+    const { container } = render(<Skeleton variant="circle" width="48px" />);
+    const el = container.querySelector('span') as HTMLElement;
+    expect(el.style.width).toBe('48px');
+    expect(el.style.height).toBe('48px');
+  });
+
+  it('for circle, explicit height wins over width-default', () => {
+    const { container } = render(<Skeleton variant="circle" width="48px" height="64px" />);
+    const el = container.querySelector('span') as HTMLElement;
+    expect(el.style.width).toBe('48px');
+    expect(el.style.height).toBe('64px');
+  });
+});
+
+describe('Skeleton — sx + slotProps', () => {
+  it('appends sx to root className', () => {
+    const { container } = render(<Skeleton sx="my-custom-sx" />);
+    expect(container.querySelector('span')!.className).toContain('my-custom-sx');
+  });
+
+  it('applies slotProps.root.className', () => {
+    const { container } = render(
+      <Skeleton slotProps={{ root: { className: 'slot-class' } }} />,
+    );
+    expect(container.querySelector('span')!.className).toContain('slot-class');
+  });
+
+  it('sx wins over variant default on conflict via tailwind-merge', () => {
+    // variant=text emits `bg-neutral-200`; sx forces `bg-red-500`.
+    const { container } = render(<Skeleton sx="bg-red-500" />);
+    const cls = container.querySelector('span')!.className;
+    expect(cls).toContain('bg-red-500');
+    expect(cls).not.toContain('bg-neutral-200');
+  });
+});
+
+describe('Skeleton — accessibility', () => {
+  it('does not appear in role-based queries (aria-hidden + role=presentation)', () => {
+    const { container } = render(<Skeleton />);
+    const el = container.querySelector('span')!;
+    expect(el.getAttribute('aria-hidden')).toBe('true');
+    expect(el.getAttribute('role')).toBe('presentation');
+  });
+});

package/src/components/Skeleton/Skeleton.tsx

@@ -0,0 +1,49 @@
+import type { CSSProperties } from 'react';
+import { cn } from '../../utils/cn.js';
+import { skeletonVariants } from './skeleton.variants.js';
+import type { SkeletonProps } from './skeleton.types.js';
+
+/**
+ * Dashforge TW `<Skeleton>` — loading placeholder primitive.
+ *
+ * Renders as a non-interactive `<span aria-hidden="true">` so screen
+ * readers skip it. The surrounding component is responsible for
+ * announcing loading state via `aria-busy` or `aria-live` if needed.
+ *
+ * Variants:
+ *   - `variant` — `text` (default, line shape) / `rectangle` / `circle`
+ *   - `animation` — `pulse` (default) / `wave` / `none`
+ *
+ * Both animations are gated by `prefers-reduced-motion` (WCAG 2.3.3).
+ *
+ * @example
+ * ```tsx
+ * <Skeleton variant="text" width="200px" />
+ * <Skeleton variant="rectangle" width="100%" height="120px" />
+ * <Skeleton variant="circle" width="40px" />
+ * ```
+ */
+export function Skeleton(props: SkeletonProps) {
+  const { variant = 'text', animation = 'pulse', width, height, sx, slotProps } = props;
+  const v = skeletonVariants({ variant, animation });
+
+  // Width / height come through as inline style — Tailwind doesn't
+  // know about arbitrary user-supplied lengths. We default `circle`'s
+  // height to `width` so consumers don't have to repeat themselves.
+  const style: CSSProperties = {};
+  if (width != null) style.width = width;
+  if (height != null) {
+    style.height = height;
+  } else if (variant === 'circle' && width != null) {
+    style.height = width;
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      role="presentation"
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+      style={style}
+    />
+  );
+}

package/src/components/Skeleton/skeleton.types.ts

@@ -0,0 +1,59 @@
+import type { SkeletonVariants } from './skeleton.variants.js';
+
+export interface SkeletonSlotProps {
+  /** Root element override. */
+  root?: { className?: string };
+}
+
+/**
+ * Props for `<Skeleton>`.
+ *
+ * Visual loading placeholder shown while data / images / components
+ * are being prepared. Three shapes (`variant`), three animations
+ * (`animation`), and free-form `width` / `height` for arbitrary
+ * dimensions.
+ *
+ * Rendered as a non-interactive `<span aria-hidden="true">` so screen
+ * readers skip it entirely.
+ *
+ * Compose by nesting: e.g. avatar + two text lines for a card
+ * placeholder.
+ *
+ * @example
+ * ```tsx
+ * <Skeleton variant="text"      width="200px" />
+ * <Skeleton variant="rectangle" width="100%" height="120px" />
+ * <Skeleton variant="circle"    width="40px" />
+ *
+ * // Compose to mimic a card shape
+ * <div className="flex gap-3">
+ *   <Skeleton variant="circle" width="48px" />
+ *   <div className="flex flex-col gap-2 flex-1">
+ *     <Skeleton variant="text" width="60%" />
+ *     <Skeleton variant="text" width="40%" />
+ *   </div>
+ * </div>
+ * ```
+ */
+export interface SkeletonProps
+  extends Pick<SkeletonVariants, 'variant' | 'animation'> {
+  /**
+   * CSS width (e.g. `"200px"`, `"100%"`, `"60%"`).
+   *
+   * Defaults: `text` → `100%`, `rectangle` → `100%`, `circle` → `40px`.
+   */
+  width?: string;
+
+  /**
+   * CSS height (e.g. `"1em"`, `"120px"`).
+   *
+   * Defaults: `text` → `1em`, `rectangle` → `100px`, `circle` → matches `width`.
+   */
+  height?: string;
+
+  /** Root-level Tailwind override (wins via `tailwind-merge`). */
+  sx?: string;
+
+  /** Per-slot overrides. */
+  slotProps?: SkeletonSlotProps;
+}

package/src/components/Skeleton/skeleton.variants.ts

@@ -0,0 +1,86 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Skeleton>` variant recipe.
+ *
+ * Slots:
+ *  - `root` — single element (atomic component)
+ *
+ * Variant axes:
+ *  - `variant` (`text` | `rectangle` | `circle`) — shape / radius
+ *  - `animation` (`pulse` | `wave` | `none`) — how the placeholder
+ *    "breathes" while data loads. Always gated on
+ *    `prefers-reduced-motion` (no exception — animations are
+ *    purely cosmetic).
+ *
+ * Implementation notes:
+ *
+ *  - `pulse` uses Tailwind's built-in `animate-pulse` (opacity
+ *    1.0 ↔ 0.5 over 2s, ease-in-out infinite).
+ *  - `wave` overlays a moving gradient. Implemented with a
+ *    `relative` container + an `::after` pseudo-element via a
+ *    Tailwind arbitrary-value class. The gradient slides
+ *    horizontally over the surface, mimicking the MUI Skeleton
+ *    "wave" look.
+ *  - Color uses neutral-200 (light) and neutral-800 (dark) for
+ *    the base, picked up automatically by the dashforge preset's
+ *    CSS-variable layer.
+ *
+ * Accessibility: the root has `aria-hidden="true"` (set on the JSX
+ * side, not here). Screen readers skip the skeleton entirely;
+ * the surrounding component is responsible for announcing
+ * loading state via `aria-busy` or `aria-live` if needed.
+ */
+export const skeletonVariants = tv({
+  slots: {
+    root: [
+      'block',
+      'bg-neutral-200 dark:bg-neutral-800',
+      'motion-reduce:animate-none',
+    ],
+  },
+  variants: {
+    variant: {
+      text: {
+        root: 'rounded h-[1em] w-full',
+      },
+      rectangle: {
+        root: 'rounded-md w-full h-[100px]',
+      },
+      circle: {
+        root: 'rounded-full w-10 h-10',
+      },
+    },
+    animation: {
+      pulse: {
+        root: 'animate-pulse',
+      },
+      wave: {
+        root: [
+          'relative overflow-hidden',
+          // The wave is rendered via an arbitrary-value ::after
+          // pseudo-element with a moving linear gradient. Tailwind
+          // doesn't ship a `wave` keyframe; we use the built-in
+          // `animate-pulse` as a fallback if a consumer needs to
+          // override. The gradient stop direction works in both
+          // light and dark mode (white shimmer in light, lighter
+          // overlay in dark).
+          'after:absolute after:inset-0',
+          'after:bg-gradient-to-r after:from-transparent after:via-white/40 after:to-transparent',
+          'dark:after:via-white/10',
+          'after:animate-pulse',
+          'after:motion-reduce:animate-none',
+        ],
+      },
+      none: {
+        root: '',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'text',
+    animation: 'pulse',
+  },
+});
+
+export type SkeletonVariants = VariantProps<typeof skeletonVariants>;

package/src/components/Tabs/Tabs.test.tsx

@@ -0,0 +1,74 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { Tabs } from './Tabs.js';
+
+void React;
+afterEach(() => cleanup());
+
+const items = [
+  { value: 'overview', label: 'Overview', content: <p>Overview body</p> },
+  { value: 'details', label: 'Details', content: <p>Details body</p> },
+  { value: 'history', label: 'History', content: <p>History body</p> },
+];
+
+describe('Tabs — rendering', () => {
+  it('renders all triggers and the default-active content', () => {
+    render(<Tabs items={items} />);
+    expect(screen.queryByRole('tab', { name: 'Overview' })).not.toBeNull();
+    expect(screen.queryByRole('tab', { name: 'Details' })).not.toBeNull();
+    expect(screen.queryByRole('tab', { name: 'History' })).not.toBeNull();
+    // Only the active panel renders content (others get data-state="inactive").
+    expect(screen.queryByText('Overview body')).not.toBeNull();
+  });
+
+  it('honors `defaultValue`', () => {
+    render(<Tabs items={items} defaultValue="history" />);
+    expect(screen.queryByText('History body')).not.toBeNull();
+  });
+
+  it('switches active panel via controlled `value` rerender', () => {
+    const { rerender } = render(
+      <Tabs items={items} value="overview" onValueChange={() => {}} />
+    );
+    expect(screen.queryByText('Overview body')).not.toBeNull();
+    rerender(<Tabs items={items} value="details" onValueChange={() => {}} />);
+    expect(screen.queryByText('Details body')).not.toBeNull();
+  });
+
+  it('marks the active tab via aria-selected', () => {
+    render(<Tabs items={items} defaultValue="details" />);
+    const detailsTab = screen.getByRole('tab', { name: 'Details' });
+    expect(detailsTab.getAttribute('aria-selected')).toBe('true');
+    const overviewTab = screen.getByRole('tab', { name: 'Overview' });
+    expect(overviewTab.getAttribute('aria-selected')).toBe('false');
+  });
+});
+
+void fireEvent; // imported for parity but not needed after the controlled-mode simplification
+
+describe('Tabs — variants', () => {
+  it.each(['underline', 'pill'] as const)('renders variant=%s', (variant) => {
+    render(<Tabs items={items} variant={variant} />);
+    expect(screen.queryByRole('tablist')).not.toBeNull();
+  });
+
+  it.each(['horizontal', 'vertical'] as const)('renders orientation=%s', (o) => {
+    render(<Tabs items={items} orientation={o} />);
+    const list = screen.getByRole('tablist');
+    expect(list.getAttribute('aria-orientation')).toBe(o);
+  });
+});
+
+describe('Tabs — disabled items', () => {
+  it('marks disabled triggers as disabled', () => {
+    const disabledItems = [
+      ...items.slice(0, 2),
+      { ...items[2]!, disabled: true },
+    ];
+    render(<Tabs items={disabledItems} />);
+    const trigger = screen.getByRole('tab', { name: 'History' }) as HTMLButtonElement;
+    expect(trigger.disabled).toBe(true);
+  });
+});

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,66 @@
+import * as RadixTabs from '@radix-ui/react-tabs';
+import { cn } from '../../utils/cn.js';
+import { tabsVariants } from './tabs.variants.js';
+import type { TabsProps } from './tabs.types.js';
+
+/**
+ * Dashforge TW `<Tabs>` — declarative tab navigation.
+ *
+ * Built on `@radix-ui/react-tabs`:
+ *  - APG tabs pattern (arrow-key navigation, automatic activation,
+ *    `role="tablist"` + `role="tab"` + `role="tabpanel"`).
+ *  - Controlled / uncontrolled (`value` / `defaultValue`).
+ *
+ * Two variant axes:
+ *  - `variant` — `underline` (default) | `pill`
+ *  - `orientation` — `horizontal` (default) | `vertical`
+ */
+export function Tabs(props: TabsProps) {
+  const {
+    items,
+    value,
+    defaultValue,
+    onValueChange,
+    variant = 'underline',
+    orientation = 'horizontal',
+    sx,
+    slotProps,
+  } = props;
+
+  const v = tabsVariants({ variant, orientation });
+  const resolvedDefault = defaultValue ?? items[0]?.value;
+
+  return (
+    <RadixTabs.Root
+      value={value}
+      defaultValue={resolvedDefault}
+      onValueChange={onValueChange}
+      orientation={orientation}
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
+      <RadixTabs.List
+        className={cn(v.list(), slotProps?.list?.className)}
+      >
+        {items.map((item) => (
+          <RadixTabs.Trigger
+            key={item.value}
+            value={item.value}
+            disabled={item.disabled}
+            className={cn(v.trigger(), slotProps?.trigger?.className)}
+          >
+            {item.label}
+          </RadixTabs.Trigger>
+        ))}
+      </RadixTabs.List>
+      {items.map((item) => (
+        <RadixTabs.Content
+          key={item.value}
+          value={item.value}
+          className={cn(v.content(), slotProps?.content?.className)}
+        >
+          {item.content}
+        </RadixTabs.Content>
+      ))}
+    </RadixTabs.Root>
+  );
+}

package/src/components/Tabs/tabs.types.ts

@@ -0,0 +1,49 @@
+import type { ReactNode } from 'react';
+import type { TabsVariants } from './tabs.variants.js';
+
+export interface TabsSlotProps {
+  root?: { className?: string };
+  list?: { className?: string };
+  trigger?: { className?: string };
+  content?: { className?: string };
+}
+
+/**
+ * Single tab item — paired `{ value, label, content }`. The `value`
+ * is the canonical id (selected via the `value` / `defaultValue`
+ * props on the root); the `label` is the trigger button text, and
+ * `content` is what renders in the panel when this tab is active.
+ */
+export interface TabItem {
+  value: string;
+  label: ReactNode;
+  /** Tab panel content. */
+  content: ReactNode;
+  /** Per-tab disabled flag. */
+  disabled?: boolean;
+}
+
+/**
+ * Props for `<Tabs>`.
+ *
+ * Built on `@radix-ui/react-tabs`. Two variant axes:
+ *  - `variant` — `underline` (default) | `pill`
+ *  - `orientation` — `horizontal` (default) | `vertical`
+ *
+ * Supports controlled (`value` + `onValueChange`) and uncontrolled
+ * (`defaultValue`) modes — the `value` prop wins when both are set.
+ */
+export interface TabsProps extends TabsVariants {
+  /** Tab items array (declarative — alternative to passing children). */
+  items: TabItem[];
+  /** Controlled active value. */
+  value?: string;
+  /** Default active value (uncontrolled). Defaults to first item's value. */
+  defaultValue?: string;
+  /** Fires when the active tab changes. */
+  onValueChange?: (value: string) => void;
+  /** Root className shortcut. */
+  sx?: string;
+  /** Per-slot overrides. */
+  slotProps?: TabsSlotProps;
+}