From 5da67e3b758b4f3c0fb172eb645e2c4953134519 Mon Sep 17 00:00:00 2001
From: Andrey Goder <andy.goder@gmail.com>
Date: Wed, 5 Aug 2026 16:04:03 -0700
Subject: [PATCH] Share one keyboard map across Select, MultiSelect, and
 AutocompleteInput (#380)

The listbox key handling lived in two places with different bugs. Pull the
decision layer into `internal/listboxKeyboard`, which maps a key event onto
an open/move/jump/commit action and leaves `preventDefault()` to the caller.
`useListboxNavigation` and `BaseAutocompleteInput` both drive off it now, so
Select, MultiSelect, TagsInput, and AutocompleteInput answer to the same
keys.

That resolves three defects in the listbox map:

- Home/End no longer fire while the caret is in a text field, so the search
  input inside the Select/MultiSelect popover gets them back for caret
  movement. The target decides, since the same handler is bound to both the
  search field and the trigger button.
- Home/End go to the actual first/last option instead of the selection.
  `getInitialHighlight` still prefers the selection, but only for opening
  the listbox with an arrow key -- an explicit jump now uses the new
  `getEdgeHighlight`.
- PageUp/PageDown jump the highlight to the first/last option. They
  previously fell through to the browser, which page-scrolled the popover
  away from `aria-activedescendant`.

AutocompleteInput picks up the jumps as part of the alignment, plus two
smaller consistency fixes it inherits from the shared map: ArrowUp on a
closed menu opens it rather than silently moving a hidden highlight, and
opening with an arrow key seeds the highlight at the matching edge.
---
 .../AutocompleteInput.test.tsx                |  44 ++++++++
 .../BaseAutocompleteInput.tsx                 |  71 +++++++-----
 .../MultiSelect/MultiSelect.test.tsx          |  38 +++++++
 src/components/Select/Select.test.tsx         |  45 ++++++++
 src/internal/listboxKeyboard.ts               |  74 +++++++++++++
 src/internal/useListboxNavigation.ts          | 101 +++++++++---------
 6 files changed, 293 insertions(+), 80 deletions(-)
 create mode 100644 src/internal/listboxKeyboard.ts

diff --git a/src/components/AutocompleteInput/AutocompleteInput.test.tsx b/src/components/AutocompleteInput/AutocompleteInput.test.tsx
index b4137d79..785257bd 100644
--- a/src/components/AutocompleteInput/AutocompleteInput.test.tsx
+++ b/src/components/AutocompleteInput/AutocompleteInput.test.tsx
@@ -292,6 +292,50 @@ describe('AutocompleteInput', () => {
     expect(onOpenChange).toHaveBeenCalledWith(false);
   });
 
+  it('jumps results with PageUp and PageDown while Home and End keep the caret', async () => {
+    const user = userEvent.setup();
+    const onChange = vi.fn();
+
+    render(
+      <AutocompleteInput
+        debounceMs={0}
+        label="Assignee"
+        onChange={onChange}
+        searchSource={createStaticSearchSource(items)}
+        value={null}
+      />,
+    );
+
+    const input = screen.getByRole('combobox', {name: 'Assignee'});
+    await user.type(input, 'a');
+
+    const highlightedId = input.getAttribute('aria-activedescendant');
+    expect(
+      screen.getByRole('option', {hidden: true, name: /Ada Lovelace/}),
+    ).toHaveAttribute('id', highlightedId);
+
+    await user.keyboard('{Home}');
+    expect(input).toHaveProperty('selectionStart', 0);
+    expect(input).toHaveAttribute('aria-activedescendant', highlightedId);
+
+    await user.keyboard('{End}');
+    expect(input).toHaveProperty('selectionStart', 1);
+    expect(input).toHaveAttribute('aria-activedescendant', highlightedId);
+
+    await user.keyboard('{PageDown}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: /Katherine Johnson/}),
+    ).toHaveAttribute('id', input.getAttribute('aria-activedescendant'));
+
+    await user.keyboard('{PageUp}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: /Ada Lovelace/}),
+    ).toHaveAttribute('id', input.getAttribute('aria-activedescendant'));
+
+    await user.keyboard('{Enter}');
+    expect(onChange).toHaveBeenCalledWith(items[0]);
+  });
+
   it('does not select or close results while composing', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
diff --git a/src/components/AutocompleteInput/BaseAutocompleteInput.tsx b/src/components/AutocompleteInput/BaseAutocompleteInput.tsx
index 789d56a0..67ef401a 100644
--- a/src/components/AutocompleteInput/BaseAutocompleteInput.tsx
+++ b/src/components/AutocompleteInput/BaseAutocompleteInput.tsx
@@ -28,7 +28,7 @@ import {Icon} from 'components/Icon';
 import {Popover} from 'components/Popover';
 import {Spinner} from 'components/Spinner';
 import {Text} from 'components/Text';
-import {isComposingEvent} from 'internal/isComposingEvent';
+import {resolveListboxKeyAction} from 'internal/listboxKeyboard';
 import {mergeRefs} from 'internal/mergeRefs';
 import {scrollOptionIntoView} from 'internal/scrollOptionIntoView';
 import {css} from 'styled-system/css';
@@ -482,47 +482,62 @@ export function BaseAutocompleteInput<T extends SearchableItem>({
             return;
           }
 
-          if (isComposingEvent(event)) {
+          const action = resolveListboxKeyAction(event, {isOpen});
+          if (action == null) {
             return;
           }
 
-          if (event.key === 'ArrowDown') {
-            event.preventDefault();
-            if (!isOpen) {
+          // Keep the highlighted result visible as the user moves through an
+          // overflowing list.
+          const highlightIndex = (index: number): void => {
+            setHighlightedIndex(index);
+            scrollOptionIntoView(`${listboxId}-option-${index}`);
+          };
+          const edgeIndex = (edge: 'first' | 'last'): number =>
+            edge === 'last' ? results.length - 1 : 0;
+
+          switch (action.type) {
+            case 'open': {
+              event.preventDefault();
               if (results.length > 0) {
                 showMenu();
+                highlightIndex(edgeIndex(action.edge));
               } else if (hasEntriesOnFocus) {
                 void runSearch('', 'bootstrap');
               }
               return;
             }
-            if (results.length === 0) {
-              setHighlightedIndex(-1);
+            case 'move': {
+              event.preventDefault();
+              if (results.length === 0) {
+                setHighlightedIndex(-1);
+                return;
+              }
+              highlightIndex(
+                highlightedIndex < 0
+                  ? edgeIndex(action.step === 1 ? 'first' : 'last')
+                  : (highlightedIndex + action.step + results.length) %
+                      results.length,
+              );
               return;
             }
-            const nextIndex = (highlightedIndex + 1) % results.length;
-            setHighlightedIndex(nextIndex);
-            // Keep the highlighted result visible as the user arrows through
-            // an overflowing list.
-            scrollOptionIntoView(`${listboxId}-option-${nextIndex}`);
-          } else if (event.key === 'ArrowUp') {
-            event.preventDefault();
-            if (results.length === 0) {
-              setHighlightedIndex(-1);
+            case 'jump': {
+              event.preventDefault();
+              if (results.length === 0) {
+                setHighlightedIndex(-1);
+                return;
+              }
+              highlightIndex(edgeIndex(action.edge));
+              return;
+            }
+            case 'commit': {
+              if (highlightedIndex < 0 || highlightedIndex >= results.length) {
+                return;
+              }
+              event.preventDefault();
+              selectItem(results[highlightedIndex]);
               return;
             }
-            const nextIndex =
-              (highlightedIndex - 1 + results.length) % results.length;
-            setHighlightedIndex(nextIndex);
-            scrollOptionIntoView(`${listboxId}-option-${nextIndex}`);
-          } else if (
-            event.key === 'Enter' &&
-            isOpen &&
-            highlightedIndex >= 0 &&
-            highlightedIndex < results.length
-          ) {
-            event.preventDefault();
-            selectItem(results[highlightedIndex]);
           }
         }}
         placeholder={placeholder}
diff --git a/src/components/MultiSelect/MultiSelect.test.tsx b/src/components/MultiSelect/MultiSelect.test.tsx
index 665b693f..5f834918 100644
--- a/src/components/MultiSelect/MultiSelect.test.tsx
+++ b/src/components/MultiSelect/MultiSelect.test.tsx
@@ -264,6 +264,44 @@ describe('MultiSelect', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 
+  it('jumps to an edge with Home, End, and PageUp/PageDown past the selection', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <MultiSelect
+        label="Columns"
+        onChange={() => {}}
+        options={['Name', 'Email', 'Role']}
+        value={['Email']}
+      />,
+    );
+
+    const trigger = screen.getByRole('combobox', {name: 'Columns'});
+    trigger.focus();
+
+    // Opening lands on the selection so the user resumes where they left off.
+    await user.keyboard('{ArrowDown}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Email'}),
+    ).toHaveAttribute('id', trigger.getAttribute('aria-activedescendant'));
+
+    // An explicit jump means the edge of the list, not the selection.
+    await user.keyboard('{Home}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Name'}),
+    ).toHaveAttribute('id', trigger.getAttribute('aria-activedescendant'));
+
+    await user.keyboard('{PageDown}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Role'}),
+    ).toHaveAttribute('id', trigger.getAttribute('aria-activedescendant'));
+
+    await user.keyboard('{PageUp}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Name'}),
+    ).toHaveAttribute('id', trigger.getAttribute('aria-activedescendant'));
+  });
+
   it('ignores navigation and commit keys while composing', async () => {
     const user = userEvent.setup();
     const onChange = vi.fn();
diff --git a/src/components/Select/Select.test.tsx b/src/components/Select/Select.test.tsx
index 436bce4f..b875055b 100644
--- a/src/components/Select/Select.test.tsx
+++ b/src/components/Select/Select.test.tsx
@@ -367,6 +367,51 @@ describe('Select', () => {
     ).toHaveAttribute('id', search.getAttribute('aria-activedescendant'));
   });
 
+  it('leaves Home and End to the search caret and jumps with PageUp and PageDown', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Select
+        hasSearch
+        label="Fruit"
+        onChange={() => {}}
+        options={['Apple', 'Apricot', 'Grape', 'Cherry']}
+        value={null}
+      />,
+    );
+
+    await user.click(screen.getByRole('combobox', {name: 'Fruit'}));
+
+    const search = screen.getByLabelText('Search Fruit');
+    await user.type(search, 'ap');
+    await user.keyboard('{ArrowDown}');
+
+    const highlightedId = search.getAttribute('aria-activedescendant');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Apple'}),
+    ).toHaveAttribute('id', highlightedId);
+
+    // Home and End stay with the text caret while the search field has focus.
+    await user.keyboard('{Home}');
+    expect(search).toHaveProperty('selectionStart', 0);
+    expect(search).toHaveAttribute('aria-activedescendant', highlightedId);
+
+    await user.keyboard('{End}');
+    expect(search).toHaveProperty('selectionStart', 'ap'.length);
+    expect(search).toHaveAttribute('aria-activedescendant', highlightedId);
+
+    // PageUp/PageDown are the jumps the listbox owns everywhere.
+    await user.keyboard('{PageDown}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Grape'}),
+    ).toHaveAttribute('id', search.getAttribute('aria-activedescendant'));
+
+    await user.keyboard('{PageUp}');
+    expect(
+      screen.getByRole('option', {hidden: true, name: 'Apple'}),
+    ).toHaveAttribute('id', search.getAttribute('aria-activedescendant'));
+  });
+
   it('does not open when disabled', async () => {
     const user = userEvent.setup();
 
diff --git a/src/internal/listboxKeyboard.ts b/src/internal/listboxKeyboard.ts
new file mode 100644
index 00000000..9cd46ac7
--- /dev/null
+++ b/src/internal/listboxKeyboard.ts
@@ -0,0 +1,74 @@
+import type {KeyboardEvent} from 'react';
+import {isComposingEvent} from 'internal/isComposingEvent';
+
+/**
+ * The combobox keyboard vocabulary shared by every listbox in the library.
+ *
+ * - `open` -- the listbox is closed and an arrow key should reveal it, seeded
+ *   from the given edge.
+ * - `move` -- step the highlight one option in `step`'s direction.
+ * - `jump` -- send the highlight straight to an edge of the list.
+ * - `commit` -- accept whatever is highlighted.
+ */
+export type ListboxKeyAction =
+  | {edge: 'first' | 'last'; type: 'jump'}
+  | {edge: 'first' | 'last'; type: 'open'}
+  | {step: -1 | 1; type: 'move'}
+  | {type: 'commit'};
+
+/**
+ * Whether the key event landed on something with a text caret, which claims
+ * Home/End for caret movement. Comboboxes with an in-popover search field bind
+ * the same handler to both the field and the trigger, so the target decides.
+ */
+function hasTextCaret(event: KeyboardEvent<HTMLElement>): boolean {
+  const target = event.target;
+  return (
+    target instanceof HTMLTextAreaElement ||
+    (target instanceof HTMLInputElement &&
+      // `selectionStart` is null on input types without a caret (checkbox,
+      // color, range) and a number on the text-entry ones.
+      target.selectionStart != null)
+  );
+}
+
+/**
+ * Maps a key event onto the listbox action it should perform, or null when the
+ * listbox has no interest in the key. Callers own `preventDefault()` so they
+ * can decline an action they cannot fulfil -- Enter with nothing highlighted,
+ * for instance, must stay with the form.
+ *
+ * Home/End only reach the listbox when the caret is not in a text field;
+ * PageUp/PageDown are the jumps that always belong to the listbox.
+ */
+export function resolveListboxKeyAction(
+  event: KeyboardEvent<HTMLElement>,
+  {isOpen}: {isOpen: boolean},
+): ListboxKeyAction | null {
+  if (isComposingEvent(event)) {
+    return null;
+  }
+
+  switch (event.key) {
+    case 'ArrowDown':
+      return isOpen ? {step: 1, type: 'move'} : {edge: 'first', type: 'open'};
+    case 'ArrowUp':
+      return isOpen ? {step: -1, type: 'move'} : {edge: 'last', type: 'open'};
+    case 'Home':
+      return isOpen && !hasTextCaret(event)
+        ? {edge: 'first', type: 'jump'}
+        : null;
+    case 'End':
+      return isOpen && !hasTextCaret(event)
+        ? {edge: 'last', type: 'jump'}
+        : null;
+    case 'PageUp':
+      return isOpen ? {edge: 'first', type: 'jump'} : null;
+    case 'PageDown':
+      return isOpen ? {edge: 'last', type: 'jump'} : null;
+    case 'Enter':
+      return isOpen ? {type: 'commit'} : null;
+    default:
+      return null;
+  }
+}
diff --git a/src/internal/useListboxNavigation.ts b/src/internal/useListboxNavigation.ts
index 675bb137..aae36d7f 100644
--- a/src/internal/useListboxNavigation.ts
+++ b/src/internal/useListboxNavigation.ts
@@ -8,7 +8,7 @@ import {
   type KeyboardEvent,
   type SetStateAction,
 } from 'react';
-import {isComposingEvent} from 'internal/isComposingEvent';
+import {resolveListboxKeyAction} from 'internal/listboxKeyboard';
 import {scrollOptionIntoView} from 'internal/scrollOptionIntoView';
 
 export type ListboxNavigationOption = {
@@ -79,24 +79,31 @@ export function useListboxNavigation({
     [getOptionId],
   );
 
-  const getInitialHighlight = useCallback(
-    (direction: 'first' | 'last' = 'first'): string | null => {
+  const getEdgeHighlight = useCallback(
+    (edge: 'first' | 'last'): string | null => {
       if (enabledOptions.length === 0) {
         return null;
       }
 
+      return edge === 'last'
+        ? enabledOptions[enabledOptions.length - 1].value
+        : enabledOptions[0].value;
+    },
+    [enabledOptions],
+  );
+
+  // Opening the listbox lands on the current selection when there is one, so
+  // the user starts from where they left off. Explicit first/last jumps go
+  // through `getEdgeHighlight` instead -- they mean the edge, not the
+  // selection.
+  const getInitialHighlight = useCallback(
+    (edge: 'first' | 'last'): string | null => {
       const selectedEnabledOption = enabledOptions.find(option =>
         selectedValues?.has(option.value),
       );
-      if (selectedEnabledOption != null) {
-        return selectedEnabledOption.value;
-      }
-
-      return direction === 'last'
-        ? enabledOptions[enabledOptions.length - 1].value
-        : enabledOptions[0].value;
+      return selectedEnabledOption?.value ?? getEdgeHighlight(edge);
     },
-    [enabledOptions, selectedValues],
+    [enabledOptions, getEdgeHighlight, selectedValues],
   );
 
   const getNextHighlight = useCallback(
@@ -126,57 +133,47 @@ export function useListboxNavigation({
         return;
       }
 
-      if (isComposingEvent(event)) {
+      const action = resolveListboxKeyAction(event, {isOpen});
+      if (action == null) {
         return;
       }
 
-      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
-        event.preventDefault();
-        if (!isOpen) {
+      switch (action.type) {
+        case 'open': {
+          event.preventDefault();
           onOpenChange(true);
-          setStoredHighlightedValue(
-            getInitialHighlight(event.key === 'ArrowUp' ? 'last' : 'first'),
-          );
+          setStoredHighlightedValue(getInitialHighlight(action.edge));
           return;
         }
-
-        const nextValue = getNextHighlight(
-          highlightedValue,
-          event.key === 'ArrowDown' ? 1 : -1,
-        );
-        setStoredHighlightedValue(nextValue);
-        scrollHighlightIntoView(nextValue);
-        return;
-      }
-
-      if (event.key === 'Home' && isOpen) {
-        event.preventDefault();
-        const nextValue = getInitialHighlight('first');
-        setStoredHighlightedValue(nextValue);
-        scrollHighlightIntoView(nextValue);
-        return;
-      }
-
-      if (event.key === 'End' && isOpen) {
-        event.preventDefault();
-        const nextValue = getInitialHighlight('last');
-        setStoredHighlightedValue(nextValue);
-        scrollHighlightIntoView(nextValue);
-        return;
-      }
-
-      if (event.key === 'Enter' && isOpen && highlightedValue != null) {
-        event.preventDefault();
-        onCommit(highlightedValue);
-        if (shouldClearOnCommit) {
-          setStoredHighlightedValue(null);
+        case 'move': {
+          event.preventDefault();
+          const nextValue = getNextHighlight(highlightedValue, action.step);
+          setStoredHighlightedValue(nextValue);
+          scrollHighlightIntoView(nextValue);
+          return;
+        }
+        case 'jump': {
+          event.preventDefault();
+          const nextValue = getEdgeHighlight(action.edge);
+          setStoredHighlightedValue(nextValue);
+          scrollHighlightIntoView(nextValue);
+          return;
+        }
+        case 'commit': {
+          if (highlightedValue == null) {
+            return;
+          }
+          event.preventDefault();
+          onCommit(highlightedValue);
+          if (shouldClearOnCommit) {
+            setStoredHighlightedValue(null);
+          }
+          return;
         }
-        return;
       }
-
-      return;
     },
     [
+      getEdgeHighlight,
       getInitialHighlight,
       getNextHighlight,
       highlightedValue,