first commit

docs/ui/react/react-control-surface/src/controls/switch-3/switch-3.md

@@ -0,0 +1,72 @@
+# `<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.