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

package/docs/checkbox.md

@@ -0,0 +1,104 @@
+<!-- index: ./index.md -->
+# checkbox
+
+`data-ui="checkbox"` · Box that turns one option on or off.
+
+## Import
+
+```ts
+import {
+  provideCheckboxDefaults,
+  SlCheckbox,
+  SlCheckboxDescription,
+} from '@slotted/angular/checkbox';
+```
+
+Selector: `[slCheckbox]` · exportAs: `slCheckbox`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlStack } from '@slotted/angular/stack';
+
+@Component({
+  selector: 'app-checkbox-basic',
+  imports: [SlCheckbox, SlStack],
+  template: `
+    <div slStack [gap]="3">
+      <div slCheckbox defaultChecked>Email the invoice to the customer</div>
+      <div slCheckbox defaultChecked>Include a packing slip</div>
+      <div slCheckbox>Gift-wrap the order</div>
+    </div>
+  `,
+})
+export class CheckboxBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slCheckbox | yes |
+| `control` | input type="checkbox", in the component’s template | yes |
+| `indicator` | span | yes |
+| `label` | label, in the component’s template | no |
+| `description` | the element carrying slCheckboxDescription | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `checked` | `boolean` | — | SlCheckbox | Makes the state controlled. Without it the box keeps its own state, starting from defaultChecked, and a native form reset restores defaultChecked. Inside a checkbox group, the group’s selection decides instead. |
+| `defaultChecked` | `boolean` | false | SlCheckbox | The state an uncontrolled box starts from. It is read once, when the component initialises, and written to the input as the native attribute, which is what a form reset returns to. |
+| `indeterminate` | `boolean` | false | SlCheckbox | The mixed state, drawn as a dash and announced as mixed. It is a state, not a third value of checked: the submitted value stays boolean, because indeterminate is a DOM property that leaves checked unchanged. |
+| `parent` | `boolean` | false | SlCheckbox | Makes the box command the set its checkbox group lists in allValues. It is checked when every value is selected and mixed when some are, and a press selects or clears the whole set. Outside a group with allValues it has no effect. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlCheckbox, provideCheckboxDefaults | The step of the control scale. When unset, the box takes the size of its checkbox group, then of its field or field group, then of the provided defaults. The theme restates the scale per density. |
+| `variant` | `'plain' \| 'tile'` | plain | SlCheckbox, provideCheckboxDefaults | How the choice is drawn. tile frames it and makes the whole surface the target; the label still names the control, so the keyboard and the accessible name are unchanged. When unset, the box takes the variant of its checkbox group, then of the provided defaults. |
+| `labelPlacement` | `'end' \| 'start'` | end | SlCheckbox, provideCheckboxDefaults | Which side of its label the box sits on. When unset, the box takes the placement of its checkbox group, then of the provided defaults. It is never read from a field, whose labelPlacement places the field’s own label. |
+| `disabled` | `boolean` | from the form control, group or field, or false | SlCheckbox | Unset rather than false, so the box follows a disabled form control, then its checkbox group or field. Written to the input as the native attribute, which removes the box from the tab order and from form submission. |
+| `readOnly` | `boolean` | from the group or field, or false | SlCheckbox | Unset rather than false. A native checkbox has no readonly, so SlCheckbox refuses every change and writes aria-readonly. The box keeps its tab stop, its focus ring and its contrast, and its value is still submitted. |
+| `invalid` | `boolean` | from the group or field, or false | SlCheckbox | Unset rather than false. Writes aria-invalid on the input and data-invalid on the root, which draws a thicker border in the danger tone. |
+| `required` | `boolean` | — | the host element | The native attribute, read once as a static attribute and passed to the input unchanged; SlCheckbox never writes it. A field marks necessity with aria-required instead, because the native attribute turns on browser constraint validation. |
+| `name / value` | `string` | — / on | SlCheckbox | The native submission pair: a checked box submits value under name. Inside a checkbox group, a box without a name takes the group’s, and value is the entry the group’s selection holds. |
+| `exportAs="slCheckbox"` | `SlCheckbox` | — | a template | Reaches the component instance. Its inputElement is the input, whose own focus() and click() methods move focus and toggle the box. |
+| `slCheckboxDescription` | `directive` | — | a projected element | Marks the description, projected outside the label. It goes on your own element, so a p, a span or an inline message keeps its semantics. |
+| `provideCheckboxDefaults()` | `{ size, variant, labelPlacement }` | — | an injector | Sets size, variant and labelPlacement once for every box the injector reaches; the nearest provider wins. A box that states a value keeps it. A checkbox group around the box outranks the defaults for all three, and a field or field group outranks them for size. |
+| `ControlValueAccessor` | `formControl, formControlName, ngModel` | — | the host element | Write the form binding on the root, beside slCheckbox. A disabled form control disables the box, and blur marks the control touched. |
+| `the host element` | `any element` | — | SlCheckbox | The element you write slCheckbox on is the root, so you choose its tag: a div, a li or a label of your own. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(checkedChange)` | `ChangeRequest<boolean>` | Before the box moves. value is the new state and previous the state it replaces. reason is pointer or keyboard, read from the click’s detail, and source is the originating event. cancel() refuses the change before anything commits, including the platform’s own toggle. There is no [(checked)], because a two-way binding carries only the value. |
+| `ControlValueAccessor` | `boolean` | Whenever the box moves under a formControl, formControlName or ngModel written on the root. The form receives the new state without listening to (checkedChange). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `tile` | `plain` |
+| `labelPlacement` | `end`, `start` | `end` |
+
+## Rules
+
+- SlCheckbox follows the WAI-ARIA Authoring Practices checkbox pattern (w3.org/WAI/ARIA/apg/patterns/checkbox/), and the native input supplies every part of it: the role, the checked and mixed states, Space to toggle, Enter left to the form, and disabled behaviour. SlCheckbox adds no key listener, so the keyboard behaviour is the platform’s in every language and in right-to-left documents.
+- The label names the control through for, which points at an identifier SlCheckbox generates unless you write a static id on the host. The description is projected outside the label and reaches the control through aria-describedby, so it is read as a description, and a press on it toggles nothing.
+- Inside a required field the control carries aria-required, never the native required, because the native attribute turns on browser constraint validation and changes how the form submits. Write required on the host to opt into the platform’s validation; it is read as a static attribute and passed through unchanged. disabled is the native attribute.
+- A native checkbox has no read-only state, so SlCheckbox enforces one: it refuses the click that a pointer and Space both produce, and aria-readonly announces the state. The box keeps its tab stop, its focus ring and its full contrast, because a read-only value is real and must not look disabled.
+- A refused change is undone by the platform, not by SlCheckbox. The HTML standard undoes a cancelled checkbox click by inverting checked again, so SlCheckbox cancels the click’s default action instead of writing the element; a controlled box therefore shows the value its consumer holds.
+- The invalid state does not rely on colour alone. In the high-contrast scheme the theme paints every border the same colour, so an invalid box also draws a thicker border. The message that says what is wrong belongs to the field or field group.
+- The target is larger than the box. A 24-pixel square around the box meets WCAG 2.2 success criterion 2.5.8 at every size and density, including size="sm", where the box is 14 pixels. The label extends the target to the end of its text, and the hover wash covers exactly that area. The target is drawn around the box, so the row keeps its line height.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-checkbox-active-background`, `--slotted-checkbox-background`, `--slotted-checkbox-border-color`, `--slotted-checkbox-border-width`, `--slotted-checkbox-checked-active-background`, `--slotted-checkbox-checked-background`, `--slotted-checkbox-checked-border-color`, `--slotted-checkbox-checked-hover-background`, `--slotted-checkbox-color`, `--slotted-checkbox-description-color`, `--slotted-checkbox-description-font-size`, `--slotted-checkbox-disabled-background`, `--slotted-checkbox-disabled-border-color`, `--slotted-checkbox-disabled-color`, `--slotted-checkbox-disabled-mark-color`, `--slotted-checkbox-halo-color`, `--slotted-checkbox-hover-border-color`, `--slotted-checkbox-invalid-border-color`, `--slotted-checkbox-invalid-checked-background`, `--slotted-checkbox-invalid-edge-width`, `--slotted-checkbox-invalid-focus-ring-color`, `--slotted-checkbox-line-height`, `--slotted-checkbox-mark-color`, `--slotted-checkbox-mark-inset`, `--slotted-checkbox-radius`, `--slotted-checkbox-readonly-background`, `--slotted-checkbox-size`, `--slotted-checkbox-tile-active-background`, `--slotted-checkbox-tile-background`, `--slotted-checkbox-tile-border-color`, `--slotted-checkbox-tile-checked-background`, `--slotted-checkbox-tile-checked-border-color`, `--slotted-checkbox-tile-checked-hover-border-color`, `--slotted-checkbox-tile-description-gap`, `--slotted-checkbox-tile-disabled-background`, `--slotted-checkbox-tile-disabled-border-color`, `--slotted-checkbox-tile-hover-background`, `--slotted-checkbox-tile-hover-border-color`, `--slotted-checkbox-tile-inset`, `--slotted-checkbox-tile-invalid-border-color`, `--slotted-checkbox-tile-invalid-checked-background`, `--slotted-checkbox-tile-invalid-checked-border-color`, `--slotted-checkbox-tile-radius`, `--slotted-checkbox-tile-readonly-background`, `--slotted-checkbox-tile-readonly-border-color`, `--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-invalid-edge-width`, `--slotted-control-label-gap-lg`, `--slotted-control-label-gap-md`, `--slotted-control-label-gap-sm`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-shadow`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--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-md`, `--slotted-radius-xs`, `--slotted-selection-halo-opacity`, `--slotted-selection-size-lg`, `--slotted-selection-size-md`, `--slotted-selection-size-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-active`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [checkbox.examples.md](./checkbox.examples.md).