svelte-kit-vice/src/uix/soma/components/switch/README.md

# Switch

A toggle control that switches between on and off states.

## Anatomy

```svelte
<Switch.Provider bind:checked>
	<Switch.Thumb />
</Switch.Provider>
```

## Parts

| Part       | Element    | Description                                  |
| ---------- | ---------- | -------------------------------------------- |
| `Provider` | `<button>` | Switch control. Toggles on click.            |
| `Thumb`    | `<span>`   | Visual indicator that slides between states. |

Both `Provider` and `Thumb` expose `{ checked }` to their snippet content. Eidos
uses the thumb payload to render its default checked icon without duplicating
switch state outside Soma.

## ARIA

| Part     | Attribute       | Value                  |
| -------- | --------------- | ---------------------- |
| Provider | `role`          | `switch`               |
| Provider | `aria-checked`  | `true` \| `false`      |
| Provider | `aria-required` | `true` (when required) |

**Accessible name required.** The Provider emits `role='switch'`, which requires a name for assistive tech. Pass `aria-label` on the Provider, or `aria-labelledby` pointing to a visible label.

## Data Attributes

| Part     | Attribute           | Values                   |
| -------- | ------------------- | ------------------------ |
| Provider | `data-switch`       | Always present           |
| Provider | `data-state`        | `checked` \| `unchecked` |
| Provider | `data-checked`      | Present when checked     |
| Provider | `data-disabled`     | Present when disabled    |
| Thumb    | `data-switch-thumb` | Always present           |
| Thumb    | `data-state`        | `checked` \| `unchecked` |
| Thumb    | `data-disabled`     | Present when disabled    |

## Keyboard

| Key     | Action                                     |
| ------- | ------------------------------------------ |
| `Enter` | Toggle the switch                          |
| `Space` | Toggle the switch (native button behavior) |

## Sema events

| Event           | Family   | Verb     | Target     | When                                                                  |
| --------------- | -------- | -------- | ---------- | --------------------------------------------------------------------- |
| `commit-toggle` | `commit` | `toggle` | `provider` | Switch toggled on/off. Intent from prop: `neutral`, `affirm`, `risk`, `threat`. |

**Pack**: [`src/uix/sema/components/switch.ts`](../../../sema/components/switch.ts) — silent-by-default (`form.toggle.silent`) + light `tap` haptic. High-frequency settings panels; intent-loaded toggles (threat) still surface audibly via `intent.deltas`.

## Usage

### Basic

```svelte
<script>
	import { Switch } from '$soma/components';

	let checked = $state(false);
</script>

<Switch.Provider bind:checked>
	<Switch.Thumb />
</Switch.Provider>
```

### Thumb content from state

```svelte
<Switch.Provider bind:checked>
	<Switch.Thumb>
		{#snippet children({ checked })}
			{checked ? 'on' : 'off'}
		{/snippet}
	</Switch.Thumb>
</Switch.Provider>
```

### Disabled

```svelte
<Switch.Provider disabled>
	<Switch.Thumb />
</Switch.Provider>
```

### With form name

```svelte
<Switch.Provider bind:checked name="notifications" value="enabled">
	<Switch.Thumb />
</Switch.Provider>
<!-- Renders a hidden input for form submission -->
```