@weave-design-system/react 0.1.0

package/src/data-display/empty-state/EmptyState.tsx

@@ -0,0 +1,34 @@
+import { cn } from '../../utils/cn';
+import { Button } from '../../primitives/button';
+
+export interface EmptyStateProps {
+  icon: React.ReactNode;
+  title: string;
+  description?: string;
+  actionLabel?: string;
+  onAction?: () => void;
+  className?: string;
+}
+
+export function EmptyState({ icon, title, description, actionLabel, onAction, className }: EmptyStateProps) {
+  return (
+    <div className={cn('flex flex-col items-center justify-center py-16 px-6 text-center', className)}>
+      <div className="w-16 h-16 rounded-full bg-surface flex items-center justify-center text-text-secondary mb-4">
+        {icon}
+      </div>
+      <h3 className="text-text-primary font-semibold" style={{ fontSize: 'var(--text-h3)', lineHeight: 'var(--leading-h3)' }}>
+        {title}
+      </h3>
+      {description && (
+        <p className="text-text-secondary mt-2 max-w-sm" style={{ fontSize: 'var(--text-body)', lineHeight: 'var(--leading-body)' }}>
+          {description}
+        </p>
+      )}
+      {actionLabel && onAction && (
+        <Button onClick={onAction} className="mt-6">
+          {actionLabel}
+        </Button>
+      )}
+    </div>
+  );
+}

package/src/data-display/empty-state/index.ts

@@ -0,0 +1,2 @@
+export { EmptyState } from './EmptyState';
+export type { EmptyStateProps } from './EmptyState';

package/src/data-display/progress-bar/ProgressBar.stories.tsx

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ProgressBar } from './ProgressBar';
+
+const meta: Meta<typeof ProgressBar> = { title: 'Data Display/ProgressBar', component: ProgressBar, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof ProgressBar>;
+
+export const Default: Story = { args: { label: 'Project Progress', value: 65 } };
+export const Full: Story = { args: { label: 'Upload Complete', value: 100 } };
+export const Small: Story = { args: { label: 'Getting Started', value: 15 } };

package/src/data-display/progress-bar/ProgressBar.test.tsx

@@ -0,0 +1,15 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { ProgressBar } from './ProgressBar';
+
+describe('ProgressBar', () => {
+  it('renders progressbar role', () => {
+    render(<ProgressBar value={50} />);
+    expect(screen.getByRole('progressbar')).toHaveAttribute('aria-valuenow', '50');
+  });
+  it('shows label and percentage', () => {
+    render(<ProgressBar label="Progress" value={75} />);
+    expect(screen.getByText('Progress')).toBeInTheDocument();
+    expect(screen.getByText('75%')).toBeInTheDocument();
+  });
+});

package/src/data-display/progress-bar/ProgressBar.tsx

@@ -0,0 +1,38 @@
+import { cn } from '../../utils/cn';
+
+export interface ProgressBarProps {
+  label?: string;
+  value: number;
+  max?: number;
+  showValue?: boolean;
+  className?: string;
+}
+
+export function ProgressBar({ label, value, max = 100, showValue = true, className }: ProgressBarProps) {
+  const percent = Math.min(100, Math.max(0, (value / max) * 100));
+
+  return (
+    <div className={cn('flex flex-col gap-1.5', className)}>
+      {(label || showValue) && (
+        <div className="flex justify-between">
+          {label && (
+            <span className="text-text-primary font-medium" style={{ fontSize: 'var(--text-body-sm)' }}>
+              {label}
+            </span>
+          )}
+          {showValue && (
+            <span className="text-text-secondary tabular-nums" style={{ fontSize: 'var(--text-body-sm)' }}>
+              {Math.round(percent)}%
+            </span>
+          )}
+        </div>
+      )}
+      <div className="h-2 w-full rounded-full bg-border overflow-hidden" role="progressbar" aria-valuenow={value} aria-valuemin={0} aria-valuemax={max}>
+        <div
+          className="h-full rounded-full bg-rust transition-all"
+          style={{ width: `${percent}%`, transitionDuration: 'var(--duration-normal)' }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/data-display/progress-bar/index.ts

@@ -0,0 +1,2 @@
+export { ProgressBar } from './ProgressBar';
+export type { ProgressBarProps } from './ProgressBar';

package/src/data-display/stat-card/StatCard.stories.tsx

@@ -0,0 +1,10 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { StatCard } from './StatCard';
+
+const meta: Meta<typeof StatCard> = { title: 'Data Display/StatCard', component: StatCard, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof StatCard>;
+
+export const Default: Story = { args: { label: 'Total Revenue', value: '$45,231', trend: { value: 12.5, direction: 'up' } } };
+export const Down: Story = { args: { label: 'Bounce Rate', value: '24.5%', trend: { value: 3.2, direction: 'down' } } };
+export const NoTrend: Story = { args: { label: 'Total Users', value: '2,420' } };

package/src/data-display/stat-card/StatCard.test.tsx

@@ -0,0 +1,15 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { StatCard } from './StatCard';
+
+describe('StatCard', () => {
+  it('renders label and value', () => {
+    render(<StatCard label="Revenue" value="$1,000" />);
+    expect(screen.getByText('Revenue')).toBeInTheDocument();
+    expect(screen.getByText('$1,000')).toBeInTheDocument();
+  });
+  it('renders trend', () => {
+    render(<StatCard label="Users" value="100" trend={{ value: 5, direction: 'up' }} />);
+    expect(screen.getByText('5%')).toBeInTheDocument();
+  });
+});

package/src/data-display/stat-card/StatCard.tsx

@@ -0,0 +1,40 @@
+import { TrendingUp, TrendingDown } from 'lucide-react';
+import { cn } from '../../utils/cn';
+
+export interface StatCardProps {
+  label: string;
+  value: string | number;
+  trend?: { value: number; direction: 'up' | 'down' };
+  className?: string;
+}
+
+export function StatCard({ label, value, trend, className }: StatCardProps) {
+  return (
+    <div className={cn('rounded-lg bg-surface p-6 shadow-1', className)}>
+      <p
+        className="text-text-secondary font-medium"
+        style={{ fontSize: 'var(--text-body-sm)', lineHeight: 'var(--leading-body-sm)' }}
+      >
+        {label}
+      </p>
+      <p
+        className="text-text-primary font-bold mt-1"
+        style={{ fontSize: 'var(--text-h1)', lineHeight: 'var(--leading-h1)' }}
+      >
+        {value}
+      </p>
+      {trend && (
+        <div
+          className={cn(
+            'flex items-center gap-1 mt-2 font-medium',
+            trend.direction === 'up' ? 'text-success' : 'text-error',
+          )}
+          style={{ fontSize: 'var(--text-body-sm)' }}
+        >
+          {trend.direction === 'up' ? <TrendingUp size={14} /> : <TrendingDown size={14} />}
+          {trend.value}%
+        </div>
+      )}
+    </div>
+  );
+}

package/src/data-display/stat-card/index.ts

@@ -0,0 +1,2 @@
+export { StatCard } from './StatCard';
+export type { StatCardProps } from './StatCard';

package/src/data-display/table/Table.stories.tsx

@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Table } from './Table';
+import { Avatar } from '../../primitives/avatar';
+import { Badge } from '../../primitives/badge';
+
+const meta: Meta<typeof Table> = { title: 'Data Display/Table', component: Table, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof Table>;
+
+export const Default: Story = {
+  render: () => (
+    <Table>
+      <Table.Head>
+        <Table.Row>
+          <Table.HeaderCell>Member</Table.HeaderCell>
+          <Table.HeaderCell>Role</Table.HeaderCell>
+          <Table.HeaderCell>Status</Table.HeaderCell>
+        </Table.Row>
+      </Table.Head>
+      <Table.Body>
+        <Table.Row>
+          <Table.Cell>
+            <div className="flex items-center gap-3">
+              <Avatar name="Alice Smith" size="sm" />
+              <span>Alice Smith</span>
+            </div>
+          </Table.Cell>
+          <Table.Cell>Designer</Table.Cell>
+          <Table.Cell><Badge variant="success">Active</Badge></Table.Cell>
+        </Table.Row>
+        <Table.Row>
+          <Table.Cell>
+            <div className="flex items-center gap-3">
+              <Avatar name="Bob Jones" size="sm" />
+              <span>Bob Jones</span>
+            </div>
+          </Table.Cell>
+          <Table.Cell>Engineer</Table.Cell>
+          <Table.Cell><Badge variant="warning">Away</Badge></Table.Cell>
+        </Table.Row>
+      </Table.Body>
+    </Table>
+  ),
+};

package/src/data-display/table/Table.test.tsx

@@ -0,0 +1,16 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { Table } from './Table';
+
+describe('Table', () => {
+  it('renders table structure', () => {
+    render(
+      <Table>
+        <Table.Head><Table.Row><Table.HeaderCell>Name</Table.HeaderCell></Table.Row></Table.Head>
+        <Table.Body><Table.Row><Table.Cell>Alice</Table.Cell></Table.Row></Table.Body>
+      </Table>,
+    );
+    expect(screen.getByText('Name')).toBeInTheDocument();
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+  });
+});

package/src/data-display/table/Table.tsx

@@ -0,0 +1,71 @@
+import { forwardRef, type ComponentPropsWithoutRef } from 'react';
+import { cn } from '../../utils/cn';
+
+const TableRoot = forwardRef<HTMLTableElement, ComponentPropsWithoutRef<'table'>>(
+  ({ className, ...props }, ref) => (
+    <div className="w-full overflow-auto">
+      <table ref={ref} className={cn('w-full border-collapse', className)} {...props} />
+    </div>
+  ),
+);
+TableRoot.displayName = 'Table';
+
+const TableHead = forwardRef<HTMLTableSectionElement, ComponentPropsWithoutRef<'thead'>>(
+  ({ className, ...props }, ref) => (
+    <thead ref={ref} className={cn('border-b border-border', className)} {...props} />
+  ),
+);
+TableHead.displayName = 'Table.Head';
+
+const TableBody = forwardRef<HTMLTableSectionElement, ComponentPropsWithoutRef<'tbody'>>(
+  ({ className, ...props }, ref) => (
+    <tbody ref={ref} className={cn('[&>tr:last-child]:border-0', className)} {...props} />
+  ),
+);
+TableBody.displayName = 'Table.Body';
+
+const TableRow = forwardRef<HTMLTableRowElement, ComponentPropsWithoutRef<'tr'>>(
+  ({ className, ...props }, ref) => (
+    <tr
+      ref={ref}
+      className={cn('border-b border-border transition-colors hover:bg-surface/50', className)}
+      style={{ transitionDuration: 'var(--duration-micro)' }}
+      {...props}
+    />
+  ),
+);
+TableRow.displayName = 'Table.Row';
+
+const TableHeaderCell = forwardRef<HTMLTableCellElement, ComponentPropsWithoutRef<'th'>>(
+  ({ className, ...props }, ref) => (
+    <th
+      ref={ref}
+      className={cn('px-4 py-3 text-left text-text-secondary font-medium', className)}
+      style={{ fontSize: 'var(--text-caption)', lineHeight: 'var(--leading-caption)', letterSpacing: '0.05em', textTransform: 'uppercase' }}
+      {...props}
+    />
+  ),
+);
+TableHeaderCell.displayName = 'Table.HeaderCell';
+
+const TableCell = forwardRef<HTMLTableCellElement, ComponentPropsWithoutRef<'td'>>(
+  ({ className, ...props }, ref) => (
+    <td
+      ref={ref}
+      className={cn('px-4 py-3 text-text-primary', className)}
+      style={{ fontSize: 'var(--text-body-sm)', lineHeight: 'var(--leading-body-sm)' }}
+      {...props}
+    />
+  ),
+);
+TableCell.displayName = 'Table.Cell';
+
+export const Table = Object.assign(TableRoot, {
+  Head: TableHead,
+  Body: TableBody,
+  Row: TableRow,
+  HeaderCell: TableHeaderCell,
+  Cell: TableCell,
+});
+
+export type { ComponentPropsWithoutRef };

package/src/data-display/table/index.ts

@@ -0,0 +1 @@
+export { Table } from './Table';

package/src/data-display/timeline/Timeline.stories.tsx

@@ -0,0 +1,16 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Timeline } from './Timeline';
+
+const meta: Meta<typeof Timeline> = { title: 'Data Display/Timeline', component: Timeline, tags: ['autodocs'] };
+export default meta;
+type Story = StoryObj<typeof Timeline>;
+
+export const Default: Story = {
+  args: {
+    items: [
+      { id: '1', title: 'Task created', description: 'Created by Alice Smith', timestamp: '2 hours ago', color: 'rust' },
+      { id: '2', title: 'Assigned to Bob', timestamp: '1 hour ago', color: 'forest' },
+      { id: '3', title: 'Status changed to In Progress', timestamp: '30 min ago' },
+    ],
+  },
+};

package/src/data-display/timeline/Timeline.test.tsx

@@ -0,0 +1,11 @@
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { Timeline } from './Timeline';
+
+describe('Timeline', () => {
+  it('renders items', () => {
+    render(<Timeline items={[{ id: '1', title: 'Created', timestamp: '1h ago' }]} />);
+    expect(screen.getByText('Created')).toBeInTheDocument();
+    expect(screen.getByText('1h ago')).toBeInTheDocument();
+  });
+});

package/src/data-display/timeline/Timeline.tsx

@@ -0,0 +1,44 @@
+import { cn } from '../../utils/cn';
+
+export type TimelineColor = 'rust' | 'forest' | 'default';
+
+export interface TimelineItem {
+  id: string;
+  title: string;
+  description?: string;
+  timestamp: string;
+  color?: TimelineColor;
+}
+
+export interface TimelineProps {
+  items: TimelineItem[];
+  className?: string;
+}
+
+const dotColor: Record<TimelineColor, string> = {
+  rust: 'bg-rust',
+  forest: 'bg-forest',
+  default: 'bg-border',
+};
+
+export function Timeline({ items, className }: TimelineProps) {
+  return (
+    <div className={cn('relative', className)}>
+      {items.map((item, i) => (
+        <div key={item.id} className="flex gap-4 pb-6 last:pb-0">
+          <div className="flex flex-col items-center">
+            <div className={cn('w-3 h-3 rounded-full shrink-0 mt-1', dotColor[item.color ?? 'default'])} />
+            {i < items.length - 1 && <div className="w-px flex-1 bg-border mt-1" />}
+          </div>
+          <div className="flex-1 min-w-0">
+            <p className="text-text-primary font-medium" style={{ fontSize: 'var(--text-body-sm)' }}>{item.title}</p>
+            {item.description && (
+              <p className="text-text-secondary mt-0.5" style={{ fontSize: 'var(--text-body-sm)' }}>{item.description}</p>
+            )}
+            <p className="text-text-secondary mt-1" style={{ fontSize: 'var(--text-caption)' }}>{item.timestamp}</p>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/data-display/timeline/index.ts

@@ -0,0 +1,2 @@
+export { Timeline } from './Timeline';
+export type { TimelineProps, TimelineItem, TimelineColor } from './Timeline';

package/src/docs/ComponentOverview.mdx

@@ -0,0 +1,192 @@
+{/* @jsxImportSource react */}
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Component Overview" />
+
+# Component Overview
+
+Weave ships **45 components** organized in layers — from foundational primitives through layout, navigation, data display, feedback, patterns, and productivity-specific components. Each layer builds on the one below it.
+
+---
+
+## Primitives (16)
+
+The building blocks. Every component extends native HTML attributes and supports `ref` forwarding.
+
+<DocTable
+  headers={['Component', 'Key Props', 'Notes']}
+  rows={[
+    ['Button', 'variant, size, loading', '5 variants, 3 sizes'],
+    ['InputGroup', 'label, error, success', 'Label + input + validation'],
+    ['TextareaGroup', 'label, error', 'Resizable multi-line'],
+    ['SelectGroup', 'label, placeholder, error', 'Native select with chevron'],
+    ['Checkbox', 'checked, onCheckedChange', 'Spring animation on check'],
+    ['Radio', 'label, name', 'Native radio group support'],
+    ['Toggle', 'checked, onCheckedChange', 'Switch role, spring thumb'],
+    ['Badge', 'variant, removable', '6 color variants'],
+    ['Avatar', 'name, src, size', 'Initials fallback, 4 sizes'],
+    ['AvatarGroup', 'max', 'Stacking with +N overflow'],
+    ['Link', 'variant', 'Inline or with external icon'],
+    ['Tooltip', 'content, variant, placement', 'Floating UI positioning'],
+    ['Slider', 'min, max, step, showValue', 'Range input with track'],
+    ['DateInput', 'label, error', 'Native date with calendar icon'],
+    ['Combobox', 'options, value, onChange', 'Searchable filtered dropdown'],
+    ['FileUploadDropzone', 'onFiles, accept, multiple', 'Drag & drop zone'],
+  ]}
+/>
+
+---
+
+## Layout (4)
+
+Structural containers that define the app shell.
+
+<DocTable
+  headers={['Component', 'Pattern', 'Notes']}
+  rows={[
+    ['Card', 'Compound: Card.Header, Card.Content, Card.Actions', 'Rounded surface with shadow'],
+    ['Sidebar', 'Context: useSidebar() for collapsed state', '240px expanded, 56px collapsed'],
+    ['TopBar', 'Slots: logo, navigation, actions', 'Fixed header bar'],
+    ['CommandPalette', 'Controlled: open + onOpenChange', 'Cmd+K, search, keyboard nav'],
+  ]}
+/>
+
+---
+
+## Navigation (3)
+
+<DocTable
+  headers={['Component', 'Pattern', 'Notes']}
+  rows={[
+    ['SidebarNavItem', 'Uses SidebarContext', 'Active state, collapsed icon-only'],
+    ['Tabs', 'Compound: Tabs.List, Tabs.Trigger, Tabs.Panel', 'Underline + Pill variants'],
+    ['Breadcrumbs', 'Data-driven: items array', 'Last item = current page'],
+  ]}
+/>
+
+---
+
+## Data Display (7)
+
+<DocTable
+  headers={['Component', 'Notes']}
+  rows={[
+    ['StatCard', 'Value + trend indicator with arrow'],
+    ['ProgressBar', 'Linear bar with label + percentage'],
+    ['CircularProgress', 'SVG donut ring'],
+    ['Table', 'Compound: Table.Head, Table.Body, Table.Row, Table.HeaderCell, Table.Cell'],
+    ['Timeline', 'Vertical connector with colored dots'],
+    ['ActivityFeed', 'Avatar + action + timestamp'],
+    ['EmptyState', 'Icon + title + CTA button'],
+  ]}
+/>
+
+---
+
+## Feedback (4)
+
+<DocTable
+  headers={['Component', 'Pattern', 'Notes']}
+  rows={[
+    ['Toast', 'Provider: ToastProvider + useToast() hook', '4 variants, auto-dismiss, stacking'],
+    ['Modal', 'Compound: Modal.Header, Modal.Body, Modal.Footer', 'Focus trap, Escape to close'],
+    ['AlertBanner', 'Self-dismissing', 'Info, Warning, Error variants'],
+    ['SkeletonLoader', 'Shape-based: text, avatar, image', 'Pulse animation'],
+  ]}
+/>
+
+---
+
+## Patterns (6)
+
+<DocTable
+  headers={['Component', 'Pattern', 'Notes']}
+  rows={[
+    ['Accordion', 'Compound: Accordion.Item, Accordion.Trigger, Accordion.Content', 'Multi-open support'],
+    ['ActionMenu', 'Data-driven: items array', 'Dividers, destructive items'],
+    ['Pagination', 'Controlled: currentPage + onPageChange', 'Ellipsis for large ranges'],
+    ['NotificationDot', 'Wrapper component', 'Red 8px dot positioned on child'],
+    ['Carousel', 'Children as slides', 'Prev/next + dot indicators'],
+    ['ImagePlaceholder', 'Static', 'Configurable size and label'],
+  ]}
+/>
+
+---
+
+## Productivity (5)
+
+Domain-specific components for task management and collaboration.
+
+<DocTable
+  headers={['Component', 'Notes']}
+  rows={[
+    ['TaskCard', 'Title, priority dot, labels, assignee, due date'],
+    ['KanbanColumn', 'Header with count + add button, card slot'],
+    ['PrioritySelector', '4 levels (urgent/high/medium/low) with color dots'],
+    ['CommentThread', 'Nested replies, avatar + timestamp'],
+    ['RichTextToolbar', 'Format toggle buttons with active state'],
+  ]}
+/>
+
+---
+
+## Component Patterns
+
+### Compound Components
+
+Components like `Card`, `Tabs`, `Modal`, `Accordion`, and `Table` use the compound pattern with `Object.assign`:
+
+```tsx
+<Card>
+  <Card.Header>Title</Card.Header>
+  <Card.Content>Body</Card.Content>
+  <Card.Actions>
+    <Button>Save</Button>
+  </Card.Actions>
+</Card>
+```
+
+### Controlled + Uncontrolled
+
+Form components support both patterns via `useControllableState`:
+
+```tsx
+// Uncontrolled (manages its own state)
+<Checkbox label="Accept" defaultChecked={false} />
+
+// Controlled (you manage state)
+<Checkbox label="Accept" checked={isChecked} onCheckedChange={setIsChecked} />
+```
+
+### Styling Overrides
+
+Every component accepts `className` for Tailwind overrides via `cn()` (clsx + tailwind-merge):
+
+```tsx
+<Button className="w-full rounded-xl">Full Width</Button>
+```
+
+export function DocTable({ headers, rows }) {
+  return (
+    <table style={{ width: '100%', borderCollapse: 'collapse', fontSize: 14, marginTop: 12 }}>
+      <thead>
+        <tr style={{ borderBottom: '2px solid #D9D2C7', textAlign: 'left' }}>
+          {headers.map((h, i) => (
+            <th key={i} style={{ padding: '8px 12px', color: '#6B635A', fontWeight: 600 }}>{h}</th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((row, i) => (
+          <tr key={i} style={{ borderBottom: '1px solid #D9D2C7' }}>
+            {row.map((cell, j) => (
+              <td key={j} style={{ padding: '8px 12px', color: j === 0 ? '#2C2825' : '#6B635A', fontWeight: j === 0 ? 600 : 400 }}>
+                {j === 0 ? cell : cell}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}