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

package/dist/docs/checkbox-group.json

@@ -0,0 +1,393 @@
+{
+  "family": "checkbox-group",
+  "ui": "checkbox-group",
+  "binding": "react",
+  "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 { Checkbox, CheckboxGroup, CheckboxGroupDefaultsProvider } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "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 boxes inside are Checkbox components with their own stylesheet, which the checkbox group’s stylesheet never selects into."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "CheckboxGroup",
+          "description": "The controlled selection. When present, the consumer owns the selection for the life of the component. When absent, the checkbox group owns it and starts from defaultValue."
+        },
+        {
+          "name": "defaultValue",
+          "type": "readonly string[]",
+          "defaultValue": "[]",
+          "appliesTo": "CheckboxGroup",
+          "description": "The selection an uncontrolled group starts from, read once."
+        },
+        {
+          "name": "allValues",
+          "type": "readonly string[]",
+          "defaultValue": "—",
+          "appliesTo": "CheckboxGroup",
+          "description": "Every value the checkbox group holds. A parent Checkbox 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": "CheckboxGroup, CheckboxGroupDefaultsProvider",
+          "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 Grid."
+        },
+        {
+          "name": "orientation",
+          "type": "'vertical' | 'horizontal'",
+          "defaultValue": "vertical",
+          "appliesTo": "CheckboxGroup, CheckboxGroupDefaultsProvider",
+          "description": "How the choices flow. A horizontal set wraps instead of scrolling."
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "CheckboxGroup, CheckboxGroupDefaultsProvider",
+          "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": "CheckboxGroup, CheckboxGroupDefaultsProvider",
+          "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": "CheckboxGroup",
+          "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": "CheckboxGroup",
+          "description": "Unset rather than false. Reaches every box as the native attribute, which takes the boxes out of the tab order and out of form submission."
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "CheckboxGroup",
+          "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": "CheckboxGroup",
+          "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": "CheckboxGroup",
+          "description": "Unset rather than false. Writes aria-required on the group, never the native required, which on a checkbox would demand that one particular box be checked."
+        },
+        {
+          "name": "showCount",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "CheckboxGroup",
+          "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": "render",
+          "type": "(props: CheckboxGroupRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "CheckboxGroup",
+          "description": "Replaces the root and hands it every attribute. The props are typed as HTMLAttributes<HTMLElement>, so a set of choices can render as a ul with each box as an li."
+        },
+        {
+          "name": "useCheckboxGroup()",
+          "type": "() => CheckboxGroupContextValue | undefined",
+          "defaultValue": "—",
+          "appliesTo": "inside a CheckboxGroup",
+          "description": "Returns what a box reads: whether it is selected, its size, and how to request a change. It returns undefined outside a checkbox group, so one Checkbox serves both a single consent box and a member of a set."
+        },
+        {
+          "name": "CheckboxGroupDefaultsProvider",
+          "type": "{ size, variant, orientation, labelPlacement }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "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": "className / style",
+          "type": "string / CSSProperties",
+          "defaultValue": "—",
+          "appliesTo": "CheckboxGroup",
+          "description": "Reach the root. Every other native prop reaches it too, because the root is the only element the checkbox group renders."
+        },
+        {
+          "name": "role",
+          "type": "string",
+          "defaultValue": "group, or none inside a field group",
+          "appliesTo": "CheckboxGroup",
+          "description": "A role the consumer writes 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": "CheckboxGroup",
+          "description": "Names the group. Inside a field, aria-labelledby points at the field’s label unless the consumer writes either attribute. Outside a field and a field group, write one of them, because a group needs a name."
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: readonly string[], request: ChangeRequest<readonly string[]>)",
+          "when": "Before the selection moves. request.value is the new array and request.previous the array it replaces. request.reason is pointer or keyboard, recovered from the box’s click; request.source is the originating event; request.cancel() refuses the move before anything commits, including the platform’s own toggle."
+        },
+        {
+          "name": "onCheckedChange, on each Checkbox",
+          "payload": "(checked: boolean, request: ChangeRequest<boolean>)",
+          "when": "Before that one box moves, and before the checkbox group builds its own request. Cancelling it also stops the group’s request, so one option can refuse to be chosen without the rest of the set taking part."
+        }
+      ],
+      "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 to assistive technology; 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, and it turns on browser constraint validation.",
+        "A checkbox has no native read-only state, so the checkbox group enforces one: every box refuses the change on the click that a pointer and Space share, 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": "tsx",
+      "source": "<CheckboxGroup allValues={['mon', 'wed', 'fri']} defaultValue={['mon']} name=\"days\">\n  <Checkbox value=\"mon\">Segunda</Checkbox>\n  <Checkbox value=\"wed\">Quarta</Checkbox>\n  <Checkbox value=\"fri\">Sexta</Checkbox>\n</CheckboxGroup>;\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": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nexport default function CheckboxGroupOrientation() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Invoice status</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup orientation=\"horizontal\" defaultValue={['open', 'overdue']}>\n          <Checkbox value=\"draft\">Draft</Checkbox>\n          <Checkbox value=\"open\">Open</Checkbox>\n          <Checkbox value=\"paid\">Paid</Checkbox>\n          <Checkbox value=\"overdue\">Overdue</Checkbox>\n          <Checkbox value=\"void\">Void</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\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": "tsx",
+      "source": "<CheckboxGroup defaultValue={['pix']} variant=\"tile\">\n  <Grid minItemWidth=\"sm\">\n    <Checkbox description=\"Compensação imediata.\" value=\"pix\">\n      Pix\n    </Checkbox>\n    <Checkbox description=\"Parcelamento em até doze vezes.\" value=\"card\">\n      Cartão de crédito\n    </Checkbox>\n  </Grid>\n</CheckboxGroup>;\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": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nconst COLUMNS = ['order', 'customer', 'placed', 'total', 'status'];\n\nexport default function CheckboxGroupParent() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Columns to export</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup\n          name=\"columns\"\n          allValues={COLUMNS}\n          defaultValue={['order', 'customer', 'total']}\n        >\n          <Checkbox parent>All columns</Checkbox>\n          <Checkbox value=\"order\">Order number</Checkbox>\n          <Checkbox value=\"customer\">Customer</Checkbox>\n          <Checkbox value=\"placed\">Placed on</Checkbox>\n          <Checkbox value=\"total\">Total</Checkbox>\n          <Checkbox value=\"status\">Status</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\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": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport {\n  FieldGroup,\n  FieldGroupContent,\n  FieldGroupDescription,\n  FieldGroupError,\n  FieldGroupLegend,\n} from '@slotted/react/field-group';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxGroupStates() {\n  return (\n    <Stack gap={6}>\n      <FieldGroup required>\n        <FieldGroupLegend>Sales regions</FieldGroupLegend>\n        <FieldGroupError>Choose at least one region for this price list.</FieldGroupError>\n        <FieldGroupContent>\n          <CheckboxGroup invalid orientation=\"horizontal\">\n            <Checkbox value=\"us\">United States</Checkbox>\n            <Checkbox value=\"ca\">Canada</Checkbox>\n            <Checkbox value=\"eu\">European Union</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n      <FieldGroup readOnly>\n        <FieldGroupLegend>Tax exemptions</FieldGroupLegend>\n        <FieldGroupDescription>\n          Set by the finance team on the customer record.\n        </FieldGroupDescription>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" defaultValue={['resale']}>\n            <Checkbox value=\"resale\">Resale</Checkbox>\n            <Checkbox value=\"nonprofit\">Nonprofit</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n      <FieldGroup disabled>\n        <FieldGroupLegend>Carriers</FieldGroupLegend>\n        <FieldGroupDescription>\n          Carriers open once a ship-from address is saved.\n        </FieldGroupDescription>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" defaultValue={['ups']}>\n            <Checkbox value=\"ups\">UPS</Checkbox>\n            <Checkbox value=\"fedex\">FedEx</Checkbox>\n            <Checkbox value=\"usps\">USPS</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n    </Stack>\n  );\n}\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": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { Field, FieldDescription, FieldLabel } from '@slotted/react/field';\n\nconst WAREHOUSES = ['seattle', 'tacoma', 'portland', 'boise'];\n\nexport default function CheckboxGroupCount() {\n  return (\n    <Field>\n      <FieldLabel>Fulfil from</FieldLabel>\n      <CheckboxGroup\n        name=\"warehouses\"\n        allValues={WAREHOUSES}\n        defaultValue={['seattle', 'tacoma']}\n        showCount\n      >\n        <Checkbox value=\"seattle\">Seattle</Checkbox>\n        <Checkbox value=\"tacoma\">Tacoma</Checkbox>\n        <Checkbox value=\"portland\">Portland</Checkbox>\n        <Checkbox value=\"boise\">Boise</Checkbox>\n      </CheckboxGroup>\n      <FieldDescription>Orders ship from the nearest selected warehouse.</FieldDescription>\n    </Field>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "field",
+      "title": "Inside a group of fields",
+      "note": "The fieldset and its legend are what group and name the set, so this group withdraws its own role rather than announcing the same set twice — and a disabled fieldset disables every box with nothing passed down.",
+      "language": "tsx",
+      "source": "<FieldGroup required>\n  <FieldGroupLegend>Notificações</FieldGroupLegend>\n  <CheckboxGroup name=\"alerts\">\n    <Checkbox value=\"approved\">Pedido aprovado</Checkbox>\n    <Checkbox value=\"refused\">Pedido recusado</Checkbox>\n  </CheckboxGroup>\n</FieldGroup>;\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": "tsx",
+      "source": "<CheckboxGroup orientation=\"horizontal\">\n  <Checkbox value=\"a\">\n    Autorizo o uso dos dados de navegação para personalizar as recomendações\n  </Checkbox>\n  <Checkbox value=\"b\">E também para medir o alcance das campanhas</Checkbox>\n</CheckboxGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Setting it once, and reaching past it",
+      "note": "The provider carries the three decisions an application takes once, render substitutes the root so a set can be a real list, and useCheckboxGroup reads the same state a box reads.",
+      "language": "tsx",
+      "source": "<CheckboxGroupDefaultsProvider orientation=\"horizontal\" size=\"sm\">\n  <CheckboxGroup>\n    <Checkbox value=\"a\">Herda os três</Checkbox>\n  </CheckboxGroup>\n</CheckboxGroupDefaultsProvider>;\n\n// The root becomes a real list, and each box a list item.\n<CheckboxGroup render={(props) => <ul {...props} />}>\n  <Checkbox render={(props) => <li {...props} />} value=\"a\">\n    Um item\n  </Checkbox>\n</CheckboxGroup>;\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": "tsx",
+      "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<CheckboxGroup allValues={['a', 'b']}>\n  <Checkbox value=\"a\">Tab até aqui</Checkbox>\n  <Checkbox value=\"b\">E de novo até aqui</Checkbox>\n</CheckboxGroup>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "basic",
+      "title": "basic.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nexport default function CheckboxGroupBasic() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Notify me about failed payments by</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup name=\"channels\" defaultValue={['email', 'in-app']}>\n          <Checkbox value=\"email\">Email</Checkbox>\n          <Checkbox value=\"sms\">Text message</Checkbox>\n          <Checkbox value=\"in-app\">In-app notification</Checkbox>\n          <Checkbox value=\"slack\">Slack, #billing-alerts</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "controlled",
+      "title": "controlled.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState } from 'react';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\nimport { Stack } from '@slotted/react/stack';\n\nconst ORDERS: Record<string, number> = { card: 812, transfer: 145, paypal: 96 };\n\nexport default function CheckboxGroupControlled() {\n  const [methods, setMethods] = useState<readonly string[]>(['card', 'transfer']);\n  const shown = methods.reduce((sum, method) => sum + (ORDERS[method] ?? 0), 0);\n\n  return (\n    <Stack gap={4}>\n      <FieldGroup>\n        <FieldGroupLegend>Payment method</FieldGroupLegend>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" value={methods} onValueChange={setMethods}>\n            <Checkbox value=\"card\">Card</Checkbox>\n            <Checkbox value=\"transfer\">Bank transfer</Checkbox>\n            <Checkbox value=\"paypal\">PayPal</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n      <span>Showing {shown} orders</span>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "defaults",
+      "title": "defaults.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup, CheckboxGroupDefaultsProvider } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxGroupDefaults() {\n  return (\n    <CheckboxGroupDefaultsProvider orientation=\"horizontal\">\n      <Stack gap={5}>\n        <FieldGroup>\n          <FieldGroupLegend>Fulfilment</FieldGroupLegend>\n          <FieldGroupContent>\n            <CheckboxGroup defaultValue={['unfulfilled', 'partial']}>\n              <Checkbox value=\"unfulfilled\">Unfulfilled</Checkbox>\n              <Checkbox value=\"partial\">Partial</Checkbox>\n              <Checkbox value=\"fulfilled\">Fulfilled</Checkbox>\n            </CheckboxGroup>\n          </FieldGroupContent>\n        </FieldGroup>\n        <FieldGroup>\n          <FieldGroupLegend>Sales channel</FieldGroupLegend>\n          <FieldGroupContent>\n            <CheckboxGroup defaultValue={['online']}>\n              <Checkbox value=\"online\">Online</Checkbox>\n              <Checkbox value=\"retail\">Retail</Checkbox>\n              <Checkbox value=\"wholesale\">Wholesale</Checkbox>\n            </CheckboxGroup>\n          </FieldGroupContent>\n        </FieldGroup>\n      </Stack>\n    </CheckboxGroupDefaultsProvider>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "descriptions",
+      "title": "descriptions.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nexport default function CheckboxGroupDescriptions() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>When stock runs low</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup defaultValue={['alert']}>\n          <Checkbox\n            value=\"alert\"\n            description=\"Sent to the buyer for the SKU when on-hand drops below the reorder point.\"\n          >\n            Alert the buyer\n          </Checkbox>\n          <Checkbox\n            value=\"draft-po\"\n            description=\"Created for the preferred supplier at the usual order quantity, waiting for approval.\"\n          >\n            Draft a purchase order\n          </Checkbox>\n          <Checkbox\n            value=\"hide\"\n            description=\"The product page shows Out of stock instead of a delivery date.\"\n          >\n            Stop selling online at zero\n          </Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "disabled-option",
+      "title": "disabled-option.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nexport default function CheckboxGroupDisabledOption() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Send order updates by</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup name=\"updates\" defaultValue={['email']}>\n          <Checkbox value=\"email\">Email</Checkbox>\n          <Checkbox\n            value=\"sms\"\n            disabled\n            description=\"Add a mobile number to the customer record to turn this on.\"\n          >\n            Text message\n          </Checkbox>\n          <Checkbox value=\"webhook\">Webhook to the storefront</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "label-placement",
+      "title": "label-placement.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\n\nexport default function CheckboxGroupLabelPlacement() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Email reports</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup labelPlacement=\"start\" defaultValue={['weekly']}>\n          <Checkbox value=\"daily\">Daily sales summary</Checkbox>\n          <Checkbox value=\"weekly\">Weekly stock report</Checkbox>\n          <Checkbox value=\"monthly\">Monthly statement</Checkbox>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "sizes",
+      "title": "sizes.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxGroupSizes() {\n  return (\n    <Stack gap={5}>\n      <FieldGroup size=\"sm\">\n        <FieldGroupLegend>Show columns</FieldGroupLegend>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" defaultValue={['sku', 'on-hand']}>\n            <Checkbox value=\"sku\">SKU</Checkbox>\n            <Checkbox value=\"on-hand\">On hand</Checkbox>\n            <Checkbox value=\"reserved\">Reserved</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n      <FieldGroup size=\"md\">\n        <FieldGroupLegend>Ship from</FieldGroupLegend>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" defaultValue={['seattle']}>\n            <Checkbox value=\"seattle\">Seattle</Checkbox>\n            <Checkbox value=\"tacoma\">Tacoma</Checkbox>\n            <Checkbox value=\"portland\">Portland</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n      <FieldGroup size=\"lg\">\n        <FieldGroupLegend>Accept payment by</FieldGroupLegend>\n        <FieldGroupContent>\n          <CheckboxGroup orientation=\"horizontal\" defaultValue={['card', 'transfer']}>\n            <Checkbox value=\"card\">Card</Checkbox>\n            <Checkbox value=\"transfer\">Bank transfer</Checkbox>\n          </CheckboxGroup>\n        </FieldGroupContent>\n      </FieldGroup>\n    </Stack>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "tiles",
+      "title": "tiles.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';\nimport { Grid } from '@slotted/react/grid';\n\nexport default function CheckboxGroupTiles() {\n  return (\n    <FieldGroup>\n      <FieldGroupLegend>Add-ons</FieldGroupLegend>\n      <FieldGroupContent>\n        <CheckboxGroup name=\"add-ons\" variant=\"tile\" defaultValue={['audit-log']}>\n          <Grid minItemWidth=\"xs\">\n            <Checkbox value=\"audit-log\" description=\"$29 per month. Every change kept for a year.\">\n              Audit log\n            </Checkbox>\n            <Checkbox value=\"sso\" description=\"$49 per month. SAML and SCIM provisioning.\">\n              Single sign-on\n            </Checkbox>\n            <Checkbox value=\"support\" description=\"$99 per month. Replies within four hours.\">\n              Priority support\n            </Checkbox>\n          </Grid>\n        </CheckboxGroup>\n      </FieldGroupContent>\n    </FieldGroup>\n  );\n}\n",
+      "verdict": "example"
+    },
+    {
+      "id": "validation",
+      "title": "validation.tsx",
+      "note": null,
+      "language": "tsx",
+      "source": "import { useState, type SubmitEvent } from 'react';\nimport { Button } from '@slotted/react/button';\nimport { Checkbox } from '@slotted/react/checkbox';\nimport { CheckboxGroup } from '@slotted/react/checkbox-group';\nimport {\n  FieldGroup,\n  FieldGroupContent,\n  FieldGroupError,\n  FieldGroupLegend,\n} from '@slotted/react/field-group';\nimport { Inline } from '@slotted/react/inline';\nimport { Stack } from '@slotted/react/stack';\n\nexport default function CheckboxGroupValidation() {\n  const [channels, setChannels] = useState<readonly string[]>([]);\n  const [submitted, setSubmitted] = useState(false);\n  const missing = submitted && channels.length === 0;\n\n  const submit = (event: SubmitEvent<HTMLFormElement>) => {\n    event.preventDefault();\n    setSubmitted(true);\n  };\n\n  return (\n    <form noValidate onSubmit={submit}>\n      <Stack gap={4}>\n        <FieldGroup required>\n          <FieldGroupLegend>Send shipping confirmations by</FieldGroupLegend>\n          <FieldGroupError live=\"polite\" reserve>\n            {missing ? 'Choose at least one channel.' : ''}\n          </FieldGroupError>\n          <FieldGroupContent>\n            <CheckboxGroup\n              invalid={missing ? true : undefined}\n              value={channels}\n              onValueChange={setChannels}\n            >\n              <Checkbox value=\"email\">Email</Checkbox>\n              <Checkbox value=\"sms\">Text message</Checkbox>\n              <Checkbox value=\"in-app\">In-app notification</Checkbox>\n            </CheckboxGroup>\n          </FieldGroupContent>\n        </FieldGroup>\n        <Inline gap={3} align=\"center\">\n          <Button type=\"submit\">Save preferences</Button>\n          {submitted && channels.length > 0 ? <span role=\"status\">Preferences saved.</span> : null}\n        </Inline>\n      </Stack>\n    </form>\n  );\n}\n",
+      "verdict": "example"
+    }
+  ]
+}

package/dist/docs/checkbox-group.md

@@ -0,0 +1,99 @@
+<!-- index: ./index.md -->
+# checkbox-group
+
+`data-ui="checkbox-group"` · Set of checkboxes under one label.
+
+## Import
+
+```tsx
+import { Checkbox, CheckboxGroup, CheckboxGroupDefaultsProvider } from '@slotted/react';
+```
+
+## Minimal example
+
+Example
+
+```tsx
+import { Checkbox } from '@slotted/react/checkbox';
+import { CheckboxGroup } from '@slotted/react/checkbox-group';
+import { FieldGroup, FieldGroupContent, FieldGroupLegend } from '@slotted/react/field-group';
+
+export default function CheckboxGroupBasic() {
+  return (
+    <FieldGroup>
+      <FieldGroupLegend>Notify me about failed payments by</FieldGroupLegend>
+      <FieldGroupContent>
+        <CheckboxGroup name="channels" defaultValue={['email', 'in-app']}>
+          <Checkbox value="email">Email</Checkbox>
+          <Checkbox value="sms">Text message</Checkbox>
+          <Checkbox value="in-app">In-app notification</Checkbox>
+          <Checkbox value="slack">Slack, #billing-alerts</Checkbox>
+        </CheckboxGroup>
+      </FieldGroupContent>
+    </FieldGroup>
+  );
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | CheckboxGroup | The controlled selection. When present, the consumer owns the selection for the life of the component. When absent, the checkbox group owns it and starts from defaultValue. |
+| `defaultValue` | `readonly string[]` | [] | CheckboxGroup | The selection an uncontrolled group starts from, read once. |
+| `allValues` | `readonly string[]` | — | CheckboxGroup | Every value the checkbox group holds. A parent Checkbox 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 | CheckboxGroup, CheckboxGroupDefaultsProvider | 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 Grid. |
+| `orientation` | `'vertical' \| 'horizontal'` | vertical | CheckboxGroup, CheckboxGroupDefaultsProvider | How the choices flow. A horizontal set wraps instead of scrolling. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | CheckboxGroup, CheckboxGroupDefaultsProvider | 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 | CheckboxGroup, CheckboxGroupDefaultsProvider | Which side of its label each box is on, set once for the set so the boxes line up. |
+| `name` | `string` | — | CheckboxGroup | 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 | CheckboxGroup | Unset rather than false. Reaches every box as the native attribute, which takes the boxes out of the tab order and out of form submission. |
+| `readOnly` | `boolean` | from the field, or false | CheckboxGroup | 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 | CheckboxGroup | 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 | CheckboxGroup | Unset rather than false. Writes aria-required on the group, never the native required, which on a checkbox would demand that one particular box be checked. |
+| `showCount` | `boolean` | false | CheckboxGroup | 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. |
+| `render` | `(props: CheckboxGroupRootProps) => ReactNode` | — | CheckboxGroup | Replaces the root and hands it every attribute. The props are typed as HTMLAttributes<HTMLElement>, so a set of choices can render as a ul with each box as an li. |
+| `useCheckboxGroup()` | `() => CheckboxGroupContextValue \| undefined` | — | inside a CheckboxGroup | Returns what a box reads: whether it is selected, its size, and how to request a change. It returns undefined outside a checkbox group, so one Checkbox serves both a single consent box and a member of a set. |
+| `CheckboxGroupDefaultsProvider` | `{ size, variant, orientation, labelPlacement }` | — | a subtree | 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. |
+| `className / style` | `string / CSSProperties` | — | CheckboxGroup | Reach the root. Every other native prop reaches it too, because the root is the only element the checkbox group renders. |
+| `role` | `string` | group, or none inside a field group | CheckboxGroup | A role the consumer writes 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 | CheckboxGroup | Names the group. Inside a field, aria-labelledby points at the field’s label unless the consumer writes either attribute. Outside a field and a field group, write one of them, because a group needs a name. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onValueChange` | `(value: readonly string[], request: ChangeRequest<readonly string[]>)` | Before the selection moves. request.value is the new array and request.previous the array it replaces. request.reason is pointer or keyboard, recovered from the box’s click; request.source is the originating event; request.cancel() refuses the move before anything commits, including the platform’s own toggle. |
+| `onCheckedChange, on each Checkbox` | `(checked: boolean, request: ChangeRequest<boolean>)` | Before that one box moves, and before the checkbox group builds its own request. Cancelling it also stops the group’s request, so one option can refuse to be chosen without the rest of the set taking part. |
+
+## 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 to assistive technology; 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, and it turns on browser constraint validation.
+- A checkbox has no native read-only state, so the checkbox group enforces one: every box refuses the change on the click that a pointer and Space share, 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).