Skip to content

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

TypeScript

fix(core): combobox minors — tri-state select-all name, listbox content model, Typeahead tab order (#4365)

Baraa Hamodie2815e176b96
diff --git a/.changeset/a11y-selector-minors.md b/.changeset/a11y-selector-minors.md
new file mode 100644
index 0000000000..f5300d1d0e
--- /dev/null
+++ b/.changeset/a11y-selector-minors.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Selector: convey MultiSelector select-all partial state in its accessible name, mark Selector/MultiSelector empty-state messages presentational inside the listbox, and remove Typeahead's collapsed input from the Tab order while a token is shown
+@bhamodi
diff --git a/packages/core/locales/en.json b/packages/core/locales/en.json
index fa4644c19e..4a3db3afd6 100644
--- a/packages/core/locales/en.json
+++ b/packages/core/locales/en.json
@@ -407,6 +407,10 @@
"defaultMessage": "Search options",
"description": "Screen-reader-only accessible name for that same search input inside a MultiSelector."
},
+ "@astryx.multiSelector.selectAllPartiallySelected": {
+ "defaultMessage": "{label}, partially selected",
+ "description": "Accessible name for the MultiSelector select-all option while only some options are selected. `{label}` is the visible select-all label (e.g. \"Select all\"). ARIA forbids aria-selected=\"mixed\" on options, so the indeterminate state is conveyed through the name instead. \"Partially\" = some but not all."
+ },
"@astryx.popover.close": {
"defaultMessage": "Close popover",
"description": "\"Close\" = shut/dismiss, not \"nearby\". Screen-reader-only label on the close button inside a Popover."
diff --git a/packages/core/src/MultiSelector/MultiSelector.test.tsx b/packages/core/src/MultiSelector/MultiSelector.test.tsx
index e8b78cd8db..236c653fc4 100644
--- a/packages/core/src/MultiSelector/MultiSelector.test.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.test.tsx
@@ -510,6 +510,59 @@ describe('MultiSelector', () => {
expect(options[0]).toHaveTextContent('Select all');
});
+ it('select-all accessible name reflects none/partial/all selection', async () => {
+ const user = userEvent.setup();
+ const options = [
+ {value: 'apple', label: 'Apple'},
+ {value: 'banana', label: 'Banana'},
+ ];
+ const {rerender} = render(
+ <MultiSelector
+ label="Fruit"
+ options={options}
+ value={[]}
+ onChange={() => {}}
+ hasSelectAll
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+
+ // None selected: plain name, not selected
+ let selectAll = screen.getAllByRole('option', h)[0];
+ expect(selectAll).not.toHaveAccessibleName(/partially selected/);
+ expect(selectAll).toHaveAttribute('aria-selected', 'false');
+
+ // Partial: aria-selected="mixed" is invalid on role="option", so the
+ // indeterminate state must be conveyed through the accessible name.
+ rerender(
+ <MultiSelector
+ label="Fruit"
+ options={options}
+ value={['apple']}
+ onChange={() => {}}
+ hasSelectAll
+ />,
+ );
+ selectAll = screen.getAllByRole('option', h)[0];
+ expect(selectAll).toHaveAccessibleName('Select all, partially selected');
+ expect(selectAll).toHaveAttribute('aria-selected', 'false');
+
+ // All selected: plain name again, selected
+ rerender(
+ <MultiSelector
+ label="Fruit"
+ options={options}
+ value={['apple', 'banana']}
+ onChange={() => {}}
+ hasSelectAll
+ />,
+ );
+ selectAll = screen.getAllByRole('option', h)[0];
+ expect(selectAll).not.toHaveAccessibleName(/partially selected/);
+ expect(selectAll).toHaveAttribute('aria-selected', 'true');
+ });
+
it('select-all toggles via keyboard Enter', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
@@ -714,6 +767,29 @@ describe('MultiSelector', () => {
).toBeInTheDocument();
});
+ it('empty-state message is not exposed as a listbox child', async () => {
+ const user = userEvent.setup();
+ render(
+ <MultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSearch
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Fruit'}));
+ await user.type(screen.getByRole('combobox', h), 'xyz');
+
+ // role="listbox" only permits option/group children — the visual
+ // empty-state message must be presentational (it is announced through
+ // the result-count live region instead).
+ const listbox = screen.getByRole('listbox', h);
+ const empty = within(listbox).getByText('No results found');
+ expect(empty).toHaveAttribute('role', 'presentation');
+ });
+
describe('result announcements', () => {
it('announces the match count politely while searching', async () => {
const user = userEvent.setup();
diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsx
index 26396725a6..ac438a4d65 100644
--- a/packages/core/src/MultiSelector/MultiSelector.tsx
+++ b/packages/core/src/MultiSelector/MultiSelector.tsx
@@ -1129,6 +1129,11 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
? allEnabledSelected
: optimisticValue.includes(item.value);
const checkboxValue = isSelectAll ? selectAllState : isSelected;
+ // aria-selected="mixed" is invalid on role="option", and the tri-state
+ // checkbox is inert/decorative, so the indeterminate state must be
+ // conveyed through the option's accessible name (WCAG 4.1.2).
+ const isPartiallySelected =
+ isSelectAll && selectAllState === 'indeterminate';
return (
<div
@@ -1136,6 +1141,13 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
id={getItemId(flatIndex)}
role="option"
aria-selected={isSelected}
+ aria-label={
+ isPartiallySelected
+ ? t('@astryx.multiSelector.selectAllPartiallySelected', {
+ label: selectAllLabel,
+ })
+ : undefined
+ }
aria-disabled={item.disabled}
onClick={() => {
if (!item.disabled) {
@@ -1180,10 +1192,12 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
optimisticValue,
allEnabledSelected,
selectAllState,
+ selectAllLabel,
getItemId,
handleNavigableToggle,
onItemMouseEnter,
size,
+ t,
],
);
@@ -1211,10 +1225,16 @@ export function MultiSelector<T extends MultiSelectorOptionType>({
cursor = 1;
}
- // Empty state — no real items to show
+ // Empty state — no real items to show. role="presentation" keeps the
+ // message out of the listbox's accessibility tree (role="listbox" only
+ // permits option/group children); the no-results outcome is announced
+ // via the result-count live region instead.
if (realItemCount === 0) {
elements.push(
- <div key="empty" {...stylex.props(styles.emptyState)}>
+ <div
+ key="empty"
+ role="presentation"
+ {...stylex.props(styles.emptyState)}>
No results found
</div>,
);
diff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsx
index 710cf4cbbf..bf79ca839b 100644
--- a/packages/core/src/Selector/Selector.test.tsx
+++ b/packages/core/src/Selector/Selector.test.tsx
@@ -613,6 +613,28 @@ describe('Selector', () => {
expect(within(listbox).getByText('No results found')).toBeInTheDocument();
});
+ it('empty-state message is not exposed as a listbox child', async () => {
+ const user = userEvent.setup();
+ render(
+ <Selector
+ label="Fruit"
+ options={OPTIONS}
+ value="Apple"
+ onChange={() => {}}
+ hasSearch
+ />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Fruit'}));
+ await user.type(screen.getByRole('combobox', h), 'xyz');
+
+ // role="listbox" only permits option/group children — the visual
+ // empty-state message must be presentational (it is announced through
+ // the result-count live region instead).
+ const listbox = screen.getByRole('listbox', h);
+ const empty = within(listbox).getByText('No results found');
+ expect(empty).toHaveAttribute('role', 'presentation');
+ });
+
it('calls onChange when selecting a filtered option', async () => {
const user = userEvent.setup();
const onChange = vi.fn();
diff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsx
index f8ec4acc49..8e3302e832 100644
--- a/packages/core/src/Selector/Selector.tsx
+++ b/packages/core/src/Selector/Selector.tsx
@@ -963,8 +963,15 @@ export function Selector<T extends SelectorOptionType>(
// Nothing matched across every group/option: show the empty state.
if (isSearching && filteredItems.length === 0) {
+ // role="presentation" keeps the message out of the listbox's
+ // accessibility tree (role="listbox" only permits option/group
+ // children); the no-results outcome is announced via the
+ // result-count live region instead.
return [
- <div key="empty" {...stylex.props(styles.emptyState)}>
+ <div
+ key="empty"
+ role="presentation"
+ {...stylex.props(styles.emptyState)}>
No results found
</div>,
];
diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsx
index 000f8a6fb9..cf0234fe5a 100644
--- a/packages/core/src/Typeahead/BaseTypeahead.tsx
+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx
@@ -157,6 +157,16 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
*/
inputXStyle?: StyleXStyles;
+ /**
+ * Tab-order override for the input element. Typeahead passes `-1` while
+ * its selected-value token is shown: the input is visually collapsed
+ * (width 0 / opacity 0) but must stay programmatically focusable for
+ * token edit/clear interactions, so removing it from the Tab order is
+ * what prevents an invisible tab stop (WCAG 2.4.3 / 2.4.7). The input
+ * remains focusable via `.focus()` regardless of this value.
+ */
+ inputTabIndex?: number;
+
/**
* Ref to the anchor element for dropdown positioning.
* The dropdown will be positioned relative to this element.
@@ -316,6 +326,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
ariaDescribedBy,
ariaLabelledBy,
inputXStyle,
+ inputTabIndex,
anchorRef,
onKeyDown: externalOnKeyDown,
debounceMs = 150,
@@ -748,6 +759,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
aria-describedby={ariaDescribedBy}
aria-labelledby={ariaLabelledBy}
aria-disabled={isFocusableDisabled ? 'true' : undefined}
+ tabIndex={inputTabIndex}
value={query}
onChange={handleInputChange}
onPointerDown={() => {
diff --git a/packages/core/src/Typeahead/Typeahead.test.tsx b/packages/core/src/Typeahead/Typeahead.test.tsx
index 463a785721..459ca58a07 100644
--- a/packages/core/src/Typeahead/Typeahead.test.tsx
+++ b/packages/core/src/Typeahead/Typeahead.test.tsx
@@ -737,6 +737,68 @@ describe('Typeahead edit mode', () => {
});
});
+describe('Typeahead collapsed input tab order', () => {
+ it('removes the invisible input from the Tab order while a token is shown', () => {
+ render(
+ <Typeahead
+ label="Fruit"
+ searchSource={fruitSource}
+ value={fruits[0]}
+ onChange={() => {}}
+ />,
+ );
+ // While the token is shown the input is collapsed (width 0 / opacity 0);
+ // it must stay programmatically focusable for token interactions but must
+ // not be an invisible Tab stop (WCAG 2.4.3 / 2.4.7).
+ expect(screen.getByRole('combobox')).toHaveAttribute('tabindex', '-1');
+ });
+
+ it('Tab from the token skips the invisible input', async () => {
+ const user = userEvent.setup();
+ render(
+ <Typeahead
+ label="Fruit"
+ searchSource={fruitSource}
+ value={fruits[0]}
+ onChange={() => {}}
+ />,
+ );
+ // Focus the token's internal button, then Tab away — focus must not land
+ // on the visually hidden combobox input.
+ const tokenButton = screen.getByRole('button', {name: fruits[0].label});
+ tokenButton.focus();
+ await user.tab();
+ expect(screen.getByRole('combobox')).not.toHaveFocus();
+ });
+
+ it('keeps the input in the Tab order when no token is shown', () => {
+ render(
+ <Typeahead
+ label="Fruit"
+ searchSource={fruitSource}
+ value={null}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+ });
+
+ it('restores the input to the Tab order in edit mode', () => {
+ render(
+ <Typeahead
+ label="Fruit"
+ searchSource={fruitSource}
+ value={fruits[0]}
+ onChange={() => {}}
+ />,
+ );
+ // Entering edit mode removes the token and uncollapses the input
+ const tokenText = screen.getByText(fruits[0].label);
+ fireEvent.click(tokenText.closest('div')!);
+ expect(screen.getByRole('combobox')).not.toHaveAttribute('tabindex');
+ });
+});
+
describe('BaseTypeahead paste behavior', () => {
it('pasting text triggers search results like typing', async () => {
const user = userEvent.setup();
diff --git a/packages/core/src/Typeahead/Typeahead.tsx b/packages/core/src/Typeahead/Typeahead.tsx
index 7e1d1a5951..bef4736239 100644
--- a/packages/core/src/Typeahead/Typeahead.tsx
+++ b/packages/core/src/Typeahead/Typeahead.tsx
@@ -467,6 +467,12 @@ export function Typeahead<T extends SearchableItem>({
anchorRef={wrapperRef}
onKeyDown={handleKeyDown}
inputXStyle={showToken ? styles.inputHidden : undefined}
+ // While the token is shown the input is collapsed (width 0 /
+ // opacity 0) — take it out of the Tab order so keyboard users
+ // don't hit an invisible stop (WCAG 2.4.3 / 2.4.7). It stays
+ // programmatically focusable: entering edit mode and clearing
+ // both refocus it after it uncollapses.
+ inputTabIndex={showToken ? -1 : undefined}
size={size}
/>
{hasClear && value && !isDisabled && (