Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): include NumberInput units in the accessible description; drop dangling describedby in groups (#4355)

Baraa Hamodi5b289eb51da0
diff --git a/.changeset/a11y-number-input-units.md b/.changeset/a11y-number-input-units.md
new file mode 100644
index 0000000000..bb372c6bfc
--- /dev/null
+++ b/.changeset/a11y-number-input-units.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] NumberInput: announce the units text through the input's accessible description, and stop TextInput/NumberInput from referencing the non-rendered status message id in aria-describedby inside InputGroup
+@bhamodi
diff --git a/packages/core/src/NumberInput/NumberInput.test.tsx b/packages/core/src/NumberInput/NumberInput.test.tsx
index 3ac017f3b2..10710a6b17 100644
--- a/packages/core/src/NumberInput/NumberInput.test.tsx
+++ b/packages/core/src/NumberInput/NumberInput.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
import {NumberInput} from './NumberInput';
import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
@@ -336,6 +337,33 @@ describe('NumberInput', () => {
expect(screen.queryByText('%')).not.toBeInTheDocument();
expect(screen.queryByText('GB')).not.toBeInTheDocument();
});
+
+ it('includes the units text in the accessible description (WCAG 1.3.1)', () => {
+ render(
+ <NumberInput
+ label="Storage"
+ value={50}
+ onChange={() => {}}
+ units="GB"
+ />,
+ );
+ expect(screen.getByRole('spinbutton')).toHaveAccessibleDescription(/GB/);
+ });
+
+ it('combines units with the description in the accessible description', () => {
+ render(
+ <NumberInput
+ label="Discount"
+ value={10}
+ onChange={() => {}}
+ description="Applied at checkout"
+ units="%"
+ />,
+ );
+ const input = screen.getByRole('spinbutton');
+ expect(input).toHaveAccessibleDescription(/Applied at checkout/);
+ expect(input).toHaveAccessibleDescription(/%/);
+ });
});
describe('event callbacks', () => {
@@ -463,6 +491,26 @@ describe('NumberInput', () => {
expect(screen.getByText('Value must be positive')).toBeInTheDocument();
});
+ it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+ // Inside an InputGroup no Field renders, so the status message element
+ // does not exist; aria-describedby must not reference its id.
+ render(
+ <InputGroup label="Price">
+ <NumberInput
+ label="Amount"
+ value={null}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Value must be positive'}}
+ />
+ </InputGroup>,
+ );
+ const input = screen.getByRole('spinbutton');
+ const describedBy = input.getAttribute('aria-describedby') ?? '';
+ for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+ expect(document.getElementById(idToken)).not.toBeNull();
+ }
+ });
+
it('does not render status message when not provided', () => {
render(
<NumberInput
diff --git a/packages/core/src/NumberInput/NumberInput.tsx b/packages/core/src/NumberInput/NumberInput.tsx
index 84209f710f..8cfaad8c3f 100644
--- a/packages/core/src/NumberInput/NumberInput.tsx
+++ b/packages/core/src/NumberInput/NumberInput.tsx
@@ -414,6 +414,7 @@ export function NumberInput({
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
+ const unitsID = useId();
const inputRef = useRef<HTMLInputElement | null>(null);
const containerRef = useRef<HTMLDivElement | null>(null);
const inputGroup = useInputGroup();
@@ -454,7 +455,10 @@ export function NumberInput({
inputLabelID,
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ // The status message element is rendered by Field, which is skipped
+ // inside an InputGroup — only reference it when it actually exists.
+ !inputGroup && status?.message ? statusMessageID : null,
+ units ? unitsID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,
@@ -660,7 +664,11 @@ export function NumberInput({
!isInputValid && styles.inputInvalid,
)}
/>
- {units && <span {...stylex.props(styles.units)}>{units}</span>}
+ {units && (
+ <span id={unitsID} {...stylex.props(styles.units)}>
+ {units}
+ </span>
+ )}
{/*
Live region announcing invalid typed input to assistive technology.
The value silently reverts on blur, so without this a screen-reader
diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsx
index 673de915c0..35a5bf2980 100644
--- a/packages/core/src/TextInput/TextInput.test.tsx
+++ b/packages/core/src/TextInput/TextInput.test.tsx
@@ -13,6 +13,7 @@ import {describe, it, expect, vi, beforeEach} from 'vitest';
import {render, screen, fireEvent, waitFor} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TestIcon} from '../__tests__/TestIcon';
+import {InputGroup} from '../InputGroup';
import {TextInput} from './TextInput';
// Mock showPopover/hidePopover since jsdom does not implement them. Used by the
@@ -229,6 +230,26 @@ describe('TextInput', () => {
expect(screen.getByText('Invalid email address')).toBeInTheDocument();
});
+ it('has no dangling aria-describedby ids inside InputGroup (WCAG 1.3.1)', () => {
+ // Inside an InputGroup no Field renders, so the status message element
+ // does not exist; aria-describedby must not reference its id.
+ render(
+ <InputGroup label="Contact">
+ <TextInput
+ label="Email"
+ value=""
+ onChange={() => {}}
+ status={{type: 'error', message: 'Invalid email address'}}
+ />
+ </InputGroup>,
+ );
+ const input = screen.getByRole('textbox');
+ const describedBy = input.getAttribute('aria-describedby') ?? '';
+ for (const idToken of describedBy.split(/\s+/).filter(Boolean)) {
+ expect(document.getElementById(idToken)).not.toBeNull();
+ }
+ });
+
it('does not render status message when not provided', () => {
render(
<TextInput
diff --git a/packages/core/src/TextInput/TextInput.tsx b/packages/core/src/TextInput/TextInput.tsx
index ee71fc91b3..62cd1a4bd6 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -356,7 +356,9 @@ export function TextInput({
inputLabelID,
[
description ? descriptionID : null,
- status?.message ? statusMessageID : null,
+ // The status message element is rendered by Field, which is skipped
+ // inside an InputGroup — only reference it when it actually exists.
+ !inputGroup && status?.message ? statusMessageID : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
],
inputGroup,