@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/switch.md

@@ -0,0 +1,508 @@
+<!-- index: ./index.md -->
+# switch
+
+`data-ui="switch"` · Toggle that turns a setting on or off.
+
+## Import
+
+```ts
+import {
+  provideSwitchDefaults,
+  SlSwitch,
+  SlSwitchDescription,
+} from '@slotted/angular/switch';
+```
+
+Selector: `[slSwitch]` · exportAs: `slSwitch`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-basic',
+  imports: [SlSwitch, SlSwitchDescription],
+  template: `
+    <span slSwitch defaultChecked labelPlacement="start" name="lowStockAlerts">
+      Low-stock alerts
+      <p slSwitchDescription>Email the buyer when a product falls below its reorder point.</p>
+    </span>
+  `,
+})
+export class SwitchBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slSwitch | yes |
+| `control` | input[type=checkbox][role=switch], from the component’s template | yes |
+| `track` | span, from the component’s template | yes |
+| `thumb` | span, from the component’s template | yes |
+| `label` | label, holding the projected content | no |
+| `description` | the element carrying slSwitchDescription | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean` | — | [slSwitch] | The state, owned by the consumer for the life of the component when it is bound. Unbound, the switch owns the state and a native form reset restores it. |
+| `defaultChecked` | `boolean` | false | [slSwitch] | The state an uncontrolled switch starts from, read once in ngOnInit. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | [slSwitch], provideSwitchDefaults | The control step. A field around the switch decides it first, then provideSwitchDefaults. The pill, the thumb, the check and the label read the control scales, which the theme restates per density. |
+| `indicator` | `'mark' \| 'none'` | mark | [slSwitch], provideSwitchDefaults | What the thumb carries. mark draws a check when the switch is on and nothing when it is off. none draws nothing, and is correct only where text beside the switch states the value. |
+| `labelPlacement` | `'end' \| 'start'` | end | [slSwitch], provideSwitchDefaults | Which side of the label the pill sits on. start is the settings row: the label takes the free width and the pill sits at the end of the row. |
+| `loading` | `boolean` | false | [slSwitch] | The value is not settled yet. The switch refuses every press, keeps its size, sets aria-busy, and announces the pending label politely once the wait passes two seconds. |
+| `messages` | `Partial<SwitchMessages>` | — | [slSwitch] | Words that replace the active language’s, key by key: loading is what a screen reader hears while the switch is pending. The words reach a live region, not the control’s name, so the name never changes with the state. |
+| `disabled` | `boolean` | from the field, or false | [slSwitch] | Unset rather than false, so the switch follows the field around it. A stated value wins. It is the native attribute, as is a disabled form control, which takes the switch out of the tab order and out of form submission. |
+| `readOnly` | `boolean` | from the field, or false | [slSwitch] | Unset rather than false. The native readonly attribute does nothing on a checkbox, so the switch sets aria-readonly and refuses every press. It stays focusable, announced and submitted. |
+| `invalid` | `boolean` | from the field, or false | [slSwitch] | Unset rather than false, so the switch follows the field around it. Writes aria-invalid on the control and data-invalid on the host, which draws the edge and the focus ring in the danger tone. |
+| `required` | `boolean` | — | [slSwitch] | The element’s own attribute, written on the host and passed through unchanged. A required field sets aria-required instead, and a switch that must be on takes Validators.requiredTrue in the form. |
+| `name / value` | `string` | — / on | [slSwitch] | What the switch submits when it is on. Nothing is submitted when it is off, as for a checkbox. |
+| `the host element` | `any element` | — | [slSwitch] | The box is the consumer’s own element, such as a span, a label or a list item, and the switch renders the control, the pill and the label into it. formControlName, id and every aria-* attribute written on the host reach the control. |
+| `ng-content` | `projected content` | — | [slSwitch] | The projected content is the label. slSwitchDescription is a directive on the consumer’s own element, so it can be a p, a span or an inline message. |
+| `exportAs` | `'slSwitch'` | — | a template | Reaches the instance: inputElement for focus(), and toggle(), which clicks the control and emits checkedChange with the reason "programmatic". |
+| `provideSwitchDefaults()` | `{ size, indicator, labelPlacement }` | — | an injector | Sets size, indicator and labelPlacement once for every switch under an injector. A field outranks the provided size, so a switch inside a field takes the field’s step. |
+| `SlField` | `injected, optional` | — | inside a field | What the switch reads from a field around it: the identifier, the description, and the disabled, read-only, invalid and required states. The switch needs no wiring inside a field. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `checkedChange` | `ChangeRequest<boolean>` | Before the switch moves. $event.value is the new state and $event.previous the state it replaces. $event.reason is "pointer" for a press, "keyboard" for Space or "programmatic" for toggle(). $event.source is the originating event, and $event.cancel() refuses the move before anything commits. There is no [(checked)] two-way binding, because it could carry none of these fields. |
+| `ControlValueAccessor` | `boolean` | Whenever the switch moves inside a form. formControlName and ngModel sit on the host. Writing the form value moves the switch, disabling the form control disables the input natively, and blur marks the control touched. A form reset shows the form model’s reset value. |
+| `click, change, focus, blur` | `the control’s own events` | Whenever the control fires them. A consumer’s (click) on the host still runs, because the switch listens on the input it renders and not on the host. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `indicator` | `mark`, `none` | `mark` |
+| `labelPlacement` | `end`, `start` | `end` |
+
+## Rules
+
+- The pattern is the Switch of the WAI-ARIA Authoring Practices, built as the third of its reference implementations: an input[type=checkbox] with role="switch". The platform supplies the rest: Space toggles it, the label names it and toggles it, name and value are submitted, form.reset() restores it, and a disabled fieldset disables it.
+- The switch writes no aria-checked. The Authoring Practices state that a switch built on a checkbox uses the HTML checked state instead, and writing both would state the value twice in two places that can disagree.
+- Enter does not toggle the switch. The Authoring Practices list Enter as optional, and inside a form Enter submits the form, which a switch bound to Enter would prevent. A reader who expects Enter presses Space.
+- The host carries no role, because ARIA makes the children of a switch presentational: the label and the description would otherwise join the control’s accessible name. The name of a switch does not change with its state, so the pending label is a live region and not part of the name.
+- A required field sets aria-required, never the native required, which would turn on browser constraint validation and change how the form submits. disabled is the native attribute. Read-only is aria-readonly plus a refused press, because the native readonly attribute does nothing on a checkbox.
+- The target is at least 24 CSS pixels in both axes at every size and every density, as WCAG 2.2 success criterion 2.5.8 requires. The label supplies the height when there is one, and a switch without a label sets the minimum on its own row.
+- The description is projected outside the label, so it describes the switch and does not name it, and a press on it changes nothing.
+
+## Tokens
+
+`--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-label-gap-lg`, `--slotted-control-label-gap-md`, `--slotted-control-label-gap-sm`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-loop`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-line-height-md`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-space-1`, `--slotted-space-3`, `--slotted-surface`, `--slotted-switch-active-background`, `--slotted-switch-border-color`, `--slotted-switch-checked-active-background`, `--slotted-switch-checked-background`, `--slotted-switch-checked-border-color`, `--slotted-switch-checked-hover-background`, `--slotted-switch-checked-thumb-border-color`, `--slotted-switch-color`, `--slotted-switch-description-color`, `--slotted-switch-description-font-size`, `--slotted-switch-disabled-background`, `--slotted-switch-disabled-border-color`, `--slotted-switch-disabled-color`, `--slotted-switch-disabled-mark-color`, `--slotted-switch-disabled-thumb-background`, `--slotted-switch-hover-background`, `--slotted-switch-invalid-border-color`, `--slotted-switch-invalid-edge-width`, `--slotted-switch-invalid-focus-ring-color`, `--slotted-switch-line-height`, `--slotted-switch-mark-color`, `--slotted-switch-pending-color`, `--slotted-switch-radius`, `--slotted-switch-readonly-background`, `--slotted-switch-readonly-border-color`, `--slotted-switch-thumb-background`, `--slotted-switch-thumb-border-color`, `--slotted-switch-thumb-shadow`, `--slotted-switch-track-background`, `--slotted-switch-track-inline-size`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-solid-active`, `--slotted-tone-secondary-solid-hover`
+
+## Examples
+
+### Playground
+
+One switch with every axis on it, driven by the controls below the canvas. Click the label as well as the pill: the label names the control and doubles its target.
+
+Excerpt — not a complete module
+
+```html
+<span slSwitch defaultChecked name="autopay">
+  Cobrança automática
+  <p slSwitchDescription>A fatura é debitada no dia 5 de cada mês.</p>
+</span>
+```
+
+### The step the control sits at
+
+Three steps, and inside a field the switch takes the field’s rather than its own: a small field holding a medium control is a field and a control disagreeing about one row.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-sizes',
+  imports: [SlStack, SlSwitch],
+  template: `
+    <div slStack [gap]="4">
+      <span slSwitch size="sm" defaultChecked>Show archived orders</span>
+      <span slSwitch size="md" defaultChecked>Group orders by warehouse</span>
+      <span slSwitch size="lg" defaultChecked>Print packing slips</span>
+    </div>
+  `,
+})
+export class SwitchSizes {}
+```
+
+### The mark inside the thumb
+
+On draws a check and off draws nothing, so the state is readable without colour and without comparing the thumb’s position to a switch you cannot see.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-indicator',
+  imports: [SlStack, SlSwitch, SlSwitchDescription],
+  template: `
+    <div slStack [gap]="5">
+      <span slSwitch defaultChecked>Accept backorders</span>
+      <span slSwitch [checked]="open()" indicator="none" (checkedChange)="open.set($event.value)">
+        Storefront
+        <p slSwitchDescription>
+          {{
+            open()
+              ? 'Open: customers can place orders.'
+              : 'Closed: customers see a maintenance page.'
+          }}
+        </p>
+      </span>
+    </div>
+  `,
+})
+export class SwitchIndicator {
+  protected readonly open = signal(true);
+}
+```
+
+### Which side the pill sits on
+
+start is the settings row every product writes: the label takes the free width, the pill sits at the end, and a column of rows ends with every pill at the same distance from the edge.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-placement',
+  imports: [SlStack, SlSwitch, SlSwitchDescription],
+  template: `
+    <div slStack [gap]="5">
+      <span slSwitch defaultChecked>
+        Email me a copy of each invoice
+        <p slSwitchDescription>Paid invoices arrive as PDF attachments.</p>
+      </span>
+      <span slSwitch labelPlacement="start">
+        Overdue reminders
+        <p slSwitchDescription>Unpaid invoices are flagged on the 5th day.</p>
+      </span>
+    </div>
+  `,
+})
+export class SwitchPlacement {}
+```
+
+### Help text under the label
+
+It is projected outside the label, so it describes the switch rather than naming it — and so a paragraph of help text does not change a setting when it is clicked.
+
+Excerpt — not a complete module
+
+```html
+<span slSwitch defaultChecked>
+  Cobrança automática
+  <p slSwitchDescription>A fatura é debitada no dia 5 de cada mês.</p>
+</span>
+```
+
+### The states the pill paints
+
+Read-only goes hollow and keeps its colour, because the value is real and still submitted; disabled goes grey and its knob goes with it, so a locked setting still says which way it is set.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-states',
+  imports: [SlStack, SlSwitch, SlSwitchDescription],
+  template: `
+    <div slStack [gap]="5">
+      <span slSwitch defaultChecked readOnly>
+        Two-step sign-in
+        <p slSwitchDescription>Your organization's security policy sets this.</p>
+      </span>
+      <span slSwitch defaultChecked disabled>
+        Audit log
+        <p slSwitchDescription>Included in the Business plan.</p>
+      </span>
+      <span slSwitch disabled>
+        Single sign-on
+        <p slSwitchDescription>Available on the Enterprise plan.</p>
+      </span>
+    </div>
+  `,
+})
+export class SwitchStates {}
+```
+
+### A setting that has not landed yet
+
+The thumb draws an arc where its mark was, the pill keeps its size so the row does not move, and a second press is refused before the DOM can show a state the server does not have.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+/** Stands in for the request that stores the setting. */
+const saveSetting = (on: boolean) =>
+  new Promise<boolean>((resolve) => setTimeout(() => resolve(on), 2500));
+
+@Component({
+  selector: 'app-switch-loading',
+  imports: [SlSwitch, SlSwitchDescription],
+  template: `
+    <span
+      slSwitch
+      [checked]="syncing()"
+      labelPlacement="start"
+      [loading]="saving()"
+      [messages]="{ loading: 'Saving order sync' }"
+      (checkedChange)="change($event.value)"
+    >
+      Order sync
+      <p slSwitchDescription>Imports new Shopify orders every five minutes.</p>
+    </span>
+  `,
+})
+export class SwitchLoading {
+  protected readonly syncing = signal(false);
+  protected readonly saving = signal(false);
+
+  protected async change(next: boolean) {
+    this.saving.set(true);
+    this.syncing.set(await saveSetting(next));
+    this.saving.set(false);
+  }
+}
+```
+
+### Inside a field
+
+The switch takes the description, the error and the four shared states without being asked, and it writes aria-required rather than the native attribute.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-field',
+  imports: [SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack, SlSwitch],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Backorders</label>
+        <span slSwitch>Accept orders when an item is out of stock</span>
+        <span slFieldDescription>Customers see the restock date at checkout.</span>
+      </div>
+      <div slField invalid>
+        <label slFieldLabel>Sales tax</label>
+        <span slSwitch defaultChecked>Collect tax on orders shipped to Nevada</span>
+        <span slFieldError>Add a Nevada tax ID before collecting tax there.</span>
+      </div>
+    </div>
+  `,
+})
+export class SwitchField {}
+```
+
+### A row on a settings page
+
+Where a switch actually lives: the label takes the free width, the pill sits at the end of the row, and the description sits under the label rather than under the pill.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCard, SlCardBody, SlCardHeader } from '@slotted/angular/card';
+import { SlDivider } from '@slotted/angular/divider';
+import { SlStack } from '@slotted/angular/stack';
+import { provideSwitchDefaults, SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+import { SlHeading, SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-switch-settings',
+  imports: [
+    SlCard,
+    SlCardBody,
+    SlCardHeader,
+    SlDivider,
+    SlHeading,
+    SlStack,
+    SlSwitch,
+    SlSwitchDescription,
+    SlText,
+  ],
+  providers: [provideSwitchDefaults({ labelPlacement: 'start' })],
+  template: `
+    <div slCard>
+      <div slCardHeader>
+        <h3 slHeading size="md">Warehouse notifications</h3>
+        <p slText size="sm" tone="muted">Sent to ops&#64;northwind.example.</p>
+      </div>
+      <div slCardBody>
+        <div slStack [gap]="4">
+          <span slSwitch defaultChecked>
+            Low stock
+            <p slSwitchDescription>When a product falls below its reorder point.</p>
+          </span>
+          <hr slDivider />
+          <span slSwitch defaultChecked>
+            Late pickups
+            <p slSwitchDescription>When a carrier misses its pickup window.</p>
+          </span>
+          <hr slDivider />
+          <span slSwitch>
+            Cycle count variances
+            <p slSwitchDescription>When a count differs from the system by more than 2%.</p>
+          </span>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class SwitchSettings {}
+```
+
+### What a consumer can replace
+
+The host element is the consumer’s own, an application sets the family’s defaults once, and a form reaches the value through the accessor rather than through an input.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideSwitchDefaults({ size: 'sm', labelPlacement: 'start' })],
+});
+
+// A switch that must be on is the form's rule, not the control's.
+new FormControl(false, Validators.requiredTrue);
+```
+
+### The keyboard
+
+Tab reaches the control and Space toggles it, both from the platform. Enter is deliberately not bound: inside a form it submits, and a switch that stole it would break the form.
+
+Excerpt — not a complete module
+
+```html
+<span slSwitch (checkedChange)="onRequest($event)">Receber a nota fiscal</span>
+
+<!-- $event.reason is "pointer", "keyboard" or "programmatic",
+     and $event.cancel() refuses the move before it commits. -->
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch, SlSwitchDescription } from '@slotted/angular/switch';
+
+@Component({
+  selector: 'app-switch-controlled',
+  imports: [SlStack, SlSwitch, SlSwitchDescription],
+  template: `
+    <div slStack [gap]="5">
+      <span
+        slSwitch
+        [checked]="paused()"
+        labelPlacement="start"
+        (checkedChange)="paused.set($event.value)"
+      >
+        Pause all alerts
+        <p slSwitchDescription>Turns off the alerts below until you resume.</p>
+      </span>
+      <div slStack [gap]="4">
+        <span slSwitch defaultChecked [disabled]="paused()" labelPlacement="start">New orders</span>
+        <span slSwitch defaultChecked [disabled]="paused()" labelPlacement="start">
+          Failed payments
+        </span>
+        <span slSwitch [disabled]="paused()" labelPlacement="start">Return requests</span>
+      </div>
+    </div>
+  `,
+})
+export class SwitchControlled {
+  protected readonly paused = signal(false);
+}
+```
+
+### form.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlSwitch } from '@slotted/angular/switch';
+import { SlText } from '@slotted/angular/typography';
+
+@Component({
+  selector: 'app-switch-form',
+  imports: [ReactiveFormsModule, SlButton, SlInline, SlStack, SlSwitch, SlText],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()" (reset)="submitted.set(null)">
+      <div slStack [gap]="4">
+        <span slSwitch formControlName="dailySummary" labelPlacement="start">
+          Daily sales summary
+        </span>
+        <span slSwitch formControlName="weeklyForecast" labelPlacement="start">
+          Weekly demand forecast
+        </span>
+        <span slSwitch formControlName="supplierDelays" labelPlacement="start">
+          Supplier delay report
+        </span>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save</button>
+          <button slButton type="reset" tone="secondary" variant="outline">Reset</button>
+          @if (submitted(); as names) {
+            <span slText size="sm" tone="muted">Submitted {{ names }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class SwitchForm {
+  protected readonly form = new FormGroup({
+    dailySummary: new FormControl(true, { nonNullable: true }),
+    weeklyForecast: new FormControl(false, { nonNullable: true }),
+    supplierDelays: new FormControl(true, { nonNullable: true }),
+  });
+  protected readonly submitted = signal<string | null>(null);
+
+  protected submit() {
+    const names = Object.entries(this.form.getRawValue())
+      .filter(([, on]) => on)
+      .map(([name]) => name);
+    this.submitted.set(names.length > 0 ? names.join(', ') : 'nothing');
+  }
+}
+```