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

package/docs/checkbox.json

@@ -0,0 +1,506 @@
+{
+  "family": "checkbox",
+  "ui": "checkbox",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Box that turns one option on or off."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "tile"
+    ],
+    "labelPlacement": [
+      "end",
+      "start"
+    ]
+  },
+  "members": {
+    "checkbox": {
+      "nativeElement": "input",
+      "defaults": {
+        "size": "md",
+        "variant": "plain",
+        "labelPlacement": "end",
+        "indeterminate": false,
+        "parent": false
+      },
+      "capabilities": [
+        "checked",
+        "size",
+        "appearance",
+        "placement",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "checked",
+        "indeterminate"
+      ],
+      "parts": [
+        "root",
+        "label",
+        "control",
+        "indicator",
+        "description"
+      ]
+    }
+  },
+  "docs": {
+    "checkbox": {
+      "imports": {
+        "source": "import {\n  provideCheckboxDefaults,\n  SlCheckbox,\n  SlCheckboxDescription,\n} from '@slotted/angular/checkbox';",
+        "selector": "[slCheckbox]",
+        "exportAs": "slCheckbox"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slCheckbox",
+          "required": true,
+          "purpose": "The two-column grid: the box in one column, the label and the description in the other. It carries data-ui=\"checkbox\", data-size, data-variant and data-label-placement, and data-checked, data-indeterminate, data-disabled, data-invalid and data-readonly. It has no role, so the native control is the only element announced. Write formControlName, formControl or ngModel on this element."
+        },
+        {
+          "part": "control",
+          "element": "input type=\"checkbox\", in the component’s template",
+          "required": true,
+          "purpose": "The native checkbox. It holds the value, the name and the identifier, and draws the box itself with appearance: none. The element belongs to the component’s template, so reach it through exportAs: box.inputElement gives focus() and click()."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": true,
+          "purpose": "The mark, drawn over the control as a mask from the glyph scale: a check when checked, a dash when mixed. It is a sibling element rather than a pseudo-element, because Firefox renders neither ::before nor ::after on an input. It takes no pointer events, so every press reaches the control underneath."
+        },
+        {
+          "part": "label",
+          "element": "label, in the component’s template",
+          "required": false,
+          "purpose": "Names the control through for. Its content is the default ng-content slot, so everything you project becomes the accessible name. It carries the target and the hover wash: a 24-pixel square around the box, and a wash behind the box and the text that extends half the control gap past the box and half as far again past the text. It is as wide as its text, so the empty space beside it does not toggle the box. It renders when nothing is projected too, and the wash then closes around the box. When the projected content is only an element with slVisuallyHidden, as for a box in a table row, the root carries data-label-hidden and the wash closes the same way."
+        },
+        {
+          "part": "description",
+          "element": "the element carrying slCheckboxDescription",
+          "required": false,
+          "purpose": "Help text under the label, projected into a slot outside the label and referenced by aria-describedby. It sits outside the label: inside, it would join the accessible name, and a press on it would toggle the value."
+        }
+      ],
+      "api": [
+        {
+          "name": "checked",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "defaultChecked",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "indeterminate",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "parent",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "SlCheckbox, provideCheckboxDefaults",
+          "description": "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."
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'tile'",
+          "defaultValue": "plain",
+          "appliesTo": "SlCheckbox, provideCheckboxDefaults",
+          "description": "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."
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'end' | 'start'",
+          "defaultValue": "end",
+          "appliesTo": "SlCheckbox, provideCheckboxDefaults",
+          "description": "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."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the form control, group or field, or false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the group or field, or false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the group or field, or false",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "the host element",
+          "description": "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": "name / value",
+          "type": "string",
+          "defaultValue": "— / on",
+          "appliesTo": "SlCheckbox",
+          "description": "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."
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs=\"slCheckbox\"",
+          "type": "SlCheckbox",
+          "defaultValue": "—",
+          "appliesTo": "a template",
+          "description": "Reaches the component instance. Its inputElement is the input, whose own focus() and click() methods move focus and toggle the box."
+        },
+        {
+          "name": "slCheckboxDescription",
+          "type": "directive",
+          "defaultValue": "—",
+          "appliesTo": "a projected element",
+          "description": "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."
+        },
+        {
+          "name": "provideCheckboxDefaults()",
+          "type": "{ size, variant, labelPlacement }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "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."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "type": "formControl, formControlName, ngModel",
+          "defaultValue": "—",
+          "appliesTo": "the host element",
+          "description": "Write the form binding on the root, beside slCheckbox. A disabled form control disables the box, and blur marks the control touched."
+        },
+        {
+          "name": "the host element",
+          "type": "any element",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckbox",
+          "description": "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": "(checkedChange)",
+          "payload": "ChangeRequest<boolean>",
+          "when": "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."
+        },
+        {
+          "name": "ControlValueAccessor",
+          "payload": "boolean",
+          "when": "Whenever the box moves under a formControl, formControlName or ngModel written on the root. The form receives the new state without listening to (checkedChange)."
+        }
+      ],
+      "accessibility": [
+        "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": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One box with every axis on it, driven by the controls below the canvas. Click the label, not only the box: the target runs from the square to the end of the text.",
+      "language": "html",
+      "source": "<div slCheckbox defaultChecked>\n  Enviar recibo\n  <p slCheckboxDescription>Enviaremos o recibo por e-mail.</p>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "The step the box sits at",
+      "note": "The square is the control glyph scale, so the three steps shrink together with the type and the gap when the toolbar switches to dense — and the label keeps its 24-pixel target at every one of them.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-sizes',\n  imports: [SlCheckbox, SlStack],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slCheckbox size=\"sm\" defaultChecked>Show archived orders</div>\n      <div slCheckbox size=\"md\" defaultChecked>Notify the warehouse</div>\n      <div slCheckbox size=\"lg\" defaultChecked>Remember this device</div>\n    </div>\n  `,\n})\nexport class CheckboxSizes {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tile",
+      "title": "The choice as a framed surface",
+      "note": "Click anywhere inside a tile, not only the box: the label’s hit area stretches over the whole surface, so the target is the frame. Chosen says it with a two-pixel accent edge as well as a tint, because the high-contrast scheme flattens every tint to white and only the width survives.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlGrid } from '@slotted/angular/grid';\n\n@Component({\n  selector: 'app-checkbox-tile',\n  imports: [SlCheckbox, SlCheckboxDescription, SlGrid],\n  template: `\n    <div slGrid [gap]=\"4\" minItemWidth=\"sm\">\n      <div slCheckbox variant=\"tile\" defaultChecked>\n        Daily backup\n        <p slCheckboxDescription>One copy a day, kept for 30 days.</p>\n      </div>\n      <div slCheckbox variant=\"tile\">\n        Audit log\n        <p slCheckboxDescription>Who changed what, and when, exported as CSV.</p>\n      </div>\n      <div slCheckbox variant=\"tile\" disabled>\n        Secondary region\n        <p slCheckboxDescription>Available on the Scale plan.</p>\n      </div>\n    </div>\n  `,\n})\nexport class CheckboxTile {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "Every state the box paints",
+      "note": "Read-only keeps full-strength ink, its ring and its tab stop, because the value is real and still submitted; disabled loses all three. Invalid thickens the border as well as reddening it, because the high-contrast scheme paints every border the same black.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-states',\n  imports: [SlCheckbox, SlCheckboxDescription, SlStack],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slCheckbox readOnly defaultChecked>\n        Tax exempt\n        <p slCheckboxDescription>Set by the customer's tax certificate.</p>\n      </div>\n      <div slCheckbox disabled>\n        Same-day delivery\n        <p slCheckboxDescription>Not offered from the Seattle warehouse.</p>\n      </div>\n      <div slCheckbox invalid>\n        I counted every item on shelf A-14\n        <p slCheckboxDescription>Confirm the count before closing the cycle.</p>\n      </div>\n    </div>\n  `,\n})\nexport class CheckboxStates {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "indeterminate",
+      "title": "The mixed state, and the box that commands a set",
+      "note": "Mixed is a state and never a third value: the form still submits a boolean. Tick the parent and the whole set follows; untick one child and the parent goes back to the dash on its own.",
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlText } from '@slotted/angular/typography';\n\nfunction summary(taxable: boolean | 'mixed'): string {\n  if (taxable === 'mixed') return 'Taxed on 2 of the 3 selected products.';\n  return taxable\n    ? 'All 3 selected products will be taxed.'\n    : 'None of the 3 selected products will be taxed.';\n}\n\n@Component({\n  selector: 'app-checkbox-indeterminate',\n  imports: [SlCheckbox, SlCheckboxDescription, SlStack, SlText],\n  template: `\n    <div slStack [gap]=\"3\">\n      <span slText weight=\"medium\">Edit 3 products</span>\n      <div\n        slCheckbox\n        [checked]=\"taxable() === true\"\n        [indeterminate]=\"taxable() === 'mixed'\"\n        (checkedChange)=\"taxable.set($event.value)\"\n      >\n        Taxable\n        <p slCheckboxDescription>{{ summary() }}</p>\n      </div>\n    </div>\n  `,\n})\nexport class CheckboxIndeterminate {\n  readonly taxable = signal<boolean | 'mixed'>('mixed');\n  readonly summary = computed(() => summary(this.taxable()));\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "placement",
+      "title": "Which side of its label the box is on",
+      "note": "start pushes the box to the end of the row, which is where a settings list puts a control — and it is why the column is a fraction rather than the label’s own width: five boxes have to line up with each other.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-placement',\n  imports: [SlCheckbox, SlStack],\n  template: `\n    <div slStack [gap]=\"3\">\n      <div slCheckbox labelPlacement=\"start\" defaultChecked>Email when an order ships</div>\n      <div slCheckbox labelPlacement=\"start\">Email when stock runs low</div>\n      <div slCheckbox labelPlacement=\"start\" defaultChecked>Weekly sales digest</div>\n    </div>\n  `,\n})\nexport class CheckboxPlacement {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "description",
+      "title": "Saying more than the label does",
+      "note": "The description aligns under the label rather than under the box, in both placements and both writing directions, and it is announced as the control’s description rather than as part of its name.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-description',\n  imports: [SlCheckbox, SlCheckboxDescription, SlStack],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slCheckbox defaultChecked>\n        Email me when a payment fails\n        <p slCheckboxDescription>One message per failed payment, sent to the billing contact.</p>\n      </div>\n      <div slCheckbox>\n        Send a daily summary instead\n        <p slCheckboxDescription>\n          Sent at 08:00 in the account's time zone, and skipped on days with no failures.\n        </p>\n      </div>\n    </div>\n  `,\n})\nexport class CheckboxDescription {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "field",
+      "title": "Inside a field, and in a reactive form",
+      "note": "The box reads the field for its step and its four shared states and never for its identifier, and the same element is where formControlName goes — the value accessor is on the root.",
+      "language": "html",
+      "source": "<fieldset slFieldGroup required>\n  <legend slFieldGroupLegend>Notificações</legend>\n  <div slCheckboxGroup name=\"alerts\" formControlName=\"alerts\">\n    <div slCheckbox value=\"approved\">Pedido aprovado</div>\n    <div slCheckbox value=\"refused\">Pedido recusado</div>\n  </div>\n</fieldset>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A label that wraps to three lines keeps the box on the first of them rather than in the middle of the block, an unbroken token breaks instead of taking the page with it, and a right-to-left label mirrors the whole row.",
+      "language": "html",
+      "source": "<div slCheckbox>\n  Concordo em receber comunicações sobre alterações contratuais e prazos de entrega.\n  <p slCheckboxDescription>A caixa continua na primeira linha do rótulo.</p>\n</div>\n\n<div slCheckbox dir=\"rtl\">أوافق على تلقي رسائل حول التغييرات في العقد.</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "The token carries the two decisions an application takes once, exportAs reaches the instance and the native element behind it, and the root is the consumer’s own element rather than one the family renders.",
+      "language": "html",
+      "source": "<!-- exportAs reaches the instance; inputElement reaches the input,\n     which already has focus() and click(). -->\n<div slCheckbox #box=\"slCheckbox\">Uma caixa</div>\n<button type=\"button\" (click)=\"box.inputElement.focus()\">Focar</button>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and who implements it",
+      "note": "Space toggles and Enter submits the form, and neither is a listener this family writes: the control is a native checkbox, so the whole table is the platform’s and arrives translated and mirrored for free.",
+      "language": "html",
+      "source": "<!-- Space and a pointer arrive as one click. A click synthesised by the\n     keyboard reports no detail, which is how the reason is told apart\n     without a key listener existing anywhere in the family. -->\n<div slCheckbox (checkedChange)=\"log($event.reason)\">Marque com o teclado</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-basic',\n  imports: [SlCheckbox, SlStack],\n  template: `\n    <div slStack [gap]=\"3\">\n      <div slCheckbox defaultChecked>Email the invoice to the customer</div>\n      <div slCheckbox defaultChecked>Include a packing slip</div>\n      <div slCheckbox>Gift-wrap the order</div>\n    </div>\n  `,\n})\nexport class CheckboxBasic {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlField, SlFieldLabel } from '@slotted/angular/field';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';\n\n@Component({\n  selector: 'app-checkbox-controlled',\n  imports: [\n    SlCheckbox,\n    SlCheckboxDescription,\n    SlField,\n    SlFieldLabel,\n    SlStack,\n    SlTextField,\n    SlTextFieldInput,\n  ],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slCheckbox [checked]=\"sameAddress()\" (checkedChange)=\"sameAddress.set($event.value)\">\n        Bill to the shipping address\n        <p slCheckboxDescription>Ships to 12 Orchestra Terrace, Walla Walla, WA 99362.</p>\n      </div>\n      @if (!sameAddress()) {\n        <div slField required>\n          <label slFieldLabel>Billing address</label>\n          <div slTextField>\n            <input slTextFieldInput autocomplete=\"billing street-address\" />\n          </div>\n        </div>\n      }\n    </div>\n  `,\n})\nexport class CheckboxControlled {\n  readonly sameAddress = signal(true);\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { provideCheckboxDefaults, SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-defaults',\n  imports: [SlCheckbox, SlStack],\n  providers: [provideCheckboxDefaults({ size: 'sm', labelPlacement: 'start' })],\n  template: `\n    <div slStack [gap]=\"2\">\n      <div slCheckbox defaultChecked>Show prices with tax</div>\n      <div slCheckbox>Show discontinued products</div>\n      <div slCheckbox defaultChecked>Group orders by customer</div>\n    </div>\n  `,\n})\nexport class CheckboxDefaults {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "form",
+      "title": "form.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlText } from '@slotted/angular/typography';\n\n@Component({\n  selector: 'app-checkbox-form',\n  imports: [SlButton, SlCheckbox, SlFieldGroup, SlFieldGroupLegend, SlInline, SlStack, SlText],\n  template: `\n    <form (submit)=\"submit($event)\" (reset)=\"saved.set(null)\">\n      <div slStack [gap]=\"4\">\n        <fieldset slFieldGroup>\n          <legend slFieldGroupLegend>Reports emailed each morning</legend>\n          <div slStack [gap]=\"2\">\n            <div slCheckbox name=\"reports\" value=\"daily-sales\" defaultChecked>Daily sales</div>\n            <div slCheckbox name=\"reports\" value=\"low-stock\">Low stock</div>\n            <div slCheckbox name=\"reports\" value=\"payouts\" defaultChecked>Payouts</div>\n          </div>\n        </fieldset>\n        <div slInline [gap]=\"3\" align=\"center\">\n          <button slButton type=\"submit\">Save</button>\n          <button slButton type=\"reset\" variant=\"outline\" tone=\"secondary\">Reset</button>\n        </div>\n        <span slText size=\"sm\" tone=\"muted\" role=\"status\">\n          {{ saved() === null ? '' : 'Submitted reports: ' + saved() + '.' }}\n        </span>\n      </div>\n    </form>\n  `,\n})\nexport class CheckboxForm {\n  readonly saved = signal<string | null>(null);\n\n  submit(event: SubmitEvent): void {\n    event.preventDefault();\n    const reports = new FormData(event.target as HTMLFormElement).getAll('reports');\n    this.saved.set(reports.length === 0 ? 'none' : reports.join(', '));\n  }\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "hidden-label",
+      "title": "hidden-label.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\nimport { SlText } from '@slotted/angular/typography';\nimport { SlVisuallyHidden } from '@slotted/angular/visually-hidden';\n\n@Component({\n  selector: 'app-checkbox-hidden-label',\n  imports: [SlCheckbox, SlInline, SlStack, SlText, SlVisuallyHidden],\n  template: `\n    <div slStack [gap]=\"2\">\n      @for (invoice of invoices; track invoice.id) {\n        <div slInline [gap]=\"3\" align=\"center\">\n          <div slCheckbox size=\"sm\" [value]=\"invoice.id\">\n            <span slVisuallyHidden>Select {{ invoice.id }}</span>\n          </div>\n          <span slText numeric=\"tabular\">{{ invoice.id }}</span>\n          <span slText tone=\"muted\">{{ invoice.customer }}</span>\n          <span slText numeric=\"tabular\">{{ invoice.amount }}</span>\n        </div>\n      }\n    </div>\n  `,\n})\nexport class CheckboxHiddenLabel {\n  readonly invoices = [\n    { id: 'INV-1042', customer: 'Alfreds Futterkiste', amount: '$1,250.00' },\n    { id: 'INV-1043', customer: 'Ernst Handel', amount: '$4,318.40' },\n    { id: 'INV-1044', customer: 'Island Trading', amount: '$872.15' },\n  ];\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "long-label",
+      "title": "long-label.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-long-label',\n  imports: [SlCheckbox, SlCheckboxDescription, SlStack],\n  template: `\n    <div slStack [gap]=\"4\">\n      <div slCheckbox defaultChecked>\n        Send notices about contract changes, delivery deadlines and changes to the return policy for\n        this store and every other store in the group\n        <p slCheckboxDescription>Notices go to the billing contact on the account.</p>\n      </div>\n      <div slCheckbox>\n        Forward order events to https://hooks.northwind.example/orders/fulfilment-updates\n      </div>\n    </div>\n  `,\n})\nexport class CheckboxLongLabel {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "parent",
+      "title": "parent.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\n\n@Component({\n  selector: 'app-checkbox-parent',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Delivery days</legend>\n      <div\n        slCheckboxGroup\n        [allValues]=\"weekdays\"\n        [defaultValue]=\"['mon', 'wed', 'fri']\"\n        name=\"days\"\n      >\n        <div slCheckbox parent>Every weekday</div>\n        <div slCheckbox value=\"mon\">Monday</div>\n        <div slCheckbox value=\"tue\">Tuesday</div>\n        <div slCheckbox value=\"wed\">Wednesday</div>\n        <div slCheckbox value=\"thu\">Thursday</div>\n        <div slCheckbox value=\"fri\">Friday</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxParent {\n  readonly weekdays = ['mon', 'tue', 'wed', 'thu', 'fri'];\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport { toSignal } from '@angular/core/rxjs-interop';\nimport { FormControl, ReactiveFormsModule, Validators } from '@angular/forms';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlField, SlFieldError } from '@slotted/angular/field';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-validation',\n  imports: [ReactiveFormsModule, SlButton, SlCheckbox, SlField, SlFieldError, SlInline, SlStack],\n  template: `\n    <form novalidate (submit)=\"submit($event)\">\n      <div slStack [gap]=\"4\">\n        <div slField required [invalid]=\"error() !== '' ? true : undefined\">\n          <div slCheckbox [formControl]=\"terms\" (checkedChange)=\"placed.set(false)\">\n            I accept the supplier terms for this purchase order\n          </div>\n          <span slFieldError live=\"polite\" reserve>{{ error() }}</span>\n        </div>\n        <div slInline [gap]=\"3\" align=\"center\">\n          <button slButton type=\"submit\">Place order</button>\n          @if (placed()) {\n            <span role=\"status\">Order placed.</span>\n          }\n        </div>\n      </div>\n    </form>\n  `,\n})\nexport class CheckboxValidation {\n  readonly terms = new FormControl(false, {\n    nonNullable: true,\n    validators: Validators.requiredTrue,\n  });\n  readonly accepted = toSignal(this.terms.valueChanges, { initialValue: this.terms.value });\n  readonly submitted = signal(false);\n  readonly placed = signal(false);\n  readonly error = computed(() =>\n    this.submitted() && !this.accepted() ? 'Accept the supplier terms to place the order.' : '',\n  );\n\n  submit(event: Event): void {\n    event.preventDefault();\n    this.submitted.set(true);\n    this.placed.set(this.terms.valid);\n  }\n}\n",
+      "verdict": "example"
+    }
+  ]
+}