## switch (`poetry_switch`)

A toggle for turning a setting on or off.

Class: Poetry::Ui::Switch::Component - BEM block `poetry-ui-switch`.
- `size:` (symbol) - one of default|sm, default "default", required - The control's size axis; the thumb scales to match.
- `checked:` (boolean) - default false - The server-rendered on/off state.
- `disabled:` (boolean) - default false - Disables the control and its hidden input - a disabled switch neither toggles nor submits.
- `label:` (string) - The accessible name, rendered as aria-label - not visible text.
- `name:` (string) - Names the hidden input, making the switch a form participant.
- `required:` (boolean) - default false - Marks the switch required via aria-required (never the native attribute).
- `unchecked_value:` (string) - default "0" - Submitted when the switch is off, so the field always posts. Ignored without name:.
- `value:` (string) - default "1" - Submitted when the switch is on. Ignored without name:.
- PART `switch` - The visual button[role=switch] - reflects the hidden input via aria-checked plus the checked pair (never indeterminate) | states: data-checked (on (the shared checked controller reflects every toggle here, aria-checked in step)); data-unchecked (off (the server-rendered default)); data-size=default|sm (always - the resolved size (the thumb reads it via group/switch selectors))
- PART `switch-thumb` - The sliding knob - travel is pure CSS off the checked pair | states: data-checked (mirrors the control (the controller reflects state on every part wearing the pair)); data-unchecked (mirrors the control - the thumb sits at the start)
- WIRING root: `poetry--core--checked` registers; values input_id (if form_participant?); actions toggle on click
- RULE: Use poetry_switch - never a styled checkbox pretending to be a switch (role=switch announces on/off; that's the point).
- RULE: Switch = instant effect; Checkbox = staged for submit. If nothing happens until a Save button, use Checkbox.
- RULE: Every switch needs an accessible name (Label/Field for= or label:).
- RULE: Switches are BINARY - no indeterminate, ever (ArgumentError). A third state means a different component.
- RULE: The instant-effect recipe pairs the flip with server persistence (Turbo auto-submit) - never flip UI-only for a setting the user believes is saved.
- RULE: NEVER write the checked attributes (data-checked/data-unchecked) without aria-checked and the input sync (the controller writes all three).