Skip to content

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

TypeScript

fix(ComplexSelector): a caller's aria-label or aria-labelledby names the built-in trigger (#8540)

Cindy Zhanga81b3ad86b06
diff --git a/.changeset/complexselector-trigger-caller-name.md b/.changeset/complexselector-trigger-caller-name.md
new file mode 100644
index 0000000000..e533ebf0bc
--- /dev/null
+++ b/.changeset/complexselector-trigger-caller-name.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] ComplexSelector: a caller's `aria-label` or `aria-labelledby` now names the built-in trigger, replacing the field label, as it already did for a `renderTrigger` control. Before, the built-in trigger always took its name from the label, so a name passed to the selector was never announced.
+
+@cixzhang
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.spec.md b/packages/core/src/ComplexSelector/ComplexSelector.spec.md
index 8954e1a863..07ecebcf21 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.spec.md
+++ b/packages/core/src/ComplexSelector/ComplexSelector.spec.md
@@ -166,7 +166,7 @@ durable constraints and their verification target.
## Accessibility contract
-- **AR1 — Built-in name and state.** The trigger plays the combobox role, receives its accessible name from Field, and exposes its dialog popup (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`), required and invalid state, description/status references, busy state, and disabled state through `aria-disabled` while it keeps its tab stop.
+- **AR1 — Built-in name and state.** The trigger plays the combobox role and is named by the field's `label` unless the selector was given `aria-label` or `aria-labelledby`, which replaces it (`family:input-fields` FR10), and exposes its dialog popup (`aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`), required and invalid state, description/status references, busy state, and disabled state through `aria-disabled` while it keeps its tab stop.
- **AR2 — Caller-rendered field.** The handed-back trigger props carry the anchor ref, id, click and ArrowDown handlers, `role="combobox"`, `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls`, `aria-busy`, `aria-required`, and `aria-disabled`, and name the control with `label` unless the selector was given `aria-label` or `aria-labelledby`, because a combobox takes no name from its content; the caller control renders unwrapped as the only opener.
- **AR3 — Focus lifecycle.** The popup autofocuses its content through the Popover owner, and every supported close route returns focus to the current trigger before `onOpenChange(false)` runs.
- **AR4 — Content responsibility.** Caller content supplies the role, name, keyboard model, selected state, and focus navigation appropriate to its own selection pattern.
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
index c0210e53b4..211ddd9b8d 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
@@ -712,6 +712,49 @@ describe('ComplexSelector trigger semantics', () => {
expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
});
+ it('names the built-in trigger with the field label when the caller gives no name', () => {
+ render(
+ <ComplexSelector label="Destination" value={[]}>
+ {() => <button type="button">Apply</button>}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('combobox', {name: 'Destination'});
+ const labelId = trigger.getAttribute('aria-labelledby');
+ expect(labelId).toBeTruthy();
+ expect(document.getElementById(labelId!)).toHaveTextContent('Destination');
+ expect(trigger).not.toHaveAttribute('aria-label');
+ });
+
+ it("lets a caller's aria-label name the built-in trigger instead of the field label (family:input-fields FR10)", () => {
+ render(
+ <ComplexSelector
+ label="Destination"
+ aria-label="Trip destination"
+ value={[]}>
+ {() => <button type="button">Apply</button>}
+ </ComplexSelector>,
+ );
+ const trigger = screen.getByRole('combobox', {name: 'Trip destination'});
+ expect(trigger).toHaveAttribute('aria-label', 'Trip destination');
+ expect(trigger).not.toHaveAttribute('aria-labelledby');
+ });
+
+ it("lets a caller's aria-labelledby replace the field label on the built-in trigger (family:input-fields FR10)", () => {
+ render(
+ <>
+ <span id="trip-heading">Where to next</span>
+ <ComplexSelector
+ label="Destination"
+ aria-labelledby="trip-heading"
+ value={[]}>
+ {() => <button type="button">Apply</button>}
+ </ComplexSelector>
+ </>,
+ );
+ const trigger = screen.getByRole('combobox', {name: 'Where to next'});
+ expect(trigger).toHaveAttribute('aria-labelledby', 'trip-heading');
+ });
+
it('spreads the combobox role, required, and disabled state onto a caller control', async () => {
const user = userEvent.setup();
const onClick = vi.fn();
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsx
index 85701f9454..47a7b92df0 100644
--- a/packages/core/src/ComplexSelector/ComplexSelector.tsx
+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx
@@ -840,7 +840,13 @@ export function ComplexSelector<Value>({
[ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
undefined
}
- aria-labelledby={labelId}
+ // The field's label names the trigger unless the selector was
+ // given a name: a caller's `aria-label` or `aria-labelledby`
+ // replaces it (family:input-fields FR10), as on `renderTrigger`.
+ aria-labelledby={
+ rest['aria-labelledby'] ??
+ (rest['aria-label'] != null ? undefined : labelId)
+ }
aria-required={isEffectivelyRequired ? 'true' : undefined}
aria-invalid={status?.type === 'error' ? 'true' : undefined}
aria-busy={isBusy || undefined}