An open source design system that's fully customizable and agent ready
TypeScript
docs(Indicator): audit CheckboxIndicator guidance (#6745)
Cindy Zhanga078d7aaf73c
diff --git a/.changeset/checkbox-indicator-canonical-target.md b/.changeset/checkbox-indicator-canonical-target.mdnew file mode 100644index 0000000000..7950336219--- /dev/null+++ b/.changeset/checkbox-indicator-canonical-target.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Correct CheckboxIndicator theming, replacement-content, and focus guidance.++@cixzhangdiff --git a/packages/core/src/Indicator/CheckboxIndicator.spec.md b/packages/core/src/Indicator/CheckboxIndicator.spec.mdnew file mode 100644index 0000000000..76fbdda383--- /dev/null+++ b/packages/core/src/Indicator/CheckboxIndicator.spec.md@@ -0,0 +1,161 @@+---+schema_version: 3+template_version: 6+kind: component+id: component:CheckboxIndicator+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, theming, accessibility, visual]+verified_by:+ [+ packages/core/src/Indicator/Indicator.test.tsx,+ packages/core/src/theme/themingTargets.test.ts,+ apps/storybook/stories/Indicator.stories.tsx,+ ]+modules: []+families: []+design_specs: []+architecture:+ [+ architecture:public-component-api,+ architecture:component-theming-surface,+ architecture:component-test-sufficiency,+ ]+contributing: []+system_specs: []+---++# CheckboxIndicator component contract++## Contract at a glance++| Area | Contract |+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Public contract | `CheckboxIndicator` is exported from `@astryxdesign/core/Indicator`; `state` is required, `size` defaults to `md`, `isDisabled` defaults to `false`, and `children` may replace the built-in mark. |+| Behavior | A decorative checkbox chrome is always rendered. Checked and indeterminate states draw their matching mark unless the shallow `isRenderable()` predicate treats `children` as replacement content. |+| End-user impact | People receive one visible checkbox-state cue while the owning control retains all semantics, focus, keyboard, and activation behavior. |+| Builder impact | Builders may restyle the canonical targets or replace the named indicator without taking over the owning control's semantics. |+| Compatibility/readiness | The released component and legacy `checkbox` target remain supported. This draft records shipped behavior and introduces no API or runtime change. |+| Review checks | Reject lost `aria-hidden`, missing state marks, dropped passthrough/ref/styling, changed replacement precedence, or removal of the legacy target before its approved window. |+| Governing rules | `architecture:public-component-api/INV1,INV5,INV6,INV8,INV9`; `architecture:component-theming-surface/INV3–INV8,INV12`; `architecture:component-test-sufficiency/INV1–INV7,INV10–INV11`. |++This table is a review projection; the body below is authoritative only after owner approval.++## Intent++Render the replaceable, decorative visual that communicates a checkbox owner's unchecked, checked, or indeterminate state without taking ownership of checkbox semantics or interaction.++## Compatibility and migration++- Released default preserved: yes+- Compatibility class: observational only; no runtime or public-type change+- Controlled/uncontrolled behavior: not applicable; `state` is supplied by the owner+- Migration decision: the deprecated `checkbox` target remains emitted beside `checkbox-indicator` under `architecture:component-theming-surface/INV12`++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- Decorative checkbox chrome, state mark, disabled appearance, size, replacement-content precedence, and component theming targets.+- A root DOM ref plus supported neutral DOM and styling passthrough.++**Does not own / non-goals**++- Checkbox role, accessible name, focus, keyboard, activation, form participation, or busy semantics — owned by the composing control.+- Row placement and logical-edge layout — owned by the host component.+- The behavior or accessibility of consumer-supplied replacement content.++## Public concepts++| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |+| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ------------------ | ----------------------------- | ------------------------------------------ | -------------------------------------------------- |+| state | `unchecked`, `checked`, `indeterminate` | Chooses the built-in visual state. | All render paths. | required | `component:CheckboxIndicator` | stable | rejected by the public type |+| size | `sm`, `md` | Selects the 20px or 24px visual box and matching mark geometry. | All states. | `md` | `component:CheckboxIndicator` | stable | rejected by the public type |+| disabled appearance | enabled, disabled | Mirrors the owning control's disabled presentation without creating semantics. | All states. | enabled | `component:CheckboxIndicator` | stable | boolean only |+| replacement content | shallow renderable or empty | Replaces both built-in marks when `isRenderable(children)` returns true. React elements and containers take this branch even when descendants render nothing. | All states. | built-in mark path | `component:CheckboxIndicator` | observed; empty-container policy unsettled | unsupported values follow React rendering behavior |++## Behavioral and layout contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ | ------------------ |+| FR1 | The component MUST render one decorative span chrome in every state and MUST set its own `aria-hidden="true"` after caller passthrough. | shipped source; `architecture:public-component-api/INV5` | verify |+| FR2 | `unchecked` MUST show no built-in mark, `checked` MUST show the checkmark, and `indeterminate` MUST show the dash. | shipped source, docs, tests, and stories | verify |+| FR3 | The current implementation uses shallow `isRenderable(children)` replacement precedence: nullish values, booleans, and the empty string keep the state mark; React elements and containers replace it even when descendants render nothing. This draft does not settle whether empty-container behavior should remain public policy. | shipped source and regression tests | verify |+| FR4 | The root MUST preserve supported DOM props, `ref`, `className`, `style`, and `xstyle` while keeping component-owned accessibility precedence. | `architecture:public-component-api/INV5,INV6,INV8` | verify |+| FR5 | The canonical root target MUST be `checkbox-indicator`; `checkbox` MUST remain a same-element deprecated alias until its approved removal window. | `architecture:component-theming-surface/INV4,INV6,INV12` | settled |+| FR6 | Size, checked/indeterminate, and disabled state MUST be reflected on the root target; the check and dash MUST retain their dedicated painting targets. | shipped source; `architecture:component-theming-surface/INV4,INV6` | verify |+| FR7 | State transitions MUST honor reduced motion, and checked/indeterminate marks MUST remain perceivable in forced-colors mode. | shipped source and WCAG 2.2 1.4.11 | verify |++### Allowed variation++- **AV1 — Theme paint.** Tokens and canonical component targets may change color, border, radius, opacity, and other admitted visual properties without changing state or semantic ownership.+- **AV2 — Replacement component.** A theme may replace the named checkbox indicator when the replacement preserves this public prop and decorative-ownership contract.++### Representative states++| State | Required invariant | Allowed variation |+| ------------------- | ------------------------------------------------------------------------------------------- | -------------------------------- |+| unchecked | Chrome remains visible with no built-in mark. | Theme-owned paint and shape. |+| checked | Chrome and checkmark remain visible. | Theme-owned paint and shape. |+| indeterminate | Chrome and dash remain visible. | Theme-owned paint and shape. |+| disabled | The requested state remains legible with muted treatment and no host-driven hover response. | Theme-owned inactive treatment. |+| replacement content | Shallow-renderable content replaces both built-in marks inside the same chrome. | Caller-owned decorative content. |++### Transformation and precedence order++- **ORD1 — Render precedence.** Caller passthrough → component-owned `aria-hidden` → merged theme/style inputs → shallow replacement-content decision → built-in state mark.++### Performance and resources++- **PR1 — Pure render.** The component owns no state, Effect, listener, observer, timer, or external resource.++## Accessibility contract++- **AR1 — Decorative ownership.** The root remains `aria-hidden`; the composing control owns role, name, state, focus, keyboard, activation, and form semantics.+- **AR2 — Forced colors.** Checked and indeterminate marks remain distinguishable when author colors are forced.+- **AR3 — Replacement boundary.** Replacement content is decorative within the hidden root and MUST NOT be the only semantic expression of the owning control's state.++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |+| ------------------ | --------------------------------------------------- | ------------------------------------------ | ------------------------- | ------------------ |+| Chrome | Semantic theme tokens and canonical painting target | prescribed by current theming architecture | supporting control visual | FR1, FR5–FR7 |+| Checkmark | Visible checked-state mark | observed shipped representation | supporting state cue | FR2, FR6–FR7 |+| Indeterminate mark | Visible partial-state mark | observed shipped representation | supporting state cue | FR2, FR6–FR7 |++The shared `Indicator.doc.mjs` owns anatomy and targets for CheckboxIndicator, CheckIndicator, and RadioIndicator together. This component draft does not add an `anatomy-theming:v1` block while that shared consumer record remains the canonical cross-component inventory; the block is optional during migration. The deprecated `checkbox` alias still maps to the CheckboxIndicator chrome for compatibility and is not a separate anatomy part.++## Family and system relationships++- `architecture:component-theming-surface` owns target placement, reflected state, and deprecated-alias compatibility.+- `architecture:public-component-api` owns export, passthrough, styling composition, ref, and compatibility requirements.+- `architecture:component-test-sufficiency` owns the evidence needed for each critical promise and distinct risk partition.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | ----------------------------------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------- |+| FR1, AR1 | `Indicator.test.tsx` decorative-contract cases | every built-in path; hostile `aria-hidden` input | Removing or reordering owned `aria-hidden` exposes duplicate semantics. | `audit:CheckboxIndicator/a11y` |+| FR2–FR3 | `Indicator.test.tsx` state and replacement-content cases | unchecked, checked, indeterminate, empty scalar, visible child | Removing a state mark or choosing the wrong children branch fails observable DOM assertions. | `audit:CheckboxIndicator/behavior` |+| FR4 | `Indicator.test.tsx`, strict lint, and public type checks | neutral DOM props, ref, class/style/xstyle | Passthrough, ref, or styling composition stops reaching the root. | `audit:CheckboxIndicator/api` |+| FR5–FR6 | theming target guards and `Indicator.test.tsx` | canonical/legacy targets; size/state/disabled axes | A target disappears, moves off its painter, or loses reflected state. | `audit:CheckboxIndicator/theming` |+| FR7, AR2 | source review plus exact-head Chromium evidence | light/dark; checked/indeterminate; reduced motion; forced colors | Motion persists under reduced motion or a state mark disappears in forced colors. | `audit:CheckboxIndicator/design-rendered` |+| All | `Indicator.stories.tsx`, component-scoped axe and RTL audit | all states, sizes, disabled, replacement content | A required rendered state is unreachable or gains an accessibility/RTL failure. | `audit:CheckboxIndicator/testing` |++## Decision log++None. This draft records only verified shipped behavior.++## Open questions++- Whether empty React containers should continue to suppress the built-in state mark is intentionally unsettled; this observational draft records the current branch without approving it as future policy.++## Content boundary++This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.diff --git a/packages/core/src/Indicator/CheckboxIndicator.tsx b/packages/core/src/Indicator/CheckboxIndicator.tsxindex 5d2f8535a0..e9a3688dbd 100644--- a/packages/core/src/Indicator/CheckboxIndicator.tsx+++ b/packages/core/src/Indicator/CheckboxIndicator.tsx@@ -159,11 +159,11 @@ const indeterminateSizeStyles = stylex.create({* indeterminate bar.** Decorative and non-interactive — it renders `aria-hidden` and owns no input,- * role, or focus behavior. The focus ring lives on the owner's control wrapper- * (see CheckboxInput), so a theme that replaces this component keeps a visible- * focus indicator for free. Themes replace it wholesale through- * `defineTheme({indicators: {checkbox: MyCheckbox}})`, or restyle it through- * the `checkbox` theme target like any other component.+ * role, or focus behavior. The owning control keeps focus semantics and paints its+ * standard focus ring onto this indicator element (see CheckboxInput), so a+ * replacement's root radius determines the ring shape. Themes replace it+ * wholesale through `defineTheme({indicators: {checkbox: MyCheckbox}})`, or+ * restyle it through the canonical `checkbox-indicator` theme target.** @example* ```diff --git a/packages/core/src/Indicator/Indicator.doc.mjs b/packages/core/src/Indicator/Indicator.doc.mjsindex 57b6dc13c5..45554405ab 100644--- a/packages/core/src/Indicator/Indicator.doc.mjs+++ b/packages/core/src/Indicator/Indicator.doc.mjs@@ -52,7 +52,7 @@ export const docs = {name: 'children',type: 'ReactNode',description:- 'Rendered inside the chrome INSTEAD of the state mark. CheckboxInput passes its loading Spinner through this while a change action is pending, so a replacement indicator must render children when they will actually draw something: use `isRenderable(children)`, never `children ?? mark`, because a host writes `children={isBusy && <Spinner/>}` and `false` slips straight past a nullish check and deletes the mark.',+ 'Rendered inside the chrome INSTEAD of the state mark when the shallow `isRenderable(children)` check accepts the value. The helper excludes `null`, `undefined`, booleans, and the empty string; React elements and containers take the replacement path even when their descendants render nothing. CheckboxInput passes its loading Spinner through as `children={isBusy && <Spinner/>}`, so replacements should use the same helper rather than a nullish check.',},],},@@ -241,12 +241,12 @@ defineTheme({name: 'brand', indicators: {check: RadioIndicator}});`,{guidance: true,description:- 'Reach for component overrides first (components: {checkbox}). Replacing the component is the heavier path, for when the shape itself is wrong.',+ "Reach for the canonical `components['checkbox-indicator']` override first. Replacing the component is the heavier path, for when the shape itself is wrong.",},{guidance: true,description:- 'A replacement must render `children` when they will actually draw something: use `isRenderable(children)`, not `children != null` or `children ?? mark`. The owning control passes its loading Spinner through as `children={isBusy && <Spinner/>}`, so the value is `false` whenever it is not busy: a nullish check takes the children branch, renders nothing, and deletes your state mark on every chosen row (#4893).',+ 'Match the shipped replacement-content branch with `isRenderable(children)`, not `children != null` or `children ?? mark`. The helper is deliberately shallow: it excludes nullish values, booleans, and the empty string, while React elements and containers take the replacement path even when their descendants render nothing. The owning control passes `children={isBusy && <Spinner/>}`, so a nullish check deletes the state mark whenever that value is `false` (#4893).',},{guidance: true,@@ -299,8 +299,8 @@ export const docsDense = {description:'Componentized selection visuals shared by CheckboxInput, RadioList, and menu rows. Decorative: the owner keeps input/role/name/focus/keyboard; the indicator turns state into a picture. That split makes them themeable: restyle via class targets or replace the component.',bestPractices: [- { guidance: true, description: 'Prefer component overrides first (components: {checkbox}). Replacing the component is the heavier path, for when the shape itself is wrong.' },- { guidance: true, description: 'A replacement must render `children` when they will draw something: use `isRenderable(children)`, not `children != null` or `children ?? mark`. The owner passes a loading Spinner as `children={isBusy && <Spinner/>}`, so it is `false` when idle; a nullish check then renders nothing and deletes the mark on every chosen row (#4893).' },+ { guidance: true, description: "Prefer the canonical `components['checkbox-indicator']` override first. Replacing the component is the heavier path, for when the shape itself is wrong." },+ { guidance: true, description: 'Match the shipped replacement-content branch with `isRenderable(children)`, not `children != null` or `children ?? mark`. The helper is shallow: it excludes nullish values, booleans, and the empty string, while React elements and containers take the replacement path even when their descendants render nothing. The owner passes `children={isBusy && <Spinner/>}`, so a nullish check deletes the state mark whenever the value is `false` (#4893).' },{ guidance: true, description: 'A replacement must set aria-hidden. The owner supplies role and accessible name; a visible indicator would be announced twice.' },{ guidance: true, description: 'Use theme tokens for every color, radius, and border width in a replacement. Run `npx astryx docs tokens` for the set.' },{ guidance: true, description: 'Render a single root ELEMENT with the border-radius the focus ring should follow. The owner paints the standard ring onto the indicator at focus time (useIndicatorFocusRing) and outline picks up its radius; the ring is never missing (WCAG 2.4.7), only mis-shaped if the root lacks a radius. Do not draw a focus ring yourself.' },diff --git a/packages/core/src/Indicator/types.ts b/packages/core/src/Indicator/types.tsindex cb3b3ff44b..17ae1ae6e8 100644--- a/packages/core/src/Indicator/types.ts+++ b/packages/core/src/Indicator/types.ts@@ -101,10 +101,12 @@ export type IndicatorPosition = 'start' | 'end';* excess-property checking, so a LITERAL `role=` is a compile error while* `aria-hidden` and `aria-label` are not — and a spread (`{...props}`, the* ordinary host idiom) bypasses the check for every member, `role` included.- * Measured, not assumed. So the components also emit their own `aria-hidden`- * AFTER `{...rest}` and drop a forwarded `tabIndex`: that ordering, not the- * type, is what enforces the contract. Nothing else is stripped — a forwarded- * `aria-label` still reaches the DOM, inert inside an `aria-hidden` subtree.+ * Measured, not assumed. So the components emit their own `aria-hidden` AFTER+ * `{...rest}`; that ordering, not the type, prevents a caller from un-hiding the+ * root. A spread can still forward `tabIndex`, so callers must keep focus props+ * on the owning control; the supported typed indicator API rejects them. Nothing+ * else is stripped — a forwarded `aria-label` remains inert inside the hidden+ * subtree.** Interaction state is deliberately *not* a prop. Hover and focus reach an* indicator through the CSS ancestor marker ({@link indicatorScope}) applieddiff --git a/packages/core/src/utils/isRenderable.ts b/packages/core/src/utils/isRenderable.tsindex 5e681c57a9..2238a00ac8 100644--- a/packages/core/src/utils/isRenderable.ts+++ b/packages/core/src/utils/isRenderable.ts@@ -3,22 +3,24 @@/*** @file isRenderable.ts* @input A ReactNode value- * @output Boolean indicating whether the value will produce DOM output- * @position Utility for checking if a React slot prop has meaningful content.+ * @output Boolean indicating whether the value passes the shallow React-slot check+ * @position Utility for checking if a React slot prop has non-empty scalar content.** React treats null, undefined, true, false, and '' as empty — they render- * nothing. This utility checks if a ReactNode is NOT one of those values,- * meaning it will produce actual DOM output when rendered.+ * nothing. This utility excludes exactly those values. It does not inspect+ * descendants: elements, arrays, fragments, and other containers return true+ * even when their contents ultimately render nothing.*- * Use this instead of `prop != null` when checking if a slot has content,- * since boolean/empty-string props also render nothing.+ * Use this instead of `prop != null` when a slot should also reject booleans and+ * the empty string. Do not use the return value as proof that DOM output exists.*/import type {ReactNode} from 'react';/**- * Returns true if a ReactNode value will produce DOM output when rendered.- * Returns false for null, undefined, true, false, and empty string.+ * Returns false for null, undefined, booleans, and the empty string; true for+ * every other ReactNode value. The check is shallow and does not inspect the+ * descendants of elements or containers.** @example* ```tsx