# `<Switch3>`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

`<Switch3>` is the three-position toggle, modelling the kind of
"down-centre-up" or "low-mid-high" switch found on outboard audio gear.
Click cycles forward (off -> mid -> on -> off), keyboard arrows step
stepwise between adjacent positions, and Space / Enter cycle in the same
direction as a click. The numeric value is mapped onto positions 0/1/2
using a third-band threshold; the emitted `onChange` values are `min`,
`(min+max)/2`, and `max`.

The component renders as a `<button role="slider">` with
`aria-valuemin=0`, `aria-valuemax=2`, `aria-valuenow=position`, and
`aria-valuetext` matching the human-readable position name. This keeps
the switch operable from a screen reader while still allowing click-to-
cycle interaction for sighted users.

## Features

- Click + Space/Enter cycle forward.
- Arrow keys step (Right/Up forwards, Left/Down backwards), clamped at
  the ends.
- Customisable position labels via `positionLabels`.
- Telemetry: increments `control_surface_interactions_total{kind="switch-3"}`
  per change.
- Pure helpers `switch3Position` and `switch3ValueForPosition`.

## Usage: Basic

```tsx
<Switch3
    value={routing}
    onChange={setRouting}
    min={0}
    max={1}
    label="Routing"
/>
```

## Usage: Advanced

```tsx
<Switch3
    value={state}
    onChange={(v) => registry.dispatch(binding, v)}
    min={-1}
    max={1}
    label="Polarity"
    positionLabels={["Inverted", "Bypass", "Normal"]}
    disabled={readOnly}
/>
```

## API Reference

- `<Switch3>` props: `BoundControlProps & { className?, style?, positionLabels? }`.
- `switch3Position(value, min, max)` — pure helper returning 0/1/2.
- `switch3ValueForPosition(position, min, max)` — inverse helper.

## Implementation Notes

The component uses `role="slider"` rather than three native radio inputs
because that better matches the visual model of a single-button cycling
toggle while still meeting WCAG keyboard requirements. The third-band
threshold for `switch3Position` uses inclusive `<=` at the lower edge and
exclusive `<` at the upper edge to ensure that a value of exactly `min`
maps to position 0 (off) and not to position 1.