# cset-ui Full API Documentation

> Complete API reference, prop interfaces, and Svelte 5 examples for all cset-ui primitives.

## 1. Setup & Installation
```bash
pnpm add github:cset-cbt/cset-ui#v0.4.0
```
`src/app.css`:
```css
@import "tailwindcss";
@import "cset-ui/styles.css";
```

All components can be imported from root:
```svelte
<script lang="ts">
  import {
    Button,
    Card,
    InputField,
    Select,
    Switch,
    DatePicker,
    Dialog,
    Sheet,
    toast,
    Badge,
    Avatar,
    Tabs,
    Pagination,
    Table,
    Accordion,
    Breadcrumb,
    Skeleton,
    PageHeader,
    ThemeToggle,
    CircuitDivider
  } from 'cset-ui';
</script>
```

---

## 2. Overlays & Actions

### Button
Interactive button supporting 3 variants, 3 sizes, and automatic link mode.
- Props:
  - `variant?: 'primary' | 'secondary' | 'danger'` (default: 'primary')
  - `size?: 'sm' | 'md' | 'lg'` (default: 'md')
  - `href?: string` (renders `<a>` tag if provided)
  - `disabled?: boolean` (default: false)
  - `class?: string`
  - `onclick?: (event: MouseEvent) => void`
  - `children?: Snippet`
- Example:
```svelte
<Button variant="primary" size="sm" onclick={() => console.log('clicked')}>
  Save Changes
</Button>
<Button variant="secondary" href="/dashboard">View Dashboard</Button>
<Button variant="danger" size="sm" onclick={handleDelete}>Delete Account</Button>
```

### Toast (Sonner-powered)
Stacked toast notification system with automatic dismissal and interactive action buttons.
- API:
  - `toast.success(message: string, options?: ToastOptions)`
  - `toast.error(message: string, options?: ToastOptions)`
  - `toast.warning(message: string, options?: ToastOptions)`
  - `toast.info(message: string, options?: ToastOptions)`
- Example:
```svelte
<script lang="ts">
  import { toast } from 'cset-ui';

  function trigger() {
    toast.success('Project deployed successfully', {
      description: 'Production worker is live on Cloudflare.',
      action: {
        label: 'Inspect',
        onClick: () => window.open('/metrics')
      }
    });
  }
</script>
```

### Dialog (Modal)
Accessible modal dialog with backdrop blur, focus trap, and clean snippet slots.
- Props:
  - `bind:open={boolean}`
  - `title?: string`
  - `description?: string`
  - `content?: Snippet`
  - `footer?: Snippet`
- Example:
```svelte
<script lang="ts">
  import { Dialog, Button } from 'cset-ui';
  let isOpen = $state(false);
</script>

<Button onclick={() => isOpen = true}>Open Modal</Button>

<Dialog bind:open={isOpen} title="Confirm System Deletion" description="This action cannot be undone.">
  {#snippet content()}
    <p class="text-sm text-ink-muted">All team members will lose database access immediately.</p>
  {/snippet}
  {#snippet footer()}
    <Button variant="secondary" onclick={() => isOpen = false}>Cancel</Button>
    <Button variant="danger" onclick={confirmDelete}>Confirm</Button>
  {/snippet}
</Dialog>
```

### Sheet (Drawer)
Slide-out drawer panel with full backdrop and direction selection.
- Props:
  - `bind:open={boolean}`
  - `side?: 'left' | 'right' | 'top' | 'bottom'` (default: 'right')
  - `title?: string`
  - `description?: string`
- Example:
```svelte
<Sheet bind:open={showDrawer} title="Quick Configuration" side="right">
  <div class="space-y-4 py-3">
    <InputField label="NODE IDENTIFIER" name="nodeId" />
  </div>
</Sheet>
```

---

## 3. Forms & Controls

### InputField
Technical input component with monospace label, error state, and corner accents.
- Props:
  - `label?: string`
  - `name?: string`
  - `type?: string` (default: 'text')
  - `placeholder?: string`
  - `bind:value={string}`
  - `error?: string`
  - `disabled?: boolean`
  - `required?: boolean`
- Example:
```svelte
<InputField
  label="DATABASE URL"
  name="dbUrl"
  type="password"
  placeholder="postgres://user:pass@host:5432/db"
  bind:value={dbUrl}
  error={formErrors.dbUrl}
  required
/>
```

### Select
Dropdown selection component with technical blueprint styling.
- Props:
  - `label?: string`
  - `items: Array<{ value: string; label: string }>`
  - `bind:value={string}`
  - `placeholder?: string`
- Example:
```svelte
<Select
  label="CLUSTER ENVIRONMENT"
  items={[
    { value: 'staging', label: 'Staging (ap-southeast-1)' },
    { value: 'production', label: 'Production High-Availability (global)' }
  ]}
  bind:value={env}
/>
```

### DatePicker
Calendar date picker supporting ISO 8601 string value binding.
- Props:
  - `label?: string`
  - `bind:value={string}`
  - `placeholder?: string`
- Example:
```svelte
<DatePicker label="EXPIRATION DATE" bind:value={expiryDate} />
```

### Switch (Toggle)
Accessible boolean toggle with smooth physical slide motion.
- Props:
  - `label?: string`
  - `bind:checked={boolean}`
  - `disabled?: boolean`
- Example:
```svelte
<Switch label="Enable Realtime Telemetry" bind:checked={enableTelemetry} />
```

---

## 4. Data & Navigation

### Card
The signature Blueprint container with corner-ticks and subtle surface glow.
- Props:
  - `class?: string`
  - `children?: Snippet`
- Example:
```svelte
<Card class="p-6">
  <span class="eyebrow-badge">METRICS</span>
  <h4 class="font-bold text-ink text-base mt-1">Memory Utilization</h4>
  <p class="text-xs text-ink-muted mt-2">Active heap: 142MB / 512MB allocated</p>
</Card>
```

### Badge
Status indicator tag.
- Props:
  - `variant?: 'default' | 'success' | 'warning' | 'danger' | 'outline'`
  - `class?: string`
- Example:
```svelte
<Badge variant="success">HEALTHY</Badge>
<Badge variant="warning">SYNCING</Badge>
<Badge variant="danger">DISCONNECTED</Badge>
```

### Avatar
User avatar with fallback monogram.
- Props:
  - `src?: string`
  - `name?: string`
  - `size?: 'sm' | 'md' | 'lg'`
- Example:
```svelte
<Avatar name="Long Vo" size="md" />
```

### Tabs
Tabbed navigation switcher.
- Props:
  - `items: Array<{ value: string; label: string }>`
  - `bind:value={string}`
- Example:
```svelte
<Tabs
  items={[
    { value: 'overview', label: 'Overview' },
    { value: 'analytics', label: 'Analytics' },
    { value: 'settings', label: 'Settings' }
  ]}
  bind:value={activeTab}
/>
```

### Table
Technical striped data table.
- Props:
  - `headers: string[]`
  - `rows: Array<Array<string | number>>`
- Example:
```svelte
<Table
  headers={['Metric', 'Current Value', 'Threshold', 'Status']}
  rows={[
    ['CPU Load', '42%', '< 80%', 'Normal'],
    ['RAM Usage', '1.2 GB', '< 2.0 GB', 'Normal']
  ]}
/>
```

### PageHeader
Consistent section and page header with eyebrow badge.
- Props:
  - `eyebrow?: string`
  - `title: string`
  - `description?: string`
  - `actions?: Snippet`
- Example:
```svelte
<PageHeader
  eyebrow="SYSTEM // ADMIN"
  title="Access & Identity Federation"
  description="Manage multi-tenant OAuth 2.1 clients, session lifetimes, and RBAC policies."
>
  {#snippet actions()}
    <Button size="sm">Export Audit Log</Button>
  {/snippet}
</PageHeader>
```

### ThemeToggle
Linear / Raycast inspired dark and light mode toggle integrating with W3C View Transitions API.
- Props:
  - `class?: string`
- Example:
```svelte
<ThemeToggle />
```