Skip to content

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

TypeScript

fix(TextInput): keep a caller aria-labelledby on the input (#8707)

홍규진a8374b5c5a6d
diff --git a/.changeset/text-input-caller-labelledby.md b/.changeset/text-input-caller-labelledby.md
new file mode 100644
index 0000000000..4164bbcdf9
--- /dev/null
+++ b/.changeset/text-input-caller-labelledby.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TextInput: a caller's `aria-labelledby` now reaches the input. Before, TextInput replaced it with its own value, so the input lost the extra name (standalone it had no `aria-labelledby` at all). Now the caller's ids follow the field's own label: `label="Email" aria-labelledby="billing-heading"` names the input "Email Billing", and inside an InputGroup the group label comes first. Inputs without a caller `aria-labelledby` are unchanged. No API changes.
+
+@kyu-rong
diff --git a/packages/core/src/TextInput/TextInput.spec.md b/packages/core/src/TextInput/TextInput.spec.md
index ac60ab74b2..4fa33bad5b 100644
--- a/packages/core/src/TextInput/TextInput.spec.md
+++ b/packages/core/src/TextInput/TextInput.spec.md
@@ -118,7 +118,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| FR10 | Enter calls `onEnter` unless the key event commits an IME composition; `onKeyDown` receives every key, including composing ones. | Current tests |
| FR11 | Standalone, height comes from the shared element size for the resolved size, as a minimum that grows with a set text size under `spec:AST-102` FR4: explicit `size`, then the nearest size provider, then `md`. Implementation gap: the height is fixed at that size. Inside InputGroup the control fills the group row's height, so its own `size` does not set its height. Text uses the body type size at every size, floored at 16 CSS px only on the iOS touch path. | `family:input-fields` FR9; `architecture:component-size-cascade`; current source and tests; `spec:AST-102` FR4 |
| FR12 | `startIcon` renders a small secondary icon before the input. While the field is enabled, a click on the control box outside the input focuses the input. | Current tests |
-| FR13 | Base props (`ref`, `id`, `aria-*`, `data-*`, DOM handlers, and the like) reach the native input; `aria-describedby` is joined with TextInput's own descriptions. `container*` reaches the Field box and `control*` the control box. Root `xstyle`, `className`, and `style` are not accepted; an untyped one is dropped with a development warning. | `family:input-fields` FR10; current tests |
+| FR13 | Base props (`ref`, `id`, `aria-*`, `data-*`, DOM handlers, and the like) reach the native input; `aria-describedby` is joined with TextInput's own descriptions, and `aria-labelledby` follows the field's own label (AR1). `container*` reaches the Field box and `control*` the control box. Root `xstyle`, `className`, and `style` are not accepted; an untyped one is dropped with a development warning. | `family:input-fields` FR10; current tests |
| FR14 | The control box carries `astryx-text-input` and reflects `data-size`, `data-status` when set, `data-disabled` when disabled, and `data-readonly` when read-only. | `architecture:component-theming-surface`; current tests |
| FR15 | The input has no minimum inline size, so a row can shrink the whole field. End controls (clear, Spinner, status icon) are in-flow items after the input and never overlap its text. | `family:input-fields` FR1, FR2; current tests |
@@ -161,8 +161,10 @@ Consumer migration instructions belong in consumer docs and release notes.
- **AR1 — Name and description.** Standalone, Field's native label names the
input; inside InputGroup, `aria-labelledby` names it by the group label, then
- its own visually hidden label. It is described per ORD3, including the
- group's description and status message inside InputGroup.
+ its own visually hidden label. A caller `aria-labelledby` follows that
+ label: the Field label standalone, the group and input labels inside
+ InputGroup. It is described per ORD3, including the group's description and
+ status message inside InputGroup.
- **AR2 — State.** `aria-required` when effectively required, `aria-invalid`
for an error, `aria-busy` while busy, `aria-disabled` while disabled.
- **AR3 — Disabled reachability.** FR6 and FR7 satisfy `spec:AST-085` FR1,
@@ -216,7 +218,7 @@ anatomy-theming map.
| FR10 | `TextInput.test.tsx` onEnter and onKeyDown suites | Enter; IME commit; other keys | `onEnter` during IME commit fails. | `audit:TextInput/behavior` |
| FR11, FR15 | `TextInput.test.tsx` text-size and narrow-row cases | Outside the iOS gate; narrow filter bar | A floor off iOS, or a field that overflows its row, fails. Evidence gap: no test asserts the height per size, the size precedence, or that end controls never overlap the text. No test asserts the grouped height. | `audit:TextInput/layout` |
| FR12 | `TextInput.test.tsx` start-icon and click-to-focus cases | Icon; wrapper padding | Clicks that do not focus the input fail. Evidence gap: no test asserts the start icon's size or color. | `audit:TextInput/behavior` |
-| FR13 | `TextInput.fr10.test.tsx` | Standalone and in group | A base prop off the input, or styling on the wrong part, fails. | `audit:TextInput/api` |
+| FR13 | `TextInput.fr10.test.tsx`; `TextInput.test.tsx` caller `aria-labelledby` cases | Standalone and in group | A base prop off the input, or styling on the wrong part, fails. | `audit:TextInput/api` |
| FR14 | `TextInput.test.tsx` theme-state suites | Disabled and read-only | A missing state attribute fails. Evidence gap: no test asserts `data-size` or `data-status`. | `audit:TextInput/theming` |
| AR4 | `TextInput.a11y.chromium.spec.ts` with its recorded known failure | Error without message | The known failure stops matching when the gap closes. Evidence gap: no test renders a `detached` status without a message. | `audit:TextInput/accessibility` |
| ORD1–ORD3, PR1 | ORD1 and ORD2 are covered by the FR3 and FR6–FR8 rows. Evidence gap: no test asserts the description order or the absence of measurement | — | — | `audit:TextInput/behavior` |
diff --git a/packages/core/src/TextInput/TextInput.test.tsx b/packages/core/src/TextInput/TextInput.test.tsx
index 7bc939bbc6..9e53fb5b6f 100644
--- a/packages/core/src/TextInput/TextInput.test.tsx
+++ b/packages/core/src/TextInput/TextInput.test.tsx
@@ -315,6 +315,49 @@ describe('TextInput', () => {
}
});
+ it('names the input by its label and a caller aria-labelledby', () => {
+ render(
+ <>
+ <span id="billing-heading">Billing</span>
+ <TextInput
+ label="Email"
+ value=""
+ onChange={() => {}}
+ aria-labelledby="billing-heading"
+ />
+ </>,
+ );
+ const input = screen.getByRole('textbox', {name: 'Email Billing'});
+ expect(input.getAttribute('aria-labelledby')?.split(' ')).toContain(
+ 'billing-heading',
+ );
+ });
+
+ it('names a grouped input by the group, its label, and a caller aria-labelledby', () => {
+ render(
+ <>
+ <span id="billing-heading">Billing</span>
+ <InputGroup label="Contact">
+ <TextInput
+ label="Email"
+ value=""
+ onChange={() => {}}
+ aria-labelledby="billing-heading"
+ />
+ </InputGroup>
+ </>,
+ );
+ expect(
+ screen.getByRole('textbox', {name: 'Contact Email Billing'}),
+ ).toBeInTheDocument();
+ });
+
+ it('leaves a standalone input named by its label element without a caller aria-labelledby', () => {
+ render(<TextInput label="Email" value="" onChange={() => {}} />);
+ const input = screen.getByRole('textbox', {name: 'Email'});
+ expect(input).not.toHaveAttribute('aria-labelledby');
+ });
+
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 93804c7af3..92aab932ab 100644
--- a/packages/core/src/TextInput/TextInput.tsx
+++ b/packages/core/src/TextInput/TextInput.tsx
@@ -49,6 +49,7 @@ import {Spinner} from '../Spinner';
import {useTooltip} from '../Tooltip';
import {VisuallyHidden} from '../VisuallyHidden';
import {getInputARIA, isImeKeyEvent} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
const styles = stylex.create({
input: {
@@ -327,6 +328,7 @@ export function TextInput({
ref,
id: idProp,
'aria-describedby': ariaDescribedByProp,
+ 'aria-labelledby': ariaLabelledByProp,
...restProps
}: TextInputProps) {
const inputGroup = useInputGroup();
@@ -352,6 +354,7 @@ export function TextInput({
const generatedID = useId();
const id = idProp ?? generatedID;
+ const fieldLabelID = useId();
const inputLabelID = useId();
const descriptionID = useId();
const statusMessageID = useId();
@@ -401,6 +404,12 @@ export function TextInput({
],
inputGroup,
);
+ // A caller aria-labelledby names the input together with the field's own
+ // label (the Field label standalone, the group and input labels in a group).
+ const inputLabelledBy =
+ ariaLabelledByProp != null
+ ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+ : ariaLabelledBy;
const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
// Value can't change while showing a disabled message (the field is
@@ -525,7 +534,7 @@ export function TextInput({
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}
- aria-labelledby={ariaLabelledBy}
+ aria-labelledby={inputLabelledBy}
{...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
/>
{hasClear && value !== '' && !isDisabled && !isReadOnly && (
@@ -556,6 +565,7 @@ export function TextInput({
isLabelHidden={isLabelHidden}
description={description}
inputID={id}
+ labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
descriptionID={description ? descriptionID : undefined}
isOptional={isOptional}
isRequired={isRequired}