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

package/docs/checkbox-group.json

@@ -0,0 +1,395 @@
+{
+  "family": "checkbox-group",
+  "ui": "checkbox-group",
+  "binding": "angular",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Set of checkboxes under one label."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "variant": [
+      "plain",
+      "tile"
+    ],
+    "orientation": [
+      "vertical",
+      "horizontal"
+    ],
+    "labelPlacement": [
+      "end",
+      "start"
+    ]
+  },
+  "members": {
+    "checkboxGroup": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "variant": "plain",
+        "orientation": "vertical",
+        "labelPlacement": "end",
+        "showCount": false
+      },
+      "capabilities": [
+        "selection",
+        "orientation",
+        "size",
+        "appearance",
+        "placement",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "disabled",
+        "readonly",
+        "invalid"
+      ],
+      "parts": [
+        "root"
+      ]
+    }
+  },
+  "docs": {
+    "checkboxGroup": {
+      "imports": {
+        "source": "import {\n  provideCheckboxGroupDefaults,\n  SlCheckboxGroup,\n} from '@slotted/angular/checkbox-group';",
+        "selector": "[slCheckboxGroup]",
+        "exportAs": "slCheckboxGroup"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element carrying slCheckboxGroup",
+          "required": true,
+          "purpose": "The only part. It arranges the boxes, holds the selection, and carries data-ui=\"checkbox-group\", data-size, data-variant and data-orientation, and data-disabled, data-invalid and data-readonly. Its role is group; inside a field group the role is withdrawn, because the fieldset and its legend already name the set. Inside a field, aria-labelledby points at the field’s label. The value accessor and the validator are on this element, so formControlName goes here too."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "The controlled selection. When present, the consumer owns the selection. When absent, the checkbox group owns it and starts from defaultValue, or from the form control bound to the root."
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "defaultValue": "[]",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "The selection an uncontrolled group starts from, read once when the directive initialises."
+        },
+        {
+          "name": "allValues",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Every value the checkbox group holds. A parent slCheckbox needs it: the parent is checked when every value is selected and mixed when some are, which a selection alone cannot tell. It also keeps the selection in the order of this list rather than in the order the boxes were pressed."
+        },
+        {
+          "name": "variant",
+          "type": "'plain' | 'tile'",
+          "defaultValue": "plain",
+          "appliesTo": "SlCheckboxGroup, provideCheckboxGroupDefaults",
+          "description": "How every choice is drawn, passed to every box. tile frames each choice and makes its whole surface the target. Arranging the tiles is left to slGrid."
+        },
+        {
+          "name": "orientation",
+          "type": "'vertical' | 'horizontal'",
+          "defaultValue": "vertical",
+          "appliesTo": "SlCheckboxGroup, provideCheckboxGroupDefaults",
+          "description": "How the choices flow. A horizontal set wraps instead of scrolling."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "SlCheckboxGroup, provideCheckboxGroupDefaults",
+          "description": "The type step, passed to every box. A field or field group around the checkbox group decides it first, then the provider."
+        },
+        {
+          "name": "labelPlacement",
+          "type": "'end' | 'start'",
+          "defaultValue": "end",
+          "appliesTo": "SlCheckboxGroup, provideCheckboxGroupDefaults",
+          "description": "Which side of its label each box is on, set once for the set so the boxes line up."
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "The submission name every box shares when it sets none of its own. No name is generated: the platform does not group checkboxes by name the way it groups radios."
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Unset rather than false. Reaches every box as the native attribute. A disabled form control sets it too, through setDisabledState."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Unset rather than false. Every box keeps its tab stop, its focus ring and its contrast, writes aria-readonly, and refuses every change."
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Unset rather than false. Writes aria-invalid on the group and on every box, and data-invalid on the group’s root and on every box’s root."
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Unset rather than false. Writes aria-required on the group, and makes the group’s validator fail while the selection is empty. It is never the native required, which on a checkbox would demand that one particular box be checked."
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "Inside a field, draws how many of allValues are selected at the end of the field’s label row, as 2/4, and adds that count to the group’s accessible description."
+        }
+      ],
+      "composition": [
+        {
+          "name": "exportAs=\"slCheckboxGroup\"",
+          "type": "SlCheckboxGroup",
+          "defaultValue": "—",
+          "appliesTo": "a template",
+          "description": "Reaches the instance, with the resolved axes and the selection for a template to read."
+        },
+        {
+          "name": "ControlValueAccessor and Validator",
+          "type": "formControl, formControlName, ngModel",
+          "defaultValue": "—",
+          "appliesTo": "the host element",
+          "description": "Both are on the root, so a form binding goes on the element that carries slCheckboxGroup. required becomes a validator over the whole selection."
+        },
+        {
+          "name": "provideCheckboxGroupDefaults()",
+          "type": "{ size, variant, orientation, labelPlacement }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "The four decisions an application takes once for every checkbox group under it. A field or field group around a checkbox group decides size before the provider."
+        },
+        {
+          "name": "the host element",
+          "type": "any element",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckboxGroup",
+          "description": "The host element is the root, so a set of choices can be a ul with each box written as an li."
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "defaultValue": "group, or none inside a field group",
+          "appliesTo": "the host element",
+          "description": "A role written as a static attribute on the host wins. Otherwise the role is group, withdrawn inside a field group, because a fieldset with a legend is already a named group and a second group named by the same legend announces the set twice."
+        },
+        {
+          "name": "aria-label / aria-labelledby",
+          "type": "string",
+          "defaultValue": "the field’s label, inside a field",
+          "appliesTo": "the host element",
+          "description": "Names the group. Inside a field, aria-labelledby points at the field’s label unless either attribute is written as a static attribute on the host. Outside a field and a field group, write one of them, because a group needs a name."
+        }
+      ],
+      "events": [
+        {
+          "name": "(valueChange)",
+          "payload": "ChangeRequest<readonly string[]>",
+          "when": "Before the selection moves. $event.value is the new array and $event.previous the array it replaces. $event.reason is pointer or keyboard, recovered from the box’s click; $event.source is the originating event; $event.cancel() refuses the move before anything commits. There is no [(value)], because a two-way binding carries only the value and none of the rest."
+        },
+        {
+          "name": "ControlValueAccessor and Validator",
+          "payload": "readonly string[]",
+          "when": "Whenever the selection moves under a formControl, formControlName or ngModel bound on the root. The checkbox group also validates the selection: when required, an empty selection fails with { required: true }, a rule about the whole set that no single box can check."
+        }
+      ],
+      "accessibility": [
+        "The WAI-ARIA Authoring Practices have no pattern for a group of checkboxes: the Checkbox pattern covers one box, and grouping is a question of naming rather than of keyboard behaviour. The sources are the ARIA group role and the Providing Accessible Names and Descriptions practice (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/).",
+        "Every box is its own tab stop, and Space toggles the box that has focus. The platform provides this whole keyboard model. It is what sets a checkbox group apart from a radio group, where the set is a single tab stop and the arrow keys move the choice.",
+        "The role depends on the container. A field group is a fieldset with a legend, which is already a named group; a role=\"group\" inside it, named by the same legend, would announce the set twice. Inside a field group the checkbox group renders no role, and the legend names the set. Inside a field, the field’s label names the group through aria-labelledby.",
+        "The group writes aria-required, never the native required on a box. The native attribute on a checkbox demands that one particular box be checked, which is not what \"choose at least one\" means. That rule is about the whole selection, so the checkbox group, not the box, is the validator.",
+        "A checkbox has no native read-only state, so the checkbox group enforces one: every box refuses the activation, aria-readonly announces it, and every tab stop and focus ring stays.",
+        "The parent box is derived from the set rather than kept as a state of its own, so it always agrees with the boxes it controls. It reports aria-checked=\"mixed\" through the platform’s indeterminate property, and pressing it replaces the selection instead of adding a value of its own."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-checkbox-group-gap",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One set with every axis on it, driven by the controls below the canvas. Tick two options and watch the array in the actions panel: the order is the set’s, never the click order.",
+      "language": "html",
+      "source": "<div slCheckboxGroup name=\"days\" [allValues]=\"days\" [defaultValue]=\"['mon']\">\n  <div slCheckbox value=\"mon\">Segunda</div>\n  <div slCheckbox value=\"wed\">Quarta</div>\n  <div slCheckbox value=\"fri\">Sexta</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "orientation",
+      "title": "How the choices flow",
+      "note": "A horizontal set wraps rather than scrolling or clipping, because a row whose last option nobody can see is worse than two rows — and the distance between two choices is twice the distance between a box and its own label.",
+      "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-group-orientation',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Invoice status</legend>\n      <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['open', 'overdue']\">\n        <div slCheckbox value=\"draft\">Draft</div>\n        <div slCheckbox value=\"open\">Open</div>\n        <div slCheckbox value=\"paid\">Paid</div>\n        <div slCheckbox value=\"overdue\">Overdue</div>\n        <div slCheckbox value=\"void\">Void</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupOrientation {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tile",
+      "title": "A set of framed choices",
+      "note": "The variant belongs to the group, not to each box: a set with one plain choice among four tiles is a set nobody meant to write. Arrangement is not the group’s — Grid already owns columns, minItemWidth and a stretching alignment, so tiles in a row come out the same width and the same height.",
+      "language": "html",
+      "source": "<div slCheckboxGroup variant=\"tile\" [defaultValue]=\"['pix']\">\n  <div slGrid minItemWidth=\"sm\">\n    <div slCheckbox value=\"pix\">\n      Pix\n      <p slCheckboxDescription>Compensação imediata.</p>\n    </div>\n    <div slCheckbox value=\"card\">\n      Cartão de crédito\n      <p slCheckboxDescription>Parcelamento em até doze vezes.</p>\n    </div>\n  </div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "parent",
+      "title": "One box that commands the set",
+      "note": "The parent is derived and never entered: ticked when every value is selected, mixed between the two, and its request replaces the whole selection rather than toggling a value of its own.",
+      "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-group-parent',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Columns to export</legend>\n      <div\n        slCheckboxGroup\n        name=\"columns\"\n        [allValues]=\"columns\"\n        [defaultValue]=\"['order', 'customer', 'total']\"\n      >\n        <div slCheckbox parent>All columns</div>\n        <div slCheckbox value=\"order\">Order number</div>\n        <div slCheckbox value=\"customer\">Customer</div>\n        <div slCheckbox value=\"placed\">Placed on</div>\n        <div slCheckbox value=\"total\">Total</div>\n        <div slCheckbox value=\"status\">Status</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupParent {\n  readonly columns = ['order', 'customer', 'placed', 'total', 'status'];\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "states",
+      "title": "What the group says to every box in it",
+      "note": "Each of the four is unstated rather than false, so a group defers to the field around it and a box defers to the group; stated anywhere, it wins from there down and every box paints it.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport {\n  SlFieldGroup,\n  SlFieldGroupDescription,\n  SlFieldGroupError,\n  SlFieldGroupLegend,\n} from '@slotted/angular/field-group';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-group-states',\n  imports: [\n    SlCheckbox,\n    SlCheckboxGroup,\n    SlFieldGroup,\n    SlFieldGroupDescription,\n    SlFieldGroupError,\n    SlFieldGroupLegend,\n    SlStack,\n  ],\n  template: `\n    <div slStack [gap]=\"6\">\n      <fieldset slFieldGroup required>\n        <legend slFieldGroupLegend>Sales regions</legend>\n        <span slFieldGroupError>Choose at least one region for this price list.</span>\n        <div slCheckboxGroup invalid orientation=\"horizontal\">\n          <div slCheckbox value=\"us\">United States</div>\n          <div slCheckbox value=\"ca\">Canada</div>\n          <div slCheckbox value=\"eu\">European Union</div>\n        </div>\n      </fieldset>\n      <fieldset slFieldGroup readOnly>\n        <legend slFieldGroupLegend>Tax exemptions</legend>\n        <span slFieldGroupDescription>Set by the finance team on the customer record.</span>\n        <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['resale']\">\n          <div slCheckbox value=\"resale\">Resale</div>\n          <div slCheckbox value=\"nonprofit\">Nonprofit</div>\n        </div>\n      </fieldset>\n      <fieldset slFieldGroup disabled>\n        <legend slFieldGroupLegend>Carriers</legend>\n        <span slFieldGroupDescription>Carriers open once a ship-from address is saved.</span>\n        <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['ups']\">\n          <div slCheckbox value=\"ups\">UPS</div>\n          <div slCheckbox value=\"fedex\">FedEx</div>\n          <div slCheckbox value=\"usps\">USPS</div>\n        </div>\n      </fieldset>\n    </div>\n  `,\n})\nexport class CheckboxGroupStates {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "count",
+      "title": "How many of them are chosen",
+      "note": "The number reaches the field’s label row through the channel a text field opened for characters, so a reader finds \"2/5\" where they already look for a count rather than in a sentence under the set.",
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';\n\n@Component({\n  selector: 'app-checkbox-group-count',\n  imports: [SlCheckbox, SlCheckboxGroup, SlField, SlFieldDescription, SlFieldLabel],\n  template: `\n    <div slField>\n      <label slFieldLabel>Fulfil from</label>\n      <div\n        slCheckboxGroup\n        name=\"warehouses\"\n        showCount\n        [allValues]=\"warehouses\"\n        [defaultValue]=\"['seattle', 'tacoma']\"\n      >\n        <div slCheckbox value=\"seattle\">Seattle</div>\n        <div slCheckbox value=\"tacoma\">Tacoma</div>\n        <div slCheckbox value=\"portland\">Portland</div>\n        <div slCheckbox value=\"boise\">Boise</div>\n      </div>\n      <span slFieldDescription>Orders ship from the nearest selected warehouse.</span>\n    </div>\n  `,\n})\nexport class CheckboxGroupCount {\n  readonly warehouses = ['seattle', 'tacoma', 'portland', 'boise'];\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "field",
+      "title": "Inside a group of fields, and in a reactive form",
+      "note": "The fieldset and its legend are what group and name the set, so this group withdraws its own role — and the same element takes formControlName, because the accessor and the validator both live on the root.",
+      "language": "html",
+      "source": "<fieldset slFieldGroup required>\n  <legend slFieldGroupLegend>Notificações</legend>\n  <div slCheckboxGroup required 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 set of long options keeps every box on the first line of its own label, a narrow column turns a horizontal set into a stack without a media query, and a right-to-left set mirrors whole rather than rearranging.",
+      "language": "html",
+      "source": "<div slCheckboxGroup orientation=\"horizontal\">\n  <div slCheckbox value=\"a\">\n    Autorizo o uso dos dados de navegação para personalizar as recomendações\n  </div>\n  <div slCheckbox value=\"b\">E também para medir o alcance das campanhas</div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "The token carries the three decisions an application takes once, exportAs reaches the instance, and the root is the consumer’s own element — so a set of choices can be a real list.",
+      "language": "html",
+      "source": "<ul slCheckboxGroup class=\"slotted-demo-list\" [defaultValue]=\"['a']\">\n  <li slCheckbox value=\"a\">Um item</li>\n  <li slCheckbox value=\"b\">E outro abaixo dele</li>\n</ul>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "What the keyboard does, and who implements it",
+      "note": "Every box is its own tab stop and Space toggles it, because a checkbox is one choice made on its own — which is exactly what tells this family apart from a radio group, where the whole set is one stop.",
+      "language": "html",
+      "source": "<!-- The group binds no key at all: each box is a native checkbox, so Tab\n     reaches every one of them and Space toggles the one that has focus. -->\n<div slCheckboxGroup>\n  <div slCheckbox value=\"a\">Tab até aqui</div>\n  <div slCheckbox value=\"b\">E de novo até aqui</div>\n</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 { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\n\n@Component({\n  selector: 'app-checkbox-group-basic',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Notify me about failed payments by</legend>\n      <div slCheckboxGroup name=\"channels\" [defaultValue]=\"['email', 'in-app']\">\n        <div slCheckbox value=\"email\">Email</div>\n        <div slCheckbox value=\"sms\">Text message</div>\n        <div slCheckbox value=\"in-app\">In-app notification</div>\n        <div slCheckbox value=\"slack\">Slack, #billing-alerts</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupBasic {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, computed, signal } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\nimport { SlStack } from '@slotted/angular/stack';\n\nconst ORDERS: Record<string, number> = { card: 812, transfer: 145, paypal: 96 };\n\n@Component({\n  selector: 'app-checkbox-group-controlled',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],\n  template: `\n    <div slStack [gap]=\"4\">\n      <fieldset slFieldGroup>\n        <legend slFieldGroupLegend>Payment method</legend>\n        <div\n          slCheckboxGroup\n          orientation=\"horizontal\"\n          [value]=\"methods()\"\n          (valueChange)=\"methods.set($event.value)\"\n        >\n          <div slCheckbox value=\"card\">Card</div>\n          <div slCheckbox value=\"transfer\">Bank transfer</div>\n          <div slCheckbox value=\"paypal\">PayPal</div>\n        </div>\n      </fieldset>\n      <span>Showing {{ shown() }} orders</span>\n    </div>\n  `,\n})\nexport class CheckboxGroupControlled {\n  readonly methods = signal<readonly string[]>(['card', 'transfer']);\n  readonly shown = computed(() =>\n    this.methods().reduce((sum, method) => sum + (ORDERS[method] ?? 0), 0),\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { provideCheckboxGroupDefaults, SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-group-defaults',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],\n  providers: [provideCheckboxGroupDefaults({ orientation: 'horizontal' })],\n  template: `\n    <div slStack [gap]=\"5\">\n      <fieldset slFieldGroup>\n        <legend slFieldGroupLegend>Fulfilment</legend>\n        <div slCheckboxGroup [defaultValue]=\"['unfulfilled', 'partial']\">\n          <div slCheckbox value=\"unfulfilled\">Unfulfilled</div>\n          <div slCheckbox value=\"partial\">Partial</div>\n          <div slCheckbox value=\"fulfilled\">Fulfilled</div>\n        </div>\n      </fieldset>\n      <fieldset slFieldGroup>\n        <legend slFieldGroupLegend>Sales channel</legend>\n        <div slCheckboxGroup [defaultValue]=\"['online']\">\n          <div slCheckbox value=\"online\">Online</div>\n          <div slCheckbox value=\"retail\">Retail</div>\n          <div slCheckbox value=\"wholesale\">Wholesale</div>\n        </div>\n      </fieldset>\n    </div>\n  `,\n})\nexport class CheckboxGroupDefaults {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "descriptions",
+      "title": "descriptions.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } 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-group-descriptions',\n  imports: [SlCheckbox, SlCheckboxDescription, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>When stock runs low</legend>\n      <div slCheckboxGroup [defaultValue]=\"['alert']\">\n        <div slCheckbox value=\"alert\">\n          Alert the buyer\n          <p slCheckboxDescription>\n            Sent to the buyer for the SKU when on-hand drops below the reorder point.\n          </p>\n        </div>\n        <div slCheckbox value=\"draft-po\">\n          Draft a purchase order\n          <p slCheckboxDescription>\n            Created for the preferred supplier at the usual order quantity, waiting for approval.\n          </p>\n        </div>\n        <div slCheckbox value=\"hide\">\n          Stop selling online at zero\n          <p slCheckboxDescription>\n            The product page shows Out of stock instead of a delivery date.\n          </p>\n        </div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupDescriptions {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "disabled-option",
+      "title": "disabled-option.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } 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-group-disabled-option',\n  imports: [SlCheckbox, SlCheckboxDescription, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Send order updates by</legend>\n      <div slCheckboxGroup name=\"updates\" [defaultValue]=\"['email']\">\n        <div slCheckbox value=\"email\">Email</div>\n        <div slCheckbox value=\"sms\" disabled>\n          Text message\n          <p slCheckboxDescription>Add a mobile number to the customer record to turn this on.</p>\n        </div>\n        <div slCheckbox value=\"webhook\">Webhook to the storefront</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupDisabledOption {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "label-placement",
+      "title": "label-placement.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-group-label-placement',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Email reports</legend>\n      <div slCheckboxGroup labelPlacement=\"start\" [defaultValue]=\"['weekly']\">\n        <div slCheckbox value=\"daily\">Daily sales summary</div>\n        <div slCheckbox value=\"weekly\">Weekly stock report</div>\n        <div slCheckbox value=\"monthly\">Monthly statement</div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupLabelPlacement {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "sizes",
+      "title": "sizes.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';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-group-sizes',\n  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend, SlStack],\n  template: `\n    <div slStack [gap]=\"5\">\n      <fieldset slFieldGroup size=\"sm\">\n        <legend slFieldGroupLegend>Show columns</legend>\n        <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['sku', 'on-hand']\">\n          <div slCheckbox value=\"sku\">SKU</div>\n          <div slCheckbox value=\"on-hand\">On hand</div>\n          <div slCheckbox value=\"reserved\">Reserved</div>\n        </div>\n      </fieldset>\n      <fieldset slFieldGroup size=\"md\">\n        <legend slFieldGroupLegend>Ship from</legend>\n        <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['seattle']\">\n          <div slCheckbox value=\"seattle\">Seattle</div>\n          <div slCheckbox value=\"tacoma\">Tacoma</div>\n          <div slCheckbox value=\"portland\">Portland</div>\n        </div>\n      </fieldset>\n      <fieldset slFieldGroup size=\"lg\">\n        <legend slFieldGroupLegend>Accept payment by</legend>\n        <div slCheckboxGroup orientation=\"horizontal\" [defaultValue]=\"['card', 'transfer']\">\n          <div slCheckbox value=\"card\">Card</div>\n          <div slCheckbox value=\"transfer\">Bank transfer</div>\n        </div>\n      </fieldset>\n    </div>\n  `,\n})\nexport class CheckboxGroupSizes {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tiles",
+      "title": "tiles.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component } from '@angular/core';\nimport { SlCheckbox, SlCheckboxDescription } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';\nimport { SlGrid } from '@slotted/angular/grid';\n\n@Component({\n  selector: 'app-checkbox-group-tiles',\n  imports: [\n    SlCheckbox,\n    SlCheckboxDescription,\n    SlCheckboxGroup,\n    SlFieldGroup,\n    SlFieldGroupLegend,\n    SlGrid,\n  ],\n  template: `\n    <fieldset slFieldGroup>\n      <legend slFieldGroupLegend>Add-ons</legend>\n      <div slCheckboxGroup name=\"add-ons\" variant=\"tile\" [defaultValue]=\"['audit-log']\">\n        <div slGrid minItemWidth=\"xs\">\n          <div slCheckbox value=\"audit-log\">\n            Audit log\n            <p slCheckboxDescription>$29 per month. Every change kept for a year.</p>\n          </div>\n          <div slCheckbox value=\"sso\">\n            Single sign-on\n            <p slCheckboxDescription>$49 per month. SAML and SCIM provisioning.</p>\n          </div>\n          <div slCheckbox value=\"support\">\n            Priority support\n            <p slCheckboxDescription>$99 per month. Replies within four hours.</p>\n          </div>\n        </div>\n      </div>\n    </fieldset>\n  `,\n})\nexport class CheckboxGroupTiles {}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.ts",
+      "note": null,
+      "language": "ts",
+      "source": "import { Component, signal } from '@angular/core';\nimport { FormControl, ReactiveFormsModule } from '@angular/forms';\nimport { SlButton } from '@slotted/angular/button';\nimport { SlCheckbox } from '@slotted/angular/checkbox';\nimport { SlCheckboxGroup } from '@slotted/angular/checkbox-group';\nimport { SlFieldGroup, SlFieldGroupError, SlFieldGroupLegend } from '@slotted/angular/field-group';\nimport { SlInline } from '@slotted/angular/inline';\nimport { SlStack } from '@slotted/angular/stack';\n\n@Component({\n  selector: 'app-checkbox-group-validation',\n  imports: [\n    ReactiveFormsModule,\n    SlButton,\n    SlCheckbox,\n    SlCheckboxGroup,\n    SlFieldGroup,\n    SlFieldGroupError,\n    SlFieldGroupLegend,\n    SlInline,\n    SlStack,\n  ],\n  template: `\n    <form novalidate (submit)=\"submit($event)\">\n      <div slStack [gap]=\"4\">\n        <fieldset slFieldGroup required>\n          <legend slFieldGroupLegend>Send shipping confirmations by</legend>\n          <span slFieldGroupError live=\"polite\" reserve>{{\n            missing ? 'Choose at least one channel.' : ''\n          }}</span>\n          <div slCheckboxGroup [formControl]=\"channels\" [invalid]=\"missing ? true : undefined\">\n            <div slCheckbox value=\"email\">Email</div>\n            <div slCheckbox value=\"sms\">Text message</div>\n            <div slCheckbox value=\"in-app\">In-app notification</div>\n          </div>\n        </fieldset>\n        <div slInline [gap]=\"3\" align=\"center\">\n          <button slButton type=\"submit\">Save preferences</button>\n          @if (submitted() && channels.valid) {\n            <span role=\"status\">Preferences saved.</span>\n          }\n        </div>\n      </div>\n    </form>\n  `,\n})\nexport class CheckboxGroupValidation {\n  /* The group is the form control and its validator: inside a required field\n     group, an empty selection fails with { required: true }. */\n  readonly channels = new FormControl<readonly string[]>([], { nonNullable: true });\n  readonly submitted = signal(false);\n\n  get missing(): boolean {\n    return this.submitted() && this.channels.invalid;\n  }\n\n  submit(event: Event): void {\n    event.preventDefault();\n    this.submitted.set(true);\n  }\n}\n",
+      "verdict": "example"
+    }
+  ]
+}

package/docs/checkbox-group.md

@@ -0,0 +1,106 @@
+<!-- index: ./index.md -->
+# checkbox-group
+
+`data-ui="checkbox-group"` · Set of checkboxes under one label.
+
+## Import
+
+```ts
+import {
+  provideCheckboxGroupDefaults,
+  SlCheckboxGroup,
+} from '@slotted/angular/checkbox-group';
+```
+
+Selector: `[slCheckboxGroup]` · exportAs: `slCheckboxGroup`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCheckbox } from '@slotted/angular/checkbox';
+import { SlCheckboxGroup } from '@slotted/angular/checkbox-group';
+import { SlFieldGroup, SlFieldGroupLegend } from '@slotted/angular/field-group';
+
+@Component({
+  selector: 'app-checkbox-group-basic',
+  imports: [SlCheckbox, SlCheckboxGroup, SlFieldGroup, SlFieldGroupLegend],
+  template: `
+    <fieldset slFieldGroup>
+      <legend slFieldGroupLegend>Notify me about failed payments by</legend>
+      <div slCheckboxGroup name="channels" [defaultValue]="['email', 'in-app']">
+        <div slCheckbox value="email">Email</div>
+        <div slCheckbox value="sms">Text message</div>
+        <div slCheckbox value="in-app">In-app notification</div>
+        <div slCheckbox value="slack">Slack, #billing-alerts</div>
+      </div>
+    </fieldset>
+  `,
+})
+export class CheckboxGroupBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slCheckboxGroup | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | SlCheckboxGroup | The controlled selection. When present, the consumer owns the selection. When absent, the checkbox group owns it and starts from defaultValue, or from the form control bound to the root. |
+| `defaultValue` | `readonly string[]` | [] | SlCheckboxGroup | The selection an uncontrolled group starts from, read once when the directive initialises. |
+| `allValues` | `readonly string[]` | — | SlCheckboxGroup | Every value the checkbox group holds. A parent slCheckbox needs it: the parent is checked when every value is selected and mixed when some are, which a selection alone cannot tell. It also keeps the selection in the order of this list rather than in the order the boxes were pressed. |
+| `variant` | `'plain' \| 'tile'` | plain | SlCheckboxGroup, provideCheckboxGroupDefaults | How every choice is drawn, passed to every box. tile frames each choice and makes its whole surface the target. Arranging the tiles is left to slGrid. |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | SlCheckboxGroup, provideCheckboxGroupDefaults | How the choices flow. A horizontal set wraps instead of scrolling. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlCheckboxGroup, provideCheckboxGroupDefaults | The type step, passed to every box. A field or field group around the checkbox group decides it first, then the provider. |
+| `labelPlacement` | `'end' \| 'start'` | end | SlCheckboxGroup, provideCheckboxGroupDefaults | Which side of its label each box is on, set once for the set so the boxes line up. |
+| `name` | `string` | — | SlCheckboxGroup | The submission name every box shares when it sets none of its own. No name is generated: the platform does not group checkboxes by name the way it groups radios. |
+| `disabled` | `boolean` | from the field, or false | SlCheckboxGroup | Unset rather than false. Reaches every box as the native attribute. A disabled form control sets it too, through setDisabledState. |
+| `readOnly` | `boolean` | from the field, or false | SlCheckboxGroup | Unset rather than false. Every box keeps its tab stop, its focus ring and its contrast, writes aria-readonly, and refuses every change. |
+| `invalid` | `boolean` | from the field, or false | SlCheckboxGroup | Unset rather than false. Writes aria-invalid on the group and on every box, and data-invalid on the group’s root and on every box’s root. |
+| `required` | `boolean` | from the field, or false | SlCheckboxGroup | Unset rather than false. Writes aria-required on the group, and makes the group’s validator fail while the selection is empty. It is never the native required, which on a checkbox would demand that one particular box be checked. |
+| `showCount` | `boolean` | false | SlCheckboxGroup | Inside a field, draws how many of allValues are selected at the end of the field’s label row, as 2/4, and adds that count to the group’s accessible description. |
+| `exportAs="slCheckboxGroup"` | `SlCheckboxGroup` | — | a template | Reaches the instance, with the resolved axes and the selection for a template to read. |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | the host element | Both are on the root, so a form binding goes on the element that carries slCheckboxGroup. required becomes a validator over the whole selection. |
+| `provideCheckboxGroupDefaults()` | `{ size, variant, orientation, labelPlacement }` | — | an injector | The four decisions an application takes once for every checkbox group under it. A field or field group around a checkbox group decides size before the provider. |
+| `the host element` | `any element` | — | SlCheckboxGroup | The host element is the root, so a set of choices can be a ul with each box written as an li. |
+| `role` | `string` | group, or none inside a field group | the host element | A role written as a static attribute on the host wins. Otherwise the role is group, withdrawn inside a field group, because a fieldset with a legend is already a named group and a second group named by the same legend announces the set twice. |
+| `aria-label / aria-labelledby` | `string` | the field’s label, inside a field | the host element | Names the group. Inside a field, aria-labelledby points at the field’s label unless either attribute is written as a static attribute on the host. Outside a field and a field group, write one of them, because a group needs a name. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<readonly string[]>` | Before the selection moves. $event.value is the new array and $event.previous the array it replaces. $event.reason is pointer or keyboard, recovered from the box’s click; $event.source is the originating event; $event.cancel() refuses the move before anything commits. There is no [(value)], because a two-way binding carries only the value and none of the rest. |
+| `ControlValueAccessor and Validator` | `readonly string[]` | Whenever the selection moves under a formControl, formControlName or ngModel bound on the root. The checkbox group also validates the selection: when required, an empty selection fails with { required: true }, a rule about the whole set that no single box can check. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `plain`, `tile` | `plain` |
+| `orientation` | `vertical`, `horizontal` | `vertical` |
+| `labelPlacement` | `end`, `start` | `end` |
+
+## Rules
+
+- The WAI-ARIA Authoring Practices have no pattern for a group of checkboxes: the Checkbox pattern covers one box, and grouping is a question of naming rather than of keyboard behaviour. The sources are the ARIA group role and the Providing Accessible Names and Descriptions practice (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/).
+- Every box is its own tab stop, and Space toggles the box that has focus. The platform provides this whole keyboard model. It is what sets a checkbox group apart from a radio group, where the set is a single tab stop and the arrow keys move the choice.
+- The role depends on the container. A field group is a fieldset with a legend, which is already a named group; a role="group" inside it, named by the same legend, would announce the set twice. Inside a field group the checkbox group renders no role, and the legend names the set. Inside a field, the field’s label names the group through aria-labelledby.
+- The group writes aria-required, never the native required on a box. The native attribute on a checkbox demands that one particular box be checked, which is not what "choose at least one" means. That rule is about the whole selection, so the checkbox group, not the box, is the validator.
+- A checkbox has no native read-only state, so the checkbox group enforces one: every box refuses the activation, aria-readonly announces it, and every tab stop and focus ring stays.
+- The parent box is derived from the set rather than kept as a state of its own, so it always agrees with the boxes it controls. It reports aria-checked="mixed" through the platform’s indeterminate property, and pressing it replaces the selection instead of adding a value of its own.
+
+## Tokens
+
+`--slotted-checkbox-group-gap`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`
+
+## Examples
+
+See [checkbox-group.examples.md](./checkbox-group.examples.md).