Skip to content

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