@malva-ui/core 0.1.12

package/docs/ai/switch.md

@@ -0,0 +1,216 @@
+# Library: switch
+
+## Overview
+
+The Switch library (`@malva-ui/core/switch`) provides accessible toggle switch components implementing the WAI-ARIA switch pattern. Supports grouped switches with keyboard navigation and reactive forms integration via `ControlValueAccessor`.
+
+> **Host `aria-label` / `aria-labelledby` forwarding** — a consumer writing
+> `<mlv-switch aria-label="Enable feature" />` (a switch with no projected text)
+> would otherwise leave the attribute on the role-less host element, which ARIA
+> prohibits (axe `aria-prohibited-attr`). `MlvSwitch` captures a **static**
+> host `aria-label`/`aria-labelledby` via `HostAttributeToken` in its constructor,
+> imperatively removes it from the host (`Renderer2.removeAttribute`), and forwards
+> it onto the inner `<input type="checkbox" role="switch">` — the real
+> accessible-name target — through the `[attr.aria-label]` / `[attr.aria-labelledby]`
+> template bindings (`_ariaLabel` / `_ariaLabelledBy` signals). When no host ARIA
+> attribute is supplied the signals stay `null`, so no empty `aria-label` is emitted
+> on the input. For **dynamic** labels use the `ariaLabel` / `ariaLabelledBy`
+> **inputs** (they win over a captured static attribute via the
+> `_resolvedAriaLabel`/`_resolvedAriaLabelledBy` computeds) — never bind
+> `[attr.aria-label]` on the host, which Angular writes straight onto the host
+> element where it cannot be intercepted. Same pattern as `mlv-checkbox` and
+> `mlv-radio`.
+
+## Public API
+
+Exported from `@malva-ui/core/switch`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvSwitch` | Component | Toggle switch — `mlv-switch` |
+| `MlvSwitchState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` (alias of `MlvFormState`) |
+| `MlvSwitchGroup` | Component | Group container — `mlv-switch-group` |
+| `MlvSwitchGroupState` | Type | Same values as `MlvSwitchState` (alias of `MlvFormState`) |
+
+---
+
+## Components
+
+### `MlvSwitch`
+
+- **Selector:** `mlv-switch`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Extends:** `MlvSignalCheckboxControlBase` from `@malva-ui/core/form-utils` (signal forms — no `ControlValueAccessor`)
+- **Focus management:** `MlvSwitchGroup` adapts switch instances to `FocusKeyManager` and uses `computedDisabled()` as the skip predicate, preserving `[disabled]` as a signal input.
+
+#### Model (two-way binding)
+
+| Name      | Type      | Default |
+| --------- | --------- | ------- |
+| `checked` | `boolean` | `false` |
+
+#### Inputs
+
+| Name             | Type                  | Default     | Description                                                                                                                                                                                                                                      |
+| ---------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `disabled`       | `boolean`             | `false`     | Component-level disabled                                                                                                                                                                                                                         |
+| `state`          | `MlvSwitchState`      | `'default'` | Semantic state for track color                                                                                                                                                                                                                   |
+| `label`          | `string`              | `''`        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-switch>`. Projected content always wins (CSS `display: none`-s the fallback), so the accessible name never duplicates. Inherited from the signal base |
+| `required`       | `boolean` (coerced)   | `false`     | Sets `aria-required` on the native input; also a signal-forms field binding. Inherited from the signal base                                                                                                                                      |
+| `ariaLabel`      | `string \| null`      | `null`      | Accessible name applied to the inner native input; wins over a captured static host `aria-label`. Inherited from the signal base since 2026-08 (was a switch-local input)                                                                        |
+| `ariaLabelledBy` | `string \| undefined` | `undefined` | Id reference(s) naming the inner native input; same precedence as `ariaLabel`                                                                                                                                                                    |
+
+#### Inputs (inherited from `MlvSignalFormUiControlBase`)
+
+| Name          | Type                                               | Default                    | Description                                                                      |
+| ------------- | -------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------- |
+| `readonly`    | `boolean`                                          | `false`                    | Read-only control; also a signal-forms field binding.                            |
+| `loading`     | `boolean`                                          | `false`                    | Shows the loading affordance.                                                    |
+| `clearable`   | `boolean`                                          | `false`                    | Renders the clear affordance while the control has a value (On counts as one).   |
+| `pill`        | `boolean`                                          | `false`                    | Fully rounded (stadium) control container.                                       |
+| `errors`      | `readonly ValidationError.WithOptionalFieldTree[]` | `[]`                       | Signal-forms field binding: current validation errors.                           |
+| `touched`     | `boolean`                                          | `false`                    | Signal-forms field binding: whether the bound field is touched.                  |
+| `dirty`       | `boolean`                                          | `false`                    | Signal-forms field binding: whether the bound field is dirty.                    |
+| `id`          | `string`                                           | `mlvNextId('mlv-control')` | HTML id applied to the control's focus target.                                   |
+| `hint`        | `string`                                           | `''`                       | Hint text rendered inside the label.                                             |
+| `description` | `string`                                           | `''`                       | Persistent help text rendered below the control (`<mlv-description>` slot wins). |
+| `message`     | `string`                                           | `''`                       | Validation/status message rendered below the control.                            |
+
+#### Outputs
+
+| Name            | Type      | Description                                                                                 |
+| --------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `checkedChange` | `boolean` | The `checked` model's change output.                                                        |
+| `touch`         | `void`    | Inherited. Emitted on blur — the signal-forms replacement for the CVA `onTouched` callback. |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-switch',
+  '[class.mlv-switch--disabled]': 'computedDisabled()',
+  '[class.mlv-switch--checked]': 'checked()',
+}
+```
+
+The host is **not** focusable. The single focus target is the visually-hidden
+native `<input type="checkbox" role="switch">` (kept in the a11y tree via the
+clip-path pattern). Its `tabindex` is the roving tabindex managed by
+`MlvSwitchGroup` (`tabIndex` signal: 0 for active, -1 for others).
+
+#### Key Methods
+
+- `focus()` — CDK `FocusableOption`; focuses the native input (not the host)
+- `toggle()` — Flip checked state (no-op if disabled)
+- `onInputChange(event)` — Reflects the native `change` event onto the `checked` model
+- `setFocused(focused)` — Inherited from the signal base; updates the focus signal driving the wrapper state.
+
+The control is a signal-forms field, not a `ControlValueAccessor` — there is no
+`writeValue`/`setDisabledState` pair.
+
+#### Internal methods (`@internal`, template-facing)
+
+- `onEnter(event)` — Enter-key toggle (Space is handled natively by the input)
+- `onFocus()` — Notify parent group via `SWITCH_GROUP` token
+- `onBlur()` — Emits the signal-forms `touch` output when focus leaves the input
+
+#### Keyboard & Focus
+
+- **Single tab stop:** the native input carries the roving tabindex; the host is not tabbable.
+- **Space** toggles natively (fires `change`); **Enter** toggles via `onEnter`.
+- **`:focus-visible`** ring is promoted from the hidden input onto `.mlv-switch__track` using `--mlv-border-focus`.
+
+#### Template Summary
+
+`<label>` wrapping:
+
+- Visually-hidden (clip-path) `<input #nativeInput type="checkbox" role="switch" [attr.tabindex]="tabIndex()" [attr.aria-checked] [attr.aria-required]>`
+- `.mlv-switch__track.mlv-switch__track--{state}` (visual track + thumb)
+- `.mlv-switch__text`, holding `.mlv-switch__content` (`<ng-content>`) followed by the `.mlv-switch__label-text` fallback rendered from the `label` input
+
+A dev-mode `console.warn` fires once per instance when a switch has no projected text, no `label`, and no `ariaLabel`/`ariaLabelledBy` — i.e. no accessible name at all.
+
+#### Styles
+
+- Track: `40px × 24px`, `border-radius: 12px`
+- Thumb: `20px × 20px`, animates `translateX(16px)` when checked
+- Transition: `0.2s ease-in-out`
+- Uses `--mlv-border-normal`, `--mlv-background-accent-1`, `--mlv-background-base`
+
+---
+
+### `MlvSwitchGroup`
+
+- **Selector:** `mlv-switch-group`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Extends:** `MlvFocusableGroupBase<MlvSwitch>` from `@malva-ui/core/form-utils` — the shared roving-tabindex `FocusKeyManager` lifecycle lives in the base; the group only supplies `_items` (projected switches) + `_isDisabled` (`computedDisabled()`).
+- **Implements:** `MlvSwitchGroupAccessor` (`onChildFocus` inherited from the base)
+
+#### Inputs
+
+| Name    | Type                  | Default     |
+| ------- | --------------------- | ----------- |
+| `label` | `string`              | `''`        |
+| `state` | `MlvSwitchGroupState` | `'default'` |
+
+#### Methods (inherited from `MlvFocusableGroupBase`)
+
+| Method                            | Description                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `onChildFocus(child)`             | Marks the focused child active in the `FocusKeyManager` (roving tabindex).         |
+| `onKeydown(event: KeyboardEvent)` | Forwards arrow/Home/End keys to the `FocusKeyManager`, skipping disabled children. |
+
+#### Keyboard Navigation
+
+#### Template Summary
+
+`div[role="group"][aria-label]` + optional `mlv-label` + `<ng-content>` + `(keydown)` handler.
+
+---
+
+## Internal Token
+
+```ts
+export const SWITCH_GROUP = new InjectionToken<MlvSwitchGroupAccessor>('SWITCH_GROUP');
+
+interface MlvSwitchGroupAccessor {
+  onChildFocus(sw: MlvSwitch): void;
+}
+```
+
+---
+
+## Usage Examples
+
+```html
+<!-- Standalone -->
+<mlv-switch [(checked)]="darkMode">Dark Mode</mlv-switch>
+
+<!-- State-based styling -->
+<mlv-switch [(checked)]="isOnline" [state]="isOnline() ? 'success' : 'error'">Status</mlv-switch>
+
+<!-- Group with keyboard navigation -->
+<mlv-switch-group label="Permissions">
+  <mlv-switch [(checked)]="canRead">Read</mlv-switch>
+  <mlv-switch [(checked)]="canWrite">Write</mlv-switch>
+  <mlv-switch [(checked)]="canDelete">Delete</mlv-switch>
+</mlv-switch-group>
+
+<!-- Reactive forms -->
+<mlv-switch formControlName="enableNotifications">Notifications</mlv-switch>
+
+<!-- Disabled -->
+<mlv-switch [disabled]="true">Locked</mlv-switch>
+```
+
+---
+
+## Dependencies
+
+- `@angular/forms` — CVA
+- `@angular/cdk/a11y` — `FocusKeyManager`, `FocusableOption`
+- `@malva-ui/cdk/accessibility` — `MlvClick`
+- `@malva-ui/core/form-utils` — `MlvLabel`
+- `@malva-ui/styles` — design tokens, `_mixins.scss`