# svelte-toggle-switch v3.0.0 Design Spec

**Date:** 2026-06-29  
**Branch:** `release/v3.0.0-runes-new-variants-interactions`  
**Version bump:** `2.3.1` → `3.0.0`

---

## 1. Breaking Changes

### Svelte 5 Runes Migration
Migrate `Switch.svelte` internals from legacy Options API to Svelte 5 runes:
- `export let prop` → `$props()` destructuring
- `let internalState` → `$state()`
- `$: derived` → `$derived()`
- `createEventDispatcher` removed

### Event API (breaking for consumers)
```svelte
<!-- v2.x -->
<Switch on:change={handler} on:focus={handler} on:blur={handler} />

<!-- v3.0 -->
<Switch onchange={handler} onfocus={handler} onblur={handler} />
```

### TypeScript Exports
New `src/lib/index.ts` barrel file:
```ts
export type { SwitchProps } from './Switch.svelte';
export { default as Switch } from './Switch.svelte';
```
Full `SwitchProps` interface exported covering all props, union literals, and callback types.

**All non-event props remain unchanged** — full backward compatibility on values, designs, styling, etc.

---

## 2. New Design Variants

Added to `design` prop union: `'flip' | 'neon' | 'pill'`

### `design="flip"`
Card physically flips 180° on Y-axis using CSS `perspective` + `rotateY`. Front = OFF, back = ON.  
New props:
- `flipFrontContent: string` (default `'OFF'`)
- `flipBackContent: string` (default `'ON'`)

### `design="neon"`
Cyberpunk-style glow toggle. Track and thumb emit layered `box-shadow` neon glow. On toggle, bloom animation shifts glow color. Works with all 9 color schemes. No new props — existing `colorScheme`, `pulse`, `pulseIntensity` apply naturally. Best with `darkMode`.

### `design="pill"`
Binary segmented control: two adjacent pill buttons for ON/OFF. Active pill gets color scheme color; inactive is muted. Uses existing `onText`/`offText` for labels. Arrow key navigation between pills. Strictly binary (not a replacement for `multi`).

---

## 3. New Interaction Features

### Drag-to-toggle with momentum
- `dragMomentum: boolean` (default `false`)
- Thumb follows pointer/finger during drag
- On release: if velocity > threshold → snap to direction of travel; else → snap by position (past midpoint = ON)
- Works on mouse and touch events

### Long-press to toggle
- `longPress: boolean` (default `false`)
- `longPressDuration: number` (default `600` ms)
- Progress ring animates around thumb during hold
- After duration fires toggle; releasing early cancels
- Disables normal click-to-toggle when enabled

### Confirm before toggle
- `confirmToggle: boolean` (default `false`)
- `confirmMessage: string` (default `'Are you sure?'`)
- `onconfirm: () => Promise<boolean>` — async callback; `true` = commit, `false` = cancel
- Switch enters "pending" state (thumb halfway, amber pulse) while awaiting confirmation
- If no `onconfirm` provided, inline Yes/No prompt appears beside the switch

---

## 4. Demo & Playground Updates

- New section in demo showcasing all 3 design variants with interactive examples
- New section for interaction features (drag, long-press, confirm)
- Playground updated to include new `design` values (`flip`, `neon`, `pill`) and new props in the prop panel
- Docs pages updated with new API reference and usage examples
- CHANGELOG.md updated with v3.0.0 entry
- README.md updated with v3.0.0 features

---

## 5. Implementation Sequence

1. Svelte 5 runes migration + TypeScript barrel export
2. `design="neon"` variant
3. `design="flip"` variant  
4. `design="pill"` variant
5. `dragMomentum` interaction
6. `longPress` interaction
7. `confirmToggle` interaction
8. Demo + playground updates
9. Docs + CHANGELOG + README
10. Version bump to 3.0.0