Skip to content

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

TypeScript

fix(Selector): a closed list opens on the selected option, never a disabled one (#8868)

Cindy Zhangd69b6aa8d90e
diff --git a/.changeset/selector-opens-on-selected.md b/.changeset/selector-opens-on-selected.md
new file mode 100644
index 0000000000..8e919b3b1f
--- /dev/null
+++ b/.changeset/selector-opens-on-selected.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] `Selector` and `useCombobox`: opening a closed list starts on the selected option, as the WAI-ARIA listbox pattern asks, and never on a disabled option. Before, ArrowDown and ArrowUp opened on the first or last option even when it was disabled, and ArrowDown then Enter changed "Hard" to the first option. Now opening highlights the selected option when it is enabled. Otherwise ArrowUp opens on the last enabled option and ArrowDown, a press, Enter or Space on the first; with no enabled option nothing is highlighted. A search list opened by a press, Enter or typing still highlights nothing. `MultiSelector` is unchanged.
+
+@cixzhang
diff --git a/docs/specs/components/Selector/Selector.spec.md b/docs/specs/components/Selector/Selector.spec.md
index 663a73d1cc..0de950f651 100644
--- a/docs/specs/components/Selector/Selector.spec.md
+++ b/docs/specs/components/Selector/Selector.spec.md
@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, layout, theming, accessibility]
verified_by:
[
packages/core/src/Selector/Selector.test.tsx,
+ packages/core/src/Selector/Selector.openHighlight.test.tsx,
packages/core/src/Selector/Selector.source-build.test.mjs,
packages/core/src/Selector/__tests__/Selector.listbox.a11y.test.tsx,
packages/core/src/Selector/__tests__/Listbox.a11y.chromium.spec.ts,
@@ -150,15 +151,16 @@ and examples remain in `Selector.doc.mjs`.
These requirements describe shipped behavior on current `main`.
-| ID | Shipped invariant | Evidence |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| FR1 | Selecting an enabled option updates the one selected value, closes the active presentation, and returns the trigger to its stable closed state. | Consumer docs and selection interaction tests |
-| FR2 | Without explicit placement, a non-search popover aligns the selected row over the trigger and clamps it to the viewport, above any software keyboard (`spec:AST-059` FR9); a keyboard that goes down while it is open does not move its top. Search popovers and explicit placement use normal Layer positioning. | Consumer docs, implementation, and geometry tests |
-| FR3 | An option whose resolved selection indicator draws no content reserves no mark-column space. Visible selected or themed replacement indicators remain in layout at `indicatorPosition`; the resulting state-dependent label position or available width is intentional, and row content keeps its existing overflow behavior. | `itemMarkColumn`, focused indicator tests, and Chromium evidence stories |
-| FR4 | `popover` uses an anchored Popover. `bottom-sheet` uses a modal BottomSheet. `adaptive` resolves to the modal bottom sheet on compact coarse-pointer screens and Popover otherwise. | Presentation controller and adaptive-presentation tests |
-| FR5 | While `isLoading` is true, the trigger exposes busy state and the listbox suppresses empty and no-results output. | Loading, empty-state, and announcement tests |
-| FR6 | While `isReadOnly` is true, the selected value remains focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable. | Read-only interaction, form, and accessibility tests |
-| FR7 | The listbox carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR3, FR5 and AR2: the option under a pointer's release is the one selected, the highlight follows a held pointer through `aria-activedescendant` while DOM focus stays on the combobox, a mouse released outside closes the list and a finger leaves it open, and the browser's stray click never selects. Trigger opening, arrow clamping and closed-trigger typeahead are unchanged. | `module:DropdownMenu/useMenuPress`; `Selector.test.tsx` press model suite |
+| ID | Shipped invariant | Evidence |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| FR1 | Selecting an enabled option updates the one selected value, closes the active presentation, and returns the trigger to its stable closed state. | Consumer docs and selection interaction tests |
+| FR2 | Without explicit placement, a non-search popover aligns the selected row over the trigger and clamps it to the viewport, above any software keyboard (`spec:AST-059` FR9); a keyboard that goes down while it is open does not move its top. Search popovers and explicit placement use normal Layer positioning. | Consumer docs, implementation, and geometry tests |
+| FR3 | An option whose resolved selection indicator draws no content reserves no mark-column space. Visible selected or themed replacement indicators remain in layout at `indicatorPosition`; the resulting state-dependent label position or available width is intentional, and row content keeps its existing overflow behavior. | `itemMarkColumn`, focused indicator tests, and Chromium evidence stories |
+| FR4 | `popover` uses an anchored Popover. `bottom-sheet` uses a modal BottomSheet. `adaptive` resolves to the modal bottom sheet on compact coarse-pointer screens and Popover otherwise. | Presentation controller and adaptive-presentation tests |
+| FR5 | While `isLoading` is true, the trigger exposes busy state and the listbox suppresses empty and no-results output. | Loading, empty-state, and announcement tests |
+| FR6 | While `isReadOnly` is true, the selected value remains focusable and form-submittable, while the selection surface, clear action, disclosure indicator, and every value-change path are unavailable. | Read-only interaction, form, and accessibility tests |
+| FR7 | The listbox carries `data-astryx-menu-press` and follows `module:DropdownMenu/useMenuPress` FR1–FR3, FR5 and AR2: the option under a pointer's release is the one selected, the highlight follows a held pointer through `aria-activedescendant` while DOM focus stays on the combobox, a mouse released outside closes the list and a finger leaves it open, and the browser's stray click never selects. Trigger opening, arrow clamping and closed-trigger typeahead are unchanged. | `module:DropdownMenu/useMenuPress`; `Selector.test.tsx` press model suite |
+| FR8 | Opening the closed list highlights the selected option when it is enabled. Otherwise ArrowUp highlights the last enabled option, and every other way of opening (ArrowDown, a press, Enter, Space) the first enabled option; with no enabled option nothing is highlighted. A disabled option is never highlighted on opening. A search list opened by a press, Enter or typing highlights nothing. | WAI-ARIA listbox and select-only combobox patterns; `Selector.openHighlight.test.tsx` |
### Allowed variation
@@ -351,19 +353,20 @@ new theming target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites, including "leaves focus on the field a press moved it to" and "returns focus to the trigger when the press lands on nothing focusable" | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |
-| FR2 | placement and selected-item geometry tests; `SelectorKeyboardInset.a11y.chromium.spec.ts` | default, explicit, RTL, transformed entry, keyboard up | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |
-| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |
-| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |
-| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract; `SelectorListboxName.a11y.chromium.spec.ts` and `Selector.test.tsx` "names the listbox with the field label, not the trigger that shows the value" for the listbox name; `Selector.test.tsx` "Selector with hasSearch: the closed trigger names the selection" for the button trigger's name; `SelectorListboxName.a11y.chromium.spec.ts` "the closed searchable trigger is named by the label and the selected value" for the accessibility tree | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates | `audit:Selector/accessibility` |
-| FR5, FR6, AR1, AR2 (anchored), AR4 | `Selector.combobox.a11y.test.tsx` and `Selector.combobox.a11y.chromium.spec.ts` against the shared Combobox contract | closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's `aria-controls` naming the inner listbox remains exact known debt | `audit:Selector/accessibility` |
-| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |
-| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |
-| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |
-| AR5 | `Selector.activeOption.test.tsx`: the ring after keyboard input, no ring after pointer input, the ring again when keyboard input follows a pointer highlight; the active option's indicator measured against the listbox in light and dark | keyboard-active option, pointer-active option | Removing the ring, or drawing it after pointer input, fails; an indicator under 3:1 against the listbox in either mode fails (the fill alone measures 1.09:1 light and 1.15:1 dark) | `audit:Selector/accessibility` |
-| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, AR2, AR3 | `Selector.test.tsx` selection, focus, and keyboard suites, including "leaves focus on the field a press moved it to" and "returns focus to the trigger when the press lands on nothing focusable" | closed/open, search/non-search, disabled option | Removing selection wiring, focus movement, or keyboard behavior fails the named interaction tests | `audit:Selector/behavior` |
+| FR2 | placement and selected-item geometry tests; `SelectorKeyboardInset.a11y.chromium.spec.ts` | default, explicit, RTL, transformed entry, keyboard up | Using the wrong positioning model fails the expected position-area or margin | `audit:Selector/behavior` |
+| FR3, AV1 | Focused `Selector.test.tsx` computed-display checks plus guarded Chromium Storybook matrix and stable visual stories | popover/bottom sheet, narrow/wide, start/end, LTR/RTL, selected/unselected, check/radio | Empty output reserves width, visible output collapses, logical placement flips incorrectly, or row content overflows | `audit:Selector/design-rendered` |
+| FR4, AR1, AR2 | presentation tests plus `aria-haspopup` source review | pointer, compact coarse pointer, search/non-search | Wrong Popover/dialog roles or focus destinations fail tests; `aria-haspopup` values require source/a11y review | `audit:Selector/accessibility` |
+| AR1, AV2 | `Selector.listbox.a11y.test.tsx` and `Listbox.a11y.chromium.spec.ts` against the shared Listbox contract; `SelectorListboxName.a11y.chromium.spec.ts` and `Selector.test.tsx` "names the listbox with the field label, not the trigger that shows the value" for the listbox name; `Selector.test.tsx` "Selector with hasSearch: the closed trigger names the selection" for the button trigger's name; `SelectorListboxName.a11y.chromium.spec.ts` "the closed searchable trigger is named by the label and the selected value" for the accessibility tree | popover/sheet, flat/grouped, selected/unselected, disabled, search, loading, custom RTL | A new or wider loss of role, listbox/option name, state, or ownership gates | `audit:Selector/accessibility` |
+| FR5, FR6, AR1, AR2 (anchored), AR4 | `Selector.combobox.a11y.test.tsx` and `Selector.combobox.a11y.chromium.spec.ts` against the shared Combobox contract | closed, open with active option, read-only, busy, bottom-sheet open, search input with active option | The trigger or search input loses its role/name/state or popup kind, its open popup or active option relationship breaks, or read-only exposes a selection surface; the bottom-sheet trigger's `aria-controls` naming the inner listbox remains exact known debt | `audit:Selector/accessibility` |
+| FR5 | loading, empty-state, and live-region tests | empty options, unmatched search, loading | Empty/no-results output appears or is announced while loading | `audit:Selector/behavior` |
+| FR6, AR4 | read-only interaction, form, ARIA, and theme-state tests | search/non-search, clearable, open→read-only, disabled precedence | A value changes, popup or edit affordance remains, form value disappears, or read-only semantics are absent | `audit:Selector/accessibility` |
+| FR7 | `Selector.test.tsx` press model suite | finger release over another option, finger/mouse release outside, listbox marker | The press option is selected, the listbox takes focus, a finger release outside closes the list, or the stray click selects | `audit:Selector/behavior` |
+| FR8 | `Selector.openHighlight.test.tsx` | selected, none selected, disabled first and last options, selected option disabled, none enabled; ArrowDown, ArrowUp, Enter | An opening highlight on a disabled option, or off the enabled selected option, fails. | `audit:Selector/accessibility` |
+| AR5 | `Selector.activeOption.test.tsx`: the ring after keyboard input, no ring after pointer input, the ring again when keyboard input follows a pointer highlight; the active option's indicator measured against the listbox in light and dark | keyboard-active option, pointer-active option | Removing the ring, or drawing it after pointer input, fails; an indicator under 3:1 against the listbox in either mode fails (the fill alone measures 1.09:1 light and 1.15:1 dark) | `audit:Selector/accessibility` |
+| source-build contract | `Selector.source-build.test.mjs` | package source compiled by consumer Babel | Moving evaluated StyleX values outside the supported source form fails compilation | `audit:Selector/code-health` |
## Decision log
diff --git a/packages/core/src/Selector/Selector.openHighlight.test.tsx b/packages/core/src/Selector/Selector.openHighlight.test.tsx
new file mode 100644
index 0000000000..ced7d9fe4e
--- /dev/null
+++ b/packages/core/src/Selector/Selector.openHighlight.test.tsx
@@ -0,0 +1,128 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Selector.openHighlight.test.tsx
+ * @input Uses Selector, Testing Library
+ * @output Tests which option a closed Selector highlights when it opens:
+ * the selected option, else the first (ArrowUp: last) enabled option,
+ * never a disabled one
+ * @position Colocated behavior test for Selector opening
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {Selector} from './Selector';
+
+const OPTIONS = [
+ {value: 'Archived', disabled: true},
+ 'Easy',
+ 'Hard',
+ 'Expert',
+ {value: 'Retired', disabled: true},
+];
+
+const h = {hidden: true} as const;
+
+function activeOptionText(control: HTMLElement): string | null {
+ const id = control.getAttribute('aria-activedescendant');
+ if (id == null) {
+ return null;
+ }
+ return document.getElementById(id)?.textContent ?? null;
+}
+
+function openWith(control: HTMLElement, key: string) {
+ control.focus();
+ fireEvent.keyDown(control, {key});
+}
+
+describe('Selector: the option a closed list highlights when it opens', () => {
+ function renderSelector(value: string, onChange = vi.fn()) {
+ render(
+ <Selector
+ label="Level"
+ options={OPTIONS}
+ value={value}
+ onChange={onChange}
+ />,
+ );
+ return screen.getByRole('combobox');
+ }
+
+ it('ArrowDown opens on the selected option', () => {
+ const trigger = renderSelector('Hard');
+ openWith(trigger, 'ArrowDown');
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(activeOptionText(trigger)).toBe('Hard');
+ });
+
+ it('ArrowUp opens on the selected option', () => {
+ const trigger = renderSelector('Hard');
+ openWith(trigger, 'ArrowUp');
+ expect(activeOptionText(trigger)).toBe('Hard');
+ });
+
+ it('ArrowDown then Enter keeps the selected value', () => {
+ // Every option is enabled, so a first-option highlight would pick Easy.
+ const onChange = vi.fn();
+ render(
+ <Selector
+ label="Level"
+ options={['Easy', 'Hard', 'Expert']}
+ value="Hard"
+ onChange={onChange}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ openWith(trigger, 'ArrowDown');
+ fireEvent.keyDown(trigger, {key: 'Enter'});
+ expect(onChange).not.toHaveBeenCalledWith('Easy');
+ expect(onChange.mock.calls.every(([picked]) => picked === 'Hard')).toBe(
+ true,
+ );
+ });
+
+ it('with nothing selected, ArrowDown opens on the first enabled option, past a disabled first one', () => {
+ const trigger = renderSelector('');
+ openWith(trigger, 'ArrowDown');
+ expect(activeOptionText(trigger)).toBe('Easy');
+ });
+
+ it('with nothing selected, ArrowUp opens on the last enabled option, past a disabled last one', () => {
+ const trigger = renderSelector('');
+ openWith(trigger, 'ArrowUp');
+ expect(activeOptionText(trigger)).toBe('Expert');
+ });
+
+ it('with nothing selected, Enter opens on the first enabled option', () => {
+ const trigger = renderSelector('');
+ openWith(trigger, 'Enter');
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(activeOptionText(trigger)).toBe('Easy');
+ });
+
+ it('a selected option that is disabled is not highlighted', () => {
+ const trigger = renderSelector('Archived');
+ openWith(trigger, 'ArrowUp');
+ expect(activeOptionText(trigger)).toBe('Expert');
+ });
+
+ it('highlights nothing when no option is enabled', () => {
+ render(
+ <Selector
+ label="Level"
+ options={[
+ {value: 'Archived', disabled: true},
+ {value: 'Retired', disabled: true},
+ ]}
+ value=""
+ onChange={() => {}}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ openWith(trigger, 'ArrowDown');
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ expect(trigger).not.toHaveAttribute('aria-activedescendant');
+ expect(screen.getAllByRole('option', h)).toHaveLength(2);
+ });
+});
diff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.ts
index 17f465c7cd..82798755ac 100644
--- a/packages/core/src/Selector/hooks.ts
+++ b/packages/core/src/Selector/hooks.ts
@@ -376,6 +376,23 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
return selectableItems.findIndex(item => item.value === value);
}, [selectableItems, value]);
+ /** Opening never lands on a disabled option. */
+ const findOpeningIndex = useCallback(
+ (fromEnd: boolean) => {
+ const selectedIndex = findSelectedIndex();
+ if (selectedIndex >= 0 && !selectableItems[selectedIndex].disabled) {
+ return selectedIndex;
+ }
+ const enabledIndices = getEnabledIndices();
+ return (
+ (fromEnd
+ ? enabledIndices[enabledIndices.length - 1]
+ : enabledIndices[0]) ?? -1
+ );
+ },
+ [findSelectedIndex, getEnabledIndices, selectableItems],
+ );
+
const closeAndReset = useCallback(() => {
setHighlightedIndex(-1);
onClose();
@@ -401,11 +418,10 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
} else {
const didOpen = onOpen() !== false;
if (didOpen && !hasSearch) {
- const selectedIndex = findSelectedIndex();
- setHighlightedIndex(selectedIndex >= 0 ? selectedIndex : 0);
+ setHighlightedIndex(findOpeningIndex(false));
}
}
- }, [isDisabled, isOpen, onOpen, closeAndReset, findSelectedIndex, hasSearch]);
+ }, [isDisabled, isOpen, onOpen, closeAndReset, findOpeningIndex, hasSearch]);
// The scroll effect lives here, the highlight owner, so every consumer
// (Selector, CommandPalette) shares one hover/keyboard split (#6077).
@@ -438,7 +454,7 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
e.preventDefault();
if (!isOpen) {
if (onOpen() !== false) {
- setHighlightedIndex(0);
+ setHighlightedIndex(findOpeningIndex(false));
}
} else {
const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
@@ -454,7 +470,7 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
e.preventDefault();
if (!isOpen) {
if (onOpen() !== false) {
- setHighlightedIndex(selectableItems.length - 1);
+ setHighlightedIndex(findOpeningIndex(true));
}
} else {
const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
@@ -480,8 +496,7 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
} else if (!isOpen) {
const didOpen = onOpen() !== false;
if (didOpen && !hasSearch) {
- const selectedIndex = findSelectedIndex();
- setHighlightedIndex(selectedIndex >= 0 ? selectedIndex : 0);
+ setHighlightedIndex(findOpeningIndex(false));
}
}
break;
@@ -569,7 +584,7 @@ export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
selectableItems,
highlightedIndex,
selectItem,
- findSelectedIndex,
+ findOpeningIndex,
getEnabledIndices,
hasSearch,
onClear,
diff --git a/packages/core/src/Selector/useCombobox.doc.mjs b/packages/core/src/Selector/useCombobox.doc.mjs
index 52d62129ff..c0535cf6cc 100644
--- a/packages/core/src/Selector/useCombobox.doc.mjs
+++ b/packages/core/src/Selector/useCombobox.doc.mjs
@@ -32,7 +32,7 @@ export const docs = {
name: 'options.selectableItems',
type: 'ReadonlyArray<T extends {value: string; disabled?: boolean}>',
description:
- 'The options in the same order as they render: `SelectorOptionData`, or any option type with a string `value` and an optional `disabled`. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list from `onKeyDown` still lands on the first or last option.',
+ 'The options in the same order as they render: `SelectorOptionData`, or any option type with a string `value` and an optional `disabled`. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list from `onKeyDown` lands on the selected option when it is enabled, else on the first or last enabled option.',
required: true,
},
{
@@ -66,7 +66,7 @@ export const docs = {
name: 'options.value',
type: 'string',
description:
- 'The selected value. Without search, opening by a press, Enter or Space highlights it, or the first option when nothing is selected; ArrowDown and ArrowUp open on the first and last option.',
+ 'The selected value. Opening the list highlights it when it is enabled; otherwise ArrowUp opens on the last enabled option and ArrowDown, a press, Enter or Space on the first. A disabled option is never highlighted on opening, and with no enabled option nothing is.',
},
{
name: 'options.onSelect',
@@ -84,7 +84,7 @@ export const docs = {
name: 'options.hasSearch',
type: 'boolean',
description:
- 'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the first and last option), and printable keys on the closed control go to `onSearchSeed`.',
+ 'Whether the list has its own search field. Space then types instead of picking, opening by a press or Enter does not pre-highlight (ArrowDown and ArrowUp still open on the selected or the first or last enabled option), and printable keys on the closed control go to `onSearchSeed`.',
default: 'false',
},
{
@@ -105,7 +105,7 @@ export const docs = {
name: 'highlightedIndex',
type: 'number',
description:
- 'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the first or last option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
+ 'Index of the active option, or -1 when none is active. With `hasSearch`, opening by a press or Enter does not set one, so it stays -1 after the hook itself closes the list; ArrowDown and ArrowUp still open on the selected or the first or last enabled option. Render it as the active option and name it in `aria-activedescendant` only while it points at a rendered option.',
},
{
name: 'setHighlightedIndex',
@@ -260,7 +260,7 @@ export const docsDense = {
paramDescriptions: {
options: 'config.',
'options.selectableItems':
- 'options in render order: SelectorOptionData or any type w/ string value + optional disabled; disabled ones not pickable, skipped while moving in open list (onKeyDown ArrowDown/Up opening still lands first / last).',
+ 'options in render order: SelectorOptionData or any type w/ string value + optional disabled; disabled ones not pickable, skipped while moving in open list (onKeyDown ArrowDown/Up opening lands on the enabled selected option, else first / last enabled).',
'options.isOpen': 'list shown; caller owns state.',
'options.onOpen':
'show list; return false to refuse (highlight untouched).',
@@ -268,19 +268,19 @@ export const docsDense = {
'hook hides list; resets highlight first. caller closing itself (outside press): also setHighlightedIndex(-1).',
'options.listboxId': 'listbox id; option ids derive from it (getItemId).',
'options.value':
- 'selected value; w/o search, press / Enter / Space opening highlights it (else first); ArrowDown/Up open on first / last.',
+ 'selected value; opening highlights it when enabled, else ArrowUp -> last enabled, other opens -> first enabled; never a disabled option.',
'options.onSelect': 'called w/ picked value; picking closes.',
'options.onClear':
'clears value; Delete / Backspace on closed control. ignored when open or hasSearch.',
'options.hasSearch':
- 'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still first / last), printable keys on closed control -> onSearchSeed.',
+ 'list has own search field: Space types, press / Enter opening does not pre-highlight (ArrowDown/Up still selected, else first / last enabled), printable keys on closed control -> onSearchSeed.',
'options.onSearchSeed':
'w/ hasSearch, each printable char except Space typed while control focused (opens first if closed).',
'options.isDisabled': 'ignore clicks + keys.',
},
returnDescriptions: {
highlightedIndex:
- 'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still first / last. name in aria-activedescendant only when it points at a rendered option.',
+ 'active option index, -1 = none. hasSearch: press / Enter opening sets none (stays -1 after hook closes); ArrowDown/Up still selected, else first / last enabled. name in aria-activedescendant only when it points at a rendered option.',
setHighlightedIndex: 'set active option (e.g. after filtering).',
getItemId:
'id for option at index; aria-activedescendant = isOpen && highlightedIndex >= 0 && highlightedIndex < selectableItems.length ? getItemId(highlightedIndex) : undefined (empty list safe).',