An open source design system that's fully customizable and agent ready
TypeScript
fix(indicator): omit tabIndex from IndicatorProps (#4947)
Cindy Zhang23b60eaacbbd
diff --git a/.changeset/indicator-tabindex.md b/.changeset/indicator-tabindex.mdnew file mode 100644index 0000000000..bbdc0be120--- /dev/null+++ b/.changeset/indicator-tabindex.md@@ -0,0 +1,9 @@+---+'@astryxdesign/core': patch+---++[fix] Indicator: `IndicatorProps` also omits `tabIndex`. An indicator is unconditionally `aria-hidden`, so a tab stop on one is a focusable node inside a hidden subtree — an axe `aria-hidden-focus` violation. `tabIndex` is a plain identifier, so the omission makes it a compile error on its own, the same way `role` already is.++Also corrects two doc claims: a replacement must render `children` when they will actually draw something (`isRenderable`, not `children ?? mark`), and "passing `role` is a compile error" holds for a literal attribute — a spread bypasses excess-property checking.++@cixzhangdiff --git a/packages/core/src/Indicator/Indicator.doc.mjs b/packages/core/src/Indicator/Indicator.doc.mjsindex cf4359b3b8..269aca83ef 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 present or the busy visual is lost.',+ '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 — `isRenderable(children)`, never `children ?? mark`, because a host writes `children={isBusy && <Spinner/>}` and `false` slips straight past a nullish check and deletes the mark.',},],},diff --git a/packages/core/src/Indicator/Indicator.test.tsx b/packages/core/src/Indicator/Indicator.test.tsxindex 9e38a84455..046053e9ab 100644--- a/packages/core/src/Indicator/Indicator.test.tsx+++ b/packages/core/src/Indicator/Indicator.test.tsx@@ -223,11 +223,19 @@ describe('falsy children never suppress the state mark (#4893)', () => {* 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('rejects `role` and `tabIndex` at compile time', () => {+ // Both are valid JS identifiers, so excess-property checking applies and+ // the type alone is enough — no runtime guard needed. `tabIndex` matters+ // because the element is unconditionally aria-hidden: a tab stop on it is+ // a focusable node in a hidden subtree (axe `aria-hidden-focus`).+ const rejected = [+ // @ts-expect-error — the owning control holds the role.+ <CheckIndicator key="a" state="checked" role="checkbox" />,+ // @ts-expect-error — the owning control holds the focus.+ <CheckboxIndicator key="b" state="checked" tabIndex={0} />,+ ];++ expect(rejected).toHaveLength(2);});it('cannot reject a hyphenated a11y attribute — TS exempts those', () => {@@ -238,6 +246,21 @@ describe('the decorative contract (#4918)', () => {expect(accepted).toBeTruthy();});+ it('cannot reject a SPREAD either — which is the ordinary host idiom', () => {+ // Also no @ts-expect-error, also deliberate. A spread bypasses+ // excess-property checking for every member, so even `role` and `tabIndex`+ // — the two the type catches as literals — get through this way.+ //+ // Left alone on purpose. Nothing in the repo spreads a hostile object at an+ // indicator, `aria-hidden` is settled by attribute order regardless, and a+ // forwarded `role`/`aria-label` is inert inside a hidden subtree. Guarding+ // it at runtime would cost a module to defend a case no call site reaches.+ const hostile = {role: 'checkbox', tabIndex: 0};+ const accepted = <CheckIndicator state="checked" {...hostile} />;++ expect(accepted).toBeTruthy();+ });+const cases = [{name: 'CheckIndicator (glyph path)',@@ -280,12 +303,13 @@ describe('the decorative contract (#4918)', () => {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'}),+ renderCase({'data-testid': 'ind', id: 'pinned', dir: 'rtl'}),);const el = container.firstElementChild;expect(el).toHaveAttribute('data-testid', 'ind');expect(el).toHaveAttribute('id', 'pinned');+ expect(el).toHaveAttribute('dir', 'rtl');});}});diff --git a/packages/core/src/Indicator/types.ts b/packages/core/src/Indicator/types.tsindex 61cebc2b8b..f76ebcab9f 100644--- a/packages/core/src/Indicator/types.ts+++ b/packages/core/src/Indicator/types.ts@@ -80,13 +80,20 @@ export type IndicatorSize = 'sm' | 'md';* owns the accessible name — the same thing said twice (#4918). A replacement* that genuinely needs announcing is not an indicator; name the owning control.*+ * `tabIndex` is omitted for the same reason, one step on: the element is+ * unconditionally `aria-hidden`, so a tab stop on it is a focusable node inside+ * a hidden subtree. Measured with axe in real Chromium: 0 `aria-hidden-focus`+ * violations becomes 1 the moment it is forwarded.+ ** 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.+ * 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.** Interaction state is deliberately *not* a prop. Hover and focus reach an* indicator through the CSS ancestor marker ({@link indicatorScope}) applied@@ -98,7 +105,7 @@ export interface IndicatorProps<F extends IndicatorFamily = IndicatorFamily,> extends Omit<BaseProps<HTMLSpanElement>,- 'aria-hidden' | 'role' | 'aria-label' | 'aria-labelledby'+ 'aria-hidden' | 'role' | 'aria-label' | 'aria-labelledby' | 'tabIndex'> {/** Ref forwarded to the indicator's root element. */ref?: Ref<HTMLSpanElement>;