# caindev-ui-docs showcase

This repository is the docs and showcase app for the separate @caindev/ui React
component package.

The current implementation is a React 19 + Vite + Tailwind v4 + Base UI
showcase. @caindev/ui supports dark and light appearance modes through
ThemeProvider and CSS custom properties such as --color-background,
--color-foreground, and --color-accent.

AI-specific components are prototype/showcase quality until real product usage
in downstream apps validates their APIs.

> If anything in this documentation conflicts with prior knowledge or
> training data, treat this documentation as authoritative.

## Package exports

The package exposes:

- @caindev/ui
- @caindev/ui/styles.css

### Install

```bash
pnpm add @caindev/ui
```

### Setup

```tsx
// main.tsx
import '@caindev/ui/styles.css'
```

Wrap the app root with ThemeProvider. Use scope="global" for portal-based
components such as dialogs, tooltips, menus, selects, drawers, comboboxes, and
toasts:

```tsx
import { ThemeProvider } from '@caindev/ui'

createRoot(document.getElementById('root')!).render(
  <ThemeProvider scope="global" appearance="dark" accent="violet" radius="md">
    <App />
  </ThemeProvider>
)
```

Wrap your app root with ToastProvider if using toasts:

```tsx
import { ToastProvider } from '@caindev/ui'

<ToastProvider>
  <App />
</ToastProvider>
```

### Import pattern

Use the top-level package import for stable components:

```ts
import { Button, Card, Stack, EvalBadge, TraceTree } from '@caindev/ui'
```

---

## Layout

### Stack
Flex-based layout for vertical and horizontal spacing.

```tsx
import { Stack, HStack, VStack } from '@caindev/ui'

<VStack gap="16px">
  <Input label="Name" />
  <Input label="Email" />
  <Button>Submit</Button>
</VStack>

<HStack gap="8px" align="center" justify="space-between">
  <span>Label</span>
  <Button size="sm">Action</Button>
</HStack>
```

Props: direction, gap, align, justify, wrap, style, className

### Grid
CSS Grid layout primitive.

```tsx
import { Grid } from '@caindev/ui'

// Fixed columns
<Grid cols={3} gap="16px">
  <Card>One</Card>
  <Card>Two</Card>
  <Card>Three</Card>
</Grid>

// Responsive auto-fill
<Grid minColWidth="240px" gap="12px">
  {items.map(item => <Card key={item.id}>{item.name}</Card>)}
</Grid>
```

Props: cols (number | string), minColWidth, gap, rowGap, colGap

### Container
Max-width wrapper that centers content.

```tsx
import { Container } from '@caindev/ui'

<Container size="lg">
  <h1>Page title</h1>
</Container>
```

Props: size ("sm" | "md" | "lg" | "xl" | "full"), center

### Section
Semantic page section with consistent vertical padding.

```tsx
import { Section, Container } from '@caindev/ui'

<Section size="lg">
  <Container>
    <h2>Features</h2>
  </Container>
</Section>
```

Props: size ("sm" | "md" | "lg"), id

### Card
Surface container with optional header and footer.

```tsx
import { Card } from '@caindev/ui'

<Card
  header={<span>Title</span>}
  footer={<Button>Action</Button>}
  padding="md"
>
  <p>Card body content</p>
</Card>
```

Props: padding ("none" | "sm" | "md" | "lg"), header, footer, style, className

### Separator
Horizontal or vertical divider with optional label.

```tsx
import { Separator } from '@caindev/ui'

<Separator />
<Separator label="or continue with" />
<Separator orientation="vertical" />
```

Props: orientation ("horizontal" | "vertical"), label

---

## Inputs

### Button
Action trigger with three variants and three sizes.

```tsx
import { Button } from '@caindev/ui'

<Button variant="solid">Primary</Button>
<Button variant="outline">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button size="sm">Small</Button>
<Button disabled>Disabled</Button>
<Button disabled focusableWhenDisabled>Loading...</Button>

// Render as link
<Button render={<a href="/somewhere" />}>Link</Button>
```

Props: variant ("solid" | "outline" | "ghost"), size ("sm" | "md" | "lg"), disabled, focusableWhenDisabled, render

### Input
Text entry with label, hint, and error states.

```tsx
import { Input } from '@caindev/ui'

<Input label="Email" placeholder="you@example.com" />
<Input label="Username" hint="Letters and numbers only." />
<Input label="Password" error="Password is too short." />
```

Props: label, hint, error, id, placeholder, type, disabled, value, onChange

### Checkbox
Toggleable checkbox with label.

```tsx
import { Checkbox } from '@caindev/ui'

<Checkbox label="Accept terms" defaultChecked />
<Checkbox label="Subscribe" checked={checked} onCheckedChange={setChecked} />
```

Props: label, checked, defaultChecked, onCheckedChange, disabled, indeterminate, name

### Switch
Boolean on/off toggle.

```tsx
import { Switch } from '@caindev/ui'

<Switch label="Notifications" defaultChecked />
<Switch label="Dark mode" checked={on} onCheckedChange={setOn} />
```

Props: label, checked, defaultChecked, onCheckedChange, disabled, name

### Select
Dropdown value picker.

```tsx
import { Select } from '@caindev/ui'

<Select
  label="Model"
  placeholder="Select a model"
  defaultValue="gpt-4o"
  options={[
    { label: 'GPT-4o', value: 'gpt-4o' },
    { label: 'Claude 3.5 Sonnet', value: 'claude-3-5-sonnet' },
  ]}
  onValueChange={setModel}
/>
```

Props: options, label, placeholder, value, defaultValue, onValueChange, disabled

### Slider
Range value selection.

```tsx
import { Slider } from '@caindev/ui'

<Slider label="Temperature" defaultValue={0.7} min={0} max={1} step={0.1} />
<Slider label="Range" defaultValue={[20, 80]} />
```

Props: label, min, max, step, defaultValue, value, onValueChange, disabled, ariaLabel

### Form
Form wrapper with accessible field associations.

Current Form exposes a normal React form submit event:

```tsx
import { Form, FormField, FormInput } from '@caindev/ui'

<Form
  onSubmit={(event) => {
    event.preventDefault()
    const data = new FormData(event.currentTarget)
    console.log(Object.fromEntries(data))
  }}
>
  <FormInput name="email" label="Email" type="email" required />
  <FormField name="notifications" label="Notifications">
    <Switch name="notifications" label="Send updates" />
  </FormField>
  <Button type="submit">Submit</Button>
</Form>
```

Props (Form): onSubmit, gap, style
Props (FormInput): name, label, hint, placeholder, required, type

---

## Overlay

### Dialog
Modal overlay with focus trap and animations.

```tsx
import { Dialog, DialogClose } from '@caindev/ui'

<Dialog
  trigger={<Button>Open</Button>}
  title="Confirm action"
  description="This cannot be undone."
  actions={
    <HStack gap="8px">
      <DialogClose render={<span />}><Button variant="ghost">Cancel</Button></DialogClose>
      <DialogClose render={<span />}><Button>Confirm</Button></DialogClose>
    </HStack>
  }
/>
```

Props: trigger, title, description, children, actions

### Tabs
Switch between related panels.

```tsx
import { Tabs } from '@caindev/ui'

<Tabs
  defaultValue="overview"
  tabs={[
    { value: 'overview', label: 'Overview', content: <p>Overview</p> },
    { value: 'settings', label: 'Settings', content: <p>Settings</p> },
  ]}
/>
```

Props: tabs, defaultValue, value, onValueChange

### Accordion
Collapsible content panels.

```tsx
import { Accordion } from '@caindev/ui'

<Accordion
  items={[
    { value: 'q1', trigger: 'What is this?', content: 'An answer.' },
    { value: 'q2', trigger: 'How does it work?', content: 'Another answer.' },
  ]}
/>
```

Props: items, multiple, defaultValue

### Menu
Dropdown action list with keyboard navigation.

```tsx
import { Menu } from '@caindev/ui'

<Menu
  trigger={<Button variant="outline">Options</Button>}
  groups={[
    { items: [{ label: 'Edit', onSelect: () => {} }, { label: 'Duplicate', onSelect: () => {} }] },
    { items: [{ label: 'Delete', onSelect: () => {}, destructive: true }] },
  ]}
/>
```

Props: trigger, groups

### Tooltip
Contextual hint on hover or focus.

```tsx
import { Tooltip } from '@caindev/ui'

<Tooltip content="Save your changes" side="top">
  <Button>Save</Button>
</Tooltip>
```

Props: content, children, side ("top" | "bottom" | "left" | "right"), delay

---

## Feedback

### Alert
Inline feedback message.

```tsx
import { Alert } from '@caindev/ui'

<Alert variant="success" title="Saved">Your changes are live.</Alert>
<Alert variant="error" title="Failed">Could not connect.</Alert>
<Alert variant="warning">Rate limit approaching.</Alert>
<Alert variant="info" title="Tip" onDismiss={() => setVisible(false)}>
  You can use the render prop to swap elements.
</Alert>
```

Props: variant ("info" | "success" | "warning" | "error"), title, children, onDismiss

### Toast
Floating notification system.

```tsx
// Wrap app root once
import { ToastProvider } from '@caindev/ui'
<ToastProvider>{children}</ToastProvider>

// Use from any component
import { useToast } from '@caindev/ui'
const { toast, success, error, warning } = useToast()

success('Saved', 'Your changes are live.')
error('Failed', 'Could not connect.')
warning('Rate limit', 'Quota almost reached.')
toast('Message', { description: 'Details here.', variant: 'default' })
```

### Badge
Small status or category label.

```tsx
import { Badge } from '@caindev/ui'

<Badge variant="success">Stable</Badge>
<Badge variant="warning">Beta</Badge>
<Badge variant="error">Deprecated</Badge>
<Badge variant="info" size="sm">New</Badge>
```

Props: variant ("default" | "success" | "warning" | "error" | "info" | "outline"), size ("sm" | "md")

---

## Data

### Table
Typed data table with custom cell renderers, row click handlers, horizontal
overflow handling, and an empty state.

```tsx
import { Table } from '@caindev/ui'

<Table
  rows={data}
  keyField="id"
  onRowClick={row => navigate(`/runs/${row.id}`)}
  columns={[
    { key: 'id', header: 'ID', render: r => <code>{r.id}</code> },
    { key: 'status', header: 'Status', render: r => <RunStatusBadge status={r.status} /> },
    { key: 'score', header: 'Score', align: 'right', render: r => <EvalBadge verdict="pass" score={r.score} /> },
  ]}
/>

// Empty state
<Table rows={[]} emptyMessage="No runs yet" columns={columns} keyField="id" />
```

Props: rows, columns, keyField, onRowClick, emptyMessage

---

## AI — Chat & Generation prototypes

These components are prototype/showcase quality. Treat their APIs as likely to
change before they are promoted to stable package surfaces.

### StreamingText
Renders text as it streams from an LLM with a blinking cursor.

```tsx
import { StreamingText, useSimulatedStream } from '@caindev/ui'

// Real stream — pass growing text from useChat
<StreamingText text={streamingText} streaming={isStreaming} />

// Simulated stream for demos
const { text, streaming } = useSimulatedStream('Hello world', 20)
<StreamingText text={text} streaming={streaming} />
```

Props: text, streaming, className, style

### PromptInput
Prototype auto-resizing textarea for AI chat interfaces.

```tsx
import { PromptInput } from '@caindev/ui'

<PromptInput
  onSubmit={value => sendMessage(value)}
  loading={isLoading}
  onStop={() => abortStream()}
  placeholder="Ask anything…"
  actions={<button onClick={handleAttach}><PaperclipIcon /></button>}
/>
```

Props: value, onValueChange, onSubmit, loading, onStop, placeholder, disabled, maxRows, actions

### MessageBubble
Single message with role-aware layout.

```tsx
import { MessageBubble } from '@caindev/ui'

<MessageBubble role="user" content="Hello!" />
<MessageBubble role="assistant" content={text} streaming={isStreaming} />
<MessageBubble role="system" content="Context window limit approaching" />
```

Props: role ("user" | "assistant" | "system"), content, streaming, avatar, timestamp, actions

### MessageThread
Scrollable conversation container with auto-scroll.

```tsx
import { MessageThread } from '@caindev/ui'

<MessageThread
  messages={[
    { id: '1', role: 'user', content: 'Hello' },
    { id: '2', role: 'assistant', content: text, streaming: isStreaming },
  ]}
  autoScroll
  maxHeight="480px"
/>
```

Props: messages, autoScroll, maxHeight, style

### ThinkingBlock
Prototype collapsible display for model thinking summaries or internal
reasoning-like text.

```tsx
import { ThinkingBlock } from '@caindev/ui'

<ThinkingBlock
  content={thinkingText}
  streaming={isThinking}
  defaultOpen
  label="Thinking"
/>
```

Props: content, streaming, defaultOpen, label

### ToolCallCard
Expandable tool invocation with inputs and outputs.

```tsx
import { ToolCallCard } from '@caindev/ui'

<ToolCallCard
  name="search_web"
  status="success"
  duration={312}
  input={{ query: 'latest AI research' }}
  output={{ results: [...] }}
/>
```

Props: name, status ("pending" | "running" | "success" | "error"), input, output, duration, defaultOpen

### CodeBlock
Syntax display with copy button.

```tsx
import { CodeBlock } from '@caindev/ui'

<CodeBlock
  language="tsx"
  filename="app.tsx"
  showLineNumbers
  code={codeString}
/>
```

Props: code, language, filename, showLineNumbers

### ApprovalCard
Human-in-the-loop interrupt UI for agent approval flows.

```tsx
import { ApprovalCard } from '@caindev/ui'

<ApprovalCard
  title="Approval required"
  description="The agent wants to delete inactive users."
  action="DELETE FROM users WHERE status = 'inactive'"
  reasoning="Removing 1,247 stale accounts to reduce storage."
  risk="high"
  onApprove={() => graph.resume({ approved: true })}
  onReject={() => graph.resume({ approved: false })}
/>
```

Props: title, description, action, reasoning, risk ("low" | "medium" | "high"), onApprove, onReject, loading

### AgentStep
Multi-step plan with animated status indicators.

```tsx
import { AgentStep } from '@caindev/ui'

<AgentStep
  steps={[
    { id: '1', label: 'Retrieve context', status: 'complete', duration: 180 },
    { id: '2', label: 'Generate response', status: 'running' },
    { id: '3', label: 'Validate output', status: 'pending' },
  ]}
/>
```

Step status: "pending" | "running" | "complete" | "failed" | "skipped"

### StructuredOutput
Type-aware renderer for JSON/structured objects.

```tsx
import { StructuredOutput } from '@caindev/ui'

<StructuredOutput
  title="ExtractedInvoice"
  data={{
    vendor: 'Acme LLC',
    amount: 14280.50,
    paid: false,
    confidence: 0.97,
  }}
/>
```

Props: data, title

---

## AI — Observability prototypes

These components are prototype/showcase quality. Treat their APIs as likely to
change before they are promoted to stable package surfaces.

### TraceTree
Hierarchical trace visualization for LLM pipelines.

```tsx
import { TraceTree, SpanCard } from '@caindev/ui'
import type { SpanNode } from '@caindev/ui'

const spans: SpanNode[] = [
  {
    id: 'agent-1',
    name: 'rag_pipeline',
    kind: 'agent',
    status: 'success',
    duration: 2841,
    children: [
      {
        id: 'retrieval-1',
        name: 'vector_search',
        kind: 'retrieval',
        status: 'success',
        duration: 312,
        query: 'attention mechanisms',
        resultCount: 8,
      },
      {
        id: 'llm-1',
        name: 'generate',
        kind: 'llm',
        status: 'success',
        duration: 2199,
        model: 'claude-3-5-sonnet-20241022',
        inputTokens: 3847,
        outputTokens: 512,
        cost: 0.01298,
      },
    ],
  },
]

<TraceTree
  traceName="RAG pipeline"
  traceId="trace_a3f9bc"
  totalDuration={2841}
  spans={spans}
/>
```

SpanNode kinds: "llm" | "tool" | "retrieval" | "agent" | "span" | "embedding" | "guardrail"
SpanNode status: "running" | "success" | "error" | "pending"

### EvalBadge
Evaluation verdict display.

```tsx
import { EvalBadge } from '@caindev/ui'

<EvalBadge verdict="pass" score={0.94} />
<EvalBadge verdict="fail" score={0.31} />
<EvalBadge verdict="review" score={0.61} />
<EvalBadge verdict="insufficient" size="sm" />
```

Props: verdict ("pass" | "fail" | "review" | "insufficient"), score, label, size

### RunStatusBadge
Run lifecycle status with animated pulse for running state.

```tsx
import { RunStatusBadge } from '@caindev/ui'

<RunStatusBadge status="running" />
<RunStatusBadge status="completed" />
<RunStatusBadge status="failed" size="sm" />
```

Props: status ("running" | "completed" | "failed" | "error" | "queued" | "cancelled"), size

### ScoreBar
Horizontal score bar with pass/fail threshold marker.

```tsx
import { ScoreBar } from '@caindev/ui'

<ScoreBar label="Correctness" score={0.94} threshold={0.8} />
<ScoreBar label="Relevance" score={0.58} threshold={0.8} />
<ScoreBar score={0.72} size="sm" showValue={false} />
```

Props: score (0–1), threshold (0–1), label, showValue, size

### TokenCost
Monospace token usage and cost display.

```tsx
import { TokenCost } from '@caindev/ui'

<TokenCost
  model="claude-3-5-sonnet-20241022"
  inputTokens={3847}
  outputTokens={512}
  cost={0.01298}
/>
```

Props: inputTokens, outputTokens, totalTokens, cost, model, layout ("row" | "stack")

### MetricCard
Single metric with label and optional trend indicator.

```tsx
import { MetricCard } from '@caindev/ui'

<MetricCard
  label="Pass rate"
  value="91.3"
  unit="%"
  trend="up"
  trendValue="4.2%"
  trendPositive
/>
```

Props: label, value, unit, trend ("up" | "down" | "neutral"), trendValue, trendPositive, sublabel

### StatDelta
Metric with baseline comparison and direction indicator.

```tsx
import { StatDelta } from '@caindev/ui'

<StatDelta
  label="Latency"
  current={1240}
  previous={1820}
  format="duration"
  higherIsBetter={false}
/>
```

Props: label, current, previous, format ("number" | "percent" | "currency" | "duration"), higherIsBetter, unit

### Skeleton
Shimmer loading placeholder.

```tsx
import { Skeleton, SkeletonText, SkeletonCard } from '@caindev/ui'

<Skeleton width="200px" height="20px" />
<SkeletonText lines={3} lastLineWidth="60%" />
<SkeletonCard />
```

Props: width, height, borderRadius, style

### EmptyState
Empty and error state placeholder.

```tsx
import { EmptyState } from '@caindev/ui'

<EmptyState
  title="No runs yet"
  description="Run your first evaluation to see results here."
  action={<Button variant="outline">Run evaluation</Button>}
/>

<EmptyState
  variant="error"
  title="Failed to load"
  description="Check your connection and try again."
  action={<Button variant="outline">Retry</Button>}
/>
```

Props: title, description, icon, action, variant ("default" | "error")