@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Selector/hooks.ts

@@ -7,7 +7,8 @@
  * @input Uses untransformed DOM layout geometry from the Selector's outer
  *   anchor, listbox, and selected option
  * @output Hooks for Selector: useSelectedItemOffset, and useCombobox (public,
- *   exported from the Selector entry point; also used by CommandPalette)
+ *   exported from the Selector entry point; also used by CommandPalette, and
+ *   by products for a combobox over a text field they render, spec:AST-075)
  * @position Selector hooks; used by Selector.tsx and CommandPalette
  *
  * SYNC: When useCombobox's options or return change, update:
@@ -17,6 +18,7 @@
 import {useCallback, useState} from 'react';
 import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
+import {isImeKeyEvent} from '../utils/ime';
 import type {RefObject} from 'react';
 import type {SelectorOptionData} from './types';
 
@@ -158,8 +160,18 @@ export function useSelectedItemOffset({
 // useCombobox - Keyboard navigation and selection
 // =============================================================================
 
-interface UseComboboxOptions {
-  selectableItems: SelectorOptionData[];
+/**
+ * What useCombobox reads from an option: its value, and whether it can be
+ * picked. Any option type that carries these works; Selector's
+ * `SelectorOptionData` is the default.
+ */
+interface ComboboxOption {
+  value: string;
+  disabled?: boolean;
+}
+
+interface UseComboboxOptions<T extends ComboboxOption> {
+  selectableItems: ReadonlyArray<T>;
   value?: string;
   isDisabled?: boolean;
   isOpen: boolean;
@@ -184,14 +196,58 @@ interface UseComboboxOptions {
   listboxId: string;
 }
 
-interface UseComboboxResult {
+/** Spread onto the caller's field. */
+interface ComboboxFieldProps {
+  role: 'combobox';
+  'aria-autocomplete': 'list';
+  'aria-expanded': boolean;
+  'aria-controls'?: string;
+  'aria-activedescendant'?: string;
+  onKeyDown: (event: React.KeyboardEvent) => void;
+}
+
+/** Spread onto the caller's listbox, which the caller names. */
+interface ComboboxListboxProps {
+  id: string;
+  role: 'listbox';
+  onMouseDown: (event: React.MouseEvent) => void;
+}
+
+/** Spread onto the caller's option at one index. */
+interface ComboboxOptionProps {
+  id: string;
+  role: 'option';
+  'aria-selected': boolean;
+  'aria-disabled'?: true;
+  onMouseMove: () => void;
+  onClick: () => void;
+}
+
+/** The caller's own handlers for its field, run after the hook's. */
+interface ComboboxFieldHandlers {
+  // Method syntax keeps the parameter bivariant, so a handler typed for its
+  // own element, such as an input, is accepted.
+  onKeyDown?(event: React.KeyboardEvent): void;
+}
+
+interface UseComboboxResult<T extends ComboboxOption> {
   highlightedIndex: number;
   setHighlightedIndex: (index: number) => void;
   getItemId: (index: number) => string;
   onTriggerClick: () => void;
   onKeyDown: (e: React.KeyboardEvent) => void;
-  onItemSelect: (item: SelectorOptionData) => void;
-  onItemMouseEnter: (item: SelectorOptionData, index: number) => void;
+  // Method syntax keeps a result built over a richer option type assignable
+  // to `ReturnType<typeof useCombobox>`, the name released callers use.
+  onItemSelect(item: T): void;
+  onItemMouseEnter(item: T, index: number): void;
+  getFieldProps: (props?: ComboboxFieldHandlers) => ComboboxFieldProps;
+  getListboxProps: () => ComboboxListboxProps;
+  getOptionProps: (index: number) => ComboboxOptionProps;
+}
+
+/** Whether a key is chorded with a modifier, such as Shift+Enter. */
+function hasModifier(e: React.KeyboardEvent): boolean {
+  return e.altKey || e.ctrlKey || e.metaKey || e.shiftKey;
 }
 
 /**
@@ -201,8 +257,14 @@ interface UseComboboxResult {
  * `useTypeahead` hook and run it ahead of this handler (see Selector). That
  * keeps matching consistent with the other collections and leaves consumers
  * whose own input already filters the items (CommandPalette) untouched.
+ *
+ * For a single-line text field the caller renders (spec:AST-075), `getFieldProps`,
+ * `getListboxProps` and `getOptionProps` carry the combobox semantics, the
+ * field's keys and the pointer model, while the caller keeps the field, the
+ * rows and where the list renders. The caller announces each new result count
+ * through useAnnounce (spec:AST-075 DEC-2), with the words the field shows.
  */
-export function useCombobox({
+export function useCombobox<T extends ComboboxOption = SelectorOptionData>({
   selectableItems,
   value,
   isDisabled = false,
@@ -214,7 +276,7 @@ export function useCombobox({
   onClear,
   onSearchSeed,
   listboxId,
-}: UseComboboxOptions): UseComboboxResult {
+}: UseComboboxOptions<T>): UseComboboxResult<T> {
   const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
 
   const getItemId = useCallback(
@@ -238,7 +300,7 @@ export function useCombobox({
   }, [onClose]);
 
   const selectItem = useCallback(
-    (item: SelectorOptionData) => {
+    (item: T) => {
       if (item.disabled) {
         return;
       }
@@ -273,7 +335,7 @@ export function useCombobox({
   });
 
   const onItemMouseEnter = useCallback(
-    (item: SelectorOptionData, index: number) => {
+    (item: T, index: number) => {
       if (!item.disabled) {
         highlightOnHover(index);
       }
@@ -434,6 +496,165 @@ export function useCombobox({
     ],
   );
 
+  // ---------------------------------------------------------------------------
+  // A field the caller renders (spec:AST-075). Focus never leaves it: the
+  // active option is named through aria-activedescendant, and the field keeps
+  // every key the list does not need.
+  // ---------------------------------------------------------------------------
+
+  // The listbox renders only while it has options; an open list with none
+  // shows the caller's empty state instead, which is not a listbox.
+  const isListboxShown = isOpen && selectableItems.length > 0;
+  const activeDescendant =
+    isListboxShown &&
+    highlightedIndex >= 0 &&
+    highlightedIndex < selectableItems.length
+      ? getItemId(highlightedIndex)
+      : undefined;
+
+  const onFieldKeyDown = useCallback(
+    (e: React.KeyboardEvent): void => {
+      // A chord is the field's own command, such as Shift+Enter, except
+      // Escape: whatever modifier is held, it hides a shown list first, so an
+      // enclosing layer never closes on the same press. An input method
+      // composing text owns every key, Escape included, until it commits or
+      // cancels.
+      if (
+        isDisabled ||
+        isImeKeyEvent(e.nativeEvent) ||
+        (hasModifier(e) && e.key !== 'Escape')
+      ) {
+        return;
+      }
+      const enabledIndices = getEnabledIndices();
+      if (!isOpen) {
+        // A single-line field has no caret work for ArrowDown, so it shows the
+        // hidden list.
+        if (
+          e.key === 'ArrowDown' &&
+          selectableItems.length > 0 &&
+          onOpen() !== false
+        ) {
+          e.preventDefault();
+          setHighlightedIndex(enabledIndices[0] ?? -1);
+        }
+        return;
+      }
+      switch (e.key) {
+        case 'ArrowDown':
+        case 'ArrowUp': {
+          // The list keeps the arrows even with nothing to move to, so they
+          // never move the caret under an open list.
+          e.preventDefault();
+          if (enabledIndices.length === 0) {
+            break;
+          }
+          // Wraps at either end, as the typeahead input does; with nothing
+          // active, ArrowDown starts at the first option and ArrowUp at the
+          // last.
+          const count = enabledIndices.length;
+          const position = enabledIndices.indexOf(highlightedIndex);
+          const next =
+            e.key === 'ArrowDown'
+              ? (position + 1) % count
+              : position < 0
+                ? count - 1
+                : (position - 1 + count) % count;
+          setHighlightedIndex(enabledIndices[next]);
+          break;
+        }
+        case 'Enter': {
+          // Only a pick stops the field's own Enter (a send, a newline).
+          const item =
+            highlightedIndex >= 0 ? selectableItems[highlightedIndex] : null;
+          if (item != null && !item.disabled) {
+            e.preventDefault();
+            selectItem(item);
+          }
+          break;
+        }
+        case 'Escape':
+          // Claimed, so an enclosing layer stays open on this press.
+          e.preventDefault();
+          closeAndReset();
+          break;
+        default:
+          // Every other key reaches the field unchanged. Home and End stay
+          // with the caret until their behavior is decided (AST-075 OQ2).
+          break;
+      }
+    },
+    [
+      isDisabled,
+      getEnabledIndices,
+      isOpen,
+      selectableItems,
+      onOpen,
+      highlightedIndex,
+      selectItem,
+      closeAndReset,
+    ],
+  );
+
+  const getFieldProps = useCallback(
+    (props: ComboboxFieldHandlers = {}): ComboboxFieldProps => {
+      return {
+        role: 'combobox',
+        'aria-expanded': isListboxShown,
+        'aria-autocomplete': 'list',
+        'aria-controls': isListboxShown ? listboxId : undefined,
+        'aria-activedescendant': activeDescendant,
+        onKeyDown: event => {
+          onFieldKeyDown(event);
+          if (!event.defaultPrevented) {
+            props.onKeyDown?.(event);
+          }
+        },
+      };
+    },
+    [isListboxShown, listboxId, activeDescendant, onFieldKeyDown],
+  );
+
+  const getListboxProps = useCallback(
+    (): ComboboxListboxProps => ({
+      id: listboxId,
+      role: 'listbox',
+      // A press anywhere in the list keeps focus in the field (FR6).
+      onMouseDown: event => event.preventDefault(),
+    }),
+    [listboxId],
+  );
+
+  const getOptionProps = useCallback(
+    (index: number): ComboboxOptionProps => {
+      const item = selectableItems[index];
+      const isOptionDisabled = item?.disabled === true;
+      return {
+        id: getItemId(index),
+        role: 'option',
+        'aria-selected': index === highlightedIndex,
+        ...(isOptionDisabled ? {'aria-disabled': true as const} : {}),
+        onMouseMove: () => {
+          if (item != null && !isOptionDisabled && index !== highlightedIndex) {
+            highlightOnHover(index);
+          }
+        },
+        onClick: () => {
+          if (item != null) {
+            selectItem(item);
+          }
+        },
+      };
+    },
+    [
+      selectableItems,
+      getItemId,
+      highlightedIndex,
+      highlightOnHover,
+      selectItem,
+    ],
+  );
+
   return {
     highlightedIndex,
     setHighlightedIndex,
@@ -442,5 +663,8 @@ export function useCombobox({
     onKeyDown,
     onItemSelect: selectItem,
     onItemMouseEnter,
+    getFieldProps,
+    getListboxProps,
+    getOptionProps,
   };
 }

package/src/Selector/useCombobox.doc.mjs

@@ -16,6 +16,7 @@ export const docs = {
     'keyboard',
     'arrow keys',
     'headless',
+    'autocomplete',
     'apg',
     'accessibility',
     'a11y',
@@ -29,9 +30,9 @@ export const docs = {
     },
     {
       name: 'options.selectableItems',
-      type: 'SelectorOptionData[]',
+      type: 'ReadonlyArray<T extends {value: string; disabled?: boolean}>',
       description:
-        'The options in the same order as they render. Options with `disabled` cannot be picked and are skipped while moving through the open list; ArrowDown or ArrowUp that opens the list 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` still lands on the first or last option.',
       required: true,
     },
     {
@@ -131,19 +132,37 @@ export const docs = {
     },
     {
       name: 'onItemSelect',
-      type: '(item: SelectorOptionData) => void',
+      type: '(item: T) => void',
       description: 'Picks an option from a press on it, then closes the list.',
     },
     {
       name: 'onItemMouseEnter',
-      type: '(item: SelectorOptionData, index: number) => void',
+      type: '(item: T, index: number) => void',
       description:
         'Makes the hovered option active without scrolling the list or moving focus.',
     },
+    {
+      name: 'getFieldProps',
+      type: '(props?: {onKeyDown?(event: React.KeyboardEvent): void}) => object',
+      description:
+        'Props for a single-line `input` you render: `role="combobox"`, `aria-expanded`, `aria-autocomplete="list"`, `aria-controls` only while the listbox renders (`isOpen` with at least one option), `aria-activedescendant` only while an option is active, and the field\u2019s key handler. Pass your own `onKeyDown` here rather than beside the spread: it runs after the hook\u2019s handler unless that handler claimed the key, and it may be typed for its element.',
+    },
+    {
+      name: 'getListboxProps',
+      type: '() => object',
+      description:
+        'Props for the listbox you render, anywhere in the document, including the page\u2019s flow: its `id` and `role`, and a press handler that keeps focus in the field. Render it while `isOpen` and there are options, and name it with `aria-label` or `aria-labelledby`.',
+    },
+    {
+      name: 'getOptionProps',
+      type: '(index: number) => object',
+      description:
+        'Props for the option at `index`: its `id`, `role`, `aria-selected` (true on the active option), `aria-disabled` on a disabled one, a pointer move that makes it active without moving focus, and a press that picks it.',
+    },
   ],
   usage: {
     description:
-      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover. It renders nothing and sets no attributes: the caller renders the control, the listbox and the options, and wires `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` from what it returns.',
+      'Tracks the active option of a single-select combobox and handles its keys, while DOM focus stays on the control. It powers Selector and CommandPalette; use it to build a combobox those components do not cover, including one over a single-line text field you render yourself, such as a search field whose results replace a page section, or an \u201cadd people\u201d field in a dialog. It renders nothing: you render the field, the listbox and the options, and spread `getFieldProps`, `getListboxProps` and `getOptionProps` onto them, or wire `role`, `aria-expanded`, `aria-controls` and `aria-activedescendant` yourself from `onKeyDown` and `getItemId` for a control such as a button.',
     bestPractices: [
       {
         guidance: true,
@@ -158,7 +177,17 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Announce the number of results through useAnnounce when the options change for a new query.',
+          'For a field you render, spread the prop getters, and set the active option yourself when a new query changes the options: the first option so Enter picks it, or -1 so Enter stays the field\u2019s.',
+      },
+      {
+        guidance: true,
+        description:
+          'Announce the number of results through useAnnounce when the options change for a new query (AST-075 DEC-2). When nothing matches, announce the words the field shows for it.',
+      },
+      {
+        guidance: false,
+        description:
+          'Render controls that are not options, such as a create button or an empty message, inside the listbox; render them beside it.',
       },
       {
         guidance: false,
@@ -166,6 +195,57 @@ export const docs = {
           'Move DOM focus onto the options; the active option is announced through `aria-activedescendant` while focus stays on the control.',
       },
     ],
+    accessibility: [
+      {
+        name: 'Focus stays in the field',
+        category: 'Semantics',
+        requirement: 'AST-075 FR1',
+        description:
+          'With the prop getters, moving the active option never moves focus out of the field. The field names the active option through `aria-activedescendant` and carries none while no option is active.',
+      },
+      {
+        name: 'Expanded state follows the list',
+        category: 'Semantics',
+        requirement: 'AST-075 FR2',
+        description:
+          'While the listbox renders, the field exposes `aria-expanded="true"` and `aria-controls` naming it. Otherwise it exposes `aria-expanded="false"` and references nothing.',
+      },
+      {
+        name: 'Roles',
+        category: 'Semantics',
+        requirement: 'AST-075 FR3',
+        description:
+          'The field is a `combobox` with `aria-autocomplete="list"`. The list is a `listbox` of `option`s with `aria-selected="true"` on the active one. You name the field and the listbox.',
+      },
+      {
+        name: 'Keys',
+        category: 'Keyboard',
+        requirement: 'AST-075 FR4',
+        description:
+          'While the list shows, ArrowDown and ArrowUp move the active option and wrap; Enter picks an active option and only then stops the field\u2019s own Enter; Escape, whatever modifier is held, hides the list without closing an enclosing dialog or popover on the same press. While it is hidden, ArrowDown shows it when there are options. An open field with no options still takes Escape, which closes the list, so render an empty message while it is open. Home, End, other chords such as Shift+Enter, and every other key reach the field.',
+      },
+      {
+        name: 'Input method',
+        category: 'Keyboard',
+        requirement: 'AST-075 FR5',
+        description:
+          'No key moves, picks or hides while an input method is composing text.',
+      },
+      {
+        name: 'Pointer',
+        category: 'Semantics',
+        requirement: 'AST-075 FR6',
+        description:
+          'Moving the pointer over an option makes it active without moving focus; pressing an option picks it, and the field keeps focus through the press.',
+      },
+      {
+        name: 'Result count',
+        category: 'Content',
+        requirement: 'AST-075 FR7',
+        description:
+          'Yours to announce: compose useAnnounce (AST-075 DEC-2) so each new query announces the number of options, or that there are none, once and politely. For none, announce the words the field shows.',
+      },
+    ],
   },
   relatedComponents: ['Selector', 'CommandPalette'],
   relatedHooks: ['useMultiCombobox', 'useTypeahead', 'useAnnounce'],
@@ -176,11 +256,11 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette. Renders nothing, sets no attrs: caller renders control / listbox / options and wires role, aria-expanded, aria-controls, aria-activedescendant.',
+    'Single-select combobox state + keys; focus stays on control. Powers Selector / CommandPalette, and comboboxes over a single-line field you render (search whose results replace a section, an add-people field). Renders nothing: spread getFieldProps / getListboxProps / getOptionProps, or wire role, aria-expanded, aria-controls, aria-activedescendant yourself.',
   paramDescriptions: {
     options: 'config.',
     'options.selectableItems':
-      'options in render order; disabled ones not pickable, skipped while moving in open list (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 still lands first / last).',
     'options.isOpen': 'list shown; caller owns state.',
     'options.onOpen':
       'show list; return false to refuse (highlight untouched).',
@@ -209,6 +289,12 @@ export const docsDense = {
       'control keydown: ArrowDown/Up open or move; Enter (Space w/o search) picks or opens; Escape / Tab close; Home / End / PageUp / PageDown jump. editable control keeping Home / End for caret: do not pass them.',
     onItemSelect: 'pick from a press, then close.',
     onItemMouseEnter: 'hover makes option active; no scroll, no focus move.',
+    getFieldProps:
+      'input props: role=combobox, aria-expanded, aria-autocomplete=list, aria-controls only while listbox renders (isOpen + options), aria-activedescendant only while an option is active, key handler. pass own onKeyDown here (may be typed for its element): runs after hook unless hook claimed key.',
+    getListboxProps:
+      'listbox props (id, role, press keeps focus in field); render anywhere incl. page flow while isOpen + options; name it (aria-label / aria-labelledby).',
+    getOptionProps:
+      'option props at index: id, role, aria-selected on active, aria-disabled, pointer move activates w/o focus move, press picks.',
   },
   usage: {
     description:
@@ -226,12 +312,73 @@ export const docsDense = {
       },
       {
         guidance: true,
-        description: 'Announce result count via useAnnounce on new query.',
+        description:
+          'Own field: spread the getters, set active option on new query (first: Enter picks; -1: Enter stays the field\u2019s).',
+      },
+      {
+        guidance: true,
+        description:
+          'Announce result count via useAnnounce on new query (AST-075 DEC-2); for none, the words the field shows.',
+      },
+      {
+        guidance: false,
+        description:
+          'Non-option controls (create button, empty message) inside listbox; render beside it.',
       },
       {
         guidance: false,
         description: 'Move DOM focus onto options; use aria-activedescendant.',
       },
     ],
+    accessibility: [
+      {
+        name: 'Focus stays in the field',
+        category: 'Semantics',
+        requirement: 'AST-075 FR1',
+        description:
+          'moving active option never moves focus; aria-activedescendant names it, none while nothing active.',
+      },
+      {
+        name: 'Expanded state follows the list',
+        category: 'Semantics',
+        requirement: 'AST-075 FR2',
+        description:
+          'listbox renders -> aria-expanded=true + aria-controls; else false + no reference.',
+      },
+      {
+        name: 'Roles',
+        category: 'Semantics',
+        requirement: 'AST-075 FR3',
+        description:
+          'field = combobox + aria-autocomplete=list. listbox of options, aria-selected=true on active. you name field + listbox.',
+      },
+      {
+        name: 'Keys',
+        category: 'Keyboard',
+        requirement: 'AST-075 FR4',
+        description:
+          'shown: ArrowDown/Up move (wrap), Enter picks active option then stops field Enter, Escape (any modifier) hides w/o closing enclosing dialog / popover same press. hidden: ArrowDown shows it w/ options. open field w/ no options still takes Escape (closes list): render an empty message while open. Home / End / other chords (Shift+Enter) / others reach field.',
+      },
+      {
+        name: 'Input method',
+        category: 'Keyboard',
+        requirement: 'AST-075 FR5',
+        description: 'no key moves / picks / hides during IME composition.',
+      },
+      {
+        name: 'Pointer',
+        category: 'Semantics',
+        requirement: 'AST-075 FR6',
+        description:
+          'pointer move over option activates w/o focus move; press picks, field keeps focus.',
+      },
+      {
+        name: 'Result count',
+        category: 'Content',
+        requirement: 'AST-075 FR7',
+        description:
+          'yours: compose useAnnounce (DEC-2), each new query announces count or none once, politely; none = the words the field shows.',
+      },
+    ],
   },
 };

package/src/Selector/useCombobox.public.test.tsx

@@ -0,0 +1,89 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file useCombobox.public.test.tsx
+ * @input useCombobox and SelectorOptionData from the public Selector barrel
+ * @output Compile-time compatibility coverage: a caller that names the result
+ *   `ReturnType<typeof useCombobox>` over an option type of its own, and a
+ *   key handler typed for an input, passed to getFieldProps and spread back
+ *   onto it
+ * @position Public API test guarding @astryxdesign/core/Selector; the core
+ *   typecheck compiles it, so a type regression fails there
+ */
+
+import {render, screen} from '@testing-library/react';
+import type {KeyboardEvent} from 'react';
+import {describe, expect, it} from 'vitest';
+import {useCombobox} from './index';
+import type {SelectorOptionData} from './index';
+
+/** An option type of the caller's own, richer than SelectorOptionData. */
+type Person = {value: string; label: string; email: string};
+
+const PEOPLE: Person[] = [
+  {value: 'ada', label: 'Ada', email: 'ada@example.com'},
+  {value: 'cy', label: 'Cy', email: 'cy@example.com'},
+];
+
+/**
+ * The released shape: the result named after the hook, the only name a
+ * caller has for it, over the caller's own option type.
+ */
+function useNamedResult(): ReturnType<typeof useCombobox> {
+  return useCombobox({
+    selectableItems: PEOPLE,
+    isOpen: true,
+    onOpen: () => {},
+    onClose: () => {},
+    listboxId: 'people',
+  });
+}
+
+function NamedResult() {
+  const combobox = useNamedResult();
+  // The released handlers still take a Selector option, or the caller's own.
+  const onSelect: (item: SelectorOptionData) => void = combobox.onItemSelect;
+  const onHover: (item: SelectorOptionData, index: number) => void =
+    combobox.onItemMouseEnter;
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        combobox.onItemSelect(PEOPLE[0]);
+        combobox.onItemMouseEnter(PEOPLE[1], 1);
+        onSelect({value: 'cy'});
+        onHover({value: 'cy'}, 1);
+      }}>
+      Pick
+    </button>
+  );
+}
+
+function FieldTypedHandlers() {
+  const closed = {
+    selectableItems: PEOPLE,
+    isOpen: false,
+    onOpen: () => {},
+    onClose: () => {},
+  };
+  const to = useCombobox({...closed, listboxId: 'to'});
+  // The handler reads a member only its own element has.
+  const onInputKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    event.currentTarget.select();
+  };
+  return (
+    <input aria-label="To" {...to.getFieldProps({onKeyDown: onInputKeyDown})} />
+  );
+}
+
+describe('useCombobox public types', () => {
+  it('keeps a result named ReturnType<typeof useCombobox> over a richer option type', () => {
+    render(<NamedResult />);
+    expect(screen.getByRole('button', {name: 'Pick'})).toBeTruthy();
+  });
+
+  it('takes a key handler typed for an input', () => {
+    render(<FieldTypedHandlers />);
+    expect(screen.getByRole('combobox', {name: 'To'})).toBeTruthy();
+  });
+});