design-system/COMPONENT_GUIDE.md

# Cameleer3 Component Guide

> This file is for Claude Code to reference when building UI features.
> Keep it up to date when components are added or changed.

## Quick Decision Trees

### "I need to show a message to the user"
- Inline contextual note → **InfoCallout**
- Page-level attention banner → **Alert**
- Temporary non-blocking feedback → **Toast** (via `useToast`)
- Destructive action confirmation → **AlertDialog**
- Destructive action needing typed confirmation → **ConfirmDialog**
- Generic dialog with custom content → **Modal**

### "I need a form input"
- Single line text → **Input**
- Multiline text → **Textarea**
- On/off toggle → **Toggle**
- Yes/no with label → **Checkbox**
- One of N options (≤5) → **RadioGroup** + **RadioItem**
- One of N options (>5) → **Select**
- Select multiple from a list → **MultiSelect**
- Edit text inline without a form → **InlineEdit**
- Date/time → **DateTimePicker**
- Date range → **DateRangePicker**
- Wrap any input with label/error/hint → **FormField**

### "I need to show loading state"
- Full component placeholder → **Skeleton** (text, circular, or rectangular)
- Inline spinner → **Spinner** (sm, md, lg)
- Operation progress → **ProgressBar** (determinate or indeterminate)

### "I need to show status"
- Dot indicator → **StatusDot** (live, stale, dead, success, warning, error, running)
- Inline colored status value → **StatusText** (success, warning, error, running, muted — with optional bold)
- Labeled status → **Badge** with semantic color
- Removable label → **Tag**

### "I need navigation"
- App-level sidebar nav → **Sidebar** (compound component — compose sections, trees, footer links)
- Sidebar tree section → **SidebarTree** (data-driven tree with expand/collapse, starring, keyboard nav)
- Starred items persistence → **useStarred** hook (localStorage-backed)
- Breadcrumb trail → **Breadcrumb**
- Paginated data → **Pagination** (standalone) or **DataTable** (built-in pagination)
- Hierarchical tree navigation → **TreeView** (generic)

### "I need floating content"
- Tooltip on hover → **Tooltip**
- Click-triggered panel → **Popover**
- Action menu → **Dropdown**
- Full-screen search/command → **CommandPalette**

### "I need to display data"
- Key metrics → **StatCard** (with optional sparkline/trend)
- Tabular data → **DataTable** (sortable, paginated)
- Time series → **LineChart**, **AreaChart**
- Categorical comparison → **BarChart**
- Inline trend → **Sparkline**
- Advanced charts (treemap, radar, heatmap, pie, etc.) → **Recharts** with `rechartsTheme` (see [Charting Strategy](#charting-strategy))
- Event log → **EventFeed**
- Processing pipeline (Gantt view) → **ProcessorTimeline**
- Processing pipeline (flow diagram) → **RouteFlow**
- Row of summary KPIs → **KpiStrip** (horizontal strip with colored borders, trends, sparklines)
- Scrollable log output → **LogViewer** (timestamped, severity-colored monospace entries)
- Searchable, selectable entity list → **EntityList** (search header, selection highlighting, pairs with SplitPane)

### "I need to organize content"
- Collapsible sections (standalone) → **Collapsible**
- Multiple collapsible sections (one/many open) → **Accordion**
- Tabbed content → **Tabs**
- Tab switching with pill/segment style → **SegmentedTabs**
- Side panel inspector → **DetailPanel**
- Master/detail split layout → **SplitPane** (list on left, detail on right, configurable ratio)
- Section with title + action → **SectionHeader**
- Empty content placeholder → **EmptyState**
- Grouped content box → **Card** (with optional accent and title)
- Grouped items with header + meta + footer → **GroupCard** (e.g., app instances)

### "I need to display text"
- Code/JSON payload → **CodeBlock** (with line numbers, copy button)
- Monospace inline text → **MonoText**
- Keyboard shortcut hint → **KeyboardHint**
- Colored inline status text → **StatusText** (semantic color + optional bold, see also "I need to show status")

### "I need to show people/users"
- Single user avatar → **Avatar**
- Stacked user avatars → **AvatarGroup**

### "I need to group buttons or toggle selections"
- Multi-select toggle group with colored indicators → **ButtonGroup** (e.g., status filters)
- Tab switching with pill/segment style → **SegmentedTabs**

### "I need filtering"
- Multi-select status/category filter → **ButtonGroup** (toggle items on/off)
- Filter pill/chip → **FilterPill** (individual toggleable pills)
- Full filter bar with search → **FilterBar**
- Select multiple from a list → **MultiSelect**

## Composition Patterns

### Standard page layout
```
AppShell → Sidebar (compound) + TopBar + main content + optional DetailPanel

Sidebar compound API:
  <Sidebar collapsed={bool} onCollapseToggle={fn} searchValue={str} onSearchChange={fn}>
    <Sidebar.Header logo={node} title="str" version="str" />
    <Sidebar.Section label="str" icon={node} open={bool} onToggle={fn} active={bool}>
      <SidebarTree nodes={[...]} selectedPath="..." filterQuery="..." ... />
    </Sidebar.Section>
    <Sidebar.Footer>
      <Sidebar.FooterLink icon={node} label="str" onClick={fn} active={bool} />
    </Sidebar.Footer>
  </Sidebar>

Notes:
- Search input auto-renders between Header and first Section (not above Header)
- Section headers have no chevron — the entire row is clickable to toggle
- The app controls all content — sections, order, tree data, collapse state
- Sidebar provides the frame, search input, and icon-rail collapse mode
```

### Data page pattern
```
FilterBar (top)
  → DataTable (center, with built-in sorting + pagination)
  → optional DetailPanel (right slide, on row click)
```

### Form layout
```
FormField wraps any input (Input, Textarea, Select, RadioGroup, etc.)
  provides: label, required indicator, hint text, error message
  gap: 6px between label and input, 4px to hint/error
```

### KPI dashboard
```
Row of StatCard components (each with optional Sparkline and trend)
Below: charts (AreaChart, LineChart, BarChart)
```

### Master/detail management pattern
```
SplitPane + EntityList for CRUD list/detail screens (users, groups, roles)
  EntityList provides: search header, add button, selectable list
  SplitPane provides: responsive two-column layout with empty state
```

### Detail/inspector pattern
```
DetailPanel (right slide) with Tabs for sections OR children for scrollable content
  Tabbed: use tabs prop for multiple panels
  Scrollable: use children for stacked sections (overview, errors, route flow, timeline)
  Each section: Cards with data, CodeBlock for payloads,
  ProcessorTimeline or RouteFlow for exchange flow
```

### Feedback flow
```
User action → Toast (success/error feedback)
Destructive action → AlertDialog (confirmation) → Toast (result)
```

### Tree navigation pattern
```
TreeView for hierarchical data (Application → Routes → Processors)
  onSelect navigates or opens DetailPanel
```

### Agent/instance health pattern
```
StatCard strip (top, recalculates per scope)
  → GroupCard grid (2-col for all, full-width for single app)
    Each GroupCard: header (app name + count) + meta (TPS, routes) + instance rows
    Instance rows: StatusDot + name + Badge + metrics
    Single instance: expanded with LineChart panels
  → EventFeed (bottom, filtered by scope)
URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/:instanceId
```

## Charting Strategy

The design system includes built-in **AreaChart**, **BarChart**, **LineChart**, and **Sparkline** components for standard use cases. For advanced chart types (treemap, radar, heatmap, pie, sankey, etc.), consuming apps should use **Recharts** directly with the design system's theme preset for visual consistency.

**Recharts is the app's dependency, not the design system's.** The design system only exports a theme config object.

### Setup in consuming app

```bash
npm install recharts
```

### Usage with theme preset

```tsx
import { rechartsTheme, CHART_COLORS } from '@cameleer/design-system'
import {
  ResponsiveContainer, LineChart, Line,
  CartesianGrid, XAxis, YAxis, Tooltip, Legend,
} from 'recharts'

<ResponsiveContainer width="100%" height={300}>
  <LineChart data={data}>
    <CartesianGrid {...rechartsTheme.cartesianGrid} />
    <XAxis dataKey="name" {...rechartsTheme.xAxis} />
    <YAxis {...rechartsTheme.yAxis} />
    <Tooltip {...rechartsTheme.tooltip} />
    <Legend {...rechartsTheme.legend} />
    <Line dataKey="value" stroke={CHART_COLORS[0]} strokeWidth={2} dot={false} />
    <Line dataKey="other" stroke={CHART_COLORS[1]} strokeWidth={2} dot={false} />
  </LineChart>
</ResponsiveContainer>
```

### Exports

| Export | Description |
|--------|-------------|
| `rechartsTheme.cartesianGrid` | Dashed gridlines, subtle stroke |
| `rechartsTheme.xAxis` | Mono font axis ticks, subtle color |
| `rechartsTheme.yAxis` | Mono font axis ticks, no axis line |
| `rechartsTheme.tooltip` | Surface bg, border, shadow, monospace values |
| `rechartsTheme.legend` | Matching text size and color |
| `rechartsTheme.colors` | The 8 `CHART_COLORS` (CSS variables with light/dark support) |
| `CHART_COLORS` | Array of `var(--chart-1)` through `var(--chart-8)` |
| `ChartSeries` / `DataPoint` | Type interfaces for chart data |

## Component Index

| Component | Layer | When to use |
|-----------|-------|-------------|
| Accordion | composite | Multiple collapsible sections, single or multi-open mode |
| Alert | primitive | Page-level attention banner with variant colors |
| AlertDialog | composite | Confirmation dialog for destructive/important actions |
| AreaChart | composite | Time series visualization with filled area |
| Avatar | primitive | User representation with initials and color |
| AvatarGroup | composite | Stacked overlapping avatars with overflow count |
| Badge | primitive | Labeled status indicator with semantic colors |
| BarChart | composite | Categorical data comparison, optional stacking |
| Breadcrumb | composite | Navigation path showing current location |
| Button | primitive | Action trigger (primary, secondary, danger, ghost) |
| ButtonGroup | primitive | Multi-select toggle group with optional colored dot indicators. Props: items (value, label, color?), value (Set), onChange |
| Card | primitive | Content container with optional accent border and title header |
| Checkbox | primitive | Boolean input with label |
| CodeBlock | primitive | Syntax-highlighted code/JSON display |
| Collapsible | primitive | Single expand/collapse section |
| CommandPalette | composite | Full-screen search and command interface. `SearchCategory` is an open `string` type — known categories (application, exchange, attribute, route, agent) have built-in labels; custom categories render with title-cased labels and appear as dynamic tabs. |
| ConfirmDialog | composite | Type-to-confirm destructive action dialog built on Modal. Props: open, onClose, onConfirm, title, message, confirmText, confirmLabel, cancelLabel, variant, loading, className |
| DataTable | composite | Sortable, paginated data table with row actions. Use `flush` prop when embedded inside a container that provides its own border/radius |
| DateRangePicker | primitive | Date range selection with presets |
| DateTimePicker | primitive | Single date/time input |
| DetailPanel | composite | Slide-in side panel with tabs or children for scrollable content |
| Dropdown | composite | Action menu triggered by any element |
| EmptyState | primitive | Placeholder for empty content areas |
| EntityList | composite | Searchable, selectable entity list with add button. Pair with SplitPane for CRUD management screens |
| EventFeed | composite | Chronological event log with severity |
| FilterBar | composite | Search + filter controls for data views |
| GroupCard | composite | Card with header, meta row, children, and optional footer/alert. Used for grouping instances by application. |
| FilterPill | primitive | Individual filter chip (active/inactive), supports forwardRef |
| FormField | primitive | Wrapper adding label, hint, error to any input |
| InfoCallout | primitive | Inline contextual note with variant colors |
| InlineEdit | primitive | Click-to-edit text field. Enter saves, Escape/blur cancels. Props: value, onSave, placeholder, disabled, className |
| Input | primitive | Single-line text input with optional icon |
| KeyboardHint | primitive | Keyboard shortcut display |
| KpiStrip | composite | Horizontal row of KPI cards with colored left border, trend, subtitle, optional sparkline |
| Label | primitive | Form label with optional required asterisk |
| LineChart | composite | Time series line visualization |
| LogViewer | composite | Scrollable log output with timestamped, severity-colored monospace entries |
| MenuItem | composite | Sidebar navigation item with health/count |
| Modal | composite | Generic dialog overlay with backdrop |
| MultiSelect | composite | Dropdown with searchable checkbox list and Apply action. Props: options, value, onChange, placeholder, searchable, disabled, className |
| MonoText | primitive | Inline monospace text (xs, sm, md) |
| Pagination | primitive | Page navigation controls |
| Popover | composite | Click-triggered floating panel with arrow |
| ProcessorTimeline | composite | Gantt-style pipeline visualization with selectable rows and optional action menus. Props: processors, totalMs, onProcessorClick?, selectedIndex?, actions?, getActions?. Use `actions` for static menus or `getActions` for per-processor dynamic actions. |
| RouteFlow | composite | Vertical processor node flow diagram with status coloring, connectors, click support, and optional action menus. Props: nodes, onNodeClick?, selectedIndex?, actions?, getActions?. Same action pattern as ProcessorTimeline. |
| ProgressBar | primitive | Determinate/indeterminate progress indicator |
| RadioGroup | primitive | Single-select option group (use with RadioItem) |
| RadioItem | primitive | Individual radio option within RadioGroup |
| SectionHeader | primitive | Section title with optional action button |
| SegmentedTabs | composite | Pill-style segmented tab bar with sliding animated indicator. Same API as Tabs but with elevated active state. Props: tabs, active, onChange, trailing, trailingValue, className |
| Select | primitive | Dropdown select input |
| ShortcutsBar | composite | Keyboard shortcuts reference bar |
| Skeleton | primitive | Loading placeholder (text, circular, rectangular) |
| Sparkline | primitive | Inline mini chart for trends |
| SplitPane | composite | Two-column master/detail layout with configurable ratio and empty state |
| Spinner | primitive | Animated loading indicator |
| StatCard | primitive | KPI card with value, trend, optional sparkline |
| StatusDot | primitive | Colored dot for status indication |
| StatusText | primitive | Inline colored status span (success, warning, error, running, muted) with optional bold |
| Tabs | composite | Tabbed content switcher with optional counts |
| Tag | primitive | Removable colored label |
| Textarea | primitive | Multi-line text input with resize control |
| Toast | composite | Temporary notification (via ToastProvider + useToast) |
| Toggle | primitive | On/off switch input |
| Tooltip | primitive | Hover-triggered text tooltip |
| TreeView | composite | Hierarchical tree with keyboard navigation |

### Layout Components

| Component | Purpose |
|-----------|---------|
| AppShell | Page shell: sidebar + topbar + main + optional detail panel |
| Sidebar | Composable compound sidebar shell with icon-rail collapse mode. Sub-components: `Sidebar.Header`, `Sidebar.Section`, `Sidebar.Footer`, `Sidebar.FooterLink`. The app controls all content via children — the DS provides the frame. |
| SidebarTree | Data-driven tree for sidebar sections. Accepts `nodes: SidebarTreeNode[]` with expand/collapse, starring, keyboard nav, search filter, and path-based selection highlighting. |
| useStarred | Hook for localStorage-backed starred item IDs. Returns `{ starredIds, isStarred, toggleStar }`. |
| TopBar | Header bar with breadcrumb, search trigger, ButtonGroup status filters, time range selector, theme toggle, environment slot (`ReactNode` — pass a string for a static label or a custom dropdown for interactive selection), user avatar |

## Import Paths

### Within this repo (design system development)

```tsx
import { Button, Input, Badge } from './design-system/primitives'
import { DataTable, Modal, Toast } from './design-system/composites'
import type { Column, SearchResult, FeedEvent } from './design-system/composites'
import { AppShell } from './design-system/layout/AppShell'
import { Sidebar } from './design-system/layout/Sidebar/Sidebar'
import { SidebarTree } from './design-system/layout/Sidebar/SidebarTree'
import type { SidebarTreeNode } from './design-system/layout/Sidebar/SidebarTree'
import { useStarred } from './design-system/layout/Sidebar/useStarred'
import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider'
```

### From consuming apps (via npm package)

```tsx
import '@cameleer/design-system/style.css'  // once at app root
import { Button, Input, Modal, DataTable, AppShell, ThemeProvider } from '@cameleer/design-system'
import type { Column, DataTableProps, SearchResult } from '@cameleer/design-system'
```

See `CLAUDE.md` "Using This Design System in Other Apps" for full setup instructions.

## Brand Assets

The design system ships logo assets as static files via package exports. These are not React components — they resolve to file URLs when imported via a bundler.

| Export | Size | Use case |
|--------|------|----------|
| `@cameleer/design-system/logo` | Original | Full resolution for print/marketing |
| `@cameleer/design-system/logo-16` | 16×16 | Browser tab favicon |
| `@cameleer/design-system/logo-32` | 32×32 | Standard favicon, bookmarks |
| `@cameleer/design-system/logo-48` | 48×48 | Windows taskbar |
| `@cameleer/design-system/logo-180` | 180×180 | Apple touch icon |
| `@cameleer/design-system/logo-192` | 192×192 | Android/PWA icon |
| `@cameleer/design-system/logo-512` | 512×512 | PWA splash, og:image |
| `@cameleer/design-system/logo-svg` | Vector | SVG logo for scalable usage |

### Usage

```tsx
import logo from '@cameleer/design-system/logo-512'
<img src={logo} alt="Cameleer3" />
```

```html
<!-- Favicons in index.html -->
<link rel="icon" type="image/png" sizes="32x32" href="/cameleer3-32.png">
<link rel="apple-touch-icon" sizes="180x180" href="/cameleer3-180.png">
```

## Styling Rules

- **CSS Modules only** — no inline styles except dynamic values (width, color from props)
- **Use existing tokens** from `tokens.css` — never hardcode hex colors
- **Theme support** — all colors via CSS custom properties, never hardcode light/dark
- **forwardRef** on all form controls (Input, Textarea, Select, Checkbox, Toggle, Label)
- **className prop** on every component for style overrides
- **Semantic color variants** — use `'success' | 'warning' | 'error'` pattern consistently