An open source design system that's fully customizable and agent ready
TypeScript
fix(indicator): the decorative contract is not a caller's to switch off (#4918) (#4921)
Cindy Zhang653729439e40
diff --git a/.changeset/indicator-decorative-contract.md b/.changeset/indicator-decorative-contract.mdnew file mode 100644index 0000000000..35f6b1c0b4--- /dev/null+++ b/.changeset/indicator-decorative-contract.md@@ -0,0 +1,11 @@+---+'@astryxdesign/core': patch+---++[fix] Indicator: a caller can no longer un-hide a decorative indicator. `IndicatorProps` now omits `aria-hidden`, `role`, `aria-label` and `aria-labelledby` — passing `role` is a compile error — and each indicator emits its own `aria-hidden` after `{...rest}`, so a forwarded one cannot win. Un-hiding an indicator had it announced next to the control that owns the accessible name, saying the same thing twice.++Nothing is stripped: every other prop, including a forwarded `aria-label`, still reaches the DOM, where it is inert inside an `aria-hidden` subtree. Note that TypeScript exempts hyphenated JSX attributes from excess-property checking, so the type alone cannot reject `aria-*`; the attribute order is what enforces it.++Fixes #4918.++@cixzhangdiff --git a/packages/core/src/Indicator/CheckIndicator.tsx b/packages/core/src/Indicator/CheckIndicator.tsxindex b68042d6a7..b171d60a93 100644--- a/packages/core/src/Indicator/CheckIndicator.tsx+++ b/packages/core/src/Indicator/CheckIndicator.tsx@@ -114,7 +114,9 @@ export function CheckIndicator({<span// Spread first, as on the glyph path below, so the indicator's own// contract (aria-hidden, and the styling it composes) outranks any- // same-named attribute a caller passed through.+ // same-named attribute a caller passed through. The type omits the+ // a11y props, but TypeScript cannot reject a hyphenated JSX attribute,+ // so order is the part that actually holds.{...rest}ref={ref}aria-hidden="true"@@ -149,6 +151,11 @@ export function CheckIndicator({// (IconFromRegistry renders one), so forwarding them is correct at// runtime; the cast only reconciles the two declarations.{...(rest as Omit<SVGProps<SVGSVGElement>, 'color' | 'ref'>)}+ // After the spread, deliberately. Icon puts its own a11y defaults BEFORE+ // `{...props}` as a documented escape hatch (Icon.tsx), which is right+ // for an icon and wrong for an indicator — this one is decorative by+ // contract, so it re-asserts it here rather than inheriting the hatch.+ aria-hidden="true"icon="check"size={iconSizeForIndicator[size]}color={isDisabled ? 'disabled' : 'accent'}diff --git a/packages/core/src/Indicator/CheckboxIndicator.tsx b/packages/core/src/Indicator/CheckboxIndicator.tsxindex 06e7e3ab34..e908c1af47 100644--- a/packages/core/src/Indicator/CheckboxIndicator.tsx+++ b/packages/core/src/Indicator/CheckboxIndicator.tsx@@ -187,6 +187,11 @@ export function CheckboxIndicator({return (<span+ // `{...rest}` first, own contract after. TypeScript cannot reject a+ // hyphenated JSX attribute (see IndicatorProps), so attribute order is+ // what actually keeps a caller from un-hiding a decorative element —+ // rubric P3, "owned aria-* set after {...rest}".+ {...rest}ref={ref}aria-hidden="true"{...mergeProps(@@ -215,8 +220,7 @@ export function CheckboxIndicator({),className,style,- )}- {...rest}>+ )}>{isRenderable(children) ? (children) : (diff --git a/packages/core/src/Indicator/Indicator.doc.mjs b/packages/core/src/Indicator/Indicator.doc.mjsindex 8371bf39ba..8db5efad76 100644--- a/packages/core/src/Indicator/Indicator.doc.mjs+++ b/packages/core/src/Indicator/Indicator.doc.mjs@@ -191,6 +191,8 @@ defineTheme({// --color-border-emphasized, --color-background-surface,// --color-background-muted. Radius: --radius-inner, --radius-full.// Border width: --border-width.+import {isRenderable} from '@astryxdesign/core/utils';+function BrandCheckbox({state, size = 'md', isDisabled, children}) {return (<span@@ -203,8 +205,14 @@ function BrandCheckbox({state, size = 'md', isDisabled, children}) {color: 'var(--color-accent)',opacity: isDisabled ? 0.5 : 1,}}>- {/* children first: the owner passes a loading Spinner through it */}- {children ?? (state === 'checked' ? <StarGlyph /> : null)}+ {/* children first: the owner passes a loading Spinner through it.+ isRenderable, NOT \`children ??\` — a host writes+ children={isBusy && <Spinner/>}, and \`false\` is neither null nor+ caught by ??, so a nullish check takes the children branch, renders+ nothing in it, and deletes your mark on every chosen row. */}+ {isRenderable(children)+ ? children+ : state === 'checked' && <StarGlyph />}</span>);}@@ -233,7 +241,7 @@ defineTheme({name: 'brand', indicators: {check: RadioIndicator}});`,{guidance: true,description:- 'A replacement must render `children` when present — the owning control passes its loading Spinner through it, and dropping it loses the busy visual while aria-busy still fires.',+ '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).',},{guidance: true,diff --git a/packages/core/src/Indicator/Indicator.test.tsx b/packages/core/src/Indicator/Indicator.test.tsxindex 8a6814594f..9e38a84455 100644--- a/packages/core/src/Indicator/Indicator.test.tsx+++ b/packages/core/src/Indicator/Indicator.test.tsx@@ -205,6 +205,91 @@ describe('falsy children never suppress the state mark (#4893)', () => {});});+/**+ * An indicator is decorative BY CONTRACT: the owning control supplies the role+ * and the accessible name, so an indicator that is also announced says the same+ * thing twice (#4918).+ *+ * The contract is held in two places, because neither covers the whole thing:+ *+ * - `IndicatorProps` omits the a11y props, which makes `role` a compile+ * error. It does NOT make `aria-hidden` one: TypeScript exempts JSX+ * attribute names that are not valid JS identifiers from excess-property+ * checking, so anything hyphenated slips through. That is a language rule,+ * not a gap in our types — the second test below is the proof, and it will+ * start failing the day TS changes its mind, which is when we can drop the+ * ordering.+ * - So each component emits its own `aria-hidden` AFTER `{...rest}`, which is+ * what actually keeps a caller from un-hiding it. Nothing is stripped.+ */+describe('the decorative contract (#4918)', () => {+ it('rejects `role` at compile time', () => {+ // @ts-expect-error — the owning control holds the role.+ const rejected = <CheckIndicator state="checked" role="checkbox" />;++ expect(rejected).toBeTruthy();+ });++ it('cannot reject a hyphenated a11y attribute — TS exempts those', () => {+ // NO @ts-expect-error here, deliberately: this compiles, and the comment+ // above explains why. Runtime order is what makes it harmless.+ const accepted = <CheckIndicator state="checked" aria-label="inert" />;++ expect(accepted).toBeTruthy();+ });++ const cases = [+ {+ name: 'CheckIndicator (glyph path)',+ render: (p: Record<string, unknown>) => (+ <CheckIndicator state="checked" {...p} />+ ),+ },+ {+ name: 'CheckIndicator (children path)',+ render: (p: Record<string, unknown>) => (+ <CheckIndicator state="checked" {...p}>+ <b />+ </CheckIndicator>+ ),+ },+ {+ name: 'CheckboxIndicator',+ render: (p: Record<string, unknown>) => (+ <CheckboxIndicator state="checked" {...p} />+ ),+ },+ {+ name: 'RadioIndicator',+ render: (p: Record<string, unknown>) => (+ <RadioIndicator state="checked" {...p} />+ ),+ },+ ] as const;++ for (const {name, render: renderCase} of cases) {+ it(`${name} stays aria-hidden even when a caller passes false`, () => {+ const {container} = render(renderCase({'aria-hidden': 'false'}));++ expect(container.firstElementChild).toHaveAttribute(+ 'aria-hidden',+ 'true',+ );+ });++ it(`${name} still forwards ordinary props`, () => {+ // The negative control: order must not turn into "drop everything".+ const {container} = render(+ renderCase({'data-testid': 'ind', id: 'pinned'}),+ );+ const el = container.firstElementChild;++ expect(el).toHaveAttribute('data-testid', 'ind');+ expect(el).toHaveAttribute('id', 'pinned');+ });+ }+});+describe('useIndicator', () => {it('returns the built-in indicator without a theme override', () => {const {result} = renderHook(() => useIndicator('checkbox'));diff --git a/packages/core/src/Indicator/RadioIndicator.tsx b/packages/core/src/Indicator/RadioIndicator.tsxindex d48315dd0f..8dcf90fb57 100644--- a/packages/core/src/Indicator/RadioIndicator.tsx+++ b/packages/core/src/Indicator/RadioIndicator.tsx@@ -155,6 +155,11 @@ export function RadioIndicator({return (<span+ // `{...rest}` first, own contract after. TypeScript cannot reject a+ // hyphenated JSX attribute (see IndicatorProps), so attribute order is+ // what actually keeps a caller from un-hiding a decorative element —+ // rubric P3, "owned aria-* set after {...rest}".+ {...rest}ref={ref}aria-hidden="true"{...mergeProps(@@ -179,8 +184,7 @@ export function RadioIndicator({),className,style,- )}- {...rest}>+ )}>{isRenderable(children)? children: isChecked && (diff --git a/packages/core/src/Indicator/types.ts b/packages/core/src/Indicator/types.tsindex 3a9d831c04..61cebc2b8b 100644--- a/packages/core/src/Indicator/types.ts+++ b/packages/core/src/Indicator/types.ts@@ -75,6 +75,19 @@ export type IndicatorSize = 'sm' | 'md';* (CheckboxInput, RadioListItem, a listbox option) keeps all of that. An* indicator's only job is to turn `state` into a picture.*+ * The a11y props are omitted from this interface rather than left to+ * convention: un-hiding an indicator has it announced next to the control that+ * owns the accessible name — the same thing said twice (#4918). A replacement+ * that genuinely needs announcing is not an indicator; name the owning control.+ *+ * The omission is only half enforceable, and it is worth knowing which half.+ * TypeScript exempts JSX attribute names that are not valid JS identifiers from+ * excess-property checking, so `role` (an identifier) is a compile error while+ * `aria-hidden` and `aria-label` (hyphenated) are not — measured, not assumed.+ * The components therefore emit their own `aria-hidden` AFTER `{...rest}`, so a+ * forwarded one cannot win. Nothing is stripped: a forwarded `aria-label` still+ * reaches the DOM, where it is inert inside an `aria-hidden` subtree.+ ** Interaction state is deliberately *not* a prop. Hover and focus reach an* indicator through the CSS ancestor marker ({@link indicatorScope}) applied* by its owner, so a row hover tints the control without anyone threading a@@ -83,7 +96,10 @@ export type IndicatorSize = 'sm' | 'md';*/export interface IndicatorProps<F extends IndicatorFamily = IndicatorFamily,-> extends BaseProps<HTMLSpanElement> {+> extends Omit<+ BaseProps<HTMLSpanElement>,+ 'aria-hidden' | 'role' | 'aria-label' | 'aria-labelledby'+> {/** Ref forwarded to the indicator's root element. */ref?: Ref<HTMLSpanElement>;/** Which state to draw. The state space is fixed by the family. */