Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/core/src/Indicator/CheckIndicator.tsx b/packages/core/src/Indicator/CheckIndicator.tsx
index 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.tsx
index 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.mjs
index 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.tsx
index 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.tsx
index 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.ts
index 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. */