---

## 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)}
/>
```

```svelte
<div class="space-y-2">
  <Toggle label="Email notifications" />
  <Toggle label="Push notifications" />
</div>
```

### Variants
- intent: danger, neutral, primary, secondary, success, warning (default: primary)
- variant: default, dot (default: default)
  - default — Classic switch pill — a track with an animated thumb.
  - dot — Small indicator dot left of the label — outline only when off, filled in the intent colour when on; monochrome, no pill background.
- size: lg, md, sm, xs (default: md)
- 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 |
| 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. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| disabled | `boolean` | no |  | Prevent interaction and dim the control. |
| error | `string` | no |  | Error message shown below the control. Replaces `helper`, flags the hidden input `aria-invalid`, and marks the unchecked track with the danger colour — e.g. for a consent toggle that must be switched on. |
| helper | `string` | no |  | Helper text shown below the control. Hidden when `error` is set. 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 | 'none' | Micro-interaction preset applied to the track. Only applies while not disabled. |
| 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. In the same Tailwind bucket `class` wins over the `slotClasses` entry for the element it lands on. Presets and provider defaults sit below both. |
| 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 variant 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'`. |
| variant | `ToggleVariants['variant']` | no | 'default' | Visual style of the control. Reach for `dot` where the switch pill is visually too loud — dense settings rows, inline toolbars. |
| 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' | 'error'> (omit-pattern)
- Omit<HTMLInputAttributes, 'type' | 'size' | 'checked' | 'class' | 'children'> (omit-pattern)

### Types
```ts
type MintProp = | MintName
  | { name: MintName; config?: MintConfig & Record<string, unknown> }
  | Array<MintName>
  | Array<MintName | { name: MintName; config?: MintConfig & Record<string, unknown> }>
```

```ts
type InteractiveTier = 'commit' | 'modify'
```

```ts
type MintName = BuiltinMintName | 'none' | (string & {})
```

```ts
interface MintConfig {
/**
   * `hover` and `focus` hold the effect while the pointer/visible focus stays
   * on the element; `click` and `load` run it once.
   */
  trigger?: 'hover' | 'click' | 'focus' | 'load';
  /**
   * Effect duration in ms. Written as an inline per-effect custom property
   * (`--blocks-mint-<effect>-duration`), so the CSS transition/animation
   * actually runs at this speed; unset, the theme duration tokens apply.
   */
  duration?: number;
  /** Delay in ms before the effect applies. */
  delay?: number;
  /**
   * CSS easing for the effect (`--blocks-mint-<effect>-easing` inline);
   * unset, the per-effect theme default applies.
   */
  easing?: string;
  disabled?: boolean;
}
```

```ts
type BuiltinMintName = (typeof BUILTIN_MINT_NAMES)[number]
```

### Slots (slotClasses keys)
`wrapper`, `control`, `track`, `thumb`, `label`, `message`