@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/CheckboxInput/CheckboxInput.spec.md

@@ -1,218 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CheckboxInput
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers:
-  [
-    public-api,
-    behavior,
-    layout,
-    interaction,
-    motion,
-    theming,
-    styling,
-    accessibility,
-    visual,
-    react-runtime,
-    compatibility,
-  ]
-verified_by:
-  [
-    packages/core/src/CheckboxInput/CheckboxInput.test.tsx,
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/__tests__/BusyOwnerAnnouncement.test.tsx,
-  ]
-modules: []
-families: []
-design_specs: [design:user-states]
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-    architecture:interaction-modality,
-  ]
-contributing: []
-system_specs: [spec:AST-021, spec:AST-085, spec:AST-086]
----
-
-# CheckboxInput component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `CheckboxInput` is a controlled native checkbox with a required `label` and `value`; it supports synchronous and transition-backed change handlers, loading, disabled, disabled-reason, read-only, validation, sizing, and field content.                                                                |
-| Behavior                | The native input owns role, state, focus, form participation, and activation. A replaceable CheckboxIndicator owns the visible box while CheckboxInput owns its focus ring and pressed overlay.                                                                                                          |
-| End-user impact         | People can identify and operate available choices, review inert values as read-only, discover disabled reasons from the keyboard, and perceive busy, validation, focus, and pressed states.                                                                                                              |
-| Builder impact          | None. Builders control the value and may use `onChange`, `changeAction`, or both; the meaning of omitting both stays an open question (OQ1).                                                                                                                                                             |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. A handlerless checkbox declares no read-only state, a mixed value can lose its native mixed state on activation, and caller key handlers run while disabled; all are listed under Current-state impact.                                        |
-| Review checks           | Reject state/name drift, duplicate activation, disabled or read-only mutation, lost form semantics, missing focus/pressed feedback, inaccessible supporting text, or target ownership changes.                                                                                                           |
-| Governing rules         | `spec:AST-021/FR4–FR10`; `spec:AST-085/FR1–FR3`; `design:user-states/DR1–DR5`; `architecture:interaction-modality/INV1–INV5,INV9`; `architecture:public-component-api/INV1,INV5–INV9`; `architecture:component-theming-surface/INV3–INV8,INV12`; WCAG 2.2 1.3.1, 1.4.11, 2.1.1, 2.4.7, 3.3.1, and 4.1.2. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Render one controlled checkbox choice whose visible value, accessible state, interaction availability, and supporting field content remain aligned across pointer, keyboard, touch, forms, and assistive technology.
-
-## Compatibility and migration
-
-- Released default preserved: yes
-- Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
-- Controlled/uncontrolled behavior: controlled only; `value` remains required and all state changes remain caller-owned
-- Migration decision: none; handlerless semantics stay open (OQ1)
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Native checkbox role, checked/mixed state, label, description/status relationships, focus, activation, availability, read-only state, required/invalid/busy state, and form participation.
-- Composition of the resolved checkbox indicator, owner-painted focus ring and pressed overlay, disabled-reason tooltip, field label, description, and detached status.
-- Ordering between `onChange`, `preventDefault`, optimistic pending state, and `changeAction`.
-
-**Does not own / non-goals**
-
-- The checkbox indicator's internal paint and theme targets — owned by CheckboxIndicator and the Indicator registry.
-- Multi-option grouping, collection values, and group-level disabled reasons — owned by CheckboxList.
-- Generic label, status-message, spinner, tooltip, or icon implementation.
-- A new uncontrolled/default-value API or any change to checked-value serialization.
-
-## Public concepts
-
-| Concept        | Closed values or states                   | Meaning                                                                                                                              | Availability by variant/orientation/state               | Default               | Owner                      | Stability                              | Invalid-value behavior                       |
-| -------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | --------------------- | -------------------------- | -------------------------------------- | -------------------------------------------- |
-| value          | `false`, `true`, `indeterminate`          | Controlled visible and native checkbox state.                                                                                        | All paths.                                              | required              | caller                     | stable                                 | rejected by the public type                  |
-| change path    | `onChange`, `changeAction`, both, neither | Accepts immediate and/or transition-backed user intent; neither leaves the controlled value inert but does not settle its semantics. | Enabled, non-busy controls.                             | neither               | caller and component       | shipped; handlerless meaning unsettled | no handler means no component-owned mutation |
-| availability   | enabled, disabled, disabled with reason   | Controls activation, form submission, opacity, and reason discovery.                                                                 | All values.                                             | enabled               | component                  | stable                                 | disabled wins over activation                |
-| read-only      | explicit                                  | Preserves a focusable, full-opacity controlled value while blocking mutation.                                                        | All values; disabled may coexist and wins availability. | false                 | component                  | stable                                 | boolean only                                 |
-| busy           | explicit loading or optimistic transition | Preserves focus, blocks duplicate change, exposes busy state, and replaces the indicator mark with Spinner.                          | Enabled and read-only values.                           | false                 | component                  | stable                                 | boolean/transition state only                |
-| field content  | label, description, status, labelIcon     | Names and explains the choice and communicates validation.                                                                           | All values and availability states.                     | label required        | caller and composed owners | stable                                 | typed values only                            |
-| size and width | `sm`, `md`; `SizeValue`                   | Sizes the indicator row and the complete field.                                                                                      | All states.                                             | `md`; intrinsic width | component                  | stable                                 | rejected by public types                     |
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                                                               |
-| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| FR1  | The role-bearing element MUST remain a native `input[type=checkbox]` named by the rendered label, with `checked` derived from the shown value being `true` and the native `indeterminate` property from the shown value being `'indeterminate'`; the shown value is `value`, or the pending optimistic value (ORD1). Implementation gap: activating a mixed checkbox whose `value` stays mixed (no handler, or an `onChange` that keeps it) clears the native mixed state, and only the disabled, busy, or read-only path restores it, so the input reads as not checked while the indicator shows mixed. | shipped source; shared checkbox contract; WCAG 4.1.2                                                                |
-| FR2  | Enabled activation MUST call `onChange` first with the next boolean value, then call `changeAction` only when present and the event was not prevented.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | shipped source and component tests                                                                                  |
-| FR3  | While `isLoading`, or while the shown value differs from `value` (a pending `changeAction` whose value `value` has not accepted), the input MUST expose busy state, refuse another change, show Spinner in the indicator without losing focus, and announce the busy start once (`spec:AST-086` FR8).                                                                                                                                                                                                                                                                                                     | shipped source, tests, and stories; `architecture:interaction-modality/INV5`                                        |
-| FR4  | `isDisabled` MUST keep the input focusable with `aria-disabled="true"` and no native `disabled`, block every change and the caller `onClick`, withhold `name`, and detach the input from its form so it neither submits nor blocks submission. With `disabledMessage`, a tooltip opens on row hover and keyboard focus and describes the input. Implementation gap: other caller DOM handlers, such as `onKeyDown`, still run while disabled.                                                                                                                                                             | `spec:AST-085` FR1–FR3; shipped source and component tests; WCAG 2.1.1 and 4.1.2                                    |
-| FR5  | Explicit `isReadOnly` MUST preserve the controlled value and ordinary focusability, expose read-only state, remain full-opacity, and refuse mutation.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | shipped source and shared checkbox binding; WCAG 4.1.2                                                              |
-| FR6  | Description, status, disabled reason, and caller-provided `aria-describedby` ids MUST compose without dropping any source; error status MUST expose invalid state.                                                                                                                                                                                                                                                                                                                                                                                                                                        | shipped source and tests; WCAG 1.3.1, 3.3.1, 4.1.2                                                                  |
-| FR7  | Explicit required state MUST retain native form validation; inherited required presentation MUST expose `aria-required` without silently enabling native validation.                                                                                                                                                                                                                                                                                                                                                                                                                                      | shipped source and shared checkbox binding                                                                          |
-| FR8  | Caller DOM props MUST reach the input, while component-owned type, checked, disabled, read-only, required, busy, invalid, description, ref, and styling values retain precedence.                                                                                                                                                                                                                                                                                                                                                                                                                         | `architecture:public-component-api/INV5–INV8`; component tests                                                      |
-| FR9  | The outer field MUST retain `checkbox-input`, the label MUST retain `checkbox-label`, and the built-in CheckboxIndicator path MUST retain its canonical targets. Replacement indicators are not required to accept target classes.                                                                                                                                                                                                                                                                                                                                                                        | source/docs target inventory; replacement component tests; `architecture:component-theming-surface/INV4–INV8,INV12` |
-| FR10 | Keyboard/programmatic focus on the hidden native input MUST paint the shared focus-visible outline on the resolved indicator element, including a replacement indicator that forwards no props.                                                                                                                                                                                                                                                                                                                                                                                                           | `architecture:interaction-modality/INV1–INV3`; component tests                                                      |
-| FR11 | CheckboxInput applies `design:user-states` DR1 and DR2 for the pressed overlay, painting it on the indicator while the row is pressed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `design:user-states/DR1–DR5`                                                                                        |
-| FR12 | `sm` and `md` MUST keep the native input, indicator, focus paint, and row geometry aligned; field `width` MUST size the whole field rather than only the input.                                                                                                                                                                                                                                                                                                                                                                                                                                           | shipped source, tests, and stories                                                                                  |
-| FR13 | With neither `onChange` nor `changeAction`, activation changes nothing the caller can observe. Implementation gap: the checkbox declares no read-only or unavailable state; its meaning is OQ1 (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                    | shared checkbox known-failure record                                                                                |
-
-### Allowed variation
-
-- **AV1 — Indicator replacement.** A theme may replace the named checkbox indicator if it preserves the Indicator prop and decorative ownership contracts; CheckboxInput still paints focus and pressed feedback on the resolved root.
-- **AV2 — Theme paint.** Canonical component targets and semantic tokens may change admitted visual properties without changing native semantics, state precedence, or interaction ownership.
-- **AV3 — Caller field content.** Label, description, status text, icon/content, and width may vary within their public types.
-
-### Representative states
-
-| State                     | Required invariant                                                                                                | Allowed variation                            |
-| ------------------------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| unchecked, checked, mixed | Native and visual states agree; activation proposes the next boolean value.                                       | Theme-owned paint and indicator replacement. |
-| loading/pending           | Focus remains; busy is exposed; duplicate change is blocked; Spinner replaces the mark.                           | Caller-controlled loading duration.          |
-| disabled                  | Focusable with `aria-disabled`; inoperable; excluded from form data.                                              | Optional disabled-reason text.               |
-| read-only                 | Explicit `isReadOnly` keeps the value visible, focusable, submitted, and immutable with read-only semantics.      | Caller-controlled explicit state.            |
-| handlerless               | Activation changes nothing the caller can observe; its read-only or unavailable meaning is OQ1 (known gap today). | —                                            |
-| invalid/status            | Status is described and errors expose invalid state.                                                              | Error, warning, or success content.          |
-| hidden label              | The label remains in the accessibility tree and names the input.                                                  | Visual hiding only.                          |
-
-### Transformation and precedence order
-
-- **ORD1 — State precedence.** Controlled `value` → optimistic pending value → visible indicator state.
-- **ORD2 — Activation precedence.** disabled/busy/read-only guard → next native boolean → `onChange` → `preventDefault` check → optimistic `changeAction`.
-- **ORD3 — Availability precedence.** disabled owns availability and form exclusion; a disabled reason changes focusability but not operability; read-only applies only to value mutation.
-- **ORD4 — Attribute precedence.** caller rest props → component-owned semantic/form attributes → component-owned StyleX props.
-
-### Performance and resources
-
-- **PR1 — Bounded resources.** The component owns no global listener or observer. Tooltip and transition resources remain scoped to their existing hooks and component lifetime.
-
-## Accessibility contract
-
-- **AR1 — Native checkbox semantics.** Name, role, checked/mixed state, required, invalid, busy, disabled, and read-only state MUST remain programmatically determinable.
-- **AR2 — Keyboard parity.** Space activation follows the same availability and change-order rules as pointer activation; focus remains on the native input.
-- **AR3 — Focus visibility.** The hidden input's focus MUST remain visibly represented on the indicator for keyboard modality, including indicator replacements.
-- **AR4 — Supporting content.** Visible descriptions, statuses, and disabled reasons MUST be referenced without replacing caller descriptions.
-- **AR5 — Visual state.** Meaningful checkbox boundaries, marks, focus rings, and busy indicators MUST remain perceivable under supported themes and forced colors.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                              | Representation authority                                               | Hierarchy role      | Component contract      |
-| ---------------- | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------- | ----------------------- |
-| Checkbox         | Visible state cue, pressed overlay, and focus ring align with the native input. | Indicator owner plus `design:user-states` and interaction architecture | primary control     | FR1, FR3–FR5, FR10–FR12 |
-| Label            | Visible or visually hidden text names the native input.                         | FieldLabel composition                                                 | primary content     | FR1, FR6                |
-| Description      | Supporting text remains associated without entering the accessible name.        | FieldLabel composition                                                 | supporting content  | FR6                     |
-| Status message   | Detached status communicates validation and participates in description.        | FieldStatus composition                                                | supporting feedback | FR6                     |
-
-The consumer record includes composed targets owned by CheckboxIndicator, FieldLabel, and FieldStatus, which keep their own target ownership; this record carries no anatomy-theming map.
-
-## Family and system relationships
-
-- `spec:AST-021` owns the reusable checkbox accessibility binding, state inventory, evidence layers, and exact known-failure lifecycle.
-- `design:user-states` owns enabled/disabled pointer-hold paint for CheckboxInput.
-- `architecture:interaction-modality` owns focus-visibility modality and the boundary between semantic focus and indicator paint.
-- `architecture:component-theming-surface` owns target placement and state reflection.
-- `spec:AST-085` owns disabled focusability; FR4 records the handler gap.
-- `spec:AST-086` FR8 owns the busy announcement.
-- CheckboxIndicator, FieldLabel, FieldStatus, Spinner, Tooltip, and the Indicator registry retain their own implementation and theming ownership when composed here.
-
-## Verification map
-
-| Contract                    | Verification                                                                                                                                                                                                                                                                                                                           | Representative states                                                                                                   | Mutation or failure expectation                                                                                                                                                                                                    | Audit section                  |
-| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1, FR4–FR7, FR13, AR1–AR4 | `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` over the shared state list                                                                                                                                                                                                                                               | Value states; hidden and described label; disabled; disabled reason; loading; read-only; handlerless; required; invalid | A role, name, state, focusability, or description expectation fails, or a removed known failure becomes stale.                                                                                                                     | `audit:CheckboxInput/a11y`     |
-| FR2, FR3                    | `CheckboxInput.test.tsx` change, changeAction-only, and loading cases; `BusyOwnerAnnouncement.test.tsx` CheckboxInput case                                                                                                                                                                                                             | Click, label click, description click; `isLoading`                                                                      | A wrong `onChange` value, a missing `aria-busy`, or a busy start announced more than once, or by the Spinner, fails. Evidence gap: no test asserts `changeAction` after `onChange` with `preventDefault`, or the optimistic value. | `audit:CheckboxInput/behavior` |
-| FR4, FR6, FR7               | `CheckboxInput.test.tsx` disabled, disabledMessage, description, status, and form suites                                                                                                                                                                                                                                               | Disabled with and without reason; required; error                                                                       | A toggling disabled box, a submitted disabled value, or a dropped description fails. Evidence gap: no test asserts that caller `onKeyDown` still runs while disabled (the FR4 gap).                                                | `audit:CheckboxInput/behavior` |
-| FR8                         | `CheckboxInput.test.tsx` passthrough, id, ref, and rest-precedence cases                                                                                                                                                                                                                                                               | Caller `id`, `data-*`, ref                                                                                              | A caller prop overriding `checked`, `disabled`, or `type` fails.                                                                                                                                                                   | `audit:CheckboxInput/api`      |
-| FR9                         | `CheckboxInput.test.tsx` label-target case; `themingTargets.test.ts`                                                                                                                                                                                                                                                                   | Label; built-in indicator                                                                                               | A missing label target, or a rendered class absent from the documented targets, fails. Evidence gap: no test asserts the root `checkbox-input` target.                                                                             | `audit:CheckboxInput/theming`  |
-| FR10, AR3                   | `CheckboxInput.test.tsx` focus-ring ownership suite                                                                                                                                                                                                                                                                                    | Built-in and prop-dropping replacement indicators; blur                                                                 | A ring on the wrong element, or none, fails.                                                                                                                                                                                       | `audit:CheckboxInput/a11y`     |
-| FR11                        | `CheckboxInput.test.tsx` pressed-state suite                                                                                                                                                                                                                                                                                           | Enabled press; disabled; touch fade                                                                                     | A missing overlay, or one on a disabled box, fails.                                                                                                                                                                                | `audit:CheckboxInput/visual`   |
-| FR12, AR5                   | `CheckboxInput.test.tsx` coarse-pointer, RTL, and forced-colors suites                                                                                                                                                                                                                                                                 | `sm`, `md`; RTL; forced colors                                                                                          | A misplaced hit target or a mark lost in forced colors fails. Evidence gap: no test asserts field `width`.                                                                                                                         | `audit:CheckboxInput/layout`   |
-| ORD1–ORD4, PR1              | ORD4 is covered by the FR8 rest-precedence case and ORD3 by the shared accessibility suite's disabled, disabled-reason, and read-only states. Evidence gap: no test asserts the optimistic value between `value` and the indicator (ORD1), the `preventDefault` check before `changeAction` (ORD2), or the absence of global listeners | —                                                                                                                       | —                                                                                                                                                                                                                                  | `audit:CheckboxInput/behavior` |
-
-## Current-state impact
-
-- **Mixed state after activation (FR1, FR13).** Activating a mixed
-  CheckboxInput whose `value` stays mixed clears the native mixed state while
-  the indicator still shows mixed, so assistive technology reads it as not
-  checked (WCAG 2.2 4.1.2).
-- **Handlerless checkbox (FR13).** A CheckboxInput with neither handler
-  declares no read-only state, so accessibility consumers cannot tell its fixed
-  value from an editable one (WCAG 2.2 4.1.2). The shared checkbox suite
-  records this as a known failure; the intended meaning is OQ1.
-- **Caller handlers while disabled (FR4).** Caller DOM handlers other than
-  `onClick`, such as `onKeyDown`, still run while disabled, against
-  `spec:AST-085` FR2.
-
-## Decision log
-
-No component-local decision. CheckboxInput applies `spec:AST-021`, `spec:AST-085`, and `design:user-states`.
-
-## Open questions
-
-- **OQ1 — What does a controlled CheckboxInput with neither `onChange` nor `changeAction` mean?** (`human-api`) Current behavior is inert while exposed as editable. The options are read-only, unavailable, or invalid usage.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, implementation steps, generated evidence, or shared-component contracts. It links to their owners.

package/src/CheckboxList/CheckboxList.spec.md

@@ -1,332 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:CheckboxList
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers:
-  [
-    public-api,
-    behavior,
-    layout,
-    interaction,
-    motion,
-    theming,
-    styling,
-    accessibility,
-    visual,
-    react-runtime,
-    compatibility,
-  ]
-verified_by:
-  [
-    packages/core/src/CheckboxList/CheckboxList.test.tsx,
-    packages/core/src/CheckboxList/__tests__/CheckboxList.a11y.chromium.spec.ts,
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.test.tsx,
-    packages/core/src/CheckboxInput/__tests__/Checkbox.a11y.chromium.spec.ts,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/CheckboxList/CheckboxList.fr10.test.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: [family:input-fields]
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-    architecture:interaction-modality,
-  ]
-contributing: []
-system_specs: [spec:AST-011, spec:AST-021, spec:AST-038, spec:AST-085]
----
-
-# CheckboxList component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                                        |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `CheckboxList` is a labeled `role="group"` of `CheckboxListItem` rows. A `value` array selects controlled collection mode (`onChange`, `changeAction`); without it, its items are standalone. The group owns naming, description, disabled, disabled-reason, read-only, pending values, and status. Each option's behavior is `component:CheckboxListItem`.                     |
-| Behavior                | The group names and describes its options, tracks every value whose `changeAction` is pending so each saving option stays busy while the others stay interactive, and applies disabled, read-only, and status to every option.                                                                                                                                                  |
-| End-user impact         | People can identify the group, operate every option by pointer, touch, and keyboard, learn why a group is unavailable, and see which options are still saving.                                                                                                                                                                                                                  |
-| Builder impact          | Builders choose collection mode by passing `value`, and then supply stable item `value`s. Invalid-status meaning stays an open question here (OQ3); per-option open questions are in `component:CheckboxListItem`.                                                                                                                                                              |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. An error status exposes no invalid state; listed under Current-state impact.                                                                                                                                                                                                                                          |
-| Review checks           | Reject a pending value that loses its busy state or re-toggle guard when another option is toggled, dropped group naming or description ids, a toggle while the group is disabled or read-only, or new target or state API introduced without an owner decision. Per-option checks are in `component:CheckboxListItem`.                                                         |
-| Governing rules         | `architecture:public-component-api/INV1–INV9`; `architecture:component-theming-surface/INV3–INV6`; `architecture:interaction-modality/INV1–INV5`; `architecture:component-test-sufficiency/INV1–INV7`; `architecture:knowledge-contracts/INV2`; `spec:AST-021/FR8–FR10`; `spec:AST-038/FR7`; `spec:AST-085/FR1, FR7`; `family:input-fields/FR10`; WCAG 2.2 1.3.1, 2.1.1, 4.1.2. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Present a small, labeled set of independent checkbox options whose checked,
-available, read-only, busy, and status states stay aligned across pointer,
-touch, keyboard, and assistive technology.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default,
-  export, or DOM change
-- Controlled/uncontrolled behavior: collection mode is controlled by `value`;
-  standalone items follow `component:CheckboxListItem`; no uncontrolled mode
-  exists
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The labeled checkbox group, its `checkbox-list` target, the group's
-  description, status, and disabled-reason relationships, and where its
-  base, `container*`, and `control*` props land.
-- Collection state shared with CheckboxListItem: checked membership, change
-  ordering, optimistic pending values, and group-level availability.
-- The composed option anatomy and its target dispositions (Theming anatomy
-  below).
-
-**Does not own / non-goals**
-
-- Each option's behavior — its checkbox, naming and description, standalone
-  mode, row-surface delegation and `onClick` routing, item disabled and loading
-  states, density sizing, and checked-row fill — owned by
-  `component:CheckboxListItem`.
-- List and option-row presentation — owned by `component:List`; its
-  `list-item` target reaches only the row root.
-- The checkbox control, its indicator, focus ring, and pressed overlay — owned
-  by `component:CheckboxInput` and CheckboxIndicator.
-- Group-label and validation-message presentation — owned by Field under `family:input-fields` (shared owner section)
-  and `component:FieldStatus`.
-- Loading-indicator presentation — owned by `component:Spinner`; tooltip
-  behavior — owned by `useTooltip`.
-- New targets or reflected states for the row, descriptions, or caller content.
-
-## Public concepts
-
-| Concept          | Closed values or states                                     | Meaning                                                                                                             | Availability by variant/orientation/state | Default                   | Owner                  | Stability                              | Invalid-value behavior                                       |
-| ---------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------- | ---------------------- | -------------------------------------- | ------------------------------------------------------------ |
-| group naming     | `label`, `isLabelHidden`, `description`                     | Names and describes the `role="group"`; a hidden label still names it.                                              | All states.                               | label required; visible   | caller and Field       | stable                                 | rejected by the public type                                  |
-| collection value | `value` array present or absent                             | Present: the group owns checked membership and change handling for its items. Absent: its items are standalone.     | All states.                               | absent                    | caller and component   | stable                                 | an item without `value` in collection mode throws (item FR4) |
-| change path      | `onChange`, `changeAction`, both, neither                   | Reports the next value array; `changeAction` runs after `onChange` in a transition with an optimistic value.        | Collection mode.                          | neither                   | caller and component   | shipped; handlerless meaning unsettled | no handler means no component-owned mutation                 |
-| availability     | enabled, `isDisabled`, `isDisabled` with `disabledMessage`  | Blocks toggling on every item, which stays focusable through `aria-disabled`; a reason adds a group tooltip.        | Reason applies only with `isDisabled`.    | enabled                   | component              | stable                                 | a reason without `isDisabled` renders nothing                |
-| read-only        | `isReadOnly`                                                | Makes every item read-only.                                                                                         | Group-wide.                               | false                     | component              | stable                                 | boolean only                                                 |
-| pending values   | the values whose `changeAction` is pending                  | Each pending value's item renders busy; toggling another item does not clear it; concurrent values settle together. | Collection mode with `changeAction`.      | none                      | component              | stable                                 | transition state only                                        |
-| status           | `warning`, `error`, `success`, optional message             | A message renders a detached FieldStatus after the list and describes the group.                                    | All states.                               | none                      | caller and FieldStatus | shipped; invalid semantics unsettled   | a status without a message renders nothing                   |
-| row layout       | `density` compact/balanced/spacious; `hasDividers`; `width` | Density reaches the List and its rows; dividers separate rows; width sizes the label, list, and status together.    | All states.                               | balanced; none; intrinsic | component and List     | stable                                 | rejected by the public types                                 |
-| pass-through     | CheckboxList rest, `ref`, `container*`, `control*`          | Base props and `ref` reach the `role="group"`; `container*` the Field box; `control*` the group element.            | All states.                               | none                      | component              | stable                                 | root `xstyle`, `className`, `style` are not accepted         |
-
-Item props (`label`, `aria-label`, `description`, `endContent`, `isChecked`,
-`onCheck`, item `isDisabled`, `isLoading`, and item pass-through) are concepts
-of `component:CheckboxListItem`.
-
-## Behavioral and layout contract
-
-| ID   | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                       | Basis                                                                                            |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| FR1  | The render MUST place CheckboxListItem children inside a List within a `role="group"` named by the group label through `aria-labelledby`; its `aria-describedby` MUST list any caller description, then the description, status message, and disabled-reason tooltip that are present, in that order.                                                                                                                           | shipped source; focused tests; WCAG 1.3.1 and 4.1.2                                              |
-| FR2  | The CheckboxList root MUST carry the current `checkbox-list` target.                                                                                                                                                                                                                                                                                                                                                            | shipped source and public docs                                                                   |
-| FR4  | A status message MUST render through a detached FieldStatus after the list.                                                                                                                                                                                                                                                                                                                                                     | shipped source, focused tests, and the Chromium accessibility suite                              |
-| FR6  | With a `value` array, the group MUST provide membership to its items, call `onChange` with the next array an item proposes (`component:CheckboxListItem` FR4), and then run `changeAction` with the same array in a transition with an optimistic value.                                                                                                                                                                        | shipped source and focused tests                                                                 |
-| FR7  | The group MUST track every value whose `changeAction` is pending and expose it to its items, each of which renders busy (`component:CheckboxListItem` FR7); toggling another item MUST NOT clear an earlier pending value. Concurrent pending values settle together, after which every busy state clears.                                                                                                                      | shipped public `changeAction` promise; focused regression test; the Chromium accessibility suite |
-| FR9  | Group `isDisabled` MUST make every checkbox focusable-disabled through `aria-disabled` (`component:CheckboxInput` FR4) and refuse toggling. With `disabledMessage`, the reason tooltip opens on group hover and keyboard focus, and the reason MUST describe each focusable checkbox (`spec:AST-085` FR5, FR7). Implementation gap: the reason describes only the `role="group"`, so a focused checkbox is not described by it. | `spec:AST-085` FR1, FR7; shipped source, focused tests, and shared checkbox binding              |
-| FR10 | Group `isReadOnly` MUST make every item in the group read-only (`component:CheckboxListItem` FR8 and FR10).                                                                                                                                                                                                                                                                                                                     | shipped source; shared checkbox binding; `spec:AST-011` read-only vocabulary                     |
-| FR13 | `density` MUST reach the List and its rows (the checkbox size follows `component:CheckboxListItem` FR11); `hasDividers` MUST separate rows without a divider after the last row; `width` MUST size the label, list, and status together.                                                                                                                                                                                        | shipped source, docs, and the Chromium accessibility suite                                       |
-| FR14 | An error `status` with a message renders it (FR4). Implementation gap: an error exposes no programmatic invalid state on the group or its checkboxes, and a status without a message renders nothing; their meaning is OQ3.                                                                                                                                                                                                     | shipped source; `spec:AST-002/FR15`                                                              |
-| FR15 | Base props, including ARIA and `ref`, MUST reach the `role="group"`; a caller `aria-labelledby` joins the group label and a caller `aria-describedby` comes first. `container*` MUST reach the Field box where one renders (in a `horizontal-labels` FormLayout none renders, and `container*` has no effect and warns), and `control*` the group element; root `xstyle`, `className`, and `style` are not accepted.            | `family:input-fields` FR10; `CheckboxList.fr10.test.tsx`                                         |
-
-Per-option requirements are owned by `component:CheckboxListItem`
-(`architecture:knowledge-contracts/INV2`).
-
-### Allowed variation
-
-- **AV1 — Group content.** The label, description, status message, and width
-  may vary within their public types.
-- **AV2 — Theme paint.** The `checkbox-list` target and the composed group
-  targets may change admitted visual properties without changing semantics or
-  state precedence.
-
-Option variation is `component:CheckboxListItem` AV1–AV3.
-
-### Representative states
-
-| State                      | Required invariant                                                                        | Allowed variation                  |
-| -------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------- |
-| Default collection         | Named group, options list, and rows render; membership reaches every item                 | Option content and selected values |
-| Pending values             | Each pending value keeps its item busy until every pending value settles                  | Which options are pending          |
-| Group disabled with reason | Checkboxes stay focusable and inoperable; the reason is reachable by hover, focus, and AT | Reason text                        |
-| Group read-only            | Every item is read-only                                                                   | Which values are checked           |
-| Group status with message  | Detached FieldStatus follows the group and describes it                                   | Error, warning, or success status  |
-
-### Transformation and precedence order
-
-- **ORD1 — Checked state.** Collection `value` → optimistic pending value → the
-  membership each item reads (`component:CheckboxListItem` ORD1).
-- **ORD2 — Toggle.** An item's proposed next array (`component:CheckboxListItem`
-  ORD2) → `onChange` → `changeAction` in a transition that adds the toggled value
-  to the pending set.
-- **ORD3 — Availability.** Group disabled wins and keeps every checkbox
-  focusable; a group reason adds the tooltip, not operability; group read-only
-  applies to mutation only.
-
-### Performance and resources
-
-- **PR1 — Bounded resources.** The component owns no observer or global
-  listener. Tooltip listeners are scoped to the group element and its lifetime.
-
-Current measurements belong in the audit record; this subsection owns only
-durable constraints and their verification target.
-
-## Accessibility contract
-
-- **AR1 — Group identity.** The group name and its description, status, and
-  disabled-reason relationships MUST remain programmatically determinable.
-- **AR2, AR3, AR5 — Option semantics, keyboard parity, and busy perception** are
-  owned by `component:CheckboxListItem` AR1, AR2, and AR4.
-- **AR4 — Disabled reasons.** A group reason MUST stay discoverable by keyboard
-  focus and assistive technology while toggling stays blocked.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                                           | Representation authority        | Hierarchy role | Component contract                    |
-| ---------------- | ---------------------------------------------------------------------------- | ------------------------------- | -------------- | ------------------------------------- |
-| Group            | Contains the current checkbox-group composition.                             | Current source and public docs  | Supporting     | FR1, FR2                              |
-| Options list     | Presents the List-owned list and row roots.                                  | Current source                  | Supporting     | FR1, FR13                             |
-| Option rows      | Present each option's checkbox, content, busy spinner, and checked-row fill. | `component:CheckboxListItem`    | Prominent      | `component:CheckboxListItem` FR1–FR13 |
-| Status message   | Presents the group's current status.                                         | Current shared-component source | Supporting     | FR4                                   |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Group": {"target": "checkbox-list"},
-  "Group label": {
-    "delegatesTo": {"owner": "component:Field", "target": "field-label"}
-  },
-  "Description": {
-    "none": {
-      "reason": "unsettled: No current public target reaches the stable Description; future exposure still needs an owner decision"
-    }
-  },
-  "Options list": {
-    "delegatesTo": {"owner": "component:List", "target": "list"}
-  },
-  "Option row": {
-    "delegatesTo": {"owner": "component:List", "target": "list-item"}
-  },
-  "Checkbox": {
-    "delegatesTo": {
-      "owner": "component:CheckboxInput",
-      "target": "checkbox-indicator"
-    }
-  },
-  "Option label": {
-    "none": {
-      "reason": "unsettled: Item rather than Text renders the stable Option label in a separate untargeted span; future exposure still needs an owner decision"
-    }
-  },
-  "Option description": {
-    "none": {
-      "reason": "unsettled: Item rather than Text renders the stable Option description in a separate untargeted span; future exposure still needs an owner decision"
-    }
-  },
-  "End content": {
-    "none": {
-      "reason": "intentional: End content is caller-provided content outside CheckboxList's public theming ownership"
-    }
-  },
-  "Spinner": {
-    "delegatesTo": {"owner": "component:Spinner", "target": "spinner"}
-  },
-  "Status message": {
-    "delegatesTo": {
-      "owner": "component:FieldStatus",
-      "target": "field-status"
-    }
-  }
-}
-```
-
-`Description` remains stable consumer anatomy, but no current public target
-reaches it. Item, not Text, renders option labels and descriptions in separate
-untargeted spans, so neither delegates to Text nor inherits the row-root
-`list-item` target; future exposure remains unsettled. Rich label content and end
-content are caller-provided, and end content intentionally stays outside
-CheckboxList's public theming ownership. The `Option row` delegation reaches the
-row surface, but not a checked-row state (`component:CheckboxListItem` FR15).
-
-## Family and system relationships
-
-- `architecture:public-component-api` owns export reachability, pass-through
-  preservation, styling composition, refs, and released-change rules.
-- `architecture:component-theming-surface` owns anatomy qualification, factual
-  `none` dispositions, composition-preserving target ownership, and state
-  reflection.
-- `architecture:interaction-modality` owns focus visibility and the boundary
-  between the focused checkbox and the element that paints its ring.
-- `architecture:knowledge-contracts/INV2` keeps each per-option fact in
-  `component:CheckboxListItem` rather than copying it here.
-- `spec:AST-021` owns the reusable checkbox accessibility binding for
-  CheckboxListItem and its exact known-failure lifecycle.
-- `spec:AST-011` records `isReadOnly` as the name for visible, focusable,
-  non-editable values.
-- `spec:AST-038/FR7` stops CheckboxList context at a layer boundary; an item
-  inside a layer needs its own provider.
-- `component:CheckboxListItem` owns the per-option contract this group
-  composes.
-- List, CheckboxInput, Field, FieldStatus, Spinner, and Tooltip retain their
-  existing public target and behavior contracts when composed by CheckboxList.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                                     | Representative states                                 | Mutation or failure expectation                                                                                                                                | Audit section                      |
-| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
-| FR1, AR1            | `CheckboxList.test.tsx` group-role, group-description, and disabledMessage cases                                                                                 | Named group; description plus status; disabled reason | A missing group name, or a description and status out of order, fails. Evidence gap: no test asserts the caller description first or the disabled reason last. | `audit:CheckboxList/accessibility` |
-| FR2, FR15           | `CheckboxList.test.tsx` ref and container case; `CheckboxList.fr10.test.tsx`                                                                                     | Standalone; `horizontal-labels` FormLayout            | A ref off the group, `container*` off the Field box, or a base prop off the group fails.                                                                       | `audit:CheckboxList/api`           |
-| FR4, FR14           | `CheckboxList.test.tsx` error-status case                                                                                                                        | Error with message                                    | A missing status message fails. Evidence gap: no test asserts the absent invalid state or the empty render without a message.                                  | `audit:CheckboxList/accessibility` |
-| FR6, FR7            | `CheckboxList.test.tsx` add, remove, and pending cases; `CheckboxList.a11y.chromium.spec.ts` `pending-single`, `pending-concurrent`, and `pending-settled` cases | Add; remove; one and two pending values; settled      | A wrong array, a cleared earlier pending value, or a busy state that outlives settlement fails.                                                                | `audit:CheckboxList/behavior`      |
-| FR9, FR10, AR4      | `CheckboxList.test.tsx` group-disabled, disabledMessage, and read-only cases; shared checkbox bindings                                                           | Group disabled; with reason; read-only item           | A lost tab stop, a toggle while disabled, or a read-only toggle fails. Evidence gap: no test asserts that a focused checkbox is not described by the reason.   | `audit:CheckboxList/accessibility` |
-| FR13                | `CheckboxList.test.tsx` density cases; `CheckboxList.a11y.chromium.spec.ts` density, divider, 320-pixel, and RTL cases                                           | Compact, balanced, spacious; dividers; narrow; RTL    | A density, divider, overflow, or direction sensor fails. Evidence gap: no test asserts `width` sizing the label, list, and status together.                    | `audit:CheckboxList/layout`        |
-| ORD1–ORD3, PR1      | ORD1 and ORD2 are covered by the FR6 and FR7 rows, ORD3 by the FR9 and FR10 rows. Evidence gap: no test asserts the absence of observers or global listeners     | —                                                     | —                                                                                                                                                              | `audit:CheckboxList/behavior`      |
-| Local target source | `themingTargets.test.ts`; `CheckboxList.test.tsx` ref and container case                                                                                         | `checkbox-list`                                       | A rendered class absent from the documented targets, or a missing `astryx-checkbox-list` on the Field root, fails.                                             | `audit:CheckboxList/theming`       |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                    | Canonical anatomy and current local target            | Canonical-key drift, invalid dispositions or target spelling, or an unclaimed current local target fails validation.                                           | `audit:CheckboxList/theming`       |
-
-Per-option verification is owned by `component:CheckboxListItem`'s
-verification map. No current repository check resolves `delegatesTo`
-owner and target pairs; the pairs above match the current Field, List,
-CheckboxInput, Spinner, and FieldStatus targets.
-
-## Current-state impact
-
-- **Group reason (FR9).** A group `disabledMessage` describes only the
-  `role="group"`, so a focused disabled checkbox is not described by it,
-  against `spec:AST-085` FR5 and FR7.
-- **Error status (FR14).** An error `status` sets no invalid state on the group
-  or its checkboxes, and a status without a message renders nothing; the
-  meaning is OQ3.
-
-## Decision log
-
-No component-local decision. CheckboxList applies `spec:AST-021`,
-`spec:AST-085`, and `family:input-fields` FR10.
-
-## Open questions
-
-- **OQ3 — Should an error status expose invalid state, and what should a status
-  without a message render?** (`human-api`)
-  Per-option questions live in `component:CheckboxListItem`.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, the per-option contract, or shared-component
-contracts. It links to their owners.