# Urbicon UI – Full API Reference for LLMs

> This file is optimized for LLM consumption. It contains everything needed to correctly generate code using Urbicon UI.

## Installation

Urbicon UI packages are published to a private registry. Create a `bunfig.toml` in your project root:

```toml
# bunfig.toml
[install.scopes]
"@urbicon-ui" = { url = "https://npm.urbicon.de/" }
```

Then install the packages:

```bash
bun add @urbicon-ui/blocks @urbicon-ui/i18n
```

CSS setup (in your app's root layout or entry CSS). Your app owns the Tailwind
import and it MUST come first; the Urbicon UI CSS that follows depends on it and
overrides its defaults:
```css
@import 'tailwindcss';
@import '@urbicon-ui/blocks/style/index.css'; /* tokens + @source directives */
@import '@urbicon-ui/table/style/index.css';  /* only if you use @urbicon-ui/table */
```

Import the single `style/index.css` — **not** the `foundation`/`semantic`/`interaction`
subfiles. `index.css` ships the design tokens, global classes (`.sr-only`, mint styles),
and the Tailwind `@source` directives that make Tailwind scan the component classes inside
`node_modules`. You do **not** need to add any manual `@source` directives; importing the
subfiles (which omit those directives) is the usual cause of responsive utilities like
`lg:hidden` going missing in production.

## Import Pattern

ALWAYS import from the package root:
```svelte
<script>
  import { Button, Input, Card, Dialog, Badge } from '@urbicon-ui/blocks';
</script>
```

NEVER import from internal paths like `@urbicon-ui/blocks/primitives/Button`.

---

## Shared API Grammar

Every component follows a predictable API. Learn once, apply everywhere.

### `intent` – Semantic Color

Values: `primary` | `secondary` | `success` | `warning` | `danger` | `neutral`
Default: `neutral` (action elements), `primary` (form/decorative elements)

### `variant` – Visual Weight

Values: `filled` | `outlined` | `ghost` | `text` (component-dependent)
- `filled`: Solid background, highest emphasis
- `outlined`: Border only, transparent background
- `ghost`: No border, no background
- `text`: Minimal, text-only (Button only)

### `size` – Dimensions

Standard scale: `xs` | `sm` | `md` | `lg` | `xl`
Default: `md` for all components.

| Size | Height | Font     |
|------|--------|----------|
| xs   | h-6    | text-xs  |
| sm   | h-8    | text-sm  |
| md   | h-10   | text-base|
| lg   | h-12   | text-lg  |
| xl   | h-14   | text-xl  |

### `unstyled` – Strip All Default Styles

```svelte
<Button unstyled class="my-custom-classes">Custom</Button>
```

### `slotClasses` – Override Specific Slots

Each component documents its slots. Override without losing other styles:
```svelte
<Card slotClasses={{ header: 'bg-primary-subtle', footer: 'border-t-2' }}>
  ...
</Card>
```

### `mint` – Micro-Interactions (opt-in)

Requires `registerDefaultMints()` call at app startup.
Values: `'scale'` | `'ripple'` | `'translate'` | `'glow'` | `'none'` | array

```svelte
<Button mint="scale">Hover me</Button>
<Card mint={['scale', 'glow']}>Interactive</Card>
```

### `preset` – Apply a Named Project Style

Values: any preset name registered via `<BlocksProvider presets={{...}}>` (project-specific).

Presets are the correct escape hatch when you need a look **outside the semantic intent palette**
(`primary | secondary | success | warning | danger | neutral`) — e.g. a dark translucent overlay
button on top of an image, a brand-colored button, or a "glass" surface. They keep hover/active/
dark-mode logic coherent AND make the custom look reusable across the project.

```svelte
<Button preset="overlay">Reinholen</Button>
<Card preset="glass">...</Card>
```

Registration happens once at the app root — see `Customization` → `Level 2: Presets` below.

**DO NOT** reach for `class="bg-…! hover:bg-…! active:bg-…!"` when the intent palette doesn't fit.
That pattern defeats the component's hover/active/dark-mode cascade and leaks visual decisions
into every call site. Register a preset instead.

### `class` – Additional CSS Classes

Merged with variant classes. Always available on every component.

---

## Component Families

Every primitive belongs to exactly one of six families. The family decides ARIA role, tier-system membership, and border-token source. Pick the right family up-front to avoid categorical bugs (button that looks like an input, menu that doubles as a listbox, avatar that mutates when commit-radii flatten).

### Family table

| Family | Members | ARIA role | Tier default | Border source |
|---|---|---|---|---|
| Action | Button, ButtonGroup, Menu, Toolbar, Toggle | `button`, `menu`, `menuitem`, `toolbar`, `switch` | `commit` (tier-aware) | Intent (`border-neutral` etc.) |
| Form | Input, Select, Combobox, Textarea, Checkbox, RadioGroup, Slider, FormField | `textbox`, `listbox`, `combobox`, `checkbox`, `radio`, `slider` | `modify` (tier-aware) | Surface (`border-border-subtle`) |
| Navigation | Breadcrumb, Pagination, SegmentGroup, Stepper, Tab | `navigation`, `tablist`, `tab` | per-component (tier-aware) | mixed |
| Container | Card, Alert, Accordion, Collapsible, Dialog, Drawer, Popover, Tooltip, Sidebar, Separator, ConfirmDialog | `dialog`, `tooltip`, `region`, `aside` | `contain` (tier-aware) | Surface or Hairline |
| Feedback / Ambient | Toast, Spinner, Progress, Skeleton, Badge | `status`, `alert`, `progressbar` | **not tier-aware** (Badge is the documented edge case) | Intent (status-tinted) or none |
| Identity | Avatar | `img` or `button` | **not tier-aware** — own shape axis (`circle` / `rounded` / `square`) | none |

### Action — interactive triggers

- ARIA: items dispatch `onSelect` / `onclick`; never hold a value.
- Border: must read as interactive even in `intent="neutral"` — uses Intent tokens (~neutral-500 in light).
- Industry analogue: Radix DropdownMenu, Headless UI Menu.
- Pick `Menu` for one-off action lists; `Button` for single triggers; `ButtonGroup` for grouped triggers; `Toolbar` for free-form bars; `Toggle` for bistable switches.

### Form — value holders

- ARIA: control owns a value, emits `onValueChange` / `bind:value`.
- Border: must read as a container, not a button — uses Surface tokens (~neutral-200 in light).
- Industry analogue: Radix Select / Combobox, Headless UI Listbox / Combobox.
- Pick `Select` for value pickers; `Combobox` for searchable Select; `Select multiple` for multi-select (NOT `Menu multiple`); `Menu` (Action family) for one-off action lists.

### Navigation — section / route selection

- ARIA: `<nav aria-label>`, `role="tablist"` + `role="tab"`, `aria-current` for breadcrumbs / pagination.
- Border: per-component; SegmentGroup indicator uses Intent (active item reads as action-like).
- Pick `Tab` for sectioned content; `SegmentGroup` for inline pickers (holds value, unlike ButtonGroup); `Stepper` for linear progress; `Breadcrumb` for route context; `Pagination` for list paging.

### Container — content surfaces

- ARIA: `<dialog>`, `role="tooltip"`, `<aside>`, `<details>` / `aria-expanded`.
- Border: never Intent in default state — Surface or Hairline. If a container border reads as a button, family mismatch.
- Pick `Card` / `Alert` for in-page surfaces; `Dialog` / `Drawer` / `ConfirmDialog` for modal overlays; `Popover` for anchored floating; `Tooltip` for hover-described inline targets; `Sidebar` for persistent app-shell; `Accordion` / `Collapsible` for disclosure.

### Feedback / Ambient — status communication

- ARIA: `role="alert"`, `role="status"`, `role="progressbar"`. Spinner inherits `aria-busy` from host.
- Tier: NOT tier-aware. Geometry is per-component (e.g. Spinner is always `rounded-full`, Toast is always `rounded-contain`). A wrapping `<Toolbar tier="modify">` does NOT flatten a Toast.
- Badge exception: Badge DOES expose a `tier` prop (`commit` default, `modify` opt-in for inline Toolbar strips) — but the family rule remains: Feedback geometry is per-component, not per-context.
- Pick `Toast` for system notifications; `Alert` for in-page banners; `Spinner` / `Progress` / `Skeleton` for loading states; `Badge` for status tags / counters (see Badge Patterns section for the 5 use cases).

### Identity — Avatar only

- Avatar lives outside the tier system. Its `variant` axis (`circle` / `rounded` / `square`) is identity-shape, not layout-tier. A brand that flattens `--radius-commit` (squared pill buttons) keeps circular avatars.
- Avatar uses no border in its default render; `ring` is the only border-adjacent affordance.

### Cross-family disambiguation

- `Menu` vs `Select` — Menu for one-off actions (Action), Select for value pickers (Form). Different ARIA, different border family.
- `ButtonGroup` vs `SegmentGroup` — ButtonGroup dispatches actions, SegmentGroup holds a value. If you `bind:value` on a ButtonGroup, switch to SegmentGroup.
- `Sidebar` vs `Drawer` — Sidebar for persistent layout (`<aside>`, no backdrop by default), Drawer for transient modal (`<dialog>`, always backdrop + focus-trap).
- `Popover` vs `Tooltip` — Popover hosts a focus-trapped panel for click-interactions, Tooltip is non-focusable for hover-descriptions.
- `Alert` vs `Toast` — Alert is in-page (`role="alert"`), Toast is system-level + stacking.

### Tier-aware components (read context from `<TierContext>`)

Seven primitives expose a `tier` prop AND inherit from a wrapping context when unset:

| Component | Default tier | Family |
|---|---|---|
| Button | `commit` | Action |
| Toggle | `commit` | Action |
| SegmentGroup | `commit` | Navigation |
| Stepper | `commit` | Navigation |
| RadioGroup | `commit` | Form |
| Checkbox | `modify` | Form |
| Tab | `modify` | Navigation |

All other primitives use a fixed tier per family (see family table above) — Container components are `contain`, Form components are `modify`, Action components are `commit`, Feedback / Identity components are not tier-aware at all.

---

## Components

---

## Accordion
Collapsible content sections with expand/collapse animation.
Supports single or multiple open items, keyboard navigation, and ARIA accordion pattern.

**Import:** `import { Accordion } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Accordion>
  <AccordionItem value="faq-1" title="What is Urbicon UI?">
    A Svelte 5 component library with built-in i18n and design tokens.
  </AccordionItem>
  <AccordionItem value="faq-2" title="How does dark mode work?">
    Semantic tokens automatically handle light/dark via the CSS light-dark() function.
  </AccordionItem>
</Accordion>
```

```svelte
<Accordion type="multiple" variant="separated" bind:value={openItems}>
  <AccordionItem value="section-1" title="Section 1">Content</AccordionItem>
  <AccordionItem value="section-2" title="Section 2">Content</AccordionItem>
</Accordion>
```

### Variants
- variant: default, ghost, separated (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Content to render inside the Accordion component |
| ...AccordionVariants | `VariantProps` | no |  | Styling variants from AccordionVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Additional CSS classes to apply to the Accordion component |
| collapsible | `boolean` | no | true | Whether items can be fully collapsed |
| defaultValue | `string | string[]` | no |  | Default open item(s) |
| disabled | `boolean` | no | false | Whether the Accordion is disabled and non-interactive |
| onValueChange | `(value: string | string[]) => void` | no |  | Callback when open items change |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Accordion: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Accordion |
| slotClasses | `Partial<Record<AccordionSlots, string>>` | no |  | Per-slot class overrides. Slots: base | item | trigger | chevron | content | contentInner |
| type | `'single' | 'multiple'` | no | 'single' | Allow single or multiple items open at once |
| unstyled | `boolean` | no |  | Remove default styles |
| value | `string | string[]` | no |  | Controlled open item(s) – string for single, string[] for multiple |
| variant | `'default' | 'separated' | 'ghost'` | no | 'default' | Visual style variant for the Accordion component |

Inherited from:
- AccordionVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## AccountSettings
Self-service account-settings panel: change name, email and
password, and delete the account. Each section talks to `basePath` (default
`/api/auth/account`); pair them with the server handlers
`createUpdateProfileHandler`, `createChangeEmailHandler`,
`createChangePasswordHandler` and `createDeleteAccountHandler`.

**Import:** `import { AccountSettings } from '@urbicon-ui/auth';`

### Examples
```svelte
<AccountSettings {user} onProfileUpdated={(u) => (auth.user = u)} onDeleted={() => goto('/')} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| user | `AuthUser | null` | yes |  | The current authenticated user — its `name` pre-fills the profile field and its `email` is shown as the current address. Pass `locals.user` / your auth store's user. While `null` the panel renders nothing. |
| basePath | `string` | no | '/api/auth/account' | API base path for the account endpoints. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| onDeleted | `() => void` | no |  | Called after the account has been deleted (e.g. redirect to a goodbye page). |
| onProfileUpdated | `(user: AuthUser) => void` | no |  | Called with the refreshed user after a successful profile change (update your store here). |
| slotClasses | `Partial<Record<'root' | 'title' | 'section' | 'sectionTitle' | 'field' | 'submit' | 'danger', string>>` | no |  | Per-slot class overrides. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `title`, `section`, `sectionTitle`, `field`, `submit`, `danger`

---

## Alert
Persistent inline notification for communicating status, warnings, errors,
or informational messages. Supports icons, titles, descriptions, actions, and dismissal.

**Import:** `import { Alert } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Alert intent="success" title="Saved successfully">
  Your changes have been saved.
</Alert>
```

```svelte
<Alert intent="danger" variant="inline" dismissible onDismiss={() => (visible = false)}>
  {#snippet icon()}<AlertCircle size={20} />{/snippet}
  Something went wrong. Please try again.
  {#snippet actions()}<Button size="sm" variant="ghost">Retry</Button>{/snippet}
</Alert>
```

### Variants
- intent: danger, info, neutral, primary, success, warning (default: primary)
- variant: filled, inline, soft (default: soft)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...AlertVariants | `VariantProps` | no |  | Styling variants from AlertVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'title' | 'children') |
| actions | `Snippet` | no |  | Action buttons snippet |
| children | `Snippet` | no |  | Description content (children slot) |
| class | `string` | no |  | Additional CSS classes to apply to the Alert component |
| dismissible | `boolean` | no | false | Show dismiss/close button |
| icon | `Snippet` | no |  | Custom icon snippet (replaces default intent icon) |
| intent | `'primary' | 'info' | 'success' | 'warning' | 'danger' | 'neutral'` | no | 'primary' | Semantic color intent |
| onDismiss | `() => void` | no |  | Callback when dismissed |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Alert: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Alert |
| slotClasses | `Partial<Record<AlertSlots, string>>` | no |  | Per-slot class overrides. Slots: base | icon | content | title | description | actions | dismissButton |
| title | `string` | no |  | Alert title (bold header text) |
| unstyled | `boolean` | no |  | Remove default styles |
| variant | `'soft' | 'inline' | 'filled'` | no | 'soft' | Visual style variant for the Alert component |

Inherited from:
- AlertVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'title' | 'children'> (omit-pattern)

---

## ApiReference
Structured API reference table for component documentation.
Renders props via `@urbicon-ui/table` with per-column cell snippets
and `Badge` indicators for source/required status.

**Import:** `import { ApiReference } from '@urbicon-ui/docs';`

### Examples
```svelte
<ApiReference props={componentData.props} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| props | `ApiProp[]` | yes |  | Array of prop definitions to display. |
| ...ApiReferenceVariantProps | `VariantProps` | no |  | Styling variants from ApiReferenceVariantProps |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the root element. |
| slotClasses | `Partial<Record<'base' | 'stats' | 'usageNotes', string>>` | no |  | Per-slot class overrides for the wrapper elements. |
| unstyled | `boolean` | no |  | Remove all default tv styles from the wrapper and cell content. |
| usageNotes | `Snippet` | no |  | Optional usage notes rendered below the table. |

Inherited from:
- ApiReferenceVariantProps (external)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`, `stats`, `usageNotes`

---

## AreaChart
Area chart for trends with volume emphasis — filled regions
under each series, optionally stacked. Zero-dependency SVG on the design-
token palette, responsive, dark-mode aware, with a screen-reader data-table
fallback.

**Import:** `import { AreaChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<AreaChart
  stacked
  data={[
    { label: 'Jan', values: [4, 6] },
    { label: 'Feb', values: [7, 3] }
  ]}
  series={[{ label: 'New' }, { label: 'Returning' }]}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `CartesianDatum[]` | yes |  | Ordered categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| fillOpacity | `number` | no | 0.2 (overlay) / 0.85 (stacked) | Opacity of the area fill (0–1). |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | Height property for the AreaChart component |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors); defaults to one per value column. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
| stacked | `boolean` | no | false | Stack series cumulatively instead of overlaying them. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Avatar
User profile image component with fallback initials, multiple sizes, and interactive states.

**Import:** `import { Avatar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Avatar src="/user-photo.jpg" name="John Doe" size="lg" />
```

```svelte
<Avatar name="Jane Smith" randomColor clickable onclick={() => showProfile()} />
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- variant: circle, rounded, square (default: circle)
- size: 2xl, lg, md, sm, xl, xs (default: md)
- interactive: true (default: false)
- ring: true (default: false)
- ringIntent: danger, neutral, primary, secondary, success, warning (default: primary)
- status: away, busy, offline, online
- statusPosition: bottom-left, bottom-right, top-left, top-right (default: bottom-right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...AvatarVariants | `VariantProps` | no |  | Styling variants from AvatarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| alt | `string` | no |  | Alt text for the image. Defaults to `name`. |
| children | `Snippet` | no |  | Custom fallback content rendered instead of auto-generated initials. Useful for overflow counters, icons, or fully custom avatars with `unstyled`. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| clickable | `boolean` | no |  | Mark the avatar as clickable (adds hover/focus styles and keyboard support). Alias for the `interactive` variant. |
| mint | `MintProp` | no |  | Micro-interaction preset. Only applies when the avatar is interactive. |
| name | `string` | no |  | Full user name — used for initials generation, `randomColor` hashing, and `aria-label`. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. Automatically enables interactive styles. |
| onHover | `(hovered: boolean) => void` | no |  | Called when the hover state changes. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Avatar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| randomColor | `boolean` | no |  | Derive a deterministic background color from `name`. The same name always produces the same color, making it easy to visually distinguish users without images. Overrides `intent`. |
| ringColor | `string` | no |  | Custom ring color (CSS value). Overrides `ringIntent` when set. |
| slotClasses | `Partial<Record<AvatarSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. Slots: base | image | fallback | status |
| src | `string` | no |  | Image URL. Falls back to initials or `children` when empty or on load error. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Avatar. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'circle' | 'rounded' | 'square'` | no | circle | Controls the visual style and presentation of the Avatar. Determines the component's visual treatment. Available options: circle, rounded, square. |
| size | `'2xl' | 'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Avatar. Affects the component's physical footprint. Available options: 2xl, lg, md, and 3 more. |
| interactive | `'true'` | no | false | Controls the interactive behavior and appearance of the Avatar component. Available options: true. |
| ring | `'true'` | no | false | Controls the ring behavior and appearance of the Avatar component. Available options: true. |
| ringIntent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the ringIntent behavior and appearance of the Avatar component. Available options: danger, neutral, primary, and 3 more. |
| status | `'away' | 'busy' | 'offline' | 'online'` | no |  | Controls the status behavior and appearance of the Avatar component. Available options: away, busy, offline, online. |
| statusPosition | `'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'` | no | bottom-right | Controls the statusPosition behavior and appearance of the Avatar component. Available options: bottom-left, bottom-right, top-left, top-right. |

Inherited from:
- AvatarVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Badge
Compact label for status, categories, counters, and notifications.

**Import:** `import { Badge } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Badge variant="filled" intent="primary">New Feature</Badge>
```

```svelte
<div class="relative">
  <Button>Notifications</Button>
  <Badge intent="danger" counter placement="top-end" border>5</Badge>
</div>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: dot, filled, outlined, soft (default: filled)
- size: lg, md, sm, xs (default: md)
- border: true (default: false)
- counter: true (default: false)
- disabled: true (default: false)
- interactive: true (default: false)
- placement: bottom, bottom-end, bottom-start, left, right, top, top-end, top-start
- pulse: true (default: false)
- removable: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| border | `boolean` | no |  | Add a ring outline in the page background color — useful to visually separate overlapping or positioned badges from their parent. |
| children | `Snippet` | no |  | Badge content (text, icons, numbers). |
| class | `string` | no |  | Extra classes merged onto the root element. |
| counter | `boolean` | no |  | Display as a compact pill for numeric counts. Tightens padding and uses tabular-nums so digits align. |
| disabled | `boolean` | no |  | Visually disable the badge (reduced opacity, no pointer events). |
| interactive | `boolean` | no |  | Enable hover/focus styles and keyboard activation. Automatically enabled when `onclick` is provided. |
| mint | `MintProp` | no |  | Micro-interaction preset. Only applies when the badge is interactive. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. Automatically enables interactive styles. |
| onHover | `(hovered: boolean) => void` | no |  | Called when the hover state changes. |
| onRemove | `() => void` | no |  | Fired when the remove button is clicked (only when `removable` is true). |
| placement | `BadgePlacement` | no |  | Anchor the badge absolutely within a `position: relative` parent. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Badge: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| pulse | `boolean` | no |  | Add a pulsing animation to draw attention (e.g. for live indicators). |
| removable | `boolean` | no |  | Show a remove (×) button. |
| role | `'status' | 'alert' | 'badge'` | no |  | ARIA role. Defaults to `"status"`. Use `"alert"` for time-sensitive notifications. |
| slotClasses | `Partial<Record<BadgeSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| variant | `'dot' | 'filled' | 'outlined' | 'soft'` | no | 'filled' | Visual variant. `dot` renders a pure indicator (content hidden); the label variants accept the full surface. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Badge. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Badge. Affects the component's physical footprint. Available options: lg, md, sm, xs. |
| tier | `'commit' | 'modify'` | no | commit | Controls the tier behavior and appearance of the Badge component. Available options: commit, modify. |

---

## BarChart
Categorical bar chart — single, grouped, or stacked. Zero-
dependency SVG rendering on the design-token chart palette, responsive via
ResizeObserver, dark-mode aware, with a screen-reader data-table fallback.

**Import:** `import { BarChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<BarChart
  data={[
    { label: 'Q1', values: [12, 8] },
    { label: 'Q2', values: [19, 11] }
  ]}
  series={[{ label: 'Revenue' }, { label: 'Cost' }]}
  formatValue={(v) => `${v}k`}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `BarChartDatum[]` | yes |  | Categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | Height property for the BarChart component |
| locale | `string` | no |  | BCP-47 locale for the default number formatter (when no `formatValue`). |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors). Defaults to one generic series per value column found in `data`. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
| stacked | `boolean` | no | false | Stack series instead of grouping them side by side. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Breadcrumb
Navigation aid showing the current page's location in a hierarchy.
Renders an accessible nav with structured items and customizable separators.

**Import:** `import { Breadcrumb } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Breadcrumb items={[
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Widget' }
]} />
```

```svelte
<Breadcrumb items={breadcrumbs} size="sm">
  {#snippet separator()}<ChevronRight size={14} />{/snippet}
</Breadcrumb>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `BreadcrumbItem[]` | yes |  | Ordered breadcrumb items (last item is current page) |
| ...BreadcrumbVariants | `VariantProps` | no |  | Styling variants from BreadcrumbVariants |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| aria-label | `string` | no | 'Breadcrumb' | Accessible label for the nav element |
| class | `string` | no |  | Additional CSS classes to apply to the Breadcrumb component |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Breadcrumb: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| separator | `Snippet` | no |  | Custom separator snippet (default: "/") |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Breadcrumb |
| slotClasses | `Partial<Record<BreadcrumbSlots, string>>` | no |  | Per-slot class overrides |
| unstyled | `boolean` | no |  | Remove default styles |

Inherited from:
- BreadcrumbVariants (external)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Button
Versatile button component with multiple variants, sizes, intents, and micro-interaction patterns.
Built with Svelte 5 and optimized for performance and accessibility.

**Import:** `import { Button } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Button variant="filled" intent="primary" size="md">
  Click me
</Button>
```

```svelte
<Button variant="outlined" intent="danger" mint={['shake', 'ripple']}>
  Delete Item
</Button>
```

```svelte
<!-- Register once at app root: -->
<BlocksProvider
presets={{
Button: {
overlay: {
slotClasses: {
 base: 'bg-black/20 hover:bg-black/30 active:bg-black/40 text-white border-transparent'
}
}
}
}}
>
<Button preset="overlay">Reinholen</Button>
</BlocksProvider>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- variant: filled, ghost, outlined, text (default: filled)
- size: 2xs, lg, md, sm, xl, xs (default: md)
- active: false, true (default: false)
- buttonGroupConnected: true
- loading: false, true (default: false)
- loadingPlacement: end, overlay, start (default: start)
- pressed: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...ButtonVariants | `VariantProps` | no |  | Styling variants from ButtonVariants |
| ...HTMLButtonAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| active | `boolean` | no | false | Whether the button is visually active/selected (e.g. in a ButtonGroup with selection). Unlike `pressed` (momentary feedback), `active` represents a persistent selected state. |
| children | `Snippet` | no |  | The content of the button |
| class | `string` | no |  | Custom CSS class name |
| disabled | `boolean` | no | false | Whether the button is disabled |
| loading | `boolean` | no | false | Whether the button is in a loading state |
| loadingPlacement | `'overlay' | 'start' | 'end'` | no | 'overlay' | Where the loading indicator should appear when loading is true - 'overlay': spinner overlays content and hides it (default) - 'start': spinner appears before the content - 'end': spinner appears after the content |
| mint | `MintProp` | no | 'scale' | Micro-interaction patterns Can be a string, array of strings, or array of config objects |
| onclick | `(event: MouseEvent) => void` | no |  | Onclick property for the Button component |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Button: {...} }}>`. Prefer this over `class="bg-…!"` overrides when the requested look is outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| pressed | `boolean` | no | false | Whether the button is pressed (for toggle buttons) |
| slotClasses | `Partial<Record<ButtonSlots, string>>` | no |  | Per-slot class overrides merged with tv styles. Slots: base | content | spinner |
| unstyled | `boolean` | no |  | Remove default tailwind-variants classes. Only user classes apply. |
| value | `string` | no |  | The value associated with the button (useful in ButtonGroups) |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Button. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'filled' | 'ghost' | 'outlined' | 'text'` | no | filled | Controls the visual style and presentation of the Button. Determines the component's visual treatment. Available options: filled, ghost, outlined, text. |
| size | `'2xs' | 'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Button. Affects the component's physical footprint. Available options: 2xs, lg, md, and 3 more. |
| buttonGroupConnected | `'true'` | no |  | Controls the buttonGroupConnected behavior and appearance of the Button component. Available options: true. |
| tier | `'commit' | 'modify'` | no | commit | Controls the tier behavior and appearance of the Button component. Available options: commit, modify. |

Inherited from:
- ButtonVariants (external)
- Omit<HTMLButtonAttributes, 'children'> (omit-pattern)

---

## ButtonGroup
Groups related buttons with shared styling, layout, and optional selection behaviour.
Supports single-select (radio), multi-select (checkbox), or no selection.

**Import:** `import { ButtonGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ButtonGroup selection="single" bind:value={selectedView}>
  <Button value="list">List</Button>
  <Button value="grid">Grid</Button>
</ButtonGroup>
```

```svelte
<ButtonGroup
  selection="multiple"
  bind:value={selectedFormats}
  connected
  size="sm"
  variant="outlined"
>
  <Button value="bold">B</Button>
  <Button value="italic">I</Button>
  <Button value="underline">U</Button>
</ButtonGroup>
```

### Variants
- connected: false, true (default: true)
- disabled: true (default: false)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label for the group (prefer this over `aria-label` for correct HTML attribute). |
| ariaLabelledBy | `string` | no |  | ID of the element that labels the group. |
| children | `Snippet` | no |  | Button children to group. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| connected | `boolean` | no |  | Visually connect buttons (overlapping borders, shared rounding). When `false`, buttons are spaced with a small gap. |
| disabled | `boolean` | no |  | Disable the entire group and all child Buttons. |
| intent | `ComponentIntent` | no |  | Semantic colour propagated to child Buttons. |
| mint | `MintProp` | no |  | Micro-interaction preset propagated to child Buttons. |
| onSelectionChange | `(value: ButtonGroupValue, selectedValues: string[]) => void` | no |  | Fired when selection changes. Receives the new value and an array of all selected values. |
| orientation | `ButtonGroupOrientation` | no |  | Orientation property for the ButtonGroup component |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ButtonGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| selection | `ButtonGroupSelection` | no |  | Selection mode. `"single"` = radio-group, `"multiple"` = checkbox-group, `"none"` = no selection. |
| size | `ComponentSize` | no |  | Size propagated to child Buttons (unless a Button sets its own). |
| slotClasses | `Partial<Record<ButtonGroupSlots, string>>` | no |  | Per-slot class overrides. Slots: base |
| tier | `InteractiveTier` | no |  | Semantic radius tier propagated to child Buttons. `commit` (default) → pill caps for the group; `modify` → soft caps. Inherits from a wrapping Toolbar via TierContext when not set explicitly. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| value | `ButtonGroupValue` | no |  | Current selection value. Bind with `bind:value` for two-way sync. String for single, string[] for multiple. |
| variant | `ButtonVariants['variant']` | no |  | Visual weight propagated to child Buttons. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Calendar
Flexible calendar component with month, year, week, and day views.
Renders timed appointments, multi-day spans and recurrence on a time grid, with
event display, date selection and configurable layout. For a headless grid that
buckets your own domain content (meals, shifts, bookings) per day, use `Planner`.

**Import:** `import { Calendar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Calendar
  events={wasteEvents}
  categories={wasteCategories}
  bind:value={selectedDate}
  showEventList
  showLegend
  locale="de-DE"
/>
```

```svelte
<Calendar view="week" bind:value={selectedDate} />
```

```svelte
<Calendar selectionMode="range" bind:value={dateRange}>
  {#snippet children()}
    <CalendarHeader showViewSwitcher />
    <CalendarGrid />
  {/snippet}
</Calendar>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CalendarVariants | `VariantProps` | no |  | Styling variants from CalendarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| agendaDays | `number` | no | 30 | Number of days shown in agenda view. |
| animated | `boolean` | no | true | Enable animated transitions for navigation. |
| categories | `CalendarEventCategory[]` | no | [] | Event categories for color coding and legend. |
| children | `Snippet` | no |  | Default children snippet for custom layout composition. |
| class | `string` | no |  | Extra CSS classes on the root element. |
| dayCell | `Snippet<[DayCellContext]>` | no |  | Custom snippet for rendering a day cell. |
| defaultDate | `Date` | no |  | Initial reference day the grid is anchored on, without selecting it. Use this to open a **week** or **day** view on a specific week — `defaultMonth`/ `defaultYear` resolve to the 1st, whose week can fall mostly in the previous month. Ignored when `value` is set (the selection anchors instead); takes priority over `defaultMonth`/`defaultYear`. Read at mount only. |
| defaultMonth | `number` | no |  | Initial displayed month (0–11). Used only when `value` and `defaultDate` are unset; when `value` is provided, the calendar opens on the value's month. Best for month/year views — for week/day views prefer `defaultDate`. Defaults to current month. |
| defaultYear | `number` | no |  | Initial displayed year. Used only when `value` is unset; when `value` is provided, the calendar opens on the value's year. Defaults to current year. |
| disabled | `boolean` | no | false | Disable the entire calendar. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled (not selectable). |
| draggable | `boolean` | no | false | Enable drag & drop to move events between dates. |
| eventItem | `Snippet<[EventItemContext]>` | no |  | Custom snippet for rendering an event item in the detail list. |
| eventPopover | `boolean` | no | false | Show a rich popover on hover/focus for days with events (month view). |
| events | `CalendarEvent[]` | no | [] | Array of events to display on the calendar. |
| fixedWeeks | `boolean` | no | false | Always show 6 weeks in the grid. |
| header | `Snippet<[HeaderContext]>` | no |  | Custom snippet for the header area. |
| isDateDisabled | `(date: Date) => boolean` | no |  | Function to test whether a date is disabled. |
| locale | `string` | no | 'de-DE' | BCP 47 locale tag for date formatting. |
| maxDate | `Date` | no |  | Latest selectable/navigable date. |
| minDate | `Date` | no |  | Earliest selectable/navigable date. |
| miniCalendarPosition | `'left' | 'right'` | no | 'left' | Position of the mini calendar sidebar. |
| mint | `MintProp` | no |  | Micro-interaction preset. |
| onDateClick | `(date: Date) => void` | no |  | Fires when a date cell is clicked (regardless of selection change). |
| onDateCreate | `(date: Date, view: CalendarViewMode) => void` | no |  | Fires on double-click on a day cell for event creation. The consumer shows their own form. |
| onDayChange | `(date: Date) => void` | no |  | Fires when the displayed day changes (day view). |
| onEventClick | `(event: CalendarEvent) => void` | no |  | Fires when an event is clicked. |
| onEventMove | `(event: CalendarEvent, newStart: Date, newEnd: Date) => void` | no |  | Fires when an event is moved via drag & drop. |
| onEventResize | `(event: CalendarEvent, newEnd: Date) => void` | no |  | Fires when an event is resized via drag handle. |
| onMonthChange | `(month: number, year: number) => void` | no |  | Fires when the displayed month/year changes via navigation. |
| onTimeSlotCreate | `(start: Date, end: Date) => void` | no |  | Fires on click on an empty time slot for event creation. Returns default 1h duration. |
| onValueChange | `(value: CalendarSelection) => void` | no |  | Fires when the selected date(s) change. |
| onViewChange | `(view: CalendarViewMode) => void` | no |  | Fires when the view mode changes. |
| onWeekChange | `(weekStart: Date) => void` | no |  | Fires when the displayed week changes (week view). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Calendar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| resizable | `boolean` | no | false | Enable resize handles on timed events in the time grid. |
| selectionMode | `'single' | 'range' | 'multiple'` | no | 'single' | SelectionMode property for the Calendar component |
| showEventList | `boolean` | no |  | Whether to show the detail list when a date is selected. Auto-enabled when events are provided. |
| showLegend | `boolean` | no |  | Whether to show the built-in legend. Defaults to true when categories are provided. |
| showMiniCalendar | `boolean` | no | false | Show a mini month calendar sidebar (week/day/agenda views). |
| showOutsideDays | `boolean` | no | true | Show days from previous/next months to fill the grid. |
| showTimeGrid | `boolean` | no |  | Show time grid in week/day views. Auto-detected from events with allDay: false. |
| showViewSwitcher | `boolean` | no | true | Show the view switcher in the header. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers in the left margin. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Calendar |
| slotClasses | `Partial<Record<CalendarSlots, string>>` | no |  | Per-slot class overrides. |
| swipeable | `boolean` | no | true | Enable swipe gestures for touch navigation. |
| timeGridEndHour | `number` | no | 20 | Last visible hour in time grid (exclusive). |
| timeGridInterval | `30 | 60` | no | 60 | Time slot interval in minutes. |
| timeGridStartHour | `number` | no | 7 | First visible hour in time grid. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. |
| value | `CalendarSelection` | no |  | Currently selected date(s). Supports bind:value. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style variant for the Calendar component |
| view | `CalendarViewMode` | no | 'month' | Active view mode. Supports bind:view. |
| views | `CalendarViewMode[]` | no | ['month', 'week', 'day', 'year', 'agenda'] | Which views appear in the view switcher. |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

Inherited from:
- Omit<CalendarVariants, 'dayState' | 'hasEvents'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Card
Flexible container for grouping related content with optional header, footer,
and interactive states. Renders as div, button, or anchor depending on the provided props.

**Import:** `import { Card } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Card padding="lg">
  {#snippet header()}
    <h3>Title</h3>
  {/snippet}
  <p>Body content</p>
</Card>
```

```svelte
<Card variant="elevated" dividers onclick={() => navigate('/detail')}>
  {#snippet header()}
    <div class="flex items-center gap-3">
      <Avatar name="Jane Doe" size="sm" />
      <span class="font-medium">Jane Doe</span>
    </div>
  {/snippet}
  <p>Interactive card that navigates on click.</p>
  {#snippet footer()}
    <span class="text-text-tertiary text-sm">2 min ago</span>
  {/snippet}
</Card>
```

### Variants
- variant: elevated, floating, outlined, quiet (default: quiet)
- disabled: true (default: false)
- dividers: true (default: false)
- padding: lg, md, none, sm, xl (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CardVariants | `VariantProps` | no |  | Styling variants from CardVariants |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Content to render inside the Card component |
| class | `string` | no |  | Extra classes merged onto the root element. |
| clickable | `boolean` | no |  | Force `<button>` rendering and interactive hover styles without providing an `onclick` handler — useful when delegating clicks through a wrapper component or library. `onclick` and `href` already enable interactive styles automatically; reach for `clickable` only when neither is appropriate.  Don't combine with an outer `<a href>` or inner interactive content — `<a><Card clickable>…</Card></a>` produces nested interactive elements (invalid HTML, a11y violation). Prefer `<Card href={…}>` so the card itself becomes the anchor. |
| footer | `Snippet` | no |  | Content rendered below the body. With `dividers`, a hairline separates body from footer. |
| header | `Snippet` | no |  | Content rendered above the body. With `dividers`, a hairline separates header from body. |
| href | `string` | no |  | URL target. When provided, the card renders as `<a>`. |
| mint | `MintProp` | no |  | Micro-interaction preset. Only takes effect on interactive cards. |
| onclick | `(event: MouseEvent) => void` | no |  | Click handler. When provided, the card renders as `<button>` and gains interactive styles. |
| onHover | `(hovered: boolean) => void` | no |  | Called when hover state changes. Receives `true` on mouse-enter, `false` on mouse-leave. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Card: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<CardSlots, string>>` | no |  | Per-slot class overrides. Slots: base | header | content | footer |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| variant | `'elevated' | 'floating' | 'outlined' | 'quiet'` | no | quiet | Controls the visual style and presentation of the Card. Determines the component's visual treatment. Available options: elevated, floating, outlined, quiet. |
| disabled | `'true'` | no | false | Controls the disabled behavior and appearance of the Card component. Available options: true. |
| dividers | `'true'` | no | false | Controls the dividers behavior and appearance of the Card component. Available options: true. |
| padding | `'lg' | 'md' | 'none' | 'sm' | 'xl'` | no | md | Controls the padding behavior and appearance of the Card component. Available options: lg, md, none, and 2 more. |

Inherited from:
- Omit<CardVariants, 'elementType' | 'interactive'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## ChartFrame
Responsive SVG chart shell: measures its width via
ResizeObserver, applies plot margins, and hands the drawable plot geometry
to a child snippet. The building block under every cartesian chart in the
family — use it directly only for fully custom marks.

**Import:** `import { ChartFrame } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ChartFrame height={200} ariaLabel="Weekly revenue">
  {#snippet children({ innerWidth, innerHeight })}
    <!-- map your data onto innerWidth / innerHeight, then draw SVG marks -->
    <polyline points={pts} fill="none" class="stroke-primary" stroke-width="2" />
  {/snippet}
</ChartFrame>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label for the chart image (role="img"). |
| children | `Snippet<[ChartPlot]>` | no |  | Renders the SVG plot content; receives the  geometry. |
| class | `string` | no |  | Extra classes merged onto the <figure> wrapper. |
| fallback | `Snippet` | no |  | Screen-reader fallback (e.g. a data table) rendered visually hidden. |
| height | `number` | no | 240 | Fixed SVG height in px. |
| legend | `Snippet` | no |  | Optional legend rendered (as HTML) below the SVG. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the frame defaults. |
| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px. Omit for responsive width measured from the container (the common case); set it only for SSR-stable, non-responsive output. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Checkbox
Accessible checkbox with indeterminate support, semantic intents, and form integration.
Uses a hidden native input for correct form behavior and ARIA semantics.

**Import:** `import { Checkbox } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Checkbox label="Accept terms" bind:checked />
```

```svelte
<Checkbox
  label="Select all"
  indeterminate
  onCheckedChange={(val) => console.log(val)}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: filled, ghost, outlined (default: outlined)
- size: lg, md, sm, xs (default: md)
- disabled: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CheckboxVariants | `VariantProps` | no |  | Styling variants from CheckboxVariants |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'type' | 'size' | 'checked' | 'class' | 'children') |
| checked | `boolean` | no |  | Current checked state. Supports two-way binding via `bind:checked`. |
| class | `string` | no |  | Extra classes merged onto the wrapper element. |
| disabled | `boolean` | no |  | Prevent interaction and dim the control. |
| error | `string` | no |  | Error message that replaces `helper`, styles the message red, and sets `aria-invalid` on the input. |
| helper | `string` | no |  | Hint text shown below the control. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` to link `<label>` and `<input>`. Auto-generated if omitted. |
| indeterminate | `boolean` | no |  | Visual-only third state showing a dash icon. Resets to unchecked on next user toggle. Does not affect the submitted form value. Supports `bind:indeterminate`. |
| label | `string` | no |  | Text label displayed to the right of the checkbox box. |
| mint | `MintProp` | no |  | Micro-interaction preset applied to the control area on hover/click. |
| name | `string` | no |  | The `name` attribute of the underlying `<input>`. Used for form submission. |
| onCheckedChange | `(checked: boolean) => void` | no |  | Fired after the checked state changes. Receives the new `checked` value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Checkbox: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Mark the native input as required for form validation. |
| slotClasses | `Partial<Record<CheckboxSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. Slots: wrapper (root — what `class` also targets) | control | box | icon | label | message. |
| tier | `InteractiveTier` | no |  | Semantic radius tier. Default `modify` — checkbox is an input-tap surface. Inherited from TierContext when omitted; falls back to `modify` outside of any tier-aware container. |
| unstyled | `boolean` | no |  | Strip all default tailwind-variants classes. Use with `slotClasses` for a fully custom look. The box exposes `data-state` for conditional styling. |
| value | `string` | no |  | The value submitted when checked. Defaults to `'on'`. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Checkbox. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| variant | `'filled' | 'ghost' | 'outlined'` | no | outlined | Controls the visual style and presentation of the Checkbox. Determines the component's visual treatment. Available options: filled, ghost, outlined. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Checkbox. Affects the component's physical footprint. Available options: lg, md, sm, xs. |

Inherited from:
- Omit<CheckboxVariants, 'error' | 'checked' | 'indeterminate'> (omit-pattern)
- Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> (omit-pattern)

---

## CodeExample
Code example with optional live preview, syntax highlighting, and copy-to-clipboard.
Delegates code display to the shared CodePanel primitive.

**Import:** `import { CodeExample } from '@urbicon-ui/docs';`

### Examples
```svelte
<CodeExample title="Basic Usage" code={`<Button>Click me</Button>`} language="svelte">
  <Button>Click me</Button>
</CodeExample>
```

### Variants
- size: lg, md, sm (default: md)
- hasPreview: false, true (default: true)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...CodeExampleVariantProps | `VariantProps` | no |  | Styling variants from CodeExampleVariantProps |
| children | `Snippet` | no |  | Live preview content rendered above the code block. |
| class | `string` | no |  | Extra classes merged onto the root container element. |
| code | `string` | no |  | Source code string to display with syntax highlighting. |
| defaultExpanded | `boolean` | no |  | Override the default expanded state from the global code-visibility context. |
| description | `string` | no |  | Short description shown between title and preview. |
| isolate | `boolean` | no |  | Opt-in for the Vite plugin: children are auto-extracted as `code` at build time. |
| language | `string` | no |  | Language for syntax highlighting (e.g. 'svelte', 'typescript', 'css'). |
| preview | `boolean` | no | true | Render the live preview section above the code block. |
| previewClass | `string` | no |  | CSS classes for the preview wrapper div when `isolate` is set. |
| slotClasses | `Partial<Record<'container' | 'title' | 'description' | 'preview' | 'previewContent' | 'toolbar' | 'codeSection' | 'codeToggle' | 'codeChevron' | 'languageTag' | 'copyButton' | 'codeCollapse', string>>` | no |  | Per-slot class overrides for internal elements. |
| title | `string` | no |  | Title displayed in the card header. |
| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodeExample. Affects the component's physical footprint. Available options: lg, md, sm. |
| hasPreview | `'false' | 'true'` | no | true | Controls the hasPreview behavior and appearance of the CodeExample component. Available options: false, true. |

Inherited from:
- CodeExampleVariantProps (external)

### Slots (slotClasses keys)
`container`, `title`, `description`, `preview`, `previewContent`, `toolbar`, `codeSection`, `codeToggle`, `codeChevron`, `languageTag`, `copyButton`, `codeCollapse`

---

## CodePanel
Shared code display primitive with Shiki syntax highlighting, collapsible panel, and copy-to-clipboard.

**Import:** `import { CodePanel } from '@urbicon-ui/docs';`

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| code | `string` | yes |  | Source code string to display with syntax highlighting. |
| ...CodePanelVariantProps | `VariantProps` | no |  | Styling variants from CodePanelVariantProps |
| class | `string` | no |  | Extra classes merged onto the root element. |
| expanded | `boolean` | no |  | Controlled expanded state. When omitted, the panel manages its own state. |
| language | `string` | no | 'svelte' | Language for syntax highlighting and the toolbar language tag. |
| onToggle | `() => void` | no |  | Called when the toggle button is clicked. Required when `expanded` is controlled. |
| slotClasses | `Partial<Record<CodePanelSlotName, string>>` | no |  | Per-slot class overrides for internal elements. |
| unstyled | `boolean` | no |  | Remove all default tv styles from internal slots. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CodePanel. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- CodePanelVariantProps (external)

---

## Collapsible
A single expand/collapse panel with animated content, trigger button,
and full ARIA support. Can be used standalone or as the foundation for compound
components like Accordion.

**Import:** `import { Collapsible } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Collapsible title="Show details">
  <p>Hidden content revealed when expanded.</p>
</Collapsible>
```

```svelte
<Collapsible bind:open={isOpen} variant="card">
  {#snippet trigger({ open, toggle })}
    <button onclick={toggle}>
      {open ? 'Hide' : 'Show'} settings
    </button>
  {/snippet}
  <SettingsForm />
</Collapsible>
```

### Variants
- variant: card, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Content to render inside the Collapsible component |
| ...CollapsibleVariants | `VariantProps` | no |  | Styling variants from CollapsibleVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Additional CSS classes to apply to the Collapsible component |
| defaultOpen | `boolean` | no | false | Initial open state for uncontrolled usage |
| disabled | `boolean` | no | false | Whether the Collapsible is disabled and non-interactive |
| name | `string` | no |  | Base name for generating ARIA IDs. Defaults to auto-generated. |
| onOpenChange | `(open: boolean) => void` | no |  | Callback fired when open state changes |
| open | `boolean` | no |  | Whether the content is visible. Supports bind:open. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Collapsible: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<CollapsibleSlots, string>>` | no |  | Per-slot class overrides. Slots: base | trigger | chevron | content | contentInner |
| title | `string` | no |  | Trigger label text (used by the default trigger) |
| trigger | `Snippet<[
      {
        open: boolean;
        toggle: () => void;
        disabled: boolean;
        triggerId: string;
        contentId: string;
      }
    ]>` | no |  | Custom trigger snippet — receives open state, toggle fn, disabled flag, and ARIA IDs |
| unstyled | `boolean` | no |  | Remove default styles |
| variant | `'card' | 'default' | 'ghost'` | no | default | Controls the visual style and presentation of the Collapsible. Determines the component's visual treatment. Available options: card, default, ghost. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Collapsible. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- CollapsibleVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Combobox
Searchable menu (autocomplete) combining a text input with a
filterable option list. Implements the ARIA combobox pattern with
keyboard navigation, custom filtering, and two-way bindable state.

**Import:** `import { Combobox } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Combobox
  options={[
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Cherry', value: 'cherry' }
  ]}
  bind:value={selected}
  placeholder="Search fruit…"
/>
```

```svelte
<Combobox
options={tenants.map((t) => ({ label: t.name, value: t.id }))}
bind:value={tenantId}
/>
```

```svelte
<Combobox
  options={countries}
  bind:value={country}
  filter={(option, query) => option.label.toLowerCase().startsWith(query.toLowerCase())}
  clearable
  size="lg"
/>
```

### Variants
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- open: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| options | `ComboboxOption<T>[]` | yes |  | Array of selectable options. Each needs a unique `value`. |
| ...ComboboxVariants | `VariantProps` | no |  | Styling variants from ComboboxVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. Click or press Escape to reset. |
| closeOnClickOutside | `boolean` | no |  | Whether the listbox closes on outside click. Default `true`. Set to `false` to pin the listbox open while the consumer manages dismissal explicitly. |
| closeOnEscape | `boolean` | no |  | Whether the listbox closes on Escape key. Default `true`. Set to `false` for inline contexts where Escape should be intercepted by an outer widget (e.g. a row editor that wants to revert on Escape). |
| customOption | `Snippet<[ComboboxOption<T>, boolean]>` | no |  | Custom option renderer. Receives the option and whether it is selected. |
| disabled | `boolean` | no | false | Disable the entire combobox. |
| error | `string` | no |  | Error message — replaces helper text and flags the field as invalid. |
| filter | `(option: ComboboxOption<T>, query: string) => boolean` | no |  | Custom filter replacing the built-in case-insensitive label match. Return `true` to include an option. |
| helper | `string` | no |  | Helper text shown below the field. Hidden when an error is set. |
| id | `string` | no |  | Deterministic HTML `id` for the component. Auto-generated when omitted. |
| label | `string` | no |  | Field label rendered above the input. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. Form controls default to 'none' for a clean feel. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| noResultsText | `string` | no | 'No results found' | Text displayed when the filter produces no matches. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the listbox. Use for analytics or side-effects on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the listbox. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnEscape`. |
| onValueChange | `(value: T | null) => void` | no |  | Fires after the selected value changes. Receives the new value or `null` on clear. |
| open | `boolean` | no | false | Controls the open state of the listbox. Supports `bind:open`. |
| placeholder | `string` | no | 'Search…' | Placeholder shown when the input is empty. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Combobox: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| query | `string` | no |  | Current search query text. Supports `bind:query` for external control (e.g. server-side filtering). |
| required | `boolean` | no | false | Marks the field as required. Adds the asterisk on the label. |
| slotClasses | `Partial<Record<ComboboxSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | label | requiredMark | inputWrapper | input | message | hint | listbox | option | optionActive | optionSelected | noResults | clear | chevron |
| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. |
| value | `T | null` | no |  | Currently selected value. Supports `bind:value` for two-way binding. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Combobox. Affects the component's physical footprint. Available options: lg, md, sm. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Combobox component. Available options: commit, modify. |

Inherited from:
- ComboboxVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## CommandPalette
Keyboard-driven command palette with search, grouped results,
and arrow-key navigation. Composes Dialog + search input into a ready-to-use overlay.
Open via bind:open or the built-in Cmd+K shortcut.

**Import:** `import { CommandPalette } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CommandPalette
  items={commands}
  bind:open
  onSelect={(item) => handleCommand(item)}
  placeholder="Type a command..."
/>
```

```svelte
<CommandPalette
  items={[
    { id: 'new', label: 'New File', category: 'File', shortcut: 'Ctrl+N' },
    { id: 'open', label: 'Open File', category: 'File', shortcut: 'Ctrl+O' },
    { id: 'theme', label: 'Toggle Theme', category: 'Settings' },
    { id: 'search', label: 'Search', category: 'Navigation', shortcut: 'Ctrl+F' }
  ]}
  bind:open={paletteOpen}
  onSelect={(item) => runAction(item.id)}
  size="md"
  showFooter
/>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CommandPaletteItem[]` | yes |  | Items to display. Grouped automatically by `category`. |
| class | `string` | no |  | Additional CSS classes on the root wrapper. |
| customEmpty | `Snippet<[query: string]>` | no |  | Custom empty-state renderer. Receives the current query string. |
| customItem | `Snippet<[item: CommandPaletteItem, highlighted: boolean, index: number]>` | no |  | Custom item renderer. Receives the item, whether it is highlighted, and its flat index. |
| emptyText | `string` | no | 'No results found.' | Message shown when the filter returns no results. |
| filter | `(item: CommandPaletteItem, query: string) => boolean` | no |  | Custom filter function. Receives each item and the current query. Return `true` to keep the item. When omitted, a case-insensitive label + category substring match is used. |
| onOpenChange | `(open: boolean) => void` | no |  | Fired when the open state changes (close via Escape, backdrop, or selection). |
| onSelect | `(item: CommandPaletteItem) => void` | no |  | Fired when an item is selected via click or Enter. |
| open | `boolean` | no | false | Controls visibility. Supports `bind:open`. |
| placeholder | `string` | no | 'Search...' | Placeholder text for the search input. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ CommandPalette: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shortcut | `string | false` | no | 'mod+k' (Cmd+K / Ctrl+K) | Register a global keyboard shortcut that toggles the palette. Set to `false` to disable. |
| showFooter | `boolean` | no | true | Show keyboard-shortcut hints in the footer. |
| size | `CommandPaletteVariants['size']` | no | 'md' | Maximum width of the palette panel. |
| slotClasses | `Partial<Record<CommandPaletteSlots, string>>` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## CompositionBar
Stacked bar with legend that breaks an aggregate value down into
its components. Suited for budget splits, pool composition, resource
allocation, token vesting — anywhere `pool = a + b + c` should be visible
at a glance.

Small segments (< 2% of the total width) are kept minimally visible;
hovering/focusing the bar or the legend highlights the counterpart in
sync. Tooltip content is fully overridable via the `tooltip` snippet.

**Import:** `import { CompositionBar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<CompositionBar
  items={[
    { label: 'Gas',         value: 220609, intent: 'primary' },
    { label: 'Power',       value: 112731, intent: 'secondary' },
    { label: 'Maintenance', value:  36102, intent: 'success' }
  ]}
  formatValue={(v) => formatCurrency(v)}
  size="lg"
  legendPlacement="right"
  showTotal
/>
```

### Variants
- size: lg, md, sm (default: md)
- legendPlacement: bottom, left, none, right, top (default: bottom)
- orientation: horizontal, vertical (default: horizontal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| items | `CompositionItem[]` | yes |  | Composition shares in the order they should appear in the bar. |
| ...CompositionBarVariants | `VariantProps` | no |  | Styling variants from CompositionBarVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| formatPercent | `(percent: number) => string` | no |  | Format function for percentages. Default: 1 fraction digit, formatted with the active locale (e.g. `12.3 %`). |
| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip, legend, total). |
| intent | `CompositionBarIntent` | no | 'primary' | Default intent for items without their own `intent`/`color`. |
| legendItem | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom rendering of a legend entry. Receives the item and its percentage. Fully replaces the default rendering (dot + label + value/percent). |
| minSegmentPercent | `number` | no | 1.5 | Minimum segment width in percent. Values below it are raised to this width so they stay visible in the bar (nothing gets swallowed). Larger segments are shrunk proportionally so the sum still adds up to 100%. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
| onItemSelect | `(item: CompositionItem, index: number) => void` | no |  | Selection callback fired when a bar segment or legend entry is clicked. Receives the item and its index. Makes the bar interactive (cursor + click handler). |
| preset | `string` | no |  | Preset name (registered via `<BlocksProvider presets={{ CompositionBar: {...} }}>`). |
| showLegend | `boolean` | no | true | ShowLegend property for the CompositionBar component |
| showPercentages | `boolean` | no | true | Show percentages in legend and tooltip. |
| showTotal | `boolean` | no | false | Render the total value after the legend. |
| showValues | `boolean` | no | false | Render the value directly inside the bar segment (in addition to the legend). Narrow segments are skipped automatically to prevent overflow — only segments with sufficient width (≥ 8% or ~40 px) show their value. Useful for print, PDF attachments, or dense dashboards where hover tooltips are not enough. |
| slotClasses | `Partial<Record<CompositionBarSlots, string>>` | no |  | Per-slot class overrides. |
| tooltip | `Snippet<[item: CompositionItem, percent: number]>` | no |  | Custom tooltip content. Replaces the default layout (label, value, percent). |
| total | `number` | no |  | Optional fixed total value. Default: Σ items.value. If the explicit total exceeds the sum, the remaining area is rendered neutrally ("unaccounted share"). If it is below the sum, segments are scaled to 100% and a console warning is emitted. |
| totalLabel | `string` | no |  | Label rendered before the total. Defaults to the localized "Total" label from the blocks i18n bundle. |
| unstyled | `boolean` | no |  | Remove all default classes; only the layout structure remains. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the CompositionBar. Affects the component's physical footprint. Available options: lg, md, sm. |
| legendPlacement | `'bottom' | 'left' | 'none' | 'right' | 'top'` | no | bottom | Controls the legendPlacement behavior and appearance of the CompositionBar component. Available options: bottom, left, none, and 2 more. |
| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the CompositionBar component. Available options: horizontal, vertical. |

Inherited from:
- Omit<CompositionBarVariants, 'isHovered'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## ConfirmDialog
Pre-configured Dialog for confirming a single, often
destructive action. Replaces the native `window.confirm()` with a
styleable, focus-trapped, keyboard-accessible modal that matches the
design system's intent palette.

`onConfirm` may be `async`; while the returned promise is pending the
dialog locks itself (no backdrop dismiss, no escape, confirm button
shows a spinner). Auto-closes on resolve.

**Import:** `import { ConfirmDialog } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  let confirmOpen = $state(false);
</script>
<Button intent="danger" onclick={() => (confirmOpen = true)}>Delete</Button>
<ConfirmDialog
  bind:open={confirmOpen}
  title="Delete project?"
  description="This cannot be undone."
  intent="danger"
  confirmLabel="Delete"
  onConfirm={async () => { await deleteProject(id); }}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| title | `string` | yes |  | Heading shown in the dialog header. |
| cancelLabel | `string` | no |  | Label of the cancel button. Defaults to the localized `button.cancel`. |
| children | `Snippet` | no |  | Optional richer markup rendered below `description`. |
| closeOnBackdropClick | `boolean` | no | true | Whether the backdrop click cancels. |
| closeOnEscape | `boolean` | no | true | Whether Escape cancels. |
| confirmIntent | `ConfirmIntent` | no |  | Override for the confirm button intent. Defaults to , with `neutral` upgraded to `primary` for visual affordance. |
| confirmLabel | `string` | no |  | Label of the confirm button. Defaults to the localized `button.confirm`. |
| description | `string` | no |  | Description rendered above the footer. Use `children` for richer markup. |
| intent | `DialogIntent` | no | 'danger' | Accent on the dialog header strip. Drives the default `confirmIntent`. |
| loading | `boolean` | no | false | Externally controlled loading flag. Combined with the internal `busy` flag from an async `onConfirm`. While truthy, both buttons are disabled and dismissal is blocked. |
| onCancel | `() => void` | no |  | Fired when the user cancels (button, backdrop, or Escape). |
| onConfirm | `() => void | Promise<void>` | no |  | Confirm handler. May return a promise — the dialog stays open and shows a loading state while it resolves, then auto-closes on success. |
| open | `boolean` | no |  | Controls visibility. Supports bind:open. |

---

## CurrencyInput
Locale-aware monetary input that stores values in **minor units**
(cents for EUR/USD, pennies for GBP, etc.). While focused the user types raw
digits with a single decimal separator; on blur the value is reformatted with
the locale's grouping separators. The currency symbol is rendered as a static
adornment (left or right of the field) and stays visible at all times.

Storing cents as integers avoids floating-point drift when summing, sorting,
or persisting amounts. Parsing also goes through string splits — never
`parseFloat * factor` — so values like `1,005` round to the expected
`100` minor units (instead of `99` due to IEEE-754 drift). Use
 for currencies with non-2 decimal
places (JPY = 0, BHD = 3).

**Import:** `import { CurrencyInput } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
let priceCents = $state(1234_56); // 1.234,56 €
</script>
<CurrencyInput label="Price" bind:value={priceCents} />
```

```svelte
<CurrencyInput
label="Amount"
bind:value={amountCents}
locale="en-US"
currency="USD"
symbolPosition="prefix"
/>
```

```svelte
<CurrencyInput bind:value={yen} locale="ja-JP" currency="JPY" precision={0} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| currency | `string` | no | 'EUR' | ISO-4217 currency code. Determines the symbol when  is `'prefix'` or `'suffix'`. |
| locale | `string` | no | 'de-DE' | BCP 47 locale used for formatting (`Intl.NumberFormat`). Controls grouping separator (`.` vs `,`) and decimal separator. Pass `'auto'` to defer to the runtime locale (`Intl.NumberFormat().resolvedOptions().locale`) — i.e. the user's browser language. Note that the runtime locale on the server (Node) and in the browser typically differ, so SSR pages using `'auto'` may briefly show a different format on initial render before hydration. `currency` is intentionally **not** auto-detected, since it is orthogonal to locale (a `de-CH` user may still bill in EUR). |
| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the integer minor-unit value (matching ) — never the locale-formatted display string. The visible Input itself stays unnamed so the formatted text is not submitted alongside.  Empty / `null` values submit as `""` so the field still appears in the FormData payload (consumers can disambiguate "untouched" via server-side schema parsing). |
| onValueChange | `(cents: number | null) => void` | no |  | Fires whenever the parsed value changes. Receives the new value in minor units (or `null`). |
| precision | `number` | no | 2 | Number of fractional digits stored in . For most currencies `2`; for JPY use `0`, for BHD/KWD use `3`. |
| symbolPosition | `CurrencySymbolPosition` | no | 'suffix' | Where the currency symbol is rendered as a static adornment. The symbol is shown in the input's left or right icon slot (always visible, including while focused) — it is never embedded in the editable text. Use `'none'` for headless numeric editing (no symbol shown at all). |
| value | `number | null` | no | null | Current monetary value in **minor units** (e.g. cents). Use `null` for "no value entered yet"; the input renders empty. |

Inherited from:
- Omit<
    InputProps,
    | 'type'
    | 'value'
    | 'onClear'
    | 'inputmode'
    | 'oninput'
    | 'onchange'
    | 'onblur'
    | 'onfocus'
    | 'name'
  > (omit-pattern)

---

## DatePicker
Date input with calendar popup for selecting a single date. Supports min/max constraints, disabled dates, and format customization.

The `value` prop accepts either a `Date` or an ISO timestamp string —
useful when surrounding state is hydrated from JSON or a SQL driver
that serialises timestamps as strings. `onValueChange` always reports
back a `Date` (or `undefined`); use `toDateInputValue` from
`@urbicon-ui/blocks` to project it back into a string state.

**Import:** `import { DatePicker } from '@urbicon-ui/blocks';`

### Examples
```svelte
<DatePicker
  bind:value={selectedDate}
  label="Date of birth"
  placeholder="Select a date"
  locale="en-US"
  clearable
/>
```

```svelte
<script>
import { DatePicker, toDateInputValue } from '@urbicon-ui/blocks';
let isoDate = $state('2026-04-22T08:00:00Z');
</script>
<DatePicker
value={isoDate}
onValueChange={(d) => (isoDate = toDateInputValue(d))}
label="Period start"
/>
```

```svelte
<DatePicker
  bind:value={deadline}
  label="Deadline"
  minDate={new Date()}
  maxDate={new Date(2026, 11, 31)}
  isDateDisabled={(d) => d.getDay() === 0 || d.getDay() === 6}
  required
  error={deadlineError}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| calendarVariant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style of the calendar popup. |
| class | `string` | no |  | Additional CSS classes to apply to the DatePicker component |
| clearable | `boolean` | no | true | Allow clearing the selected date. |
| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
| closeOnSelect | `boolean` | no | true | Close popover after selecting a date. |
| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
| disabled | `boolean` | no | false | Disable the entire picker. |
| disabledDates | `Date[]` | no |  | Specific dates that are disabled. |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for the displayed date. |
| error | `string` | no |  | Error message shown below the input. |
| fixedWeeks | `boolean` | no | false | Always show 6 weeks. |
| helper | `string` | no |  | Helper text shown below the input. |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no | 'outlined' | InputVariant property for the DatePicker component |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Errors thrown by the predicate are caught and logged; the date is then treated as allowed so a faulty consumer callback can't take the picker down. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no | 'de-DE' | BCP 47 locale for date formatting and calendar. |
| maxDate | `Date` | no |  | Latest selectable date. |
| minDate | `Date` | no |  | Earliest selectable date. |
| mint | `MintProp` | no |  | Micro-interaction preset. |
| name | `string` | no |  | Shared `name` for native form submission. When set, a hidden input is rendered carrying the serialized date — matching what the user picked, so the visible input's locale-formatted display string is never submitted instead.  Empty / unset values submit as `""` so the field still appears in the FormData payload. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Notification only — does NOT govern whether close happens. That is controlled by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes. |
| onValueChange | `(value: Date | undefined) => void` | no |  | Fires when the selected date changes. |
| placeholder | `string` | no |  | Placeholder when no date is selected. |
| required | `boolean` | no | false | Mark input as required. |
| showOutsideDays | `boolean` | no | true | Show days from adjacent months. |
| showWeekNumbers | `boolean` | no | false | Show ISO week numbers. |
| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no | 'md' | Size variant that controls dimensions and spacing of the DatePicker |
| value | `Date | string | null` | no |  | Currently selected date. Supports bind:value. Accepts a `Date`, an ISO timestamp string, or `null` / `undefined`. Internally coerced to a `Date`; the picker emits `Date` instances via . When both `bind:value` and `onValueChange` are wired, both fire on every user-driven change — pick one to drive side-effects (saves, analytics) to avoid duplicates. |
| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise the date for the hidden form input. - `'date'` (default): `YYYY-MM-DD` in the local timezone — matches   the native `<input type="date">` payload and Zod schemas like   `z.string().regex(/^\d{4}-\d{2}-\d{2}$/).transform((v) => new Date(v))`. - `'iso'`: full ISO-8601 with `Z` suffix (UTC). Use this when the   downstream schema expects a parseable timestamp string (e.g. a   Drizzle `timestamp({ withTimezone: true, mode: 'date' })` column).  Only relevant when  is set. |
| weekStartsOn | `WeekdayIndex` | no | 1 | First day of the week. 0 = Sunday, 1 = Monday. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## DateRangePicker
Date range picker with a dual-calendar popup for selecting a start and end date — min/max constraints, disabled dates, and native form submission via paired hidden inputs.

**Import:** `import { DateRangePicker } from '@urbicon-ui/blocks';`

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| calendarVariant | `'default' | 'bordered' | 'ghost'` | no |  | calendarVariant property |
| class | `string` | no |  | Additional CSS classes to apply to the DateRangePicker component |
| clearable | `boolean` | no |  | Clearable property for the DateRangePicker component |
| closeOnClickOutside | `boolean` | no | true | Whether the popover closes on outside click. |
| closeOnEscape | `boolean` | no | true | Whether the popover closes on Escape key. |
| closeOnSelect | `boolean` | no | true | Close popover after selecting both dates. |
| defaultMonth | `MonthIndex` | no |  | Default month shown when the picker opens without a value. `0`–`11`. |
| defaultYear | `number` | no |  | Default year shown when the picker opens without a value. |
| disabled | `boolean` | no |  | Whether the DateRangePicker is disabled and non-interactive |
| disabledDates | `Date[]` | no |  | disabledDates property |
| displayFormat | `DateFormatOptions` | no |  | Intl.DateTimeFormat options for displayed dates. |
| error | `string` | no |  | Error property for the DateRangePicker component |
| fixedWeeks | `boolean` | no |  | FixedWeeks property for the DateRangePicker component |
| helper | `string` | no |  | Helper property for the DateRangePicker component |
| inputVariant | `'outlined' | 'filled' | 'ghost' | 'underline'` | no |  | inputVariant property |
| isDateDisabled | `(date: Date) => boolean` | no |  | Predicate that disables specific dates. Throws are caught and logged; the date is then treated as allowed. |
| label | `string` | no |  | Label above the input. |
| locale | `string` | no |  | Locale property for the DateRangePicker component |
| maxDate | `Date` | no |  | MaxDate property for the DateRangePicker component |
| minDate | `Date` | no |  | MinDate property for the DateRangePicker component |
| mint | `MintProp` | no |  | Micro-interaction configuration for enhanced user experience |
| name | `string` | no |  | Shared base `name` for native form submission. When set, two hidden inputs are rendered — `{name}_start` and `{name}_end` — each carrying the serialized date, so the visible input's locale-formatted display string is never submitted instead.  Empty range submits both halves as `""`. The `_start` / `_end` convention reflects the picker's domain language — date ranges read naturally as start/end rather than min/max. |
| onClickOutside | `() => void` | no |  | Notification only — does NOT govern close behavior. |
| onEscape | `() => void` | no |  | Notification only — does NOT govern close behavior. |
| onOpenChange | `(open: boolean) => void` | no |  | onOpenChange property |
| onValueChange | `(value: DateRange | undefined) => void` | no |  | Fires when the selected range changes. During calendar selection the user clicks twice — once to set the start, once to set the end. `onValueChange` only fires when the range is *complete* (start ≠ end); the intermediate `{ start: d, end: d }` state does NOT fire this callback. Use `bind:value` if you need the in-progress state. |
| placeholder | `string` | no |  | Placeholder when no range is selected. |
| required | `boolean` | no |  | Required property for the DateRangePicker component |
| showOutsideDays | `boolean` | no |  | showOutsideDays property |
| showWeekNumbers | `boolean` | no |  | showWeekNumbers property |
| size | `'xs' | 'sm' | 'md' | 'lg' | 'xl'` | no |  | Size variant that controls dimensions and spacing of the DateRangePicker |
| value | `DateRange` | no |  | Currently selected date range. Supports bind:value. |
| valueFormat | `'date' | 'iso'` | no | 'date' | Format used to serialise both range halves. See  for semantics. |
| weekStartsOn | `WeekdayIndex` | no |  | weekStartsOn property |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Dialog
Overlay dialog built on native dialog element. Can be used as a simple
content-agnostic overlay or as a structured dialog with title, footer, and intent accent.

**Import:** `import { Dialog } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Dialog bind:open>
<p>Are you sure?</p>
<Button onclick={() => (open = false)}>Close</Button>
</Dialog>
```

```svelte
<Dialog bind:open title="Confirm deletion" intent="danger">
<p>This action cannot be undone.</p>
{#snippet footer()}
<Button variant="ghost" onclick={() => (open = false)}>Cancel</Button>
<Button intent="danger" onclick={handleDelete}>Delete</Button>
{/snippet}
</Dialog>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- size: full, fullscreen, lg, md, sm, xl (default: sm)
- placement: center, top (default: center)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Dialog body content. When `title` is omitted the content fills the entire panel. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open') |
| class | `string` | no |  | Additional CSS classes applied to the dialog panel. |
| closeOnBackdropClick | `boolean` | no | true | Whether clicking the backdrop dismisses the dialog. |
| closeOnEscape | `boolean` | no | true | Whether pressing Escape dismisses the dialog. |
| footer | `Snippet` | no |  | Action buttons rendered in a footer bar. Only rendered when provided. |
| hideCloseButton | `boolean` | no | false | Hides the built-in close button. Only takes effect when `title` is also set — the close button only renders in the structured (titled) header. Without a title, no close button exists to hide. |
| intent | `DialogVariants['intent']` | no | 'neutral' | Semantic purpose marker (e.g. `danger` for destructive actions). After the Lighter-Refactor, the Dialog itself no longer paints an accent bar — the value is exposed on the panel as `data-intent="…"` so consumers can hook presets, CSS overrides, or icon/title color via their own snippets. |
| onClose | `() => void` | no |  | Fires when the dialog is dismissed via Escape, backdrop click, or close button. |
| open | `boolean` | no |  | Controls whether the dialog is visible. Supports bind:open. |
| placement | `DialogVariants['placement']` | no | 'center' | Vertical placement within the viewport. Use 'top' for command-palette style positioning. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Dialog: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `DialogVariants['size']` | no | 'sm' | Controls the maximum width of the dialog panel. |
| slotClasses | `Partial<Record<DialogSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. |
| title | `string` | no |  | Heading displayed in a header bar. Enables the structured header/body/footer layout. |
| transitionDuration | `number` | no |  | Override the enter/exit animation duration in milliseconds. Defaults to the overlay token `--blocks-overlay-enter-duration` / `--blocks-overlay-exit-duration` (200ms / 180ms). Set globally via the CSS custom properties or per-instance via this prop. Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit easing function. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for fully custom appearance. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open'> (omit-pattern)

---

## DocsLayout
Standard documentation page layout with optional table of contents.
Provides a responsive two-column layout with a mobile ToC fallback.

When `breadcrumbs` is provided, the layout uses a collapsing-hero pattern:
a unified sticky bar shows breadcrumbs + code toggle initially, then
transitions to a compact bar with title + scrollspy when the header
scrolls out of view.

**Import:** `import { DocsLayout } from '@urbicon-ui/docs';`

### Examples
```svelte
<DocsLayout
  title="Badge"
  description="Status and labels"
  breadcrumbs={[
    { label: 'Blocks', href: '/blocks' },
    { label: 'Primitives', href: '/blocks/primitives' }
  ]}
  showToc
  navigation={nav}
>
  <Section id="examples">...</Section>
</DocsLayout>
```

### Variants
- centered: true (default: false)
- maxWidth: 2xl, 7xl, lg, md, sm, xl (default: lg)
- sidebar: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...DocsLayoutVariantProps | `VariantProps` | no |  | Styling variants from DocsLayoutVariantProps |
| breadcrumbs | `BreadcrumbItem[]` | no |  | Structured breadcrumb trail (ancestors only, title is appended automatically). Enables the collapsing-hero sticky bar layout. |
| children | `Snippet` | no |  | Content to render inside the DocsLayout component |
| class | `string` | no |  | Extra classes merged onto the root container. |
| description | `string` | no |  | Short description rendered below the title. |
| navigation | `Array<{ id: string; title: string; order?: number }>` | no |  | Navigation items for the table of contents. |
| related | `RelatedLink[]` | no |  | Optional related-links list — passed through to the TableOfContents as a `// RELATED` block below the page sections. Each entry needs a pre-resolved `href`; the layout does not call `resolve()` on it. |
| showCodeToggle | `boolean` | no |  | Show the global code-visibility toggle for collapsing all code examples. Default: true. |
| showToc | `boolean` | no |  | Show a sticky table of contents sidebar on desktop and a collapsible one on mobile. |
| slotClasses | `Partial<Record<'container' | 'wrapper' | 'main' | 'header' | 'title' | 'subtitle' | 'content' | 'stickyBar' | 'pageToolbar', string>>` | no |  | Per-slot class overrides. |
| sourceHref | `string` | no |  | GitHub blob URL for the component's source file — rendered as a `source ↗` link next to the stability badge when present. |
| stability | `'experimental' | 'beta' | 'stable' | 'deprecated'` | no |  | Editorial stability badge — drives the `[STABLE]` / `[BETA]` / etc. stamp above the page title. When omitted, no badge renders; the default is applied upstream in docs-gen, so component pages receive `'stable'` automatically via `componentData?.stability`. |
| title | `string` | no |  | Page title rendered as an h1 in the header area. |
| unstyled | `boolean` | no |  | Remove all default tv styles. |
| centered | `'true'` | no | false | Controls the centered behavior and appearance of the DocsLayout component. Available options: true. |
| maxWidth | `'2xl' | '7xl' | 'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the maxWidth behavior and appearance of the DocsLayout component. Available options: 2xl, 7xl, lg, and 3 more. |
| sidebar | `'true'` | no | false | Controls the sidebar behavior and appearance of the DocsLayout component. Available options: true. |

Inherited from:
- DocsLayoutVariantProps (external)

### Slots (slotClasses keys)
`container`, `wrapper`, `main`, `header`, `title`, `subtitle`, `content`, `stickyBar`, `pageToolbar`

---

## DonutChart
Donut (or pie) chart for part-to-whole composition. Zero-
dependency SVG arcs on the design-token palette, dark-mode aware, with an
optional center total, legend, and a screen-reader data-table fallback. Set
`innerRadiusRatio={0}` for a full pie. Pairs with CompositionBar for the
linear equivalent.

**Import:** `import { DonutChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<DonutChart
  data={[
    { label: 'Direct', value: 45 },
    { label: 'Referral', value: 30 },
    { label: 'Organic', value: 25 }
  ]}
  showTotal
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `DonutDatum[]` | yes |  | Slices; angle is each value's share of the total. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| formatValue | `(value: number) => string` | no |  | Format values for the center total, tooltips, and the data table. |
| innerRadiusRatio | `number` | no | 0.6 | Inner-hole radius as a fraction of the outer radius (0 = pie). |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| padAngle | `number` | no | 0 | Gap between slices in degrees. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| showLegend | `boolean` | no | true | ShowLegend property for the DonutChart component |
| showTotal | `boolean` | no | false | Show the summed total in the center hole. |
| size | `number` | no | 220 | Square SVG size in px. |
| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
| totalLabel | `string` | no |  | Caption under the center total (e.g. "Total"). |
| unstyled | `boolean` | no |  | Remove all default tv classes. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Drawer
Slide-in panel overlay from any edge of the viewport.
Uses native dialog with focus trap, backdrop click dismiss, and Escape key support.

**Import:** `import { Drawer } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Drawer bind:open title="Settings" placement="right">
  <p>Drawer content here</p>
</Drawer>
```

```svelte
<Drawer bind:open title="Menu" placement="left" size="sm">
  <nav>...</nav>
</Drawer>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)
- size: full, lg, md, sm, xl (default: md)
- placement: bottom, left, right, top (default: right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Content rendered inside the drawer body. |
| ...HTMLDialogAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'open') |
| class | `string` | no |  | Additional CSS classes applied to the drawer panel. |
| closeOnBackdropClick | `boolean` | no | true | Whether clicking the backdrop closes the drawer. |
| closeOnEscape | `boolean` | no | true | Whether pressing Escape closes the drawer. |
| footer | `Snippet` | no |  | Action buttons rendered in the drawer footer. |
| hideCloseButton | `boolean` | no | false | Hides the built-in close button in the header. |
| intent | `DrawerVariants['intent']` | no | 'neutral' | Semantic purpose marker (mirrors Dialog). After the Lighter-Refactor, the Drawer itself no longer paints an accent border — the value is exposed on the panel as `data-intent="…"` so consumers can hook presets, CSS overrides, or icon/title color via their own snippets. |
| onClose | `() => void` | no |  | Fires when the drawer is dismissed via Escape, backdrop click, or close button. |
| open | `boolean` | no |  | Controls whether the drawer is visible. Supports `bind:open`. |
| placement | `DrawerVariants['placement']` | no | 'right' | Edge of the viewport from which the drawer slides in. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Drawer: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `DrawerVariants['size']` | no | 'md' | Width (for left/right) or height (for top/bottom) of the drawer panel. |
| slotClasses | `Partial<Record<DrawerSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. |
| title | `string` | no |  | Heading displayed in the drawer header. |
| transitionDuration | `number` | no |  | Override the enter/exit animation duration in milliseconds. Defaults to the overlay token `--blocks-overlay-enter-duration` / `--blocks-overlay-exit-duration` (200ms / 180ms). Respects `prefers-reduced-motion`. |
| transitionEasing | `(t: number) => number` | no |  | Override the enter/exit easing function. Defaults to the overlay token easing (`quintOut`). |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for fully custom appearance. |

Inherited from:
- Omit<HTMLDialogAttributes, 'children' | 'open'> (omit-pattern)

---

## EmptyState
Centered placeholder block for "no data yet" / "no results"
states. Pairs an optional icon with a heading, supporting text, and an
optional call-to-action slot.

**Import:** `import { EmptyState } from '@urbicon-ui/blocks';`

### Examples
```svelte
<EmptyState
  icon={BuildingIcon}
  title="No apartments yet"
  description="Get started by adding the first apartment to the system."
>
  {#snippet cta()}
    <Button intent="primary" onclick={openCreate}>Add apartment</Button>
  {/snippet}
</EmptyState>
```

### Variants
- density: compact, default (default: default)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| title | `string` | yes |  | Title property for the EmptyState component |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'title') |
| children | `Snippet` | no |  | Optional richer content rendered below the description (and replacing it visually). |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| cta | `Snippet` | no |  | Action buttons rendered below the description. |
| density | `'compact' | 'default'` | no | 'default' | Visual density. `compact` is suitable for inline empty rows in tables or cards; `default` for full-page empty states. |
| description | `string` | no |  | Supporting paragraph below the title. |
| icon | `Component<IconProps>` | no |  | Icon component rendered above the title. Pass any icon from `@urbicon-ui/blocks/icons` (or a compatible stroke icon). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ EmptyState: {...} }}>`. Prefer this over `class` overrides when the same look should be reused across the project. |
| slotClasses | `Partial<Record<EmptyStateSlots, string>>` | no |  | Per-slot class overrides. Slots: base | iconWrapper | title | description | children | cta |
| unstyled | `boolean` | no |  | Remove all default tv classes. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'title'> (omit-pattern)

---

## FileUpload
Drag-and-drop file upload with validation, image previews, progress tracking, and animated file list.

**Import:** `import { FileUpload } from '@urbicon-ui/blocks';`

### Examples
```svelte
<FileUpload
  bind:files
  multiple
  maxFiles={5}
  maxFileSize={10 * 1024 * 1024}
  title="Drop files here or click to browse"
  description="PDF, DOCX, XLSX — max 10 MB per file"
/>
```

```svelte
<FileUpload
  bind:files
  accept={IMAGE_MIME_TYPES}
  multiple
  maxFiles={8}
  title="Upload images"
  description="PNG, JPG, WebP — max 5 MB"
  onFileReject={(rejections) => console.log('Rejected:', rejections)}
/>
```

### Variants
- intent: neutral, primary (default: neutral)
- size: lg, md, sm (default: md)
- disabled: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...FileUploadVariants | `VariantProps` | no |  | Styling variants from FileUploadVariants |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| accept | `string | string[]` | no |  | Accepted MIME types or file extensions (e.g. 'image/*', '.pdf'). |
| allowDrop | `boolean` | no | true | Enable drag-and-drop. |
| allowPaste | `boolean` | no | false | Enable paste from clipboard. |
| children | `Snippet` | no |  | Default slot for fully custom dropzone content. |
| class | `string` | no |  | Additional CSS class for the root element. |
| description | `string` | no |  | Dropzone description text (accepted types, limits). |
| disabled | `boolean` | no |  | Disable all interaction. |
| dropzoneIcon | `Snippet` | no |  | Custom dropzone icon snippet. |
| file | `File | null` | no |  | Convenience binding for single-file uses. Two-way: - Reads as `files[0]?.file ?? null`. - Setting to a `File` replaces the current selection (object URLs are   revoked, no validation re-runs — assumes the caller already validated). - Setting to `null` clears the list.  Recommended when `maxFiles === 1` (e.g. logo / avatar uploads). Use `bind:files` instead when you need progress, errors, or status metadata. |
| fileItem | `Snippet<[FileItemContext]>` | no |  | Custom file item renderer. Receives file entry and remove callback. |
| files | `FileUploadFile[]` | no |  | Current file list. Supports two-way binding. |
| maxFiles | `number` | no |  | Maximum number of files. |
| maxFileSize | `number` | no |  | Maximum file size in bytes. |
| minFileSize | `number` | no |  | Minimum file size in bytes. |
| mint | `MintProp` | no |  | Micro-interaction preset for the dropzone. |
| multiple | `boolean` | no |  | Allow selecting multiple files. |
| name | `string` | no |  | Shared `name` for native form submission. When set, the underlying hidden `<input type="file">` carries the current file list — including files added via drag/drop, paste, or programmatic `bind:files`, not just files picked through the file dialog. Submits as a `File[]` under `{name}` in the FormData payload. |
| onFileAccept | `(files: FileUploadFile[]) => void` | no |  | Fires when valid files are accepted. |
| onFileReject | `(rejections: FileRejection[]) => void` | no |  | Fires when files are rejected by validation. |
| onFileRemove | `(file: FileUploadFile) => void` | no |  | Fires when a file is removed. |
| onFilesChange | `(files: FileUploadFile[]) => void` | no |  | Fires when the file list changes (add or remove). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ FileUpload: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| preventDocumentDrop | `boolean` | no | true | Prevent browser navigation when files are dropped outside the zone. |
| required | `boolean` | no |  | Mark as required for form validation. |
| slotClasses | `Partial<Record<FileUploadSlots, string>>` | no |  | Per-slot class overrides. |
| title | `string` | no |  | Dropzone title text. |
| unstyled | `boolean` | no |  | Strip all default styles. |
| validate | `(file: File) => FileUploadError[] | null` | no |  | Custom validation function. Return errors array or null. |
| intent | `'neutral' | 'primary'` | no | neutral | Controls the color theme and semantic meaning of the FileUpload. Affects the overall appearance and user perception. Available options: neutral, primary. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the FileUpload. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- Omit<FileUploadVariants, 'dragging' | 'invalid'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## ForgotPasswordPage
Pre-built forgot-password page. Sends POST to `apiPath` (default `/api/auth/forgot-password`).
Pair with `createForgotPasswordHandler(authDeps)` on the server. Timing-safe to prevent email enumeration.

**Import:** `import { ForgotPasswordPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<ForgotPasswordPage {t} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/forgot-password' | ApiPath property for the ForgotPasswordPage component |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## FormField
Layout wrapper for composite form fields that need a label,
helper text, and error message but cannot rely on the built-in slots of
primitives like  or . Examples:
a custom file picker, a slider/number-input pair, a media uploader.

The `id` is auto-generated and forwarded to the slot via the `for`
snippet parameter so the rendered control can wire `aria-describedby`
and `aria-invalid` correctly.

**Import:** `import { FormField } from '@urbicon-ui/blocks';`

### Examples
```svelte
<FormField label="Document" required error={fileError} hint="PDF, JPG, PNG — max 10 MB">
  {#snippet children({ id, describedBy, invalid })}
    <FileUpload {id} aria-describedby={describedBy} aria-invalid={invalid} bind:files />
  {/snippet}
</FormField>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet<[FormFieldSlotContext]>` | yes |  | Snippet receiving wiring metadata (`id`, `describedBy`, `invalid`, `required`, `disabled`). The wrapped control should spread or apply these to itself for accessibility. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the wrapper element. |
| disabled | `boolean` | no | false | Disables visual emphasis. Pass through to the slot's control as needed. |
| error | `string` | no |  | Error message shown below the control. Replaces the helper text and propagates `invalid: true` to the slot for ARIA wiring. |
| hint | `string` | no |  | Helper text shown below the control. Hidden when `error` is present. |
| id | `string` | no |  | Explicit HTML `id` for the control. Auto-generated when omitted, then forwarded to the slot. Caller may use it to attach external `<label for>`. |
| label | `string` | no |  | Label rendered above the control. Auto-linked to the slot via the generated `id`. |
| required | `boolean` | no | false | Adds a required asterisk to the label and propagates `required: true` to the slot. Does **not** apply the native `required` attribute — the slot's control is responsible for that. |
| slotClasses | `Partial<Record<'wrapper' | 'label' | 'message' | 'hint', string>>` | no |  | Per-slot class overrides. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`wrapper`, `label`, `message`, `hint`

---

## Guide
The guided-tour renderer — the deliberately opt-in, intrusive Guide surface
(§6, low priority). Renders the active tour the controller drives (`startTour`/`next`/`prev`/
`skip`/`finish`): a spotlight that dims everything but a cut-out hole over the current step's
target (the one *subtractive* Guide treatment, D5) plus an anchored bubble with the step
title, body, dot progress, and Back / Next / Skip controls. Mount once inside `GuideProvider`;
it renders nothing until a tour starts. Top-layer (native popover), so it clears app stacking
contexts; it steps aside (pauses) when a foreign modal stacks above it. A step with no `target`
renders centered over a full scrim. Renders inert without a `GuideProvider`.

**Import:** `import { Guide } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  import { GuideProvider, Guide, GuideController } from '@urbicon-ui/blocks';
  const guide = new GuideController();
  const tour = {
    id: 'welcome',
    steps: [
      { target: 'save-button', title: 'Save', body: 'Persist your changes here.' },
      { target: 'filter-control', title: 'Filter', body: 'Narrow the list.', interactive: true }
    ]
  };
</script>

<GuideProvider controller={guide}>
  <Guide />
  <button onclick={() => guide.startTour(tour)}>Take the tour</button>
</GuideProvider>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| arrow | `boolean` | no | true | Render the bubble's pointer arrow on anchored steps. |
| class | `string` | no |  | Additional classes on the bubble. |
| padding | `number` | no | 8 | Padding in px between the step target and the spotlight hole edge. Also frames the additive highlight ring the engine paints on the target. |
| placement | `Placement` | no | 'bottom' | Preferred bubble placement when a step omits its own `placement`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Guide: {...} }}>`. |
| radius | `number` | no |  | Spotlight hole corner radius in px. When omitted, it follows the target's own border-radius (plus `padding`), clamped to the hole size. Set a number to force it. |
| slotClasses | `Partial<Record<GuideTourSlots | 'skip' | 'prev' | 'next', string>>` | no |  | Per-slot class overrides. Beyond the tour's own `tv()` slots, `skip` / `prev` / `next` forward to the footer's nested `<Button>`s (which own their internal markup). |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideArticle
A single help article inside a `GuidePanel`. Registers itself in the panel's
list (by `title`) and renders its content only when it is the active article
(`controller.activeArticle === id`). Use `GuideMention` inside to link back to UI elements.

**Import:** `import { GuideArticle } from '@urbicon-ui/blocks';`

### Examples
```svelte
<GuideArticle id="seats" title="Seats & billing">
  <p>Each <GuideMention for="seat-count">seat</GuideMention> is one team member.</p>
</GuideArticle>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| id | `string` | yes |  | Unique article id — referenced by `GuideMarker` and `openPanel(id)`. |
| title | `string` | yes |  | Title shown in the panel list and header. |
| children | `Snippet` | no |  | Content to render inside the GuideArticle component |
| class | `string` | no |  | Additional classes on the article root. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideArticle: {...} }}>`. |
| slotClasses | `Partial<Record<GuideArticleSlots, string>>` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideBeacon
A waiting, pulsing hotspot that invites the user into an opt-in guided tour (§6.3)
— the gentlest tour entry point, the opposite of an auto-starting tour. A real `<button>` the
consumer positions (inline, or absolutely over a feature corner); on activation it starts the
given `tour` and/or calls `onActivate`. Hides itself once that tour has been seen. The pulse
halts under `prefers-reduced-motion` (static dot). Renders inert without a `GuideProvider`.

**Import:** `import { GuideBeacon } from '@urbicon-ui/blocks';`

### Examples
```svelte
<span class="relative">
  New feature
  <GuideBeacon class="absolute -right-3 -top-1" {tour} />
</span>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Additional classes on the beacon button (use for absolute positioning over a target). |
| label | `string` | no | i18n `guide.startTour` | Accessible label for the button. |
| onActivate | `() => void` | no |  | Called on activation (click / Enter / Space), after `tour` is started when both are set. |
| once | `boolean` | no | true | Hide the beacon once its `tour` has been seen (and while that tour is running). Needs `tour`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideBeacon: {...} }}>`. |
| size | `GuideBeaconVariants['size']` | no | 'md' | Visual size of the hotspot. |
| slotClasses | `Partial<Record<GuideBeaconSlots, string>>` | no |  | Per-slot class overrides. |
| tour | `GuideTour` | no |  | The tour to start when the beacon is activated. When set, the beacon also hides itself once the tour has been seen (subject to `once`). Omit to drive everything from `onActivate`. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideHint
A contextual, non-blocking hint anchored to a `data-guide` element via
`floating.ts` (flip/shift/arrow), rendered in the native popover top-layer. Waits at the
right element rather than interrupting: shows on mount (or when `open` for `trigger="manual"`),
persists "seen" so it appears once (`once`), and steps aside while a foreign modal or guided
tour is open. Dismissable; announces itself via `aria-live`. Renders inert without a provider.

**Import:** `import { GuideHint } from '@urbicon-ui/blocks';`

### Examples
```svelte
<button data-guide="export">Export</button>

<GuideHint for="export" title="New: scheduled exports">
  You can now export on a schedule from here.
</GuideHint>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| for | `string` | yes |  | `data-guide` id of the element to anchor to. Required — a hint with no anchor has nothing to point at. |
| arrow | `boolean` | no | true | Render the pointer arrow. |
| children | `Snippet` | no |  | Content to render inside the GuideHint component |
| class | `string` | no |  | Additional classes on the hint root. |
| once | `boolean` | no | true | When dismissed, persist a "seen" flag (via the controller's StorageAdapter) so the hint does not reappear on later mounts. Mirrors the tour's "mark seen on end" rule — a hint shown but never dismissed may show again. Set `false` to always show. |
| onDismiss | `() => void` | no |  | Called when the hint is dismissed (close button or Escape). |
| open | `boolean` | no | false | Manual visibility for `trigger="manual"` (the on-route / on-condition strategy). Ignored for `trigger="mount"`. Re-raising it to `true` after a dismiss re-surfaces the hint (subject to `once`). |
| placement | `Placement` | no | 'bottom' | Preferred placement relative to the target. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideHint: {...} }}>`. |
| seenId | `string` | no | the `for` id | Persistence key for the "seen once" state, decoupled from the anchor (this is *not* a DOM id — the popover gets none). Override only to track two hints on one element independently, or to keep a stable key across a renamed anchor. |
| slotClasses | `Partial<Record<GuideHintSlots, string>>` | no |  | Per-slot class overrides. |
| title | `string` | no |  | Optional bold heading above the body. |
| trigger | `'mount' | 'manual'` | no | 'mount' | When the hint may appear: `'mount'` shows it as soon as it mounts; `'manual'` waits for `open` to become `true` (the consumer's route/condition logic). |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideMarker
Direction A of the bidirectional link (UI → Guide): a discreet "ⓘ" trigger
that sits on a UI element and opens the `GuidePanel` at the matching article. A real
`<button>` with `aria-controls`/`aria-expanded` — deliberately *not* a status `Badge`
(which is a non-interactive label, not a trigger). Renders inert without a `GuideProvider`,
or when the topic's direction excludes UI→Guide (`'to-ui'`).

**Import:** `import { GuideMarker } from '@urbicon-ui/blocks';`

### Examples
```svelte
<h3>Billing <GuideMarker for="billing" article="billing-help" /></h3>
```

### Variants
- size: md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| article | `string` | no |  | Article to open in the panel. Overrides the topic meta's `article`; falls back to `for`. |
| children | `Snippet` | no |  | Custom trigger content, replacing the default "ⓘ" icon. |
| class | `string` | no |  | Additional classes on the marker button. |
| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The marker is live unless this resolves to `'to-ui'`. |
| for | `string` | no |  | `data-guide` topic id this marker explains. Resolves the article (from topic meta) and the link direction. Optional (unlike `GuideMention.for`) because `article` can stand alone — supply one of the two. With neither, the marker opens the panel index. |
| label | `string` | no | i18n `guide.infoAbout` (with the topic's label) or `guide.info` | Accessible label for the icon button. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMarker: {...} }}>`. |
| size | `GuideMarkerVariants['size']` | no | 'md' | Size variant that controls dimensions and spacing of the GuideMarker |
| slotClasses | `Partial<Record<GuideMarkerSlots, string>>` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideMention
Direction B of the bidirectional link (Guide → UI): an inline reference inside a
`GuideArticle` that highlights the matching UI element on hover *and* focus (keyboard parity).
Additive `outline` ring, no scrim, no layout shift (D5); clicking also scrolls the element into
view (reduced-motion-aware). A real `<button>`; degrades to plain inline text without a
`GuideProvider` or when the topic's direction excludes Guide→UI (`'to-guide'`).

**Import:** `import { GuideMention } from '@urbicon-ui/blocks';`

### Examples
```svelte
<p>Click the <GuideMention for="save-button">Save button</GuideMention> to persist.</p>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| for | `string` | yes |  | `data-guide` id of the UI element to highlight. Required (unlike `GuideMarker.for`): a mention with no target has nothing to highlight. |
| children | `Snippet` | no |  | Content to render inside the GuideMention component |
| class | `string` | no |  | Additional classes on the mention. |
| direction | `GuideDirection` | no | the topic's `direction`, or `'both'` | Override the topic's link direction. The mention is interactive unless this resolves to `'to-guide'`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuideMention: {...} }}>`. |
| scroll | `boolean` | no | true | Scroll the target into view on click (reduced-motion-aware). |
| slotClasses | `Partial<Record<GuideMentionSlots, string>>` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuidePanel
Non-modal help panel for the Guide system. Slides in (default from the right)
without a backdrop or focus trap, so the app stays interactive behind it — this is what lets
a `GuideMention` highlight a UI element while the panel is open (D1). Visibility is driven by
the controller (`openPanel`/`closePanel`), not a local prop. Place `GuideArticle` children
inside: the panel shows a list of them, or the active article's content with a back button.

**Import:** `import { GuidePanel } from '@urbicon-ui/blocks';`

### Examples
```svelte
<GuidePanel title="Help">
  <GuideArticle id="saving" title="Saving your work">
    <p>Use the Save button to persist your changes.</p>
  </GuideArticle>
</GuidePanel>
```

### Variants
- size: lg, md, sm (default: md)
- placement: left, right (default: right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | no |  | `GuideArticle` children and any custom content. |
| class | `string` | no |  | Additional classes on the panel root. |
| closeOnEscape | `boolean` | no | true | Close the panel when Escape is pressed. |
| footer | `Snippet` | no |  | Optional footer content. |
| id | `string` | no | auto-generated (`guide-panel-<id>`) | Stable DOM id for the panel root. `GuideMarker`s reference it via `aria-controls`. |
| placement | `GuidePanelVariants['placement']` | no | 'right' | Side the panel docks to. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ GuidePanel: {...} }}>`. |
| size | `GuidePanelVariants['size']` | no | 'md' | Size variant that controls dimensions and spacing of the GuidePanel |
| slotClasses | `Partial<Record<GuidePanelSlots, string>>` | no |  | Per-slot class overrides. |
| title | `string` | no | i18n `guide.openHelp` | Heading shown when no article is open. |
| unstyled | `boolean` | no | false | Strip all default styles. |

---

## GuideProvider
Root provider for the Guide help system. Instantiates a `GuideController`
and shares it via context with all Guide surfaces (Panel, Marker, Mention, Hint, Tour).
Place once near the app root. The context is optional — a surface used without a provider
renders inert rather than throwing.

**Import:** `import { GuideProvider } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
  import { GuideProvider, GuideController } from '@urbicon-ui/blocks';
  const guide = new GuideController();
</script>

<GuideProvider controller={guide}>
  <App />
</GuideProvider>

<button onclick={() => guide.startTour(welcomeTour)}>Take the tour</button>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | App subtree wired to the Guide context. |
| controller | `GuideController` | no |  | Supply a pre-created `GuideController` for programmatic access from outside the provider (start tours, open the panel, query `hasSeen`). When omitted, the provider creates one internally and shares it via context. When supplied, `storage` is ignored. |
| storage | `GuideStorageAdapter` | no | localStorage-backed adapter | Persistence adapter for "seen" state (tours/hints). |

---

## InfoCard
Simple memo-style card for inline callouts or notes within docs content.

**Import:** `import { InfoCard } from '@urbicon-ui/docs';`

### Examples
```svelte
<InfoCard title="Tip" icon="lightbulb">Use variants to change tone.</InfoCard>
```

### Variants
- intent: api, danger, example, info, neutral, playground, primary, secondary, success, warning (default: info)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...InfoCardVariantProps | `VariantProps` | no |  | Styling variants from InfoCardVariantProps |
| children | `Snippet` | no |  | Content to render inside the InfoCard component |
| class | `string` | no |  | Additional CSS classes to apply to the InfoCard component |
| href | `string` | no |  | Render the card as a link to this URL. Falls back to a plain `<div>` when omitted. |
| icon | `string` | no |  | Icon property for the InfoCard component |
| title | `string` | no |  | Title property for the InfoCard component |
| intent | `'api' | 'danger' | 'example' | 'info' | 'neutral' | 'playground' | 'primary' | 'secondary' | 'success' | 'warning'` | no | info | Controls the color theme and semantic meaning of the InfoCard. Affects the overall appearance and user perception. Available options: api, danger, example, and 7 more. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the InfoCard. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- InfoCardVariantProps (external)

---

## Input
Text input with labels, validation states, icons, and clearable functionality.
Supports outlined, filled, and ghost visual variants with automatic ARIA linking.

**Import:** `import { Input } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Input label="Email" placeholder="name@example.com" required />
```

### Variants
- intent: danger, default, success, warning (default: default)
- variant: filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm, xl, xs (default: md)
- disabled: true (default: false)
- hasLeftIcon: true (default: false)
- hasRightIcon: true (default: false)
- iconPosition: left, right (default: left)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'size' | 'class' | 'disabled' | 'readonly' | 'children') |
| ...InputVariants | `VariantProps` | no |  | Styling variants from InputVariants |
| autoComplete | `string` | no |  | HTML autocomplete hint for browser autofill. |
| children | `Snippet` | no |  | Snippet content rendered below the input for advanced layouts. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| clearable | `boolean` | no | false | Show a clear button when the input has a value. Press Escape or click the button to clear. Fires `onClear` after clearing. |
| disabled | `boolean` | no | false | Whether the Input is disabled and non-interactive |
| error | `string` | no |  | Error message below the input. When set, overrides `helper` and forces danger border styling regardless of `intent`. |
| helper | `string` | no |  | Helper text below the input — hidden when `error` is present. |
| label | `string` | no |  | Label text displayed above the input, auto-linked via `for`/`id`. |
| leftIcon | `Snippet` | no |  | Icon snippet rendered on the left side of the input field. |
| leftIconAriaLabel | `string` | no |  | Accessible label for the clickable left icon button. Required when `onLeftIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the input element. |
| onClear | `() => void` | no |  | Fired after the value is cleared via the clear button or Escape key. |
| onLeftIconClick | `() => void` | no |  | When provided, the left icon becomes a clickable button. |
| onRightIconClick | `() => void` | no |  | When provided, the right icon becomes a clickable button. |
| persistDebounceMs | `number` | no | 300 | Debounce interval (ms) for storage writes. |
| persistKey | `string` | no |  | Key for persisting the input value to storage. |
| persistNamespace | `string` | no |  | Namespace (e.g. user id) to scope the persist key. |
| persistStorage | `'localStorage' | 'sessionStorage'` | no | 'localStorage' | Storage backend for persistence. |
| persistVersion | `number` | no | 1 | Version stamp included in the storage key. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Input: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | Readonly property for the Input component |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| rightIcon | `Snippet` | no |  | Icon snippet rendered on the right side of the input field. |
| rightIconAriaLabel | `string` | no |  | Accessible label for the clickable right icon button. Required when `onRightIconClick` is set so screen-reader users hear a name for the button (icons inside are `aria-hidden`). |
| slotClasses | `Partial<Record<InputSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | container | base (the `<input>` element) | label | message | iconContainer | iconButton | iconDecoration. |
| unstyled | `boolean` | no |  | Remove all default tv() classes — only user-provided classes apply. |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the Input. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| variant | `'filled' | 'ghost' | 'outlined' | 'underline'` | no | outlined | Controls the visual style and presentation of the Input. Determines the component's visual treatment. Available options: filled, ghost, outlined, underline. |
| size | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Input. Affects the component's physical footprint. Available options: lg, md, sm, and 2 more. |
| hasLeftIcon | `'true'` | no | false | Controls the hasLeftIcon behavior and appearance of the Input component. Available options: true. |
| hasRightIcon | `'true'` | no | false | Controls the hasRightIcon behavior and appearance of the Input component. Available options: true. |
| iconPosition | `'left' | 'right'` | no | left | Controls the iconPosition behavior and appearance of the Input component. Available options: left, right. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Input component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Input component. Available options: commit, modify. |

Inherited from:
- Omit<InputVariants, 'error'> (omit-pattern)
- Omit<HTMLInputAttributes, 'size' | 'class' | 'disabled' | 'readonly' | 'children'> (omit-pattern)

---

## InvitationManager
Admin panel for managing invitation-gated registration with email toggle.
Communicates with `basePath` (default `/api/invitations`). Pair with `createInvitationHandlers(authDeps, { authorize, roles })` on the server — mount its `POST` + `GET` on `/api/invitations` and `DELETE` on `/api/invitations/[id]`.

**Import:** `import { InvitationManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<InvitationManager {t} roles={[{ value: 'ADMIN', label: 'Admin' }, { value: 'USER', label: 'User' }]} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| roles | `RoleOption[]` | yes |  | Available roles for the invitation menu. |
| basePath | `string` | no | '/api/invitations' | BasePath property for the InvitationManager component |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| slotClasses | `Partial<Record<'root' | 'title' | 'form' | 'list' | 'item' | 'error', string>>` | no |  | Per-slot class overrides. See component source for available slot keys. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `title`, `form`, `list`, `item`, `error`

---

## LineChart
Line chart for trends over an ordered category axis. One path
per series on the design-token palette; zero-dependency SVG, responsive,
dark-mode aware, with optional points, gridlines, legend, and a screen-
reader data-table fallback.

**Import:** `import { LineChart } from '@urbicon-ui/blocks';`

### Examples
```svelte
<LineChart
  data={[
    { label: 'Mon', values: [12] },
    { label: 'Tue', values: [18] },
    { label: 'Wed', values: [9] }
  ]}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `CartesianDatum[]` | yes |  | Ordered categories with per-series values. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ariaLabel | `string` | no |  | Accessible label; a summary is generated when omitted. |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| formatValue | `(value: number) => string` | no |  | Format values for axis labels, tooltips, and the data table. |
| height | `number` | no | 240 | Height property for the LineChart component |
| includeZero | `boolean` | no | false | Start the value axis at zero instead of framing the data range. |
| locale | `string` | no |  | BCP-47 locale for the default number formatter. |
| margin | `ChartMargin` | no |  | Plot margins; merged over the defaults. |
| preset | `string` | no |  | Apply a named preset registered on `<BlocksProvider>`. |
| series | `ChartSeries[]` | no |  | Series metadata (labels + colors); defaults to one per value column. |
| showGrid | `boolean` | no | true | Render horizontal gridlines. |
| showLegend | `boolean` | no | true | Show the series legend (only renders with >1 series). |
| showPoints | `boolean` | no | true | Render a dot at each data point. |
| slotClasses | `ChartSlotClasses` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no |  | Remove all default tv classes. |
| width | `number` | no |  | Fixed width in px; omit for responsive width. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## LocaleSwitcher
Convenience wrapper around Select to switch UI locales.
Single-select only — locale is always exactly one value. Options, value,
form integration, multi-select, and null-option are all owned internally
and intentionally not forwarded to the underlying Select.

**Import:** `import { LocaleSwitcher } from '@urbicon-ui/blocks';`

### Examples
```svelte
<LocaleSwitcher />
```

```svelte
<LocaleSwitcher showFlag variant="filled" size="sm" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| locales | `Locale[]` | no |  | Restrict the displayed locales. Defaults to all locales registered in i18n. |
| onLocaleChange | `(locale: Locale) => void` | no |  | Called after the locale has been changed successfully. |
| showFlag | `boolean` | no | true | Show flag emoji alongside locale name. |

Inherited from:
- Omit<
    SelectSingleProps<string>,
    // Owned by LocaleSwitcher's internal options/value pipeline:
    | 'options'
    | 'groups'
    | 'value'
    | 'onValueChange'
    | 'multiple'
    | 'multiPlaceholder'
    | 'nullOption'
    | 'closeOnSelect'
    | 'name'
    | 'label'
    | 'helper'
    | 'error'
  > (omit-pattern)

---

## LoginPage
Pre-built login page with email/password, optional passkey, and remember-me.
Sends POST to `apiPath` (default `/api/auth/login`). Pair with `createLoginHandler(authDeps)` on the server.

**Import:** `import { LoginPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<LoginPage {t} onSuccess={() => goto('/')} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/login' | API endpoint for the login request. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links (e.g. terms checkbox). |
| forgotPasswordUrl | `string` | no | '/auth/forgot-password' | URL for the forgot-password page link. |
| header | `Snippet` | no |  | Content rendered above the form (e.g. social login buttons, welcome text). |
| links | `Snippet` | no |  | Replaces the link area below the form. |
| mode | `'password' | 'passkey' | 'both'` | no | 'both' | Login mode. `'password'` shows only email/password, `'passkey'` shows only passkey button, `'both'` shows both with separator. |
| onSuccess | `() => void` | no |  | Called after successful login. |
| passkeyApiPath | `string` | no | undefined | Passkey API base path. Required when mode is `'passkey'` or `'both'`. |
| registerUrl | `string` | no | '/auth/register' | URL for the register page link. |
| rememberMe | `boolean` | no | false | Show a "Remember me" checkbox. When checked, sends `rememberMe: true` in the login request body. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| twoFactorApiPath | `string` | no | '/api/auth/2fa/verify' | API endpoint for the 2FA verify step. When the login response signals `twoFactorRequired`, the page switches to a code-entry step that POSTs here. Pair with `createTwoFactorVerifyHandler`. |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## Menu
Action menu triggered by a button with nested items, icons, separators, and keyboard navigation.

**Import:** `import { Menu } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Menu placeholder="Actions" items={[
  { label: 'Edit', onSelect: () => edit() },
  { label: 'Duplicate', onSelect: () => duplicate() },
  { type: 'section', label: 'Danger' },
  { label: 'Delete', onSelect: () => confirmDelete() }
]} />
```

```svelte
<Menu placeholder="More">
  <MenuSection label="Edit" />
  <MenuItem onSelect={() => rename()}>Rename</MenuItem>
  <MenuItem onSelect={() => duplicate()}>Duplicate</MenuItem>
  <MenuDivider />
  <MenuItem onSelect={() => confirmDelete()}>Delete</MenuItem>
</Menu>
```

```svelte
<Menu items={actionItems}>
  {#snippet customTrigger(toggle, open)}
    <Button
      variant="ghost"
      aria-label="Actions"
      aria-haspopup="menu"
      aria-expanded={open}
      onclick={toggle}
    >
      <MoreHorizontalIcon />
    </Button>
  {/snippet}
</Menu>
```

### Variants
- chevronAnimation: fade, none, rotate, translate (default: rotate)
- disabled: true
- itemSize: lg, md, sm (default: md)
- open: true (default: false)
- placement: bottom, bottom-end, bottom-start, top, top-end, top-start (default: bottom-start)
- syncWidth: false, true (default: true)
- tier: commit, modify (default: commit)
- usePortal: false, true (default: true)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...AnimationProps | `inherited` | no |  | Properties inherited from AnimationProps |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class' | 'placeholder') |
| ...MenuVariants | `VariantProps` | no |  | Styling variants from MenuVariants |
| class | `string` | no |  | Additional CSS classes to apply to the Menu component |
| customFooter | `Snippet` | no |  | Optional custom footer rendered below the items list. |
| customHeader | `Snippet` | no |  | Optional custom header rendered above the items list. |
| customItem | `Snippet<[TItem]>` | no |  | Custom per-item content. **Render visible content only** — the outer `role="menuitem"` button is provided by Menu and handles the click / keyboard activation. Putting an interactive element (`<button>`, `<a>`) inside the snippet creates nested-interactive HTML and triggers the item's action twice via event bubbling.  Positional arg: `(item)`. To dispatch from outside the normal click (e.g. a "Recent" entry that needs to activate from a parent shortcut), call the item's own `onSelect` directly. |
| customTrigger | `Snippet<[() => void, boolean, () => void]>` | no |  | Replace the default trigger button (chevron + label) with a custom element. Positional args: `(toggle, open, dismiss)`.  - `toggle`: flips the open state — wire this to your custom trigger's   click handler so the menu can be opened from the consumer's element. - `open`: current open state — useful for `aria-expanded`. - `dismiss`: closes the menu without changing toggle history; rarely   needed but provided for symmetry.  The consumer's element should bind its `onclick` to `toggle` and set `aria-expanded={open}` + `aria-haspopup="menu"` for ARIA correctness. |
| id | `string` | no |  | Id property for the Menu component |
| chevronAnimation | `'fade' | 'none' | 'rotate' | 'translate'` | no | rotate | Controls the chevronAnimation behavior and appearance of the Menu component. Available options: fade, none, rotate, translate. |
| disabled | `'true'` | no |  | Controls the disabled behavior and appearance of the Menu component. Available options: true. |
| itemSize | `'lg' | 'md' | 'sm'` | no | md | Controls the itemSize behavior and appearance of the Menu component. Available options: lg, md, sm. |
| open | `'true'` | no | false | Controls the open behavior and appearance of the Menu component. Available options: true. |
| placement | `'bottom' | 'bottom-end' | 'bottom-start' | 'top' | 'top-end' | 'top-start'` | no | bottom-start | Controls the positioning and alignment of the Menu relative to its container or trigger element. Available options: bottom, bottom-end, bottom-start, and 3 more. |
| syncWidth | `'false' | 'true'` | no | true | Controls the syncWidth behavior and appearance of the Menu component. Available options: false, true. |
| tier | `'commit' | 'modify'` | no | commit | Controls the tier behavior and appearance of the Menu component. Available options: commit, modify. |
| usePortal | `'false' | 'true'` | no | true | Controls the usePortal behavior and appearance of the Menu component. Available options: false, true. |

Inherited from:
- MenuVariants (external)
- Omit<MenuSpecificProps<TItem>, keyof MenuVariants> (omit-pattern)
- MenuCustomSlots (local-interface)
- AnimationProps (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class' | 'placeholder'> (omit-pattern)

---

## NotificationBadge
Unread notification count badge. Uses blocks Badge primitive.
Renders nothing when count is 0.

**Import:** `import { NotificationBadge } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationBadge count={store.unreadCount} onclick={() => (open = !open)} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| count | `number` | yes |  | Number of unread notifications. Badge hidden when 0. |
| class | `string` | no |  | Extra classes on the root element. |
| onclick | `() => void` | no |  | Click handler (e.g. toggle notification center). |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## NotificationCenter
Menu-ready notification list with mark-as-read, delete, and empty state.
Renders each notification as a clickable card with timestamp.

**Import:** `import { NotificationCenter } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationCenter {t} notifications={store.notifications}
  onMarkAsRead={(id) => store.markAsRead(id)}
  onMarkAllAsRead={() => store.markAllAsRead()}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| notifications | `import('../../../server/adapters/types.js').NotificationRecord[]` | yes |  | Notification records to display. |
| class | `string` | no |  | Extra classes on the root element. |
| item | `Snippet<[import('../../../server/adapters/types.js').NotificationRecord]>` | no |  | Custom notification item renderer. |
| onClick | `(notification: import('../../../server/adapters/types.js').NotificationRecord) => void` | no |  | Called when a notification is clicked (e.g. to navigate to a URL). SECURITY: `notification.url` is DB-/server-sourced and untrusted — before passing it to `goto()` / `window.location`, validate it is same-origin or relative (reject `javascript:` and absolute cross-origin URLs). Never navigate to a raw `notification.url`. |
| onDelete | `(id: string) => void` | no |  | Called when a notification is deleted. |
| onMarkAllAsRead | `() => void` | no |  | Called when all notifications are marked as read. |
| onMarkAsRead | `(id: string) => void` | no |  | Called when a single notification is marked as read. |
| slotClasses | `Partial<Record<'root' | 'header' | 'list' | 'item' | 'empty', string>>` | no |  | Per-slot class overrides. See component source for available slot keys. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `header`, `list`, `item`, `empty`

---

## NotificationListener
Headless SSE listener for real-time notifications. Reconnects with exponential backoff (1–30s).
Connects to `basePath` (default `/api/notifications/stream`). Pair with `createStreamHandler(sse)` on the server — mount its `GET` on the stream route.

**Import:** `import { NotificationListener } from '@urbicon-ui/auth';`

### Examples
```svelte
<NotificationListener onNotification={(n) => store.add(n)} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| basePath | `string` | no | '/api/notifications/stream' | SSE stream endpoint. Read once when the component mounts — to switch endpoints (e.g. after a user change), unmount and remount the listener. |
| maxReconnectAttempts | `number` | no | 5 | Maximum reconnection attempts before giving up. Read once at mount. |
| onError | `(error: Event) => void` | no |  | Called when the SSE connection encounters an error. |
| onNotification | `(
    notification: import('../../../server/adapters/types.js').NotificationRecord
  ) => void` | no |  | Called when a new notification arrives via SSE. |
| onReconnect | `(attempt: number) => void` | no |  | Called when a reconnection attempt starts. Receives current attempt number. |

---

## Pagination
Navigation control for paged data sets.
Supports multiple layouts, intents, button variants, and configurable ellipsis behaviour.

**Import:** `import { Pagination } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Pagination
  currentPage={page}
  totalPages={20}
  onPageChange={(p) => page = p}
/>
```

### Variants
- size: lg, md, sm (default: md)
- layout: default, minimal, navigation, table (default: default)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| currentPage | `number` | yes |  | 1-based index of the currently active page. |
| totalPages | `number` | yes |  | Total number of pages in the data set. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'class') |
| ...PaginationVariants | `VariantProps` | no |  | Styling variants from PaginationVariants |
| class | `string` | no |  | Additional CSS classes merged onto the root `<nav>` element. |
| disabled | `boolean` | no |  | Disables all buttons and dims the component. |
| endItem | `number` | no |  | Override the calculated end item number for the info text. |
| firstIcon | `Snippet` | no |  | Custom icon rendered inside the "First" button. |
| firstLabel | `string` | no |  | Label for the "First" button. Falls back to i18n key `pagination.first`. |
| infoText | `string` | no |  | Override the auto-generated info text with a fully custom string. |
| intent | `'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'neutral'` | no |  | Semantic color applied to every pagination button. |
| itemsPerPage | `number` | no |  | Items shown per page. Used by the table layout to compute "Showing X to Y of Z". |
| lastIcon | `Snippet` | no |  | Custom icon rendered inside the "Last" button. |
| lastLabel | `string` | no |  | Label for the "Last" button. Falls back to i18n key `pagination.last`. |
| loading | `boolean` | no |  | Shows a loading state with reduced opacity. |
| mint | `MintProp` | no |  | Micro-interaction animation applied to the pagination container. |
| nextIcon | `Snippet` | no |  | Custom icon rendered inside the "Next" button. |
| nextLabel | `string` | no |  | Label for the "Next" button. Falls back to i18n key `pagination.next`. |
| onPageChange | `(page: number) => void` | no |  | Fires when the user selects a different page. Receives the 1-based page number. |
| pageLabel | `string` | no |  | Prefix for the info text (e.g. "Page"). Falls back to i18n key `pagination.page`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Pagination: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| previousIcon | `Snippet` | no |  | Custom icon rendered inside the "Previous" button. |
| previousLabel | `string` | no |  | Label for the "Previous" button. Falls back to i18n key `pagination.previous`. |
| showFirstLast | `boolean` | no |  | Show "First" / "Last" boundary buttons when the current page is far from the edges. |
| showInfo | `boolean` | no |  | Show a text summary such as "Page 3 of 10" beneath the controls. |
| showNumbers | `boolean` | no |  | Show numbered page buttons. Set to false for a compact prev/next-only bar. |
| showPreviousNext | `boolean` | no |  | Show "Previous" / "Next" navigation buttons. |
| size | `'sm' | 'md' | 'lg'` | no |  | Button dimensions. Affects page numbers, prev/next, and first/last. |
| slotClasses | `Partial<Record<PaginationSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when unstyled) tv styles. Slots: base, info, controls, ellipsis. |
| startItem | `number` | no |  | Override the calculated start item number for the info text. |
| tier | `InteractiveTier` | no |  | Semantic radius tier forwarded to pagination buttons. |
| totalItems | `number` | no |  | Total number of items across all pages. Used by the table layout info text. |
| unstyled | `boolean` | no |  | Strip all default tailwind-variants classes for a fully custom build. |
| variant | `'outlined' | 'filled' | 'ghost'` | no |  | Visual weight of pagination buttons. |
| visiblePages | `number` | no |  | Maximum number of page buttons shown between the ellipsis indicators. |
| layout | `'default' | 'minimal' | 'navigation' | 'table'` | no | default | Controls the layout behavior and appearance of the Pagination component. Available options: default, minimal, navigation, table. |

Inherited from:
- Omit<PaginationVariants, 'disabled' | 'loading'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'class'> (omit-pattern)

---

## PasskeyManager
Admin panel for managing passkeys (WebAuthn credentials). Register and delete passkeys.
Communicates with `basePath` (default `/api/auth/passkey`). Pair with the `createPasskeyRegistrationOptionsHandler`, `createPasskeyRegistrationVerifyHandler`, `createPasskeyAuthenticationOptionsHandler` and `createPasskeyAuthenticationVerifyHandler` server handlers.

**Import:** `import { PasskeyManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<PasskeyManager {t} basePath="/api/auth/passkey" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| basePath | `string` | no | '/api/auth/passkey' | API base path for passkey operations. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| slotClasses | `Partial<Record<'root' | 'title' | 'list' | 'item' | 'empty', string>>` | no |  | Per-slot class overrides. See component source for available slot keys. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `title`, `list`, `item`, `empty`

---

## Planner
Date-indexed planning board — a week, month or custom-range grid
whose cells hold YOUR domain content (meals, shifts, bookings, content slots)
via a generic `cell` snippet. Buckets `items` by calendar day, then handles
navigation, ISO week numbers, keyboard a11y and a responsive column→stack
layout. For timed appointments, multi-day spans or recurrence use `Calendar`
instead.

**Import:** `import { Planner } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Planner view="week" items={entries} getDate={(e) => e.date}
sort={(a, b) => MEAL_ORDER[a.mealType] - MEAL_ORDER[b.mealType]}
bind:value={referenceDate} onNavigate={(_, range) => loadWeek(range.start)}>
{#snippet cell({ items, isoDate })}
{#each items as entry (entry.id)}
<MealCard {entry} />
{/each}
<Button variant="ghost" size="sm" onclick={() => openAdd(isoDate)}>Add meal</Button>
{/snippet}
</Planner>
```

### Variants
- variant: bordered, default, ghost (default: default)
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| getDate | `(item: T) => Date | string` | yes |  | Map an item to its calendar day. Return a `Date`, or a local date string (`'2026-06-16'`) taken verbatim — never UTC-parsed, so a plain date never shifts across timezones. A date-*time* string is bucketed by its written date part too; if your value is a UTC instant whose local day matters (`'…T23:00:00Z'`), return `new Date(value)` so the local timezone applies. Required. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PlannerVariants | `VariantProps` | no |  | Styling variants from PlannerVariants |
| animated | `boolean` | no | true | Slide-transition the grid on navigate (respects reduced-motion). |
| cell | `Snippet<[PlannerCellContext<T>]>` | no |  | Render a day's content — the core of the API. Receives bucketed `items: T[]`. Called for **every** day, including empty ones (`items: []`) — unless an `empty` snippet is given, which then handles empty days instead. Put an "add" affordance here to keep it available on empty days. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| dayHeader | `Snippet<[PlannerDayContext]>` | no |  | Customise each weekday/column header. |
| disabled | `boolean` | no | false | Disable navigation and selection. |
| empty | `Snippet<[PlannerCellContext<T>]>` | no |  | Placeholder rendered **instead of** `cell` for days with no items. Omit it to let `cell` render empty days too. |
| header | `Snippet<[PlannerHeaderContext]>` | no |  | Replace the default toolbar (prev/next/today/title/week). |
| highlightToday | `boolean` | no | true | Visually mark today's cell. |
| highlightWeekend | `boolean` | no | false | Tint Saturday/Sunday cells. |
| items | `T[]` | no |  | The items to lay out. Each is bucketed onto a day via . |
| locale | `string` | no | 'de-DE' | BCP 47 locale for the title and weekday names. |
| onDateSelect | `(date: Date) => void` | no |  | Fires when a day cell is activated (click / Enter / Space). |
| onNavigate | `(date: Date, range: PlannerRange) => void` | no |  | Fires after navigation. Receives the new reference date and visible range — load data here. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Planner: {...} }}>`. |
| rangeEnd | `Date` | no |  | End of the window for `view="range"`. |
| rangeStart | `Date` | no |  | Start of the window for `view="range"`. |
| selectedDate | `Date` | no |  | The active highlighted day. Supports `bind:selectedDate`. |
| showWeekNumber | `boolean` | no | false | Show the ISO week-number column on the left. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Density of the grid and header. |
| slotClasses | `Partial<Record<PlannerSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: base | header | headerTitle | nav | navButton | grid | weekdayHeader | weekday | weekNumber | week | cell | cellHeader | cellWeekday | cellDate | cellItems | empty |
| sort | `(a: T, b: T) => number` | no |  | Comparator for items within a day cell (e.g. by meal type or start label). |
| swipeable | `boolean` | no | true | Enable horizontal swipe-to-navigate on touch. |
| unstyled | `boolean` | no | false | Remove all default tv() classes — only user-provided classes apply. |
| value | `Date` | no | today | Reference date the view is anchored on. Supports `bind:value`. |
| variant | `'default' | 'bordered' | 'ghost'` | no | 'default' | Visual style variant for the Planner component |
| view | `PlannerView` | no | 'week' | View property for the Planner component |
| weekStartsOn | `0 | 1 | 2 | 3 | 4 | 5 | 6` | no | 1 | First day of the week (0=Sun … 6=Sat). |

Inherited from:
- Omit<PlannerVariants, 'view'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## PlaygroundConfigurator
Interactive playground configurator for component documentation.
Renders a live preview, control panel for props, and generated code block.

**Import:** `import { PlaygroundConfigurator } from '@urbicon-ui/docs';`

### Examples
```svelte
<PlaygroundConfigurator
  componentName="Button"
  controls={controls}
  values={values}
>
  {#snippet children(vals)}
    <Button {...vals}>Click me</Button>
  {/snippet}
</PlaygroundConfigurator>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet<[Record<string, any>]>` | yes |  | Render snippet receiving the current values map. The argument is typed loosely (`Record<string, any>`) so consumers can spread it onto child components without type-asserting each variant key — the trade-off is that direct property access inside the snippet is also `any`. Use the `values` prop type for typed access.  The `any` here is a pragmatic exception to the project-wide ban: it enables docs-page playgrounds (`<Component {...values} />`) to compile without forcing every consumer to mirror the full prop union locally. |
| controls | `ControlDefinition[]` | yes |  | Control definitions that drive the props panel (dropdown, toggle, text, etc.). |
| values | `TValues` | yes |  | Current control values. Supports `bind:values` for two-way binding. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PlaygroundConfiguratorVariantProps | `VariantProps` | no |  | Styling variants from PlaygroundConfiguratorVariantProps |
| class | `string` | no |  | Extra CSS classes merged onto the root element. |
| codeGenerator | `(values: TValues) => string` | no |  | Custom code generator. Falls back to auto-generated Svelte tag syntax. |
| componentName | `string` | no |  | Component name used in the auto-generated code output. |
| onValuesChange | `(values: TValues) => void` | no |  | Fires after any control value changes with the full values map. |
| propDocs | `Record<string, string>` | no |  | Hand-written prop descriptions (from JSDoc). Shown as tooltip behind an info icon. |
| showHeader | `boolean` | no |  | Show the title/subtitle header above the playground. |
| size | `'sm' | 'md' | 'lg'` | no |  | Controls the density of the playground layout – padding, grid columns, and text size. |
| slotClasses | `Partial<Record<'root' | 'header' | 'title' | 'subtitle' | 'container' | 'preview' | 'previewContent' | 'controlsPanel' | 'controlsHeader' | 'controlsGrid' | 'controlItem' | 'controlLabel' | 'controlControl' | 'controlControlCompact' | 'controlHint' | 'actionsBar' | 'helpToggle' | 'codePanel' | 'codeToolbar' | 'codeDisplay', string>>` | no |  | Per-slot class overrides for internal elements. |
| subtitle | `string` | no |  | Descriptive text below the title. |
| title | `string` | no |  | Heading text above the playground panel. |
| unstyled | `boolean` | no |  | Strip all default tv() styles from internal slots. |
| variantKeys | `string[]` | no |  | Prop names originating from tailwind-variants. Shown with a "V" indicator. |

Inherited from:
- Omit<PlaygroundConfiguratorVariantProps, 'size'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`root`, `header`, `title`, `subtitle`, `container`, `preview`, `previewContent`, `controlsPanel`, `controlsHeader`, `controlsGrid`, `controlItem`, `controlLabel`, `controlControl`, `controlControlCompact`, `controlHint`, `actionsBar`, `helpToggle`, `codePanel`, `codeToolbar`, `codeDisplay`

---

## Popover
Floating panel anchored to a trigger element. Uses the native Popover API
for top-layer rendering, light dismiss, and Escape handling. Floating UI provides
precise positioning with automatic flip, shift, and optional width syncing.

**Import:** `import { Popover } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Popover placement="bottom-start">
  {#snippet trigger()}
    <Button>Open</Button>
  {/snippet}
  {#snippet children()}
    <div class="p-3">Popover content</div>
  {/snippet}
</Popover>
```

```svelte
<Popover placement="top" arrow bind:open={showInfo}>
  {#snippet trigger()}
    <Button variant="ghost" size="sm">More info</Button>
  {/snippet}
  {#snippet children()}
    <div class="max-w-xs p-4">
      <h4 class="font-semibold">Details</h4>
      <p class="text-text-secondary text-sm">Additional context shown in a floating panel.</p>
    </div>
  {/snippet}
</Popover>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Popover body rendered inside the floating panel. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PopoverVariants | `VariantProps` | no |  | Styling variants from PopoverVariants |
| autoTrigger | `boolean` | no |  | When true (default), the trigger wrapper handles click and keyboard to toggle the popover. Set to `false` to manage `open` yourself. |
| class | `string` | no |  | Extra classes merged onto the floating panel element. |
| closeOnClickOutside | `boolean` | no |  | Whether the popover closes on outside click / pointer interaction. Default `true`. Set to `false` to pin the popover open until the consumer explicitly toggles `open`. |
| closeOnEscape | `boolean` | no |  | Whether the popover closes on Escape key. Default `true`. Set to `false` for cases where Escape should be intercepted by an inner widget (e.g. an editable cell that wants to revert on Escape). |
| offsetDistance | `number` | no |  | Gap in px between the trigger edge and the popover. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes from user interaction (click, escape, click-outside). Receives the new open state. |
| open | `boolean` | no |  | Controlled open state. Supports `bind:open`. |
| placement | `Placement` | no |  | Where the popover appears relative to the trigger. All Floating UI `Placement` values are supported. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Popover: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shiftPadding | `number` | no |  | Minimum px padding from viewport edges when the popover shifts to stay visible. |
| slotClasses | `Partial<Record<'base', string>>` | no |  | Per-slot class overrides. Available slots: `base` (the floating panel). |
| syncMinWidth | `boolean` | no |  | Match the popover's *minimum* width to the trigger width while still letting content grow the panel beyond it. Useful for menu-style overlays where items longer than the trigger should not get truncated. Ignored when `syncWidth` is true (hard width wins). |
| syncWidth | `boolean` | no |  | Match the popover width to the trigger width. Useful for select/autocomplete patterns where the floating panel should align with the input. |
| trigger | `Snippet` | no |  | Trigger element that anchors and toggles the popover. Receives click/keyboard handlers when `autoTrigger` is true. |
| triggerElement | `HTMLElement` | no |  | External trigger element ref. Use instead of the `trigger` snippet when the trigger lives outside the Popover tree. Supports `bind:triggerElement`. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `class` or `slotClasses` for full custom styling. |
| usePortal | `boolean` | no | true | Render the floating panel into the browser's top layer via the native `popover` attribute, so it cannot be clipped by `overflow: auto` ancestors. Set to `false` when the popover is itself embedded inside another floating surface (Dialog, Drawer, another Popover) — nested top-layer rendering stacks unpredictably across browsers and stealing focus from the parent surface is usually unwanted. In-flow mode positions the panel absolutely relative to the trigger's offset parent. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Popover. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- PopoverVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`

---

## Progress
Progress indicator for determinate and indeterminate loading states.
Supports linear bar and circular ring variants with semantic intents and animation.

**Import:** `import { Progress } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Progress value={65} label="Upload progress" showValue />
```

```svelte
<Progress value={80} shape="circular" intent="success" showValue />
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- size: lg, md, sm, xs (default: md)
- animated: true (default: false)
- indeterminate: true (default: false)
- striped: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...ProgressVariants | `VariantProps` | no |  | Styling variants from ProgressVariants |
| animated | `boolean` | no | false | Animate the striped pattern. Requires `striped` to be true. |
| circularSize | `number` | no | 80 | Diameter of the circular indicator in pixels. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| formatValue | `(value: number, max: number) => string` | no | (v, max) => `${Math.round((v/max) * 100)}%` | Format function for the displayed value. |
| label | `string` | no |  | Text label displayed above or inside the progress indicator. |
| max | `number` | no | 100 | Maximum value for the progress range. |
| min | `number` | no | 0 | Minimum value for the progress range. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Progress: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shape | `'linear' | 'circular'` | no | 'linear' | Shape of the progress indicator. |
| showValue | `boolean` | no | false | Show the numeric value (percentage or absolute) next to the label. |
| slotClasses | `Partial<Record<ProgressSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (linear root — what `class` targets in linear shape) | header | label | valueText | track | fill | circularWrapper (circular root — what `class` targets in circular shape) | circularTrack | circularFill | circularLabel. |
| striped | `boolean` | no | false | Display striped pattern on the fill. |
| strokeWidth | `number` | no | 6 | Stroke width of the circular indicator in pixels. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| value | `number` | no |  | Current progress value (0–100). Omit for indeterminate mode. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Progress. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Progress. Affects the component's physical footprint. Available options: lg, md, sm, xs. |
| indeterminate | `'true'` | no | false | Controls the indeterminate behavior and appearance of the Progress component. Available options: true. |

Inherited from:
- ProgressVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

---

## PushPermissionPrompt
Dismissible prompt asking the user to enable push notifications.
Handles VAPID subscription and server-side registration.

**Import:** `import { PushPermissionPrompt } from '@urbicon-ui/auth';`

### Examples
```svelte
<PushPermissionPrompt {t} vapidPublicKey={PUBLIC_VAPID_KEY}
  onSubscribed={(sub) => console.log('Subscribed', sub)}
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| vapidPublicKey | `string` | yes |  | VAPID public key for push subscription. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| onDismissed | `() => void` | no |  | Called when the user dismisses the prompt. |
| onSubscribed | `(subscription: PushSubscription) => void` | no |  | Called after successful push subscription. |
| slotClasses | `Partial<Record<'root' | 'text' | 'actions', string>>` | no |  | Per-slot class overrides. See component source for available slot keys. |
| subscriptionEndpoint | `string` | no | '/api/notifications/push-subscription' | API endpoint for registering subscriptions. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `text`, `actions`

---

## RadioGroup
Accessible radio group for single-option selection with semantic intents and form integration.
Uses native radio inputs for correct form behavior and ARIA semantics with keyboard navigation.

**Import:** `import { RadioGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<RadioGroup label="Plan" bind:value={plan}>
  <RadioItem value="free" label="Free" />
  <RadioItem value="pro" label="Pro" description="Best for teams" />
</RadioGroup>
```

### Variants
- disabled: true (default: false)
- error: true (default: false)
- orientation: horizontal, vertical (default: vertical)
- required: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | RadioItem children to render inside the group. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| disabled | `boolean` | no |  | Disable all radio items in the group. |
| error | `string` | no |  | Error message below the group. Replaces `helper` and sets `aria-invalid`. |
| helper | `string` | no |  | Hint text below the group. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` for the group element. Auto-generated if omitted. |
| intent | `RadioItemVariants['intent']` | no | 'primary' | Semantic color propagated to all child RadioItems. |
| label | `string` | no |  | Group label displayed above the radio items. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset propagated to child RadioItems. |
| name | `string` | no |  | Shared `name` attribute for all radio inputs. Auto-generated if omitted. |
| onValueChange | `(value: string) => void` | no |  | Fired after the selected value changes. Receives the new value. |
| orientation | `'horizontal' | 'vertical'` | no | 'vertical' | Stack direction for the radio items. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ RadioGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Mark the group as required for form validation. Adds an asterisk to the label. |
| size | `RadioItemVariants['size']` | no | 'md' | Visual size propagated to all child RadioItems. |
| slotClasses | `Partial<Record<RadioGroupSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. |
| tier | `InteractiveTier` | no | 'commit' | Semantic radius tier propagated to every RadioItem. Default `commit` — radio indicators read as identity circles. Set to `modify` (or inherit via TierContext from a wrapping `<Toolbar tier="modify">`) for inline-toolbar contexts where a circle feels oversized. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Only user-provided classes apply. |
| value | `string` | no |  | Currently selected value. Supports two-way binding via `bind:value`. |
| variant | `RadioItemVariants['variant']` | no | 'outlined' | Visual weight propagated to all child RadioItems. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

---

## RegisterPage
Pre-built registration page with invitation-gated signup, password requirements checklist, and confirm field.
Sends POST to `apiPath` (default `/api/auth/register`). Pair with `createRegisterHandler(authDeps)` on the server.

**Import:** `import { RegisterPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<RegisterPage {t} onSuccess={() => goto('/')} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| apiPath | `string` | no | '/api/auth/register' | ApiPath property for the RegisterPage component |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| defaultEmail | `string` | no | '' | Pre-fills the email field. Pass the `?email=` query param from the invitation link (`createInvitationHandlers` builds `/auth/register?email=<invitee>`) so an invited user lands on a ready-to-submit form instead of retyping — and a typo can't trigger the opaque "invitation required" 403. Following the same explicit-prop pattern as `ResetPasswordPage`/`VerifyEmailPage`'s `token`, read it from the page in your route (SSR-safe), e.g. `defaultEmail={page.url.searchParams.get('email') ?? ''}`. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| footer | `Snippet` | no |  | Content rendered below the form, above links (e.g. terms checkbox). |
| header | `Snippet` | no |  | Content rendered above the form (e.g. social login buttons). |
| links | `Snippet` | no |  | Replaces the link area. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| onSuccess | `() => void` | no |  | Called after successful registration. |
| passwordMinLength | `number` | no | 8 | Minimum password length. |
| requireDigit | `boolean` | no | true | RequireDigit property for the RegisterPage component |
| requireLowercase | `boolean` | no | true | Require lowercase letter. |
| requireSpecial | `boolean` | no | false | Require special character. |
| requireUppercase | `boolean` | no | true | Require uppercase letter. |
| showRequirements | `boolean` | no | true | Show real-time password requirements checklist. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## ResetPasswordPage
Pre-built reset-password page with password confirmation.
Sends POST to `apiPath` (default `/api/auth/reset-password`). Pair with `createResetPasswordHandler(authDeps)` on the server.

**Import:** `import { ResetPasswordPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<ResetPasswordPage {t} token={$page.url.searchParams.get('token') ?? ''} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| token | `string` | yes |  | Reset token from URL query parameter. |
| apiPath | `string` | no | '/api/auth/reset-password' | ApiPath property for the ResetPasswordPage component |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| loginUrl | `string` | no | '/auth/login' | URL for the login page link. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## Sankey
Flow diagram (Sankey) for visualizing multi-stage data or value
pipelines. Nodes are split into layers; paths are rendered as cubic Bezier
curves with value-proportional width. The layout algorithm is embedded (no
d3-sankey dependency, ISC license attributed).

Hovering/focusing a node or path highlights the connected paths and
neighboring nodes. A ResizeObserver adapts the width responsively. An
sr-only table provides a screen-reader fallback with source/target/value.

**Import:** `import { Sankey } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Sankey
  nodes={[
    { id: 'gas',  label: 'Gas',     intent: 'primary' },
    { id: 'pot',  label: 'Pool',    intent: 'neutral' },
    { id: 'heat', label: 'Heating', intent: 'success' }
  ]}
  links={[
    { source: 'gas', target: 'pot',  value: 220609 },
    { source: 'pot', target: 'heat', value: 220609 }
  ]}
  formatValue={(v) => formatCurrency(v)}
  height={400}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: neutral)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| links | `SankeyLink[]` | yes |  | Links property for the Sankey component |
| nodes | `SankeyNode[]` | yes |  | Nodes property for the Sankey component |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SankeyVariants | `VariantProps` | no |  | Styling variants from SankeyVariants |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| defaultOpacity | `number` | no | 0.45 | Default stroke opacity of paths without hover. |
| dimmedOpacity | `number` | no | 0.25 | Hover opacity of the non-focused paths. |
| formatPercent | `(percent: number) => string` | no |  | Format function for percentages (tooltip). |
| formatValue | `(value: number) => string` | no |  | Format function for values (tooltip + sr-only table). |
| height | `number | 'auto'` | no | 400 | Height of the diagram. Accepts a fixed pixel number or `'auto'`.  `'auto'` scales with the node count: roughly `nodes.length × (12 + nodePadding)`, clamped to `[280, 800]`. Useful when the number of nodes varies at runtime and a fixed pixel value would be too small or too large. |
| highlightedOpacity | `number` | no | 0.7 | Stroke opacity of the highlighted paths. |
| highlightOnHover | `boolean` | no | true | Hover highlight (paths + connected nodes). |
| intent | `SankeyIntent` | no | 'neutral' | Default intent for nodes without their own `intent`. |
| iterations | `number` | no | 6 | Number of relaxation iterations in the layout. |
| linkContent | `Snippet<[link: SankeyLaidOutLinkWithMeta]>` | no |  | Custom snippet for path rendering (instead of the default cubic Bezier). |
| nodeAlign | `'left' | 'right' | 'center' | 'justify'` | no | 'justify' | NodeAlign property for the Sankey component |
| nodeContent | `Snippet<[node: SankeyLaidOutNodeWithMeta]>` | no |  | Custom snippet for node content (inside the SVG, instead of the label). |
| nodePadding | `number` | no | 16 | Vertical gap between nodes within a layer. |
| nodeWidth | `number` | no | 24 | Pixel width of a node. |
| onLinkClick | `(link: SankeyLaidOutLinkWithMeta) => void` | no |  | Click callback for a path. |
| onNodeClick | `(node: SankeyLaidOutNodeWithMeta) => void` | no |  | Click callback for a node. |
| preset | `string` | no |  | Preset property for the Sankey component |
| showValues | `boolean` | no | false | Persistently display values next to node labels (instead of only in the hover tooltip). Useful for print, PDF attachments, static screenshots, or tenant- and client-facing statements where hovering is not possible. Uses `formatValue` for formatting. |
| slotClasses | `Partial<Record<SankeySlots, string>>` | no |  | Per-slot class overrides. |
| tooltip | `Snippet<[datum: SankeyLaidOutNodeWithMeta | SankeyLaidOutLinkWithMeta, kind: 'node' | 'link']>` | no |  | Custom tooltip content for node or path. |
| unstyled | `boolean` | no |  | Remove default classes. |
| width | `number` | no |  | Optional fixed width. Default: derived from the container via ResizeObserver. Set a value only if you need SSR-stable layouts and are willing to give up responsiveness. |

Inherited from:
- Omit<SankeyVariants, never> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Section
Content section with title/subtitle, badges, and semantic footer.

**Import:** `import { Section } from '@urbicon-ui/docs';`

### Examples
```svelte
<Section id="usage" title="Usage" subtitle="Quick start">
  <p>Install and import the component.</p>
</Section>
```

### Variants
- intent: default, hero, primary, secondary (default: default)
- size: lg, md, sm, xl (default: lg)
- centered: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| id | `string` | yes |  | Section ID for navigation anchors |
| ...SectionVariantProps | `VariantProps` | no |  | Styling variants from SectionVariantProps |
| badges | `Array<{
    text: string;
    variant?: 'soft' | 'filled';
    intent?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
  }>` | no |  | Badges property for the Section component |
| children | `Snippet` | no |  | Main content snippet |
| class | `string` | no |  | Custom CSS class for the section element |
| footerSnippet | `Snippet` | no |  | Optional footer snippet (renders a semantic <footer>) |
| headingLevel | `1 | 2 | 3 | 4 | 5 | 6` | no | 2 | Heading level for the section title, clamped to 1..6 |
| marker | `string` | no |  | Optional editorial marker before the title (e.g. `"01"` renders as a quieter monospace stamp). |
| meta | `string` | no |  | Optional right-aligned monospace meta information in the title row (e.g. `"20 props"`, `"6 recipes"`). Renders as an editorial counter next to the title with `font-meta`, so the information stays visually subordinate to the section title. Lighter editorial polish (cluster A.3). |
| subtitle | `string` | no |  | Subtitle text (property) |
| subtitleSnippet | `Snippet` | no |  | Custom subtitle snippet (overrides subtitle prop) |
| title | `string` | no |  | Title text (property) |
| titleSnippet | `Snippet` | no |  | Custom title snippet (overrides title prop) |
| intent | `'default' | 'hero' | 'primary' | 'secondary'` | no | default | Controls the color theme and semantic meaning of the Section. Affects the overall appearance and user perception. Available options: default, hero, primary, secondary. |
| size | `'lg' | 'md' | 'sm' | 'xl'` | no | lg | Controls the dimensions, padding, and text size of the Section. Affects the component's physical footprint. Available options: lg, md, sm, xl. |
| centered | `'false' | 'true'` | no | false | Controls the centered behavior and appearance of the Section component. Available options: false, true. |

Inherited from:
- SectionVariantProps (external)

---

## SegmentGroup
Inline segment control with animated sliding indicator for single-selection scenarios.
Compact mode/view switcher with smooth animation.

**Import:** `import { SegmentGroup } from '@urbicon-ui/blocks';`

### Examples
```svelte
<SegmentGroup bind:value={view}>
  <SegmentItem value="list">List</SegmentItem>
  <SegmentItem value="grid">Grid</SegmentItem>
  <SegmentItem value="board">Board</SegmentItem>
</SegmentGroup>
```

### Variants
- size: lg, md, sm (default: md)
- appearance: default, text (default: default)
- disabled: true (default: false)
- fullWidth: true (default: false)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SegmentGroupVariants | `VariantProps` | no |  | Styling variants from SegmentGroupVariants |
| ariaLabel | `string` | no |  | Accessible label for the segment group. |
| children | `Snippet` | no |  | Segment items to render. Must be SegmentItem components. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| collapseOnOverflow | `boolean` | no | true | When the segments can't fit their available width, collapse the horizontal track to a vertical radio-style stack (all options stay visible) instead of overflowing. Triggered by real measured overflow (ResizeObserver), not a viewport breakpoint, so it only engages when an instance genuinely doesn't fit — a 2-segment switcher that fits stays horizontal. Set `false` to keep the track horizontal (it still won't push the page wider than its parent). |
| disabled | `boolean` | no | false | Prevent interaction and dim the control. |
| mint | `MintProp` | no | 'none' | Micro-interaction effect applied to each segment item (per-item, not the container). Accepts a preset name, an array of names, or configured mint objects. |
| onValueChange | `(value: string) => void` | no |  | Fires after the selected value changes. Receives the new value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SegmentGroup: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<SegmentGroupSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| value | `string` | no |  | Currently selected value. Supports `bind:value` for two-way binding. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the SegmentGroup. Affects the component's physical footprint. Available options: lg, md, sm. |
| appearance | `'default' | 'text'` | no | default | Controls the appearance behavior and appearance of the SegmentGroup component. Available options: default, text. |
| fullWidth | `'true'` | no | false | Controls the fullWidth behavior and appearance of the SegmentGroup component. Available options: true. |
| tier | `'commit' | 'modify'` | no | commit | Controls the tier behavior and appearance of the SegmentGroup component. Available options: commit, modify. |

Inherited from:
- SegmentGroupVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Select
Discriminated union over `multiple`. Consumers pick a single shape at the
call site and the value type narrows accordingly — `<Select multiple bind:value>`
binds to `T[]`, `<Select bind:value>` binds to `T | null`. See
`SelectSingleProps` / `SelectMultipleProps` for the per-mode details.

**Import:** `import { Select } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Select
  label="Country"
  options={[
    { label: 'Germany', value: 'de' },
    { label: 'France', value: 'fr' },
    { label: 'Spain', value: 'es' },
  ]}
  bind:value={country}
  placeholder="Choose a country"
/>
```

```svelte
<Select
  label="Tenant"
  options={tenants.map((t) => ({ label: t.name, value: t.id }))}
  bind:value={tenantId}
/>
```

```svelte
<Select
  label="Tags"
  options={tags}
  multiple
  selectionIndicator="checkbox"
  bind:value={selectedTags}
/>
```

```svelte
<Select options={...} multiple bind:value bind:open>
  {#snippet customTrigger(selected, isOpen, clear)}
    <Button variant="ghost" size="sm">
      <FilterIcon />
      {#if selected.length > 0}
        <Badge size="xs">{selected.length}</Badge>
      {/if}
    </Button>
  {/snippet}
</Select>
```

```svelte
<Select
  label="Role"
  groups={[
    { label: 'Engineering', options: [
      { label: 'Frontend', value: 'fe' },
      { label: 'Backend', value: 'be' }
    ]},
    { label: 'Design', options: [
      { label: 'UX', value: 'ux' },
      { label: 'Visual', value: 'vis' }
    ]}
  ]}
  bind:value={role}
  required
  error={roleError}
/>
```

### Variants
- variant: filled, ghost, outlined, underline (default: outlined)
- size: lg, md, sm (default: md)
- disabled: true (default: false)
- error: true (default: false)
- messageType: error, helper (default: helper)
- open: true (default: false)
- required: true (default: false)
- selected: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| clearable | `boolean` | no | false | Show a clear button when a value is selected. |
| closeOnClickOutside | `boolean` | no |  | Whether the listbox closes on outside click. Default `true`. Set to `false` to pin the listbox open while the consumer manages dismissal explicitly. |
| closeOnEscape | `boolean` | no |  | Whether the listbox closes on Escape key. Default `true`. Set to `false` for inline contexts where Escape should be intercepted by an outer widget (e.g. a row editor that wants to revert on Escape). |
| closeOnSelect | `boolean` | no |  | Whether the listbox closes after a selection is made. Defaults to `true` in single-select and `false` in multi-select — the multi-select default lets users tick multiple options without re-opening, matching the established multi-select pattern. |
| customItem | `Snippet<[SelectOption<T>, boolean, () => void]>` | no |  | Replace the default per-option rendering. Receives the option, its selection state, and a `toggle` callback (call to select/deselect). The outer `<div role="option">` container is still owned by Select for ARIA correctness — the snippet renders the option's visible contents.  Positional args: `(option, isSelected, toggle)`. |
| customTrigger | `Snippet<[SelectOption<T>[], boolean, () => void]>` | no |  | Replace the entire trigger button (chevron, label, clear control) with a custom element. Receives the selected options, current open state, and a `clear` callback. Use this for icon-only triggers, badge-counter triggers, or any non-standard chrome — the Select still owns open/close + selection state via the returned callbacks.  Positional args: `(selected, open, clear)`. |
| customTriggerContent | `Snippet<[SelectOption<T>[]]>` | no |  | Replace only the trigger's text/label area (chevron and clear button stay intact). Receives the selected options. Useful for showing icons next to the label, badges with counts, or formatted multi-select summaries while keeping the standard outlined-Select chrome.  Positional args: `(selected)`. |
| disabled | `boolean` | no | false | Whether the Select is disabled and non-interactive |
| error | `string` | no |  | Error message below the select. Overrides `helper` and forces danger styling. |
| groups | `SelectGroup<T>[]` | no |  | Grouped options with section labels. Takes precedence over `options`. |
| helper | `string` | no |  | Helper text below the select. Hidden when `error` is set. |
| id | `string` | no |  | Explicit `id` for the component. Auto-generated if omitted. |
| label | `string` | no |  | Label text displayed above the select, auto-linked via `id`. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
| multiPlaceholder | `string | ((selected: SelectOption<T>[]) => string)` | no |  | Placeholder shown when one or more values are picked. Pass a string for a static label ("3 selected") or a function that receives the currently selected options and returns a custom string. When unset, the trigger lists the selected labels comma-separated. |
| multiple | `'false' | 'true'` | no |  | Single-select mode (the default). Omit or set to `false` explicitly. |
| name | `string` | no |  | Shared `name` for a hidden input for native form submission. |
| nullOption | `string | NullOptionConfig` | no |  | Render an explicit "no value" option as the first row of the listbox. Selecting it sets the bound value to `null`. When `value` is `null`, the trigger displays this label instead of the placeholder.  Pass a string to use it as the label, or a `NullOptionConfig` for more control. Ignored when `groups` is set — group structures own their option list. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the listbox. Use for analytics or side-effects on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the listbox. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the listbox closes — that is governed by `closeOnEscape`. |
| onValueChange | `(value: T | null) => void` | no |  | Fires after the selected value changes. Receives the new value or `null` on clear. |
| open | `boolean` | no | false | Controls whether the listbox is open. Supports `bind:open` for parents that need to coordinate open/close (e.g. attaching a custom trigger button outside the Select wrapper). |
| options | `SelectOption<T>[]` | no |  | Flat list of selectable options. |
| placeholder | `string` | no | 'Select...' | Text shown when no value is selected. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Select: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no | false | Adds a required asterisk to the label. |
| selectionIndicator | `'checkmark' | 'none'` | no |  | Selection indicator rendered next to each option. - `'checkmark'` — trailing check icon (default) - `'none'` — no indicator (typical when using `customItem`) |
| slotClasses | `Partial<Record<SelectSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | base | trigger | triggerText | placeholder | chevron | clear | listbox | option | optionLabel | optionCheck | optionCheckbox | group | groupLabel | label | message. |
| syncWidth | `boolean` | no | true | Whether the listbox matches the trigger's width. Set `false` for icon-only or compact triggers where the listbox should size to its content instead. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| usePortal | `boolean` | no | true | When true, the listbox is rendered into the browser top layer via the native `popover` API, so it cannot be clipped by `overflow: auto` ancestors. When false, the listbox stays in the regular DOM flow — useful inside other popovers/portals to avoid double-portaling. |
| value | `T[]` | no | [] | Currently selected values. Supports `bind:value`. |
| variant | `SelectVariants['variant']` | no | 'outlined' | Visual style. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border (compact toolbars) - `ghost` — transparent until hover/focus (dense menus, inline editors) - `underline` — bottom-line only, no border-box (editorial knob-strips,   docs playgrounds) |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Select. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Select component. Available options: error, helper. |
| selected | `'true'` | no | false | Controls the selected behavior and appearance of the Select component. Available options: true. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Select component. Available options: commit, modify. |

---

## Separator
Visual divider for separating content sections. Supports horizontal and
vertical orientations with proper ARIA semantics.

**Import:** `import { Separator } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Separator />
```

```svelte
<div class="flex items-center gap-4">
  <span>Item A</span>
  <Separator orientation="vertical" size="sm" />
  <span>Item B</span>
</div>
```

### Variants
- size: lg, md, sm (default: md)
- orientation: horizontal, vertical (default: horizontal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...SeparatorVariants | `VariantProps` | no |  | Styling variants from SeparatorVariants |
| class | `string` | no |  | Additional CSS class merged onto the root element. |
| decorative | `boolean` | no |  | When true, the separator is purely visual (role="none"); when false, it uses role="separator" with aria-orientation. |
| orientation | `'horizontal' | 'vertical'` | no |  | Horizontal renders a full-width line; vertical renders a full-height line (e.g. inside flex rows). |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Separator: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `'sm' | 'md' | 'lg'` | no |  | Controls margin around the line — sm (0.5 rem), md (1 rem), lg (1.5 rem). |
| slotClasses | `Partial<Record<'base', string>>` | no |  | Per-slot class overrides. |
| unstyled | `boolean` | no |  | Strip all default styles; combine with slotClasses to rebuild from scratch. |

Inherited from:
- SeparatorVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

### Slots (slotClasses keys)
`base`

---

## SessionManager
Lists the user's active sessions (refresh-token families) with a
device label, last-active time and a "this device" badge, and lets them sign
out an individual session or all other devices. Requires refresh-token
rotation on the server (`config.refreshToken`); without it the list reports
itself unavailable. Pair with `createListSessionsHandler` (GET `basePath`),
`createRevokeSessionHandler` (POST `basePath/revoke`) and
`createRevokeOtherSessionsHandler` (POST `basePath/revoke-others`).

**Import:** `import { SessionManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<SessionManager basePath="/api/auth/sessions" />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| basePath | `string` | no | '/api/auth/sessions' | API base path for the session endpoints. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| slotClasses | `Partial<Record<'root' | 'title' | 'list' | 'item' | 'empty' | 'badge', string>>` | no |  | Per-slot class overrides. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `title`, `list`, `item`, `empty`, `badge`

---

## Sidebar
Sidebar primitive — fixed-position panel that is permanent on
desktop (≥1024px) and slides in as a backdropped overlay on mobile. Use
this directly for right-side detail panels or custom shells. For the
standard "permanent left rail + mobile hamburger" application chrome,
prefer the higher-level `<SidebarLayout>` component, which handles main
content offset and the mobile header for you.

The component exposes `--sidebar-width` and `--sidebar-effective-width`
(0px when collapsed) as CSS variables on its `<aside>` element. CSS
custom properties only inherit to descendants, so these variables are
available **inside** the sidebar's subtree but not on its siblings — that
is precisely why `<SidebarLayout>` exists for app-shell layouts.

**Import:** `import { Sidebar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
import { Sidebar, Button, CloseIcon, Badge } from '@urbicon-ui/blocks';
let detailOpen = $state(false);
</script>

<Button onclick={() => (detailOpen = true)}>Show details</Button>

<Sidebar bind:open={detailOpen} side="right" width="20rem">
{#snippet header()}
<div class="flex items-center justify-between py-3">
<span class="font-semibold">Item details</span>
<Button variant="ghost" size="xs" onclick={() => (detailOpen = false)}>
<CloseIcon class="h-4 w-4" />
</Button>
</div>
{/snippet}
<div class="space-y-3 p-4">
<dt class="text-text-tertiary text-xs">Status</dt>
<dd><Badge intent="success" size="sm">Active</Badge></dd>
</div>
</Sidebar>
```

```svelte
<Sidebar bind:open={sidebarOpen} mode="collapsible" width="16rem">
{#snippet header()}<span class="font-semibold">App</span>{/snippet}
<nav class="p-3"><!-- links --></nav>
</Sidebar>
```

### Variants
- mode: collapsible, responsive (default: responsive)
- side: left, right (default: left)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Main scrollable content of the sidebar. |
| class | `string` | no |  | Additional CSS classes applied to the sidebar panel. |
| closeOnBackdropClick | `boolean` | no | true | Close the mobile overlay when clicking the backdrop. |
| closeOnEscape | `boolean` | no | true | Close the mobile overlay when pressing Escape. |
| footer | `Snippet` | no |  | Content rendered in the sidebar footer (below the scrollable area). |
| header | `Snippet` | no |  | Content rendered in the sidebar header (above the scrollable area). |
| mode | `SidebarVariants['mode']` | no | 'responsive' | Controls sidebar behavior across viewports. - `responsive` (default): permanently visible on desktop (≥1024px), slide-in overlay on mobile. - `collapsible`: toggleable via `open` at all viewports — width animation on desktop, overlay on mobile. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the open state changes (mobile overlay dismissed, or collapsible toggled). |
| open | `boolean` | no |  | Controls sidebar visibility. In `responsive` mode (default) this only affects the mobile overlay — on desktop the sidebar is always visible. In `collapsible` mode this controls visibility at all viewports. Supports bind:open. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Sidebar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| side | `SidebarVariants['side']` | no | 'left' | Which edge the sidebar attaches to. |
| slotClasses | `Partial<Record<SidebarSlots, string>>` | no |  | Per-slot class overrides merged with variant styles. |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with slotClasses for custom appearance. |
| width | `string` | no | '16rem' | CSS width of the sidebar panel. Also exposed as `--sidebar-width` (constant) and `--sidebar-effective-width` (0px when collapsed) CSS variables on the `<aside>`. These inherit only inside the sidebar's own subtree — for the main content offset use `<SidebarLayout>`. |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## SidebarLayout
App-shell layout that wires a `<Sidebar>` to a main content
region and an optional mobile header. Use this whenever you want a
permanent sidebar on desktop with a hamburger overlay on mobile — it
resolves the CSS-variable scoping so the main content offset works without
boilerplate.

The component renders the sidebar internally; consumers configure it via
`sidebarHeader`, `sidebar`, and `sidebarFooter` snippets and bind `open`
for the mobile overlay (or for collapsible mode at all viewports).

For non-shell sidebars (right-side detail panels, drawers inside a page),
keep using the `<Sidebar>` primitive directly.

**Import:** `import { SidebarLayout } from '@urbicon-ui/blocks';`

### Examples
```svelte
<script>
import { SidebarLayout, Button, MenuIcon } from '@urbicon-ui/blocks';
let sidebarOpen = $state(false);
</script>

<SidebarLayout bind:open={sidebarOpen} sidebarWidth="16rem">
{#snippet sidebarHeader()}
<a href="/" class="font-semibold">My App</a>
{/snippet}

{#snippet sidebar()}
<nav class="flex flex-col gap-1 p-3">
<a href="/dashboard">Dashboard</a>
<a href="/settings">Settings</a>
</nav>
{/snippet}

{#snippet mobileHeader({ openSidebar })}
<Button variant="ghost" size="sm" onclick={openSidebar} aria-label="Open menu">
<MenuIcon />
</Button>
<span class="font-semibold">My App</span>
{/snippet}

<h1>Page content</h1>
</SidebarLayout>
```

```svelte
<SidebarLayout bind:open={sidebarOpen} mode="collapsible" sidebarWidth="16rem">
{#snippet sidebarHeader()}<span class="font-semibold">App</span>{/snippet}
{#snippet sidebar()}<nav class="p-3"><!-- … --></nav>{/snippet}

<Button onclick={() => (sidebarOpen = !sidebarOpen)}>Toggle</Button>
<!-- main content -->
</SidebarLayout>
```

### Variants
- contentMaxWidth: 2xl, lg, md, none, sm, xl (default: xl)
- side: left, right (default: left)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| children | `Snippet` | no |  | Page content rendered inside the centered main column. |
| class | `string` | no |  | Additional CSS classes applied to the root wrapper. |
| closeOnBackdropClick | `boolean` | no | true | Close the mobile sidebar overlay when clicking the backdrop. |
| closeOnEscape | `boolean` | no | true | Close the mobile sidebar overlay when pressing Escape. |
| contentMaxWidth | `SidebarLayoutVariants['contentMaxWidth']` | no | 'xl' | Maximum width of the centered content column. |
| mobileHeader | `Snippet<[MobileHeaderContext]>` | no |  | Mobile header bar, hidden on desktop in `responsive` mode. Receives a helper to open the sidebar so a hamburger button needs no extra wiring. If omitted, no mobile header is rendered. |
| mode | `'responsive' | 'collapsible'` | no | 'responsive' | Sidebar mode. - `responsive` (default): permanent on desktop (≥1024px), slide-in overlay on mobile. - `collapsible`: toggleable at all viewports — width animation on desktop, overlay on mobile. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the sidebar open state changes. |
| open | `boolean` | no | false | Sidebar visibility. In `responsive` mode this only affects the mobile overlay. In `collapsible` mode it controls visibility at all viewports. Supports `bind:open`. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ SidebarLayout: {...} }}>`. Use this to share a branded shell look across the app instead of repeating class overrides. |
| side | `SidebarLayoutVariants['side']` | no | 'left' | Which edge the sidebar attaches to. |
| sidebar | `Snippet` | no |  | Sidebar main content — typically a `<nav>`. |
| sidebarFooter | `Snippet` | no |  | Sidebar footer (below the scrollable nav). |
| sidebarHeader | `Snippet` | no |  | Sidebar header (above the scrollable nav). |
| sidebarWidth | `string` | no | '16rem' | Sidebar panel width. Single source of truth — the layout exposes it as `--sidebar-width` (constant) and `--sidebar-effective-width` (animates to `0` when collapsed) on the layout root, so the main content offset stays in sync automatically. |
| slotClasses | `Partial<Record<SidebarLayoutSlot, string>>` | no |  | Per-slot class overrides. `sidebar*` slots are forwarded to the embedded `<Sidebar>` component (mapped to its `slotClasses.panel`/`header`/...). |
| unstyled | `boolean` | no |  | Strip all default styles. Combine with `slotClasses` for a custom layout. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Skeleton
Placeholder loading animation that mimics content layout.
Use to reduce perceived loading time and prevent layout shift.

**Import:** `import { Skeleton } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Skeleton variant="text" size="lg" />
<Skeleton variant="circular" size="md" />
<Skeleton variant="rectangular" width="100%" height="200px" />
```

```svelte
<div class="flex items-center gap-3">
  <Skeleton variant="circular" size="md" />
  <div class="flex flex-col gap-2 flex-1">
    <Skeleton variant="text" size="sm" />
    <Skeleton variant="text" size="xs" class="w-2/3" />
  </div>
</div>
```

### Variants
- variant: circular, rectangular, rounded, text (default: text)
- size: lg, md, sm, xl, xs (default: md)
- animation: none, pulse, wave (default: pulse)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...ElementAttributes | `HTMLAttributes` | no |  | All standard HTML element attributes |
| ...SkeletonVariants | `VariantProps` | no |  | Styling variants from SkeletonVariants |
| animation | `SkeletonVariants['animation']` | no |  | Animation style. `pulse` fades opacity, `wave` sweeps a shimmer gradient, `none` renders a static placeholder. All animations respect `prefers-reduced-motion`. |
| class | `string` | no |  | Extra classes merged onto the root element (or wrapper when `count > 1`). |
| count | `number` | no |  | Number of skeleton lines to render. Wraps items in a flex-column container when > 1. |
| gap | `string` | no |  | Tailwind gap class between repeated lines (e.g. `"gap-2"`, `"gap-4"`). Only applies when `count > 1`. |
| height | `string` | no |  | Custom height (CSS value, e.g. `"48px"`). Overrides the size preset height. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Skeleton: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `SkeletonVariants['size']` | no |  | Physical dimensions following the Standard size scale (xs–xl). Dimensions vary per variant — text heights range from h-3 (xs) to h-6 (xl), circular from 24 px to 64 px. |
| slotClasses | `Partial<Record<SkeletonSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) tv() output. Slots: base | wrapper |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `slotClasses` for full control. |
| variant | `SkeletonVariants['variant']` | no |  | Shape preset. `text` is a slim bar, `circular` for avatars/icons, `rectangular` for images/cards, `rounded` like rectangular with softer corners. |
| width | `string` | no |  | Custom width (CSS value, e.g. `"200px"` or `"100%"`). Overrides the size preset width. |

Inherited from:
- SkeletonVariants (external)
- HTMLAttributes (html-attributes)

---

## Slider
Slider for selecting a numeric value or range within min/max bounds.
Supports single and range modes, step snapping, tick marks, and labels.

Optional `validRange` and `recommendedRange` paint the track as a three-zone
gradient (red/yellow/green) and show a live status text that is also announced
via an ARIA live region. Both props are optional and additive — a slider
without `validRange`/`recommendedRange` behaves exactly as before.

**Import:** `import { Slider } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Slider label="Volume" bind:value={volume} />
```

```svelte
<Slider label="Price range" range bind:value={priceRange} min={0} max={500} step={10} showValue />
```

```svelte
<Slider
  label="Consumption share of heating costs"
  bind:value={share}
  min={0}
  max={100}
  step={5}
  validRange={[50, 100]}
  recommendedRange={[60, 80]}
  formatValue={(v) => `${v} %`}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- size: lg, md, sm (default: md)
- appearance: default, rail (default: default)
- disabled: true (default: false)
- messageType: error, helper (default: helper)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children' | 'class') |
| ...SliderVariants | `VariantProps` | no |  | Styling variants from SliderVariants |
| class | `string` | no |  | Extra classes merged onto the root wrapper. |
| disabled | `boolean` | no | false | Whether the Slider is disabled and non-interactive |
| error | `string` | no |  | Error message below the slider. Overrides `helper`. |
| formatValue | `(value: number | [number, number]) => string` | no |  | Format function for the displayed value. |
| helper | `string` | no |  | Helper text below the slider. Hidden when `error` is set. |
| label | `string` | no |  | Text label displayed above the slider. |
| marks | `SliderMark[]` | no |  | Tick marks along the track. |
| max | `number` | no | 100 | Maximum allowed value. |
| min | `number` | no | 0 | Minimum allowed value. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset. |
| name | `string` | no |  | Shared `name` for hidden inputs for form submission. |
| onValueChange | `(value: number | [number, number]) => void` | no |  | Fires after the value changes. Receives the new value. |
| outOfValidRangeIntent | `'danger' | 'warning'` | no | 'danger' | Intent applied outside the `validRange`. `'warning'` for softer limits (recommendation, not a violation), `'danger'` for hard limits. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Slider: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| range | `boolean` | no | false | Enable range mode with two thumbs. |
| rangeStatusText | `SliderRangeStatusText` | no |  | Custom status texts for the three zones. Defaults to the UIB i18n localization (`bt('slider.rangeStatus.*')`). |
| recommendedRange | `[number, number]` | no |  | Recommended value range (UX recommendation, softer than `validRange`). Values inside appear green, values outside yellow (warning). Typically `recommendedRange ⊂ validRange`, but this is not enforced. |
| showValue | `boolean` | no | false | Show the current value next to the label. |
| slotClasses | `Partial<Record<SliderSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | header | label | valueText | base (the interactive track container) | track | range | thumb | mark | boundaryTick | rangeStatus | rangeStatusIcon | message. |
| step | `number` | no | 1 | Snap to increments of this value. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| validRange | `[number, number]` | no |  | Valid value range (e.g. a legal limit). Values outside it style track and thumb in the `outOfValidRangeIntent` color (default: `danger`). Status changes are announced via an ARIA live region. If the range lies outside `[min, max]`, a console warning is emitted — the visible `min`/`max` are NOT shifted automatically. |
| value | `number | [number, number]` | no |  | Current value. Number for single, [min, max] tuple for range. Supports `bind:value`. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Slider. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Slider. Affects the component's physical footprint. Available options: lg, md, sm. |
| appearance | `'default' | 'rail'` | no | default | Controls the appearance behavior and appearance of the Slider component. Available options: default, rail. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Slider component. Available options: error, helper. |

Inherited from:
- Omit<SliderVariants, 'error' | 'rangeStatus'> (omit-pattern)
- Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> (omit-pattern)

---

## Sparkline
Tiny inline trend line — no axes, no labels — sized to flow in
table cells, cards, or running text. Zero-dependency SVG, optional area fill
and end-point dot. Aria-hidden by default with an optional `ariaLabel`.

**Import:** `import { Sparkline } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Sparkline data={[3, 5, 4, 8, 6, 9]} area />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| data | `number[]` | yes |  | Sequence of values plotted left → right. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| area | `boolean` | no | false | Fill the area under the line. |
| ariaLabel | `string` | no |  | Accessible label; when omitted the sparkline is aria-hidden. |
| class | `string` | no |  | Extra classes merged onto the wrapper. |
| color | `string` | no | var(--color-chart-1) | Color property for the Sparkline component |
| height | `number` | no | 24 | Height property for the Sparkline component |
| showEndPoint | `boolean` | no | false | Mark the last point with a dot. |
| slotClasses | `SparklineSlotClasses` | no |  | Per-slot class overrides. |
| strokeWidth | `number` | no | 1.5 | StrokeWidth property for the Sparkline component |
| unstyled | `boolean` | no |  | Remove all default classes. |
| width | `number` | no | 96 | Width property for the Sparkline component |

Inherited from:
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

---

## Spinner
Animated loading indicator with multiple animation styles and semantic intents.

**Import:** `import { Spinner } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Spinner size="md" intent="primary" />
```

```svelte
<Spinner variant="bars" speed="fast" intent="success" />
```

### Variants
- intent: current, danger, neutral, primary, secondary, success, warning (default: primary)
- variant: bars, default, dots, pulse, ring (default: default)
- size: lg, md, sm, xl, xs (default: md)
- speed: fast, normal, slow (default: normal)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...SpinnerVariants | `VariantProps` | no |  | Styling variants from SpinnerVariants |
| children | `Snippet` | no |  | Optional content rendered beside the spinner (e.g. loading text). |
| class | `string` | no |  | Extra classes merged onto the root element. |
| intent | `SpinnerVariants['intent']` | no |  | Semantic color applied via `text-*` token. |
| label | `string` | no |  | Accessible label announced by screen readers. Defaults to "Loading...". |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Spinner: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `SpinnerVariants['size']` | no |  | Physical dimensions from `xs` (16 px) to `xl` (40 px). |
| slotClasses | `Partial<Record<SpinnerSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) tv() output. Slots: base | svg | svgCircle | svgPath | dots | dot | pulse | pulseCenter | pulseRing | ring | ringElement | bars | bar | content | srOnly |
| speed | `SpinnerVariants['speed']` | no |  | Animation speed — controls `--spinner-speed` custom property. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `slotClasses` for full control. |
| variant | `SpinnerVariants['variant']` | no |  | Animation style. `default` is an SVG arc, `dots` bounces three dots, `pulse` radiates a sonar ping, `ring` spins cascading borders, `bars` animates vertical equalizer bars. |
| visible | `boolean` | no |  | When false the spinner is removed from the DOM. |

Inherited from:
- SpinnerVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Stepper
Multi-step progress indicator with horizontal/vertical layout,
clickable navigation, and per-step state overrides (error, warning).

**Import:** `import { Stepper } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Stepper activeStep={1}>
  <StepperStep label="Account" description="Create your account" />
  <StepperStep label="Profile" description="Set up your profile" />
  <StepperStep label="Review" description="Review and submit" />
</Stepper>
```

```svelte
<Stepper activeStep={0} orientation="vertical" clickable>
  <StepperStep label="Details" description="Enter your information">
    <p>Form content here...</p>
  </StepperStep>
  <StepperStep label="Confirm" description="Verify and submit" />
</Stepper>
```

### Variants
- variant: default, minimal, outlined (default: default)
- size: lg, md, sm (default: md)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: commit)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | StepperStep children. |
| ...HTMLAttributes<HTMLOListElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...StepperVariants | `VariantProps` | no |  | Styling variants from StepperVariants |
| activeStep | `number` | no | 0 | Current active step index (0-based). Supports bind:activeStep. |
| class | `string` | no |  | Extra classes merged onto the root element. |
| clickable | `boolean` | no | false | Allow clicking step indicators to navigate between steps. |
| disabled | `boolean` | no | false | Disable all steps and prevent navigation. |
| linear | `boolean` | no | false | Restrict navigation to sequential order — only completed steps and the next step are clickable. |
| onStepChange | `(step: number) => void` | no |  | Fires when a step is activated via click. Passes the new step index. |
| orientation | `'horizontal' | 'vertical'` | no | 'horizontal' | Orientation property for the Stepper component |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Stepper: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| responsive | `boolean | { breakpoint?: number }` | no | false | Container-responsive mode: when the Stepper's container is narrower than `breakpoint`, automatically switch to `orientation="vertical"` and `variant="minimal"` so the steps stay readable.  - `false` (default): never auto-switch. - `true`: switch below 640 px container width. - `{ breakpoint: 480 }`: switch below 480 px.  Uses `ResizeObserver` on the root element — works inside Drawers, Cards, or split layouts where viewport-based media queries miss the actual available width. |
| size | `'sm' | 'md' | 'lg'` | no | 'md' | Size variant that controls dimensions and spacing of the Stepper |
| slotClasses | `Partial<Record<StepperSlots, string>>` | no |  | Per-slot class overrides. Slots: base | stepItem | step | indicatorColumn | indicator | labelGroup | label | description | separator | content |
| tier | `InteractiveTier` | no | 'commit' | Semantic radius tier propagated to every StepperStep. Default `commit` — step indicators read as identity circles. Set to `modify` (or inherit via TierContext from a wrapping `<Toolbar tier="modify">`) to render a compact soft-rectangle stepper for inline wizards. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. |
| variant | `'default' | 'outlined' | 'minimal'` | no | 'default' | Visual style of step indicators. |

Inherited from:
- Omit<StepperVariants, 'stepState' | 'clickable' | 'stepDisabled' | 'separatorComplete'> (omit-pattern)
- Omit<HTMLAttributes<HTMLOListElement>, 'children'> (omit-pattern)

---

## Tab
Tab container that manages tab switching and content display.
Supports horizontal/vertical orientation, visual variants, and keyboard navigation.

**Import:** `import { Tab } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Tab
  tabs={[
    { value: 'overview', label: 'Overview' },
    { value: 'settings', label: 'Settings' },
    { value: 'billing', label: 'Billing' }
  ]}
  bind:value={activeTab}
>
  {#snippet panels()}
    {#if activeTab === 'overview'}<p>Overview content</p>{/if}
    {#if activeTab === 'settings'}<p>Settings content</p>{/if}
    {#if activeTab === 'billing'}<p>Billing content</p>{/if}
  {/snippet}
</Tab>
```

```svelte
<Tab
  tabs={[
    { value: 'code', label: 'Code' },
    { value: 'preview', label: 'Preview' }
  ]}
  variant="underline"
  size="sm"
  defaultValue="code"
>
  {#snippet panels()}
    <div>Tab panel content</div>
  {/snippet}
</Tab>
```

### Variants
- variant: enclosed, line, pills, solid (default: line)
- size: lg, md, sm (default: md)
- fullWidth: true (default: false)
- orientation: horizontal, vertical (default: horizontal)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Additional CSS class merged onto the root element. |
| defaultValue | `string` | no |  | Default active tab for uncontrolled mode. Ignored when `value` is set. |
| disabled | `boolean` | no | false | Disables all tabs, preventing interaction and dimming the UI. |
| fullWidth | `boolean` | no | false | Stretch triggers to fill the available width. Only meaningful on horizontal tabs. |
| mint | `MintProp` | no | 'none' | Micro-interaction animation applied to each tab trigger (per-item, not the container). |
| onValueChange | `(value: string) => void` | no |  | Fires when the active tab changes. Receives the new tab value string. |
| orientation | `'horizontal' | 'vertical'` | no | 'horizontal' | Tab strip axis. Determines whether triggers stack horizontally or vertically. |
| panels | `Snippet` | no |  | Snippet containing TabPanel components for the content area. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Tab: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<TabSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing when unstyled) tv() styles. Slots: base | list | trigger | icon | label | badge | panel | indicator |
| tabs | `Snippet` | no |  | Snippet containing TabItem components for the tab strip. |
| tier | `InteractiveTier` | no | 'modify' | Semantic radius tier propagated to every TabItem. Default `modify` — tabs read as navigation tap surfaces. Set to `commit` (or inherit via TierContext from a wrapping `<Toolbar tier="commit">`) for full-pill tab strips in marketing/product-overview contexts. Only the `pills`, `solid`, and `enclosed` variants render a visible corner; `line` is radius-agnostic. |
| unstyled | `boolean` | no |  | Strip all default tv() styles from the container and children. |
| value | `string` | no |  | Controlled active tab value. Use with `bind:value` for two-way binding. When set, the component is controlled — you must handle `onValueChange` to update it. |
| variant | `'enclosed' | 'line' | 'pills' | 'solid'` | no | line | Controls the visual style and presentation of the Tab. Determines the component's visual treatment. Available options: enclosed, line, pills, solid. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Tab. Affects the component's physical footprint. Available options: lg, md, sm. |

---

## Table
Advanced data table component with smart filtering, column factories, responsive design,
and extensible features for complex data visualization. Supports row selection, keyboard navigation,
virtual scrolling, column reorder, server-side data, live updates, and custom cell components.

**Import:** `import { Table } from '@urbicon-ui/table';`

### Examples
```svelte
<Table
items={data}
columns={columns}
itemsPerPage={25}
enableSmartFilter={true}
/>
```

```svelte
{#snippet statusCell(item, value)}
<Badge intent={value === 'active' ? 'success' : 'danger'}>{value}</Badge>
{/snippet}

<Table items={data} columns={[
{ accessor: 'name', title: 'Name', sortable: true },
{ accessor: 'status', title: 'Status', cell: statusCell }
]} />
```

```svelte
<Table
items={data}
columns={columns}
selectionMode="multi"
onSelectionChange={(selected) => console.log(selected)}
/>
```

```svelte
<Table
mode="server"
columns={columns}
queryFn={async (query, { signal }) => {
const res = await fetch(`/api/users?page=${query.page}`, { signal });
return await res.json();
}}
/>
```

```svelte
<Table items={tenThousandRows} columns={columns} virtualized virtualHeight="500px" />
```

```svelte
<Table {items} {columns} persistenceConfig={{ tableId: 'expenses' }} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| appearance | `'flush' | 'surface' | 'framed'` | no | "flush" | Visual appearance of the table chrome (see docs/MIGRATION-v5.md §3): - `flush` (default): no outer frame, sits inline in the reading flow - `surface`: gentle `surface-quiet` tinted zone, no border - `framed`: bordered + rounded + shadowed standalone block |
| ariaLabel | `string` | no | undefined | Accessible label for the table, announced by screen readers. |
| autoApplyOnNavigation | `boolean` | no | true | Automatically apply pending live updates when the user navigates (page change, sort, filter, search). Since the view is already changing, applying buffered changes at this point is non-disruptive. |
| body | `Snippet` | no | undefined | Body property for the Table component |
| cell | `Snippet<[item: T, value: unknown, column: Column<T>]>` | no | undefined | Global cell snippet that overrides rendering for ALL columns. For per-column customization, prefer `column.cell` instead. |
| class | `string` | no | undefined | Additional CSS class names for the table container |
| columns | `Column<T>[]` | no | [] | Column configuration array defining the table structure |
| empty | `Snippet` | no | undefined | Custom empty state snippet |
| enableColumnReorder | `boolean` | no | false | Enable drag-and-drop column reordering on desktop. Users can drag column headers to rearrange them. Also supports keyboard reorder via Shift+ArrowLeft/Right on focused headers. |
| enableLiveUpdates | `boolean` | no | false | Enable live update support. When enabled, a `LiveUpdateBanner` is shown when pending inserts/updates/deletes are buffered. Use `getTableContext()` to access `pushInsert`, `pushUpdate`, `pushDelete` from WebSocket/SSE handlers. |
| enableSmartFilter | `boolean` | no | true | Enable smart filtering functionality |
| error | `Snippet` | no | undefined | Custom error state snippet |
| errorText | `string` | no | "Error loading data" | Text displayed on error |
| expandedRowContent | `Snippet<[item: T]>` | no | undefined | Snippet to render expanded row content |
| fit | `'content' | 'viewport'` | no | "content" | Make the table its own scroll container so wide **and** long lists scroll *within* the table instead of pushing overflow onto the page.  - `'content'` (default): the table grows with its content; vertical overflow   scrolls the page. Pair with `sticky` for page-relative pinning. - `'viewport'`: the table is height-capped to the viewport and becomes a   self-contained scroll box. The column header (and group header when   grouping) pin to the top of the box, while the toolbar and pagination stay   fixed outside the scrolling area — only the rows scroll, in both axes. The   available height is measured automatically (the container's distance from   the top of the viewport), so no magic `max-height` is needed in the   consumer, and it adapts to whatever sits above the table (tabs, banners).  Notes for `'viewport'`: - Desktop only (`md`+); mobile keeps normal document-level scroll. - Supersedes `sticky`: header/group pinning is intrinsic to the box, so the   `sticky` prop is ignored. `stickyOffset` is ignored too — the measured top   absorbs app-shell offsets automatically. - Mutually exclusive with `virtualized`, which manages its own bounded   scroll via `virtualHeight`; `fit` has no effect when `virtualized`. |
| groupHeaderContent | `Snippet<[groupName: string, items: T[], isExpanded: boolean]>` | no | null | Custom content for group headers |
| groupOrder | `string[]` | no | [] | Custom order for group display |
| header | `Snippet` | no | undefined | Custom header snippet |
| initialGroupBy | `string | null` | no | null | Initial grouping key (if no persisted value exists). When grouping is active, pagination is disabled — all grouped items are shown at once. |
| initialPage | `number` | no | 1 | InitialPage property for the Table component |
| initialSummaryConfigs | `SummaryConfig[]` | no | [] | Initial summary configurations (if no persisted value exists). Each entry defines a column + aggregation type (sum, avg, count, min, max). |
| items | `T[]` | no | [] | Array of data items to display in the table. Items with an `id` property get better key stability for animations. If no `id` is present, the array index is used as fallback key. |
| itemsPerPage | `number` | no | 10 | Number of items to display per page |
| loading | `Snippet` | no | undefined | Custom loading state snippet |
| loadingText | `string` | no | "Loading data..." | Text displayed during loading state |
| mode | `'client' | 'server'` | no | "client" | Data processing mode. - `'client'` (default): Filtering, sorting, and pagination are done locally. - `'server'`: The table delegates all data operations to the server. Items passed via   `items` prop (or returned by `queryFn`) are displayed as-is. |
| multiExpand | `boolean` | no | false | Allow multiple rows to be expanded simultaneously. When false (default), expanding a row collapses the previously expanded one. |
| noDataText | `string` | no | "No data found." | Text displayed when no data is available |
| onQueryChange | `(query: TableQuery) => void` | no | undefined | Callback fired when the table query changes in `mode: 'server'`. Use this for manual control — fetch data yourself and update `items`, `serverTotalItems`, `loading`, and `error` props accordingly. Fires after debounce (controlled by `queryDebounceMs`). |
| onRowClick | `(item: T) => void` | no | undefined | Callback fired when a row is clicked. Receives the clicked row's data item. |
| onSelectionChange | `(selectedItems: T[]) => void` | no | undefined | Callback fired when the selection changes. Receives the array of currently selected items. |
| pagination | `Snippet` | no | undefined | Custom pagination snippet |
| persistenceConfig | `TablePersistenceConfig` | no | undefined | Persist table view state across reloads. Pass `{ tableId: 'foo' }` to opt in — every axis (filters, search, group, summary, sort, column visibility, column order) is persisted by default into `localStorage` under keys scoped to `tableId`. Set individual `persist*` flags to `false` to keep an axis volatile.  Pagination (current page) is intentionally never persisted — page 1 on navigation is standard UX. |
| queryDebounceMs | `number` | no | 300 | Debounce delay in milliseconds for server query changes. Prevents excessive requests during rapid filter/search input. |
| queryFn | `(query: TableQuery, options: { signal: AbortSignal }) => Promise<TableQueryResult>` | no |  | Async function for managed server-side fetching. When provided in `mode: 'server'`, the table calls this function automatically when the query changes (debounced). The table manages loading/error states and request cancellation via `AbortSignal`. |
| searchDebounceMs | `number` | no | 300 | Debounce delay for search in milliseconds |
| searchPlaceholder | `string` | no | "Search..." | Placeholder text for search input |
| selectedIds | `Array<string | number>` | no | undefined | Controlled selected row IDs. When provided, the component reflects this value instead of managing selection internally. |
| selectionMode | `'none' | 'single' | 'multi'` | no | "none" | Row selection mode. - `'none'`: No selection (default) - `'single'`: Only one row can be selected at a time - `'multi'`: Multiple rows can be selected with checkboxes |
| serverTotalItems | `number` | no | 0 | Total number of items on the server. Required when `mode` is `'server'` and manual control is used (without `queryFn`). Drives pagination calculation. |
| size | `'sm' | 'md' | 'lg'` | no | "md" | Size variant for the table |
| slotClasses | `Partial<TableSlotClasses>` | no | {} | Per-slot class overrides merged with (or replacing, if `unstyled`) variant styles. Available slots: `container`, `toolbar`, `scrollArea`, `table`, `thead`, `tbody`, `headerRow`, `headerCell`, `row`, `cell`, `groupHeader`, `summaryRow`, `emptyState`, `loadingState`, `errorState`, `filterBar`, `mobileCard`.  **Breaking change in v1.5:** the former `wrapper` slot has been replaced by `scrollArea`. The former hardcoded `overflow-hidden` on `wrapper` blocked `position: sticky`, see [docs/STICKY-PINNING.md](../../../../../docs/STICKY-PINNING.md). |
| sticky | `boolean | 'toolbar' | 'header' | 'both'` | no | false | Pin toolbar/header/group-header to the top of the scroll ancestor on scroll. - `false` (default): no pinning, layout matches v1.4.x - `true` / `'both'`: toolbar + thead + group-header all pin - `'toolbar'`: only the toolbar pins - `'header'`: only the thead (and group-header when grouping is active) pins  Pair with `stickyOffset` for app shells that have a fixed top bar.  For tables wider than the viewport, prefer `fit="viewport"` — it contains horizontal scroll inside the table instead of falling back to page-level horizontal scroll (a sticky pin host cannot also be a horizontal scroll ancestor). `fit="viewport"` supersedes `sticky` when set. |
| stickyOffset | `number` | no | 0 | Pixel offset for the topmost sticky layer (toolbar, or thead when no toolbar). Writes the CSS custom property `--blocks-table-sticky-top` on the container. Use this to push the pin below a fixed app shell top bar. |
| toolbar | `Snippet` | no | undefined (renders default SmartFilterBar when enableSmartFilter) | Custom toolbar snippet. Replaces the default `SmartFilterBar`. Renders inside the sticky toolbar wrapper when `sticky` is enabled — so a custom toolbar inherits the pinning behavior without extra wiring.  Access the table context via `getTableContext()` to wire up custom filter UIs. |
| unstyled | `boolean` | no | false | Remove default tailwind-variants classes. Only user-provided `slotClasses` apply. |
| virtualHeight | `string` | no | "600px" | Height of the virtual scroll container. Only used when `virtualized` is true. Accepts any CSS height value. |
| virtualized | `boolean` | no | false | Enable virtualization for large datasets. When enabled, only visible rows are rendered for performance with >1000 items. Pagination is bypassed — all filtered/sorted items are virtualized in a scrollable container. Not compatible with grouping (grouping takes precedence). |

---

## TableOfContents
TableOfContents component

**Import:** `import { TableOfContents } from '@urbicon-ui/docs';`

### Examples
```svelte
<TableOfContents
  navigation={[
    { id: 'usage', title: 'Usage' },
    { id: 'api', title: 'API', children: [{ id: 'props', title: 'Props' }] }
  ]}
/>
```

### Variants
- position: left, right (default: right)
- width: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| navigation | `Array<{
    id: string;
    title: string;
    order?: number;
    href?: string;
    children?: Array<{ id: string; title: string; order?: number; href?: string }>;
  }>` | yes |  | Navigation items with optional nested children. |
| ...TableOfContentsVariantProps | `VariantProps` | no |  | Styling variants from TableOfContentsVariantProps |
| class | `string` | no |  | Extra classes merged onto the root aside element. |
| related | `RelatedLink[]` | no |  | Optional Editorial `// RELATED` block rendered below the main nav. Each entry needs a pre-resolved `href` (the TOC does not call `resolve()`, mirroring the existing nav behaviour). When omitted, the related block does not render at all. |
| showCodeToggle | `boolean` | no | true | Render the Editorial `// CODE` block at the bottom of the TOC, hosting the global show-/hide-all-code toggle. Requires a host page that provided a `CodeVisibilityStore` via context — the block silently skips itself if no store is found, so callers outside of `DocsLayout` don't have to know about it. |
| slotClasses | `Partial<Record<'aside' | 'title' | 'nav' | 'relatedTitle' | 'relatedNav' | 'relatedLink' | 'codeTitle' | 'codeToggle', string>>` | no |  | Per-slot class overrides. |
| title | `string` | no |  | Heading rendered above the nav links. |
| trackScroll | `boolean` | no |  | Enable scroll-based active section tracking. |
| unstyled | `boolean` | no |  | Remove all default tv styles. |
| position | `'left' | 'right'` | no | right | Controls the position behavior and appearance of the TableOfContents component. Available options: left, right. |
| width | `'lg' | 'md' | 'sm'` | no | md | Controls the width behavior and appearance of the TableOfContents component. Available options: lg, md, sm. |

Inherited from:
- TableOfContentsVariantProps (external)

### Slots (slotClasses keys)
`aside`, `title`, `nav`, `relatedTitle`, `relatedNav`, `relatedLink`, `codeTitle`, `codeToggle`

---

## Textarea
Multi-line text input with auto-resize, character counter, and validation states.
Shares the same variant/intent/size system as Input for visual consistency.

**Import:** `import { Textarea } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Textarea label="Description" placeholder="Tell us more..." bind:value={text} />
```

```svelte
<Textarea label="Bio" maxlength={280} showCounter autoResize />
```

### Variants
- intent: danger, default, success, warning (default: default)
- size: lg, md, sm (default: md)
- autoResize: true (default: false)
- disabled: true (default: false)
- messageType: error, helper (default: helper)
- readonly: true (default: false)
- required: true (default: false)
- tier: commit, modify (default: modify)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLTextareaAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'size' | 'class' | 'children') |
| ...TextareaVariants | `VariantProps` | no |  | Styling variants from TextareaVariants |
| autoResize | `boolean` | no | false | Automatically grow the textarea height to fit content. Disables manual resize handle. |
| class | `string` | no |  | Extra classes merged onto the root wrapper element. |
| counterWarningThreshold | `number` | no | 0.9 | Character threshold (percentage of maxlength) at which the counter turns warning color. |
| disabled | `boolean` | no | false | Whether the Textarea is disabled and non-interactive |
| error | `string` | no |  | Error message below the textarea. Overrides `helper` and forces danger border styling. |
| helper | `string` | no |  | Helper text below the textarea. Hidden when `error` is set. |
| label | `string` | no |  | Label text displayed above the textarea, auto-linked via `for`/`id`. |
| maxRows | `number` | no |  | Maximum number of visible text rows when autoResize is enabled. |
| minRows | `number` | no | 3 | Minimum number of visible text rows. |
| mint | `MintProp` | no | 'none' | Micro-interaction preset applied to the textarea element. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Textarea: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| readonly | `boolean` | no | false | Readonly property for the Textarea component |
| required | `boolean` | no | false | Adds a required asterisk to the label and sets the native `required` attribute. |
| showCounter | `boolean` | no |  | Show a live character counter. Requires `maxlength` to display remaining count. |
| slotClasses | `Partial<Record<TextareaSlots, string>>` | no |  | Per-slot class overrides merged with tv() styles. Slots: wrapper (root — what `class` also targets) | base (the `<textarea>` element) | label | footer | message | counter. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Only user-provided classes apply. |
| variant | `TextareaVariants['variant']` | no | 'outlined' | Visual style. - `outlined` (default) — visible border, surface-base background - `filled` — surface-interactive fill, no border - `ghost` — transparent until hover/focus - `underline` — bottom-line only, no border-box (editorial style) |
| intent | `'danger' | 'default' | 'success' | 'warning'` | no | default | Controls the color theme and semantic meaning of the Textarea. Affects the overall appearance and user perception. Available options: danger, default, success, warning. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Textarea. Affects the component's physical footprint. Available options: lg, md, sm. |
| messageType | `'error' | 'helper'` | no | helper | Controls the messageType behavior and appearance of the Textarea component. Available options: error, helper. |
| tier | `'commit' | 'modify'` | no | modify | Controls the tier behavior and appearance of the Textarea component. Available options: commit, modify. |

Inherited from:
- Omit<TextareaVariants, 'error' | 'counterState' | 'variant'> (omit-pattern)
- Omit<HTMLTextareaAttributes, 'size' | 'class' | 'children'> (omit-pattern)

---

## ThemeSwitcher
Cycles between light, dark, and system color schemes. Sets a
`light`/`dark` class on the `<html>` element for explicit choices and clears
it in system mode (so the CSS `light-dark()` function follows the OS natively).
Persists the choice to localStorage.

**Import:** `import { ThemeSwitcher } from '@urbicon-ui/blocks';`

### Examples
```svelte
<ThemeSwitcher />
```

```svelte
<ThemeSwitcher size="lg" variant="outlined" strategy="toggle" />
```

### Variants
- variant: filled, ghost, outlined (default: ghost)
- size: lg, md, sm (default: md)
- disabled: true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| class | `string` | no |  | Additional CSS classes. |
| disabled | `boolean` | no |  | Disable the switcher. |
| onThemeChange | `(theme: Theme) => void` | no |  | Called after the theme changes. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ ThemeSwitcher: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| size | `ThemeSwitcherVariants['size']` | no | 'md' | Size variant that controls dimensions and spacing of the ThemeSwitcher |
| slotClasses | `Partial<Record<ThemeSwitcherSlots, string>>` | no |  | Per-slot class overrides. |
| storageKey | `string | false` | no | 'urbicon-theme' | `localStorage` key for persistence. Set to `false` to disable. |
| strategy | `'cycle' | 'toggle'` | no | 'cycle' | Interaction mode. - `'cycle'` — single button cycling light → dark → system (default) - `'toggle'` — single button toggling light ↔ dark (no system option) |
| theme | `Theme` | no | 'system' | Current theme. Supports `bind:theme`. |
| unstyled | `boolean` | no | false | Strip all default styles. |
| variant | `ThemeSwitcherVariants['variant']` | no | 'ghost' | Visual style of the button. |

---

## Toast
Container that renders and manages toast notifications.
Place once in your root layout. Use the toaster store to trigger toasts from anywhere.

**Import:** `import { Toast } from '@urbicon-ui/blocks';`

### Examples
```svelte
<!-- +layout.svelte -->
<Toaster placement="bottom-right" />
```

```svelte
<script>
  import { toaster } from '@urbicon-ui/blocks';

  toaster.success('Saved!', { description: 'Changes applied.' });
  toaster.danger('Error', { description: 'Something went wrong.', duration: 8000 });
</script>
```

### Variants
- intent: danger, info, neutral, primary, success, warning (default: neutral)
- placement: bottom-center, bottom-left, bottom-right, top-center, top-left, top-right (default: bottom-right)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| class | `string` | no |  | Extra classes merged onto the container element. |
| max | `number` | no | 5 | Maximum number of toasts visible at once. Oldest are hidden first. |
| placement | `ToastPlacement` | no | 'bottom-right' | Screen corner where toasts stack. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toaster: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<ToasterSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. |
| unstyled | `boolean` | no |  | Strip all default tv classes. Use with `slotClasses` for a fully custom look. |
| intent | `'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Toast. Affects the overall appearance and user perception. Available options: danger, info, neutral, and 3 more. |

Inherited from:
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Toggle
Accessible switch control for boolean on/off states.
Built on a hidden native input with semantic intents and Mint micro-interactions.

**Import:** `import { Toggle } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Toggle label="Enable notifications" bind:checked />
```

```svelte
<Toggle
  intent="success"
  size="lg"
  withBorder
  onCheckedChange={(val) => console.log('toggled', val)}
/>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- size: lg, md, sm, xs (default: md)
- appearance: default, dot (default: default)
- disabled: true (default: false)
- tier: commit, modify (default: commit)
- withBorder: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| ...HTMLInputAttributes | `HTMLAttributes` | no |  | HTML attributes (excluding: 'type' | 'size' | 'checked' | 'class' | 'children') |
| ...ToggleVariants | `VariantProps` | no |  | Styling variants from ToggleVariants |
| appearance | `ToggleVariants['appearance']` | no | 'default' | Visual style. `default` renders a classic Switch-Pill (track + sliding thumb). `dot` renders a small monochrome circular indicator instead — outline-only when off, filled in the intent colour when on. Use `dot` for dense settings rows, inline-toolbars, or anywhere the Switch-Pill is visually too loud. |
| checked | `boolean` | no |  | Current on/off state. Supports two-way binding via `bind:checked`. |
| class | `string` | no |  | Extra classes merged onto the outermost wrapper element. |
| disabled | `boolean` | no |  | Prevent interaction and dim the control. |
| helper | `string` | no |  | Hint text shown below the control. Useful for explaining side-effects of the toggle. |
| id | `string` | no |  | Explicit `id` to link `<label>` and `<input>`. Auto-generated if omitted. |
| label | `string` | no |  | Text label displayed to the right of the toggle track. |
| mint | `MintProp` | no |  | Micro-interaction preset applied to the control area on hover/click. |
| name | `string` | no |  | The `name` attribute of the underlying `<input>`. Used for form submission. |
| onCheckedChange | `(checked: boolean) => void` | no |  | Fired after the checked state changes. Receives the new `checked` value. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toggle: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| required | `boolean` | no |  | Mark the native input as required for form validation. |
| slotClasses | `Partial<Record<ToggleSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when `unstyled`) the default styles. Slots: wrapper (root — what `class` also targets) | control (the `<label>` wrapping the input) | track | thumb | label | message. |
| tier | `InteractiveTier` | no |  | Semantic radius tier. Default `commit` — a toggle declares status (on/off identity), and reads as a pill. Set to `modify` (usually via a wrapping `<Toolbar tier="modify">` propagating through TierContext) for inline-toolbar contexts where the Pill feels oversized — the track and thumb shrink to a soft-rectangle.  Inherited from TierContext when omitted; falls back to `commit` outside of any tier-aware container. |
| unstyled | `boolean` | no |  | Strip all default tailwind-variants classes. Use with `slotClasses` for a fully custom look. The track exposes `data-state` for conditional styling. |
| value | `string` | no |  | The value submitted when checked. Defaults to `'on'`. |
| withBorder | `boolean` | no |  | Draw a subtle border around the track. Helps distinguish the control on busy backgrounds. |
| intent | `'danger' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | primary | Controls the color theme and semantic meaning of the Toggle. Affects the overall appearance and user perception. Available options: danger, neutral, primary, and 3 more. |
| size | `'lg' | 'md' | 'sm' | 'xs'` | no | md | Controls the dimensions, padding, and text size of the Toggle. Affects the component's physical footprint. Available options: lg, md, sm, xs. |

Inherited from:
- Omit<ToggleVariants, 'checked'> (omit-pattern)
- Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> (omit-pattern)

---

## Toolbar
Container for grouping related controls in a horizontal or vertical bar.
Renders with role="toolbar" and auto-sets aria-orientation.

**Import:** `import { Toolbar } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Toolbar aria-label="Text formatting">
  <Button variant="ghost" size="sm">B</Button>
  <Button variant="ghost" size="sm">I</Button>
  <Separator orientation="vertical" size="sm" />
  <Button variant="ghost" size="sm">Left</Button>
  <Button variant="ghost" size="sm">Center</Button>
</Toolbar>
```

```svelte
<Toolbar aria-label="Actions" orientation="horizontal">
  <ButtonGroup connected size="sm" variant="ghost">
    <Button value="undo">Undo</Button>
    <Button value="redo">Redo</Button>
  </ButtonGroup>
  <Separator orientation="vertical" />
  <Button variant="ghost" size="sm" intent="danger">Delete</Button>
</Toolbar>
```

### Variants
- variant: elevated, ghost, outlined, quiet (default: quiet)
- gap: lg, md, sm, xl, xs (default: sm)
- orientation: horizontal, vertical (default: horizontal)
- padding: lg, md, sm, xl, xs (default: sm)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| aria-label | `string` | yes |  | Accessible label describing the toolbar's purpose (e.g. "Formatting toolbar"). Required. |
| children | `Snippet` | yes |  | Toolbar content — typically Buttons, Toggles, Separators, or ButtonGroups. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...ToolbarVariants | `VariantProps` | no |  | Styling variants from ToolbarVariants |
| class | `string` | no |  | Additional CSS class applied to the root element. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Toolbar: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| slotClasses | `Partial<Record<ToolbarSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing when `unstyled`) the default classes. Slots: base |
| tier | `InteractiveTier` | no | 'modify' | Semantic radius tier propagated to tier-aware children (Buttons, Badges, Inputs, …). The Toolbar's own surface stays `r-structure` regardless of this prop.  Default `modify` — toolbars typically hold compact, icon-only actions where pill-shaped buttons read as tags. Set to `commit` for marketing or hero toolbars with full CTAs. |
| unstyled | `boolean` | no |  | Remove all default tv() classes. Combine with `slotClasses` to restyle from scratch. |
| variant | `'elevated' | 'ghost' | 'outlined' | 'quiet'` | no | quiet | Controls the visual style and presentation of the Toolbar. Determines the component's visual treatment. Available options: elevated, ghost, outlined, quiet. |
| gap | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | sm | Controls the gap behavior and appearance of the Toolbar component. Available options: lg, md, sm, and 2 more. |
| orientation | `'horizontal' | 'vertical'` | no | horizontal | Controls the orientation behavior and appearance of the Toolbar component. Available options: horizontal, vertical. |
| padding | `'lg' | 'md' | 'sm' | 'xl' | 'xs'` | no | sm | Controls the padding behavior and appearance of the Toolbar component. Available options: lg, md, sm, and 2 more. |

Inherited from:
- ToolbarVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## Tooltip
Contextual overlay that displays brief, supplementary text on hover or focus.
Built with Floating UI for precise positioning and accessibility support.

**Import:** `import { Tooltip } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Tooltip label="Save your changes">
  <Button>Save</Button>
</Tooltip>
```

```svelte
<Tooltip label="Copy to clipboard" placement="right" arrow showDelay={100}>
  <Button variant="ghost" size="sm" onclick={handleCopy}>Copy</Button>
</Tooltip>
```

### Variants
- intent: danger, info, neutral, primary, secondary, success, warning (default: neutral)
- size: lg, md, sm (default: md)
- visible: false, true (default: false)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | The trigger element(s) that activate the tooltip. |
| label | `string` | yes |  | Text displayed inside the tooltip bubble. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...TooltipVariants | `VariantProps` | no |  | Styling variants from TooltipVariants |
| arrow | `boolean` | no | true | Whether to show a directional arrow pointing at the trigger. |
| class | `string` | no |  | Additional CSS class for the tooltip panel. |
| disabled | `boolean` | no | false | Prevent the tooltip from appearing regardless of hover/focus. |
| hideDelay | `number` | no | 100 | Milliseconds before the tooltip disappears after leaving the trigger. |
| onVisibleChange | `(visible: boolean) => void` | no |  | Fires when tooltip visibility changes (hover in/out, Escape key). |
| placement | `Placement` | no | 'top' | Where the tooltip appears relative to the trigger. Auto-flips when clipped. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Tooltip: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| showDelay | `number` | no | 200 | Milliseconds before the tooltip appears after hover/focus. Prevents accidental activation. |
| slotClasses | `Partial<Record<TooltipSlots, string>>` | no |  | Per-slot class overrides merged with (or replacing, when unstyled) tv styles. |
| unstyled | `boolean` | no |  | Remove default tv classes; only consumer classes apply. |
| intent | `'danger' | 'info' | 'neutral' | 'primary' | 'secondary' | 'success' | 'warning'` | no | neutral | Controls the color theme and semantic meaning of the Tooltip. Affects the overall appearance and user perception. Available options: danger, info, neutral, and 4 more. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Tooltip. Affects the component's physical footprint. Available options: lg, md, sm. |
| visible | `'false' | 'true'` | no | false | Controls the visible behavior and appearance of the Tooltip component. Available options: false, true. |

Inherited from:
- TooltipVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

---

## TwoFactorManager
Self-service two-factor (TOTP) management: enrol with an
authenticator app, show one-time backup codes, and disable with a password
re-auth. Talks to `basePath` (default `/api/auth/account/2fa`); pair with the
server handlers `createTwoFactorSetupHandler`, `createTwoFactorEnableHandler`
and `createTwoFactorDisableHandler`. The core stays zero-dependency, so QR
rendering is delegated to the `qr` snippet — without it the otpauth URI +
Base32 secret are shown for manual entry.

**Import:** `import { TwoFactorManager } from '@urbicon-ui/auth';`

### Examples
```svelte
<TwoFactorManager {user} onEnabled={() => auth.checkStatus()}>
  {#snippet qr({ uri })}
    <MyQrCode value={uri} />
  {/snippet}
</TwoFactorManager>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| user | `AuthUser | null` | yes |  | The current authenticated user — its `totpEnabled` seeds the initial state and its `email` labels the otpauth entry. While `null` the panel renders nothing. Resolve `user` before mount, or remount with `{#key user?.id}…{/key}` to re-seed after an async load. |
| basePath | `string` | no | '/api/auth/account/2fa' | API base path for the 2FA account endpoints. |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. |
| onDisabled | `() => void` | no |  | Called after 2FA was disabled. |
| onEnabled | `() => void` | no |  | Called after 2FA was successfully enabled (e.g. refresh your auth store). |
| qr | `Snippet<[{ uri: string; secret: string }]>` | no |  | QR-code renderer for the otpauth URI shown during setup. Receives the `otpauth://` `uri` and the Base32 `secret`. Optional — the package ships no QR encoder (zero-dep), so without this snippet only the URI + secret are shown for manual entry. |
| slotClasses | `Partial<Record<'root' | 'title' | 'section' | 'sectionTitle' | 'field' | 'submit' | 'code' | 'backupCode', string>>` | no |  | Per-slot class overrides. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

### Slots (slotClasses keys)
`root`, `title`, `section`, `sectionTitle`, `field`, `submit`, `code`, `backupCode`

---

## TypesReference
Displays expandable type definitions extracted from component source,
with inline code blocks, literal value badges, and cross-links to the API Reference.

**Import:** `import { TypesReference } from '@urbicon-ui/docs';`

### Examples
```svelte
<TypesReference
  types={componentData.types}
  title="Type Definitions"
  description="Local types used by this component."
/>
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| types | `LocalTypeDef[]` | yes |  | Array of type definitions to display. |
| ...HTMLAttributes<HTMLElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...TypesReferenceVariantProps | `VariantProps` | no |  | Styling variants from TypesReferenceVariantProps |
| class | `string` | no |  | Extra CSS classes merged onto the root section element. |
| description | `string` | no |  | Descriptive text below the title. |
| emptyState | `Snippet` | no |  | Optional snippet rendered below the table when no types match the filter. |
| size | `'sm' | 'md' | 'lg'` | no |  | Controls the density – text size, padding, badge size. |
| slotClasses | `Partial<Record<'root' | 'header' | 'title' | 'description' | 'card' | 'toolbar' | 'codeBlock' | 'literalValues' | 'literalBadge' | 'usedBySection' | 'usedByLink', string>>` | no |  | Per-slot class overrides for internal elements. |
| title | `string` | no |  | Section heading text. |
| unstyled | `boolean` | no |  | Strip all default tv() styles from internal slots. |

Inherited from:
- Omit<TypesReferenceVariantProps, 'size'> (omit-pattern)
- Omit<HTMLAttributes<HTMLElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`root`, `header`, `title`, `description`, `card`, `toolbar`, `codeBlock`, `literalValues`, `literalBadge`, `usedBySection`, `usedByLink`

---

## VerifyEmailPage
Auto-verifying email confirmation page. Sends GET to `apiPath` (default `/api/auth/verify-email`) on mount.
Pair with `createVerifyEmailHandler(authDeps)` on the server.

**Import:** `import { VerifyEmailPage } from '@urbicon-ui/auth';`

### Examples
```svelte
<VerifyEmailPage {t} token={$page.url.searchParams.get('token') ?? ''} />
```

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| token | `string` | yes |  | Verification token from URL query parameter. |
| apiPath | `string` | no | '/api/auth/verify-email' | ApiPath property for the VerifyEmailPage component |
| class | `string` | no |  | Extra classes on the root element. |
| csrf | `CsrfClientOptions` | no |  | CSRF cookie/header names — only needed when the server overrides the defaults via `config.csrf`. Mutating requests echo the token automatically. |
| fetcher | `typeof globalThis.fetch` | no |  | Custom fetch implementation for all API calls. Defaults to the global `fetch`. Useful for mock backends in demos/tests or custom retry/auth layers. |
| slotClasses | `AuthPageSlotClasses` | no |  | Per-slot class overrides. Keys: `root`, `card`, `title`, `form`, `field`, `submit`, `error`, `success`, `links`. |
| t | `AuthLocale` | no |  | Locale bundle. Auto-detected from i18n context when omitted. |
| unstyled | `boolean` | no |  | Strip all default styling. |

---

## Design Token System

This is the COMPLETE list of available semantic tokens. Use ONLY these — do not invent token names.

### Surface Tokens (backgrounds)

```
bg-surface-base          /* page background */
bg-surface-quiet         /* softly tinted in-page zone (Lighter default) */
bg-surface-subtle        /* visible tinted zone */
bg-surface-elevated      /* floating surfaces (paired with shadow) */
bg-surface-overlay       /* modals, popovers */
bg-surface-interactive   /* interactive backgrounds */
bg-surface-hover         /* hover state */
bg-surface-active        /* active/pressed state */
bg-surface-disabled      /* disabled elements */
bg-surface-selected      /* selected items (uses primary-50) */
bg-surface-inverted      /* inverted surfaces (tooltips) */
```

### Text Tokens

```
text-text-primary        /* main text */
text-text-secondary      /* supporting text */
text-text-tertiary       /* muted text, metadata */
text-text-quaternary     /* most subtle text */
text-text-disabled       /* disabled text */
text-text-inverted       /* text on inverted surfaces */
text-text-on-primary     /* text on intent-colored backgrounds */
text-text-on-dark        /* text on dark surfaces */
text-text-on-surface     /* text on any surface (auto-contrast) */
```

### Border Tokens

```
border-border-subtle     /* gentle grouping */
border-border-default    /* standard borders */
border-border-emphasis   /* emphasized borders */
border-border-strong     /* high-contrast borders */
```

### Intent Tokens (available for ALL intents: primary, secondary, neutral, success, warning, danger)

Each intent has 5 variants. Example with `success`:
```
bg-success               /* base intent color */
bg-success-hover         /* hover state */
bg-success-active        /* pressed state */
bg-success-subtle        /* soft background (e.g. success-50) */
bg-success-emphasis      /* strong/dark variant */
text-success             /* intent-colored text */
text-success-hover       /* hover text */
text-success-subtle      /* subtle intent text */
border-success           /* intent-colored border */
```

Same pattern for: `primary-*`, `secondary-*`, `neutral-*`, `warning-*`, `danger-*`

### Feedback Tokens (status messages)

```
bg-feedback-info            text-feedback-info            /* maps to primary */
bg-feedback-info-subtle                                   /* soft info background */
bg-feedback-success         text-feedback-success         /* maps to success */
bg-feedback-success-subtle                                /* soft success background */
bg-feedback-warning         text-feedback-warning         /* maps to warning */
bg-feedback-warning-subtle                                /* soft warning background */
bg-feedback-error           text-feedback-error           /* maps to danger */
bg-feedback-error-subtle                                  /* soft error background */
```

### DON'T invent token names — common mistakes:

```
/* WRONG — these don't exist */
text-status-danger       bg-status-warning       border-l-status-*
text-feedback-success-fg text-feedback-danger-fg

/* CORRECT equivalents */
text-danger              bg-warning              border-l-danger
text-feedback-success    text-feedback-error
```

### DON'T use primitive colors with dark: overrides:

```
/* WRONG */
bg-white dark:bg-neutral-900

/* CORRECT */
bg-surface-base
```

### Shadow Tokens

```
shadow-[var(--blocks-shadow-xs)]   /* minimal */
shadow-[var(--blocks-shadow-sm)]   /* buttons */
shadow-[var(--blocks-shadow-md)]   /* hover states */
shadow-[var(--blocks-shadow-lg)]   /* menus, popovers */
```

### Z-Index Tokens

```
z-[var(--z-dropdown)]  /* 9999 */
z-[var(--z-overlay)]   /* 1300 */
z-[var(--z-modal)]     /* 1400 */
z-[var(--z-popover)]   /* 1500 */
z-[var(--z-tooltip)]   /* 1800 */
```

### Duration Tokens

```
duration-[var(--blocks-duration-instant)]  /* 75ms */
duration-[var(--blocks-duration-fast)]     /* 150ms */
duration-[var(--blocks-duration-normal)]   /* 250ms */
duration-[var(--blocks-duration-slow)]     /* 350ms */
```

### Easing Tokens

```
var(--blocks-ease-confident)  /* standard transitions */
var(--blocks-ease-springy)    /* bouncy animations */
var(--blocks-ease-smooth)     /* gentle animations */
var(--blocks-ease-snappy)     /* quick, decisive */
```

### Border Radius Scale

```
rounded-xs    /* 0.125rem */    rounded-sm    /* 0.25rem */
rounded-md    /* 0.375rem */    rounded-lg    /* 0.5rem */
rounded-xl    /* 0.75rem */     rounded-2xl   /* 1rem */
rounded-3xl   /* 1.5rem */      rounded-4xl   /* 2rem */
```

---

## Design Quality

These guidelines help you create interfaces with genuine visual identity. They are framed as
"AVOID → INSTEAD" patterns because knowing what NOT to do is more effective than abstract principles.

### Vary Visual Weight

Don't give every element the same visual importance. Vary `variant`, `padding`, and grid span to reflect content hierarchy.

```
/* AVOID — uniform grid, all cards identical */
<div class="grid grid-cols-4 gap-4">
  <Card variant="elevated" padding="md">Metric A</Card>
  <Card variant="elevated" padding="md">Metric B</Card>
  <Card variant="elevated" padding="md">Metric C</Card>
  <Card variant="elevated" padding="md">Metric D</Card>
</div>

/* INSTEAD — weight reflects importance */
<div class="grid grid-cols-4 gap-4">
  <Card variant="elevated" padding="lg" class="col-span-2">Hero metric</Card>
  <Card variant="outlined" padding="md">Secondary</Card>
  <Card variant="outlined" padding="md">Secondary</Card>
</div>
```

### Color = Meaning, Not Decoration

Neutral surfaces should dominate (80–90%). Use `intent` and semantic color tokens ONLY for
their semantic meaning — status, severity, actions — never as visual flair.

```
/* AVOID — color without purpose */
<Card class="bg-primary-subtle">             <!-- why primary? -->
<Badge intent="primary">Active</Badge>       <!-- "Active" isn't a primary action -->

/* INSTEAD — color communicates state */
<Card variant="elevated">                    <!-- neutral default -->
<Badge intent="success" variant="soft">Healthy</Badge>   <!-- green = healthy -->
<Badge intent="danger" variant="filled">Critical</Badge>  <!-- red = critical -->
```

### Spacing Signals Relationships

Don't use the same gap everywhere. Tight spacing groups related items; generous spacing
separates distinct sections.

```
/* AVOID — uniform spacing */
<div class="space-y-4">
  <section>...</section>    <!-- same gap between sections -->
  <section>...</section>
</div>

/* INSTEAD — spacing hierarchy */
<div class="space-y-10">                      <!-- generous between sections -->
  <section class="space-y-3">...</section>    <!-- tight within sections -->
  <section class="space-y-3">...</section>
</div>
```

### Commit to a Shape Language

Choose a border-radius philosophy and apply it consistently. Override component defaults
with `class` or `slotClasses` when your design requires it.

| Strategy | Radius | Personality |
|----------|--------|-------------|
| Sharp | `rounded-sm` / `rounded` | Technical precision, data-dense |
| Soft | `rounded-lg` / `rounded-xl` | Professional, approachable |
| Round | `rounded-2xl` / `rounded-3xl` | Friendly, modern |

Use larger radii for hero/prominent elements, smaller radii for compact/data-dense elements.
Don't rely on component defaults alone — make a deliberate choice:

```svelte
<!-- Override Card radius for a softer design -->
<Card class="rounded-2xl" padding="lg">...</Card>

<!-- Or set globally via BlocksProvider -->
<BlocksProvider defaults={{
  Card: { slotClasses: { base: 'rounded-2xl' } }
}}>
```

### Data-Driven Styling

Let the data shape the presentation. Different states, severities, or categories should look
visually distinct — not just carry a different label.

```
/* AVOID — identical rows regardless of content */
{#each alerts as alert}
  <div class="py-3 border-b border-border-subtle">
    <Badge>{alert.severity}</Badge> {alert.message}
  </div>
{/each}

/* INSTEAD — severity drives visual weight */
{#each alerts as alert}
  {@const critical = alert.severity === 'critical'}
  <div class="border-b border-border-subtle {critical ? 'py-4 font-medium' : 'py-2.5'}">
    <Badge intent={severityIntent(alert.severity)}
           variant={critical ? 'filled' : 'soft'}>
      {alert.severity}
    </Badge>
    <span class={critical ? 'text-text-primary' : 'text-text-secondary'}>
      {alert.message}
    </span>
  </div>
{/each}
```

### Don't Copy, Compose

Recipes and examples show ONE possible interpretation. Use them for API understanding,
not as visual templates. Your implementation should:

- Vary Card `variant` across the page based on content importance (not all `elevated`)
- Use different density (padding, gap, text size) for different page sections
- Make one element per section clearly dominant — if everything is emphasized, nothing is
- Use `text-text-secondary` and `text-text-tertiary` generously to push supporting content back
- Choose your OWN spacing rhythm, radius strategy, and color distribution

---

## Customization

Four levels of customization, from simple color swaps to fully custom designs.
**Pick the lowest level that solves your problem** — lower levels preserve more of the
design system's behavior (dark mode, hover/active cascade, focus rings).

### Level 1: CSS Token Themes

Import a theme CSS file after base styles to override the color palette:
```css
@import '@urbicon-ui/blocks/style/index.css';
@import '@urbicon-ui/blocks/style/themes/ocean.css';
```

Built-in themes: `ocean.css`, `forest.css`, `sunset.css`, `rose.css`, `neutral.css`.

Create custom themes with a `@theme` block:
```css
@theme {
  --color-primary-50: oklch(0.95 0.03 YOUR_HUE);
  --color-primary-500: oklch(0.58 0.13 YOUR_HUE);
  --color-primary-900: oklch(0.26 0.06 YOUR_HUE);
  /* ... full 50–950 scale */
}
```

### Level 2: Presets – Named Project-Defined Styles

**Use this when the built-in `intent` palette doesn't fit.** Presets are named, reusable
`slotClasses` bundles you register once at the app root, then apply per component via
a `preset="…"` prop. They are the **preferred alternative** to ad-hoc `class="bg-…!"`
overrides at call sites.

Register once at the app root:
```svelte
<script>
  import { BlocksProvider } from '@urbicon-ui/blocks';
</script>

<BlocksProvider
  presets={{
    Button: {
      overlay: {
        slotClasses: {
          base: 'bg-black/20 hover:bg-black/30 active:bg-black/40 text-white border-transparent'
        }
      },
      brand: {
        slotClasses: {
          base: 'bg-[#FF5A1F] hover:bg-[#E04C15] active:bg-[#C53F0D] text-white border-transparent'
        }
      }
    },
    Card: {
      glass: {
        slotClasses: {
          base: 'bg-white/10 backdrop-blur-xl border-white/20'
        }
      }
    }
  }}
>
  <slot />
</BlocksProvider>
```

Then use across the project:
```svelte
<Button preset="overlay">Reinholen</Button>
<Button preset="brand">Jetzt kaufen</Button>
<Card preset="glass">Heads-up display</Card>
```

**Why presets over inline `class` overrides?**

```svelte
<!-- ❌ AVOID: Defeats hover/active cascade, leaks decisions into every call site,
     requires `!` to out-specify tv() defaults, inconsistent across the project. -->
<Button intent="primary" class="bg-black/20! hover:bg-black/30! active:bg-black/40!">
  Reinholen
</Button>

<!-- ✅ PREFER: Intent-less, cohesive cascade, reusable across the codebase. -->
<Button preset="overlay">Reinholen</Button>
```

When defining a preset, specify **all interactive states explicitly** (`hover:`, `active:`,
and `focus-visible:` where applicable). The preset's `slotClasses.base` is merged *after*
the `tv()` defaults, so conflicting Tailwind utilities are resolved by the built-in bucket
conflict resolver (last source wins) — no `!` needed.

An unknown preset name emits a dev-only console warning, so typos are discoverable.

### Level 3: BlocksProvider – Global Component Defaults

Use `defaults` (distinct from `presets`) to set **project-wide baseline styles** that
apply to *every* instance of a component — e.g. "all Buttons should be rounded-full in this app":

```svelte
<BlocksProvider
  defaults={{
    Button: { slotClasses: { base: 'rounded-full font-bold uppercase' } },
    Card: { slotClasses: { base: 'rounded-3xl shadow-2xl' } },
    Input: { slotClasses: { base: 'rounded-full' } }
  }}
>
  <slot />
</BlocksProvider>
```

`defaults` vs. `presets` vs. `overrides` — when to use which:
- **`defaults.slotClasses`**: blanket project style applied to every instance (no opt-in required)
- **`presets`**: named alternative look, opt-in via `preset="…"` prop at the call site
- **`defaults.overrides` / `presets[…].overrides`**: prop-conditional rules targeting only a specific
  variant/intent/state (e.g. only `variant="outlined"`) — what unconditional `slotClasses` cannot express

```svelte
<!-- Only outlined badges get a 1px border; the conflict resolver strips the variant's border-2. -->
<BlocksProvider defaults={{ Badge: { overrides: [{ variant: 'outlined', class: { base: 'border' } }] } }}>
  <slot />
</BlocksProvider>
```

Each `overrides` entry is a `compoundVariant`-shaped matcher (`string` = equals, `string[]` = one-of →
per-slot `class`); it matches active prop *values*, so it works regardless of whether the library
defines the conflicting class in a `variant` or a `compoundVariant`.

Merge priority (lowest → highest), conflict-resolved per Tailwind bucket (a later source wins):
1. `tv()` variant styles (library default)
2. `defaults.slotClasses` (global baseline)
3. `defaults.overrides[match]` (prop-conditional)
4. `presets[Component][name].slotClasses` (when `preset` prop is set)
5. `presets[Component][name].overrides[match]`
6. Instance `slotClasses` prop
7. Instance `class` prop

### Level 4: Global Unstyled Mode

Strip all default styles from every component, then apply your own:
```svelte
<BlocksProvider unstyled defaults={{
  Button: { slotClasses: { base: 'inline-flex items-center border-2 px-6 py-3 font-mono' } }
}}>
  <slot />
</BlocksProvider>
```

---

## Style Patterns

Urbicon UI components are designed to be radically reskinned. Do NOT default to the standard
look from examples — choose a visual style that fits the project's identity. Every component
supports `unstyled` (strips all defaults) and `slotClasses` (targeted sub-element overrides).

### Slot Reference

| Component | Slots |
|-----------|-------|
| Button | `base`, `content`, `spinner` |
| Card | `base`, `header`, `content`, `footer` |
| Input | `wrapper`, `container`, `base`, `label`, `message`, `iconContainer` |
| Badge | `base`, `content`, `removeButton`, `removeIcon` |
| Dialog | `base`, `overlay`, `header`, `body`, `footer` |
| Alert | `base`, `icon`, `content`, `title`, `description`, `actions` |
| Tooltip | `base`, `arrow` |

### Pattern: Glassmorphism

```svelte
<BlocksProvider defaults={{
  Card: {
    slotClasses: {
      base: 'bg-white/10 backdrop-blur-xl border border-white/20 shadow-2xl rounded-2xl'
    }
  },
  Button: {
    slotClasses: {
      base: 'bg-white/15 backdrop-blur-md border border-white/25 hover:bg-white/25 rounded-xl text-white shadow-lg'
    }
  },
  Input: {
    slotClasses: {
      base: 'bg-white/10 backdrop-blur-sm border-white/20 text-white placeholder:text-white/50 rounded-xl',
      label: 'text-white/80'
    }
  }
}}>
```

Combine with a gradient or image background on the page container.

### Pattern: Brutalist / Raw

```svelte
<BlocksProvider unstyled defaults={{
  Card: {
    slotClasses: {
      base: 'border-4 border-black bg-white p-0 shadow-[8px_8px_0_black]'
    }
  },
  Button: {
    slotClasses: {
      base: 'border-3 border-black bg-yellow-300 px-6 py-3 font-black uppercase tracking-widest hover:bg-black hover:text-yellow-300 active:translate-x-1 active:translate-y-1 active:shadow-none shadow-[4px_4px_0_black]'
    }
  },
  Input: {
    slotClasses: {
      base: 'border-3 border-black bg-white font-mono text-lg',
      label: 'font-black uppercase tracking-widest text-xs'
    }
  },
  Badge: {
    slotClasses: {
      base: 'border-2 border-black bg-lime-400 font-black uppercase text-black rotate-[-2deg]'
    }
  }
}}>
```

### Pattern: Terminal / Hacker

```svelte
<BlocksProvider unstyled defaults={{
  Card: {
    slotClasses: {
      base: 'border border-green-500/30 bg-black/90 font-mono text-green-400 rounded-none'
    }
  },
  Button: {
    slotClasses: {
      base: 'border border-green-500/50 bg-green-500/10 font-mono text-green-400 rounded-none hover:bg-green-500/20 hover:text-green-300 px-4 py-2 uppercase tracking-wider text-xs'
    }
  },
  Input: {
    slotClasses: {
      base: 'border border-green-500/30 bg-black font-mono text-green-400 rounded-none caret-green-400 placeholder:text-green-800',
      label: 'font-mono text-green-600 uppercase text-[10px] tracking-[0.2em]'
    }
  },
  Badge: {
    slotClasses: {
      base: 'border border-green-500/40 bg-green-500/10 font-mono text-green-400 text-[10px] uppercase rounded-none'
    }
  }
}}>
```

### Pattern: Soft / Organic

```svelte
<BlocksProvider defaults={{
  Card: {
    slotClasses: {
      base: 'rounded-[2rem] bg-amber-50 border-0 shadow-sm'
    }
  },
  Button: {
    slotClasses: {
      base: 'rounded-full bg-stone-800 text-amber-50 hover:bg-stone-700 px-8 font-light tracking-wide border-0 shadow-none'
    }
  },
  Input: {
    slotClasses: {
      base: 'rounded-2xl border-stone-200 bg-stone-50 font-light',
      label: 'font-light text-stone-500'
    }
  }
}}>
```

### Override Interaction Tokens

Change the feel of all components at once:
```css
:root {
  --blocks-ease-confident: cubic-bezier(0.22, 1, 0.36, 1);
  --blocks-duration-normal: 300ms;
  --blocks-scale-hover: 1.00;    /* disable scale on hover */
  --blocks-scale-press: 0.98;
  --blocks-focus-ring-width: 3px;
  --blocks-focus-ring-color: oklch(0.7 0.15 var(--primary-hue, 240));
}
```

### Per-Instance Override

For one-off customizations without changing the global style:
```svelte
<Card unstyled slotClasses={{ base: 'my-custom-card-class', header: 'my-header' }}>
  ...
</Card>

<Button class="rounded-full px-12 tracking-widest uppercase">
  Custom Button
</Button>
```

`class` merges with defaults; `unstyled` + `slotClasses` replaces them entirely.

---

## Callback Naming Convention

Native DOM events: lowercase (`onclick`, `onfocus`)
Custom state callbacks: `on` + PascalCase (`onCheckedChange`, `onValueChange`, `onPageChange`)

Always pass the NEW STATE VALUE, not the raw event:
```svelte
<Checkbox onCheckedChange={(checked) => ...} />
<Menu onValueChange={(value) => ...} />
<Pagination onPageChange={(page) => ...} />
```

---

## i18n Integration

```svelte
<script>
  import { T, LocaleSwitcher } from '@urbicon-ui/blocks';
</script>

<T key="blocks.button.loading" />
<LocaleSwitcher />
```

Supported locales: `en`, `de`. Components auto-translate their internal text.

---

## Common Patterns

### Form with validation
```svelte
<form onsubmit={handleSubmit}>
  <Input label="Email" type="email" bind:value={email} error={errors.email} required />
  <Input label="Password" type="password" bind:value={password} error={errors.password} required />
  <Checkbox label="Remember me" bind:checked={remember} />
  <Button intent="primary" type="submit" loading={submitting}>Sign In</Button>
</form>
```

### Confirmation dialog
```svelte
<Dialog bind:open={showConfirm} title="Delete Item?" intent="danger" size="sm">
  <p>This action cannot be undone.</p>
  {#snippet footer()}
    <Button variant="ghost" onclick={() => showConfirm = false}>Cancel</Button>
    <Button intent="danger" onclick={handleDelete} loading={deleting}>Delete</Button>
  {/snippet}
</Dialog>
```

### Data display card
```svelte
<Card variant="outlined" padding="lg">
  {#snippet header()}
    <div class="flex items-center justify-between">
      <h3 class="text-text-primary font-semibold">Revenue</h3>
      <Badge intent="success" variant="soft">+12%</Badge>
    </div>
  {/snippet}
  <p class="text-3xl font-bold text-text-primary">$48,200</p>
  <p class="text-text-tertiary text-sm">vs. $43,000 last month</p>
</Card>
```

### Navigation tabs
```svelte
<Tab
  tabs={[
    { label: 'Overview', value: 'overview' },
    { label: 'Analytics', value: 'analytics' },
    { label: 'Settings', value: 'settings', disabled: true }
  ]}
  bind:value={activeTab}
  variant="pills"
/>

{#if activeTab === 'overview'}
  <OverviewPanel />
{:else if activeTab === 'analytics'}
  <AnalyticsPanel />
{/if}
```

### Menu with custom items
```svelte
<Menu
  items={users}
  getItemLabel={(u) => u.name}
  getItemValue={(u) => u.id}
  placeholder="Assign to..."
  bind:value={assignee}
>
  {#snippet customItem(user, isSelected, toggle)}
    <div class="flex items-center gap-2 p-2" onclick={toggle}>
      <Avatar name={user.name} size="xs" />
      <span>{user.name}</span>
    </div>
  {/snippet}
</Menu>
```

### Loading skeleton
```svelte
{#if loading}
  <div class="flex items-center gap-3">
    <Skeleton variant="circular" size="md" />
    <div class="flex-1 flex flex-col gap-2">
      <Skeleton variant="text" size="sm" />
      <Skeleton variant="text" size="xs" class="w-2/3" />
    </div>
  </div>
{:else}
  <UserCard {user} />
{/if}
```

### Breadcrumb navigation
```svelte
<Breadcrumb items={[
  { label: 'Dashboard', href: '/dashboard' },
  { label: 'Settings', href: '/dashboard/settings' },
  { label: 'Profile' }
]} size="sm" />
```

---

## Auth Setup

`@urbicon-ui/auth` is a zero-runtime-dependency auth system for SvelteKit (JWT sessions,
refresh-token rotation, passkeys, notifications). Server code imports from
`@urbicon-ui/auth/server`; client stores and components from `@urbicon-ui/auth`.
`createAuthHandle` is **mandatory** — it hydrates `locals.user`, guards routes, applies
the response security headers, and enforces CSRF; the handler factories alone do none of
that. Setup is staged: start with the dev quickstart, then layer on production hardening.

### Stage 1 — Dev quickstart (no database, no mail server)

In-memory adapter + console email transport. State is wiped on restart — **dev only**.

```typescript
// src/lib/server/auth-setup.ts
import { createAuthDeps } from '@urbicon-ui/auth/server';
import { createInMemoryRepos } from '@urbicon-ui/auth/server/adapters/in-memory';
import { createConsoleEmailTransport } from '@urbicon-ui/auth/server/email/console';

export const authDeps = createAuthDeps({
  config: {
    jwt: { secret: 'dev-secret-change-me', cookieSecure: false }, // cookieSecure:false = http dev
    appUrl: 'http://localhost:5173', // required — builds email verification/reset links
    routes: { afterLogin: '/', loginPage: '/auth/login' }
  },
  repos: createInMemoryRepos(),
  email: createConsoleEmailTransport() // dev only — prints emails to the terminal
});
```

```typescript
// src/hooks.server.ts
import { createAuthHandle } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth-setup';
export const handle = createAuthHandle({ config: authDeps.config, repos: authDeps.repos });
```

**Note — Origin/CSRF is enforced only for requests routed _through_ the handle.** If you later
add a cross-origin, form-encoded endpoint (an OAuth 2.1 token endpoint, a webhook) _around_
`createAuthHandle`, SvelteKit's own built-in `csrf.checkOrigin` — which runs in the request
kernel before any hook, in production builds only — rejects it with `403 "Cross-site POST form
submissions are forbidden"` (most visibly the OAuth token endpoint: RFC 6749 mandates
`application/x-www-form-urlencoded` and its callers send no `Origin` header). Set
`kit.csrf: { trustedOrigins: ['*'] }` in `svelte.config.js` to disable the kernel check and let
this package's stricter `validateCsrf` be the single Origin gate — safe only when every
cookie-authenticated mutating route flows through `createAuthHandle` and the bypassed routes are
cookieless (bearer/PKCE/API-key). JSON endpoints (e.g. MCP JSON-RPC) are unaffected.

```typescript
// src/routes/api/auth/login/+server.ts — one file per handler
import { createLoginHandler } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth-setup';
export const { POST } = createLoginHandler(authDeps);
// Repeat with createLogoutHandler, createRegisterHandler, createForgotPasswordHandler,
// createResetPasswordHandler, createVerifyEmailHandler, createMeHandler.
```

```svelte
<!-- src/routes/auth/login/+page.svelte -->
<script>
  import { LoginPage } from '@urbicon-ui/auth';
  import { en } from '@urbicon-ui/auth/i18n/en';
  import { goto } from '$app/navigation';
</script>

<LoginPage t={en} onSuccess={() => goto('/')} />
```

`createAuthDeps` applies secure brute-force defaults automatically (login rate-limit
5 / 15 min + lockout 5 / 15 min), so even the quickstart isn't an open door.
`cookieSecure: false` marks the config as dev and suppresses the production hardening
warnings (and HSTS). Registration is invitation-gated — seed one first:
`authDeps.repos.invitation.create({ email, role: 'USER', invitedById: 'seed' })`.

### Stage 2 — Production

Swap the two dev pieces (in-memory → Prisma, console → a real transport) and enable the
additive hardening layers. The hook and route stubs are unchanged.

```typescript
// src/lib/server/auth-setup.ts
import { createAuthDeps } from '@urbicon-ui/auth/server';
import { createPrismaRepos } from '@urbicon-ui/auth/server/adapters/prisma';
import { createLettermintTransport } from '@urbicon-ui/auth/server/email/lettermint';
import { env } from '$env/dynamic/private';
import { prisma } from './prisma';

type AppRole = 'ADMIN' | 'USER';

export const authDeps = createAuthDeps<AppRole>({
  config: {
    jwt: { secret: env.JWT_SECRET }, // cookieSecure defaults true → HTTPS + auto HSTS
    appUrl: env.PUBLIC_APP_URL, // trusted base for email links — never request.url
    csrf: { doubleSubmit: true }, // token layer on top of the always-on Origin check
    refreshToken: { accessTokenTtl: '15m', refreshTokenTtl: '30d' }, // rotating refresh
    rateLimit: { login: { windowMs: 900_000, max: 5 } },
    lockout: { maxAttempts: 5, durationMinutes: 15 },
    routes: { afterLogin: '/', loginPage: '/auth/login' }
  },
  repos: createPrismaRepos<AppRole>(prisma), // pulls in the refreshToken adapter
  email: createLettermintTransport({ apiKey: env.LETTERMINT_KEY })
});
```

Add a `refresh` route stub (`createRefreshHandler`) once rotation is on. With
`csrf.doubleSubmit` enabled, the bundled stores/components send the CSRF header
automatically; custom client fetches use `csrfFetch` from `@urbicon-ui/auth`. Copy the
Prisma models from the package's `prisma/auth-schema.prisma`. Before going live: enforce
HTTPS, use persistent stores for challenges / refresh tokens / rate limits when running
more than one instance, tune `securityHeaders.csp` to your app, and keep `JWT_SECRET` in
a secret store with a `keyId` + `previousSecrets` rotation runbook.

### Stage 3 — Advanced

- **Custom persistence adapter** (Drizzle, Kysely, raw SQL): implement the repository interface and prove it upholds the atomic claim/scope contract with `describeRepositoryConformance` from `@urbicon-ui/auth/server/adapters/conformance`.
- **JWT key rotation**: set `jwt.keyId` + `jwt.previousSecrets` to roll the signing secret without invalidating live sessions.
- **Passkeys (WebAuthn)**: wire `createPasskeyRegistrationOptionsHandler`, `createPasskeyRegistrationVerifyHandler`, `createPasskeyAuthenticationOptionsHandler`, `createPasskeyAuthenticationVerifyHandler` with a `webauthn: WebAuthnConfig` (persistent `challengeStore` at >1 instance; `requireUserVerification: true` to enforce UV), then add `<PasskeyManager>` and `<LoginPage mode="both" passkeyApiPath="/api/auth/passkey">`.
- **Notifications + Web Push**: register events with `createNotificationRegistry` server-side; listen with `<NotificationListener>` + `<NotificationCenter>` client-side. `notification.url` is untrusted at navigation time — validate/allow-list it before `goto()`. Mark-read/delete route handlers must scope `userId` from `locals.user`, never the request body (IDOR).
- **Federated identity / SSO**: on the roadmap (`createFederatedAuthHandle()`).