An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file hooks.ts
* @input Uses untransformed DOM layout geometry from the Selector's outer
* anchor, listbox, and selected option, and the layer runtime's keyboard
* inset
* @output Hooks for Selector. useSelectedItemOffset and useCombobox are
* public, exported from the Selector entry point. CommandPalette also uses
* useCombobox, and so do products with a combobox over their own text field
* (spec:AST-075). useSelectedItemOverlayMargin is Selector's own.
* @position Selector hooks; used by Selector.tsx and CommandPalette
*
* SYNC: When useCombobox's options or return change, update:
* - /packages/core/src/Selector/useCombobox.doc.mjs
*/
import {useCallback, useState} from 'react';
import {enabledEdgeIndex} from '../utils/enabledEdgeIndex';
import {useHighlightedOptionScroll} from '../hooks/useHighlightedOptionScroll';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {LAYER_KEYBOARD_INSET_PROPERTY} from '../Layer/useLayerKeyboardClearance';
import {isImeKeyEvent} from '../utils/ime';
import {layoutViewportHeight} from '../utils/layoutViewport';
import type {RefObject} from 'react';
import type {SelectorOptionData} from './types';
// The selected row renders one optical pixel below the closed trigger label at
// the same mathematical center, so compensate before viewport clamping.
const SELECTED_ITEM_OPTICAL_OFFSET = 1;
/**
* Return an element's document-relative layout top without CSS transforms.
* getBoundingClientRect includes the popover's entry scale, which would make
* the measured error grow with each option's distance from the menu top.
*/
function getLayoutTop(element: HTMLElement): number {
let top = 0;
let current: HTMLElement | null = element;
while (current) {
top += current.offsetTop;
current = current.offsetParent as HTMLElement | null;
}
return top;
}
// =============================================================================
// useSelectedItemOffset - Position dropdown to center selected item over trigger
// =============================================================================
interface UseSelectedItemOffsetOptions {
isOpen: boolean;
selectedItemIndex: number;
listboxId: string;
listboxRef: RefObject<HTMLDivElement | null>;
anchorRef: RefObject<HTMLElement | null>;
}
interface UseSelectedItemOffsetResult {
offset: number;
isPositioned: boolean;
}
interface SelectedItemPlacement {
/** The block-start shift, px, from the anchor's bottom to the clamped top. */
offset: number;
/** The anchor's bottom edge, viewport px. */
anchorBottom: number;
/** The listbox's layout height, px. */
listboxHeight: number;
}
/**
* Measures where the open list goes so that its selected item sits over the
* anchor, clamped to the viewport. Returns null when there is nothing to
* measure.
*/
function measureSelectedItem(
listbox: HTMLElement | null,
anchor: HTMLElement | null,
listboxId: string,
selectedItemIndex: number,
{countsLayerGutter = false}: {countsLayerGutter?: boolean} = {},
): SelectedItemPlacement | null {
if (listbox == null || anchor == null) {
return null;
}
// Find the target item: selected item or first item
const targetIndex = selectedItemIndex >= 0 ? selectedItemIndex : 0;
const targetItemId = `${listboxId}-item-${targetIndex}`;
// Use getElementById - works with special characters without escaping
const targetItem = document.getElementById(targetItemId);
if (!targetItem) {
return null;
}
const anchorRect = anchor.getBoundingClientRect();
// offset* metrics intentionally exclude the popover's entry transform.
const listboxHeight = listbox.offsetHeight;
if (listboxHeight <= 0) {
return null;
}
// Item center relative to listbox top. This remains stable even as the
// popover animates between scale values. scrollTop keeps the calculation
// correct when a previously scrolled listbox is reopened.
const itemCenterInListbox =
getLayoutTop(targetItem) -
getLayoutTop(listbox) -
listbox.scrollTop +
targetItem.offsetHeight / 2;
const anchorCenter = anchorRect.top + anchorRect.height / 2;
// Desired top aligns the selected item's center with the anchor center.
const desiredTop =
anchorCenter - itemCenterInListbox - SELECTED_ITEM_OPTICAL_OFFSET;
// The layer keeps a gutter from the viewport's block end. A list that
// reaches into it overflows the layer's room, and the browser then takes a
// position fallback, which can flip the list off screen. The gutter is the
// layer's far-edge margin. The browser can flip the layer above its anchor
// before the overlay margin applies. The flip moves the gutter to the
// block-start margin. So read the larger of the two margins. A software
// keyboard's own inset replaces the gutter.
const layer = countsLayerGutter
? listbox.closest<HTMLElement>('[popover]')
: null;
let blockEndGutter = 0;
if (layer != null) {
const layerStyle = getComputedStyle(layer);
blockEndGutter = Math.max(
0,
parseFloat(layerStyle.marginBlockStart) || 0,
parseFloat(layerStyle.marginBlockEnd) || 0,
);
}
const viewportHeight = window.innerHeight;
const maxTop = Math.max(0, viewportHeight - listboxHeight - blockEndGutter);
const clampedTop = Math.min(Math.max(desiredTop, 0), maxTop);
// useLayer positions the popover below the outer anchor. Apply a negative
// block-start margin to the layer container so the listbox top moves from
// anchorRect.bottom to clampedTop.
const clampedOffset = Math.max(0, anchorRect.bottom - clampedTop);
return {
offset: clampedOffset,
anchorBottom: anchorRect.bottom,
listboxHeight,
};
}
/**
* Calculates the offset needed to position the dropdown so that the selected
* item appears centered over the outer selector control (macOS-style selector).
*
* The desired dropdown top is calculated directly from the anchor center and
* selected-item center, then clamped to the viewport. This preserves the
* default "selected item over trigger" behavior while letting the menu slide
* upward near the bottom edge or downward near the top edge instead of being
* clipped off-screen.
*/
export function useSelectedItemOffset({
isOpen,
selectedItemIndex,
listboxId,
listboxRef,
anchorRef,
}: UseSelectedItemOffsetOptions): UseSelectedItemOffsetResult {
const [offset, setOffset] = useState(0);
const [isPositioned, setIsPositioned] = useState(false);
const commitPosition = useCallback(
(nextOffset: number, nextIsPositioned: boolean) => {
// eslint-disable-next-line @eslint-react/set-state-in-effect -- selector popover position is derived from DOM layout
setOffset(nextOffset);
// eslint-disable-next-line @eslint-react/set-state-in-effect -- selector popover position is derived from DOM layout
setIsPositioned(nextIsPositioned);
},
[],
);
useIsomorphicLayoutEffect(() => {
if (!isOpen) {
// Reset offset when closed
commitPosition(0, false);
return;
}
const placement = measureSelectedItem(
listboxRef.current,
anchorRef.current,
listboxId,
selectedItemIndex,
);
commitPosition(placement?.offset ?? 0, true);
}, [
isOpen,
selectedItemIndex,
listboxId,
listboxRef,
anchorRef,
commitPosition,
]);
return {offset, isPositioned};
}
interface SelectedItemOverlayMargin {
marginBlockStart: string | undefined;
isPositioned: boolean;
}
/**
* Selector's own overlay margin: `useSelectedItemOffset`'s shift, or more
* while a software keyboard is up. The keyboard's part is CSS. The layer
* runtime's keyboard inset lifts the list above the keyboard. It does so in
* the commit that publishes the inset, before the runtime's cap reads the box.
*/
export function useSelectedItemOverlayMargin({
isOpen,
selectedItemIndex,
listboxId,
listboxRef,
anchorRef,
}: UseSelectedItemOffsetOptions): SelectedItemOverlayMargin {
const [marginBlockStart, setMarginBlockStart] = useState<string>();
const [isPositioned, setIsPositioned] = useState(false);
// Syncs the overlay's margin with the open list's layout: its selected
// item, its anchor and the viewport.
useIsomorphicLayoutEffect(() => {
const placement = isOpen
? measureSelectedItem(
listboxRef.current,
anchorRef.current,
listboxId,
selectedItemIndex,
{countsLayerGutter: true},
)
: null;
let margin: string | undefined;
if (placement != null) {
const {offset, anchorBottom, listboxHeight} = placement;
// The room below the anchor for the list, in the keyboard inset's
// layout px. With no keyboard the inset falls back to the room itself.
// The keyboard term is then 0, and the measured shift stands.
const room = layoutViewportHeight(window) - listboxHeight - anchorBottom;
margin = `min(${-offset}px, max(${-anchorBottom}px, calc(${room}px - var(${LAYER_KEYBOARD_INSET_PROPERTY}, ${room}px))))`;
}
// eslint-disable-next-line @eslint-react/set-state-in-effect -- selector popover position is derived from DOM layout
setMarginBlockStart(margin);
// eslint-disable-next-line @eslint-react/set-state-in-effect -- selector popover position is derived from DOM layout
setIsPositioned(isOpen);
}, [isOpen, selectedItemIndex, listboxId, listboxRef, anchorRef]);
return {marginBlockStart, isPositioned};
}
// =============================================================================
// useCombobox - Keyboard navigation and selection
// =============================================================================
/**
* 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;
hasSearch?: boolean;
onOpen: () => unknown;
onClose: () => void;
onSelect?: (value: string) => void;
/**
* Clear the current value. When provided, pressing Delete or Backspace on the
* closed trigger clears the selection — a keyboard equivalent of the clear
* button, so clearing is not mouse-only. No-op when the popup is open (arrow
* navigation owns those keys there) or when there is no value.
*/
onClear?: () => void;
/**
* With `hasSearch`, printable characters typed on the trigger are appended to
* the search query (opening the popup if needed), so type-to-find works
* without a separate open step. Characters keep arriving here until focus
* lands in the search input, which then owns its own typing.
*/
onSearchSeed?: (char: string) => void;
listboxId: string;
}
/** 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;
// 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;
}
/**
* Handles keyboard navigation and selection for combobox/listbox patterns.
*
* Type-to-select is not handled here: callers that want it compose the shared
* `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<T extends ComboboxOption = SelectorOptionData>({
selectableItems,
value,
isDisabled = false,
isOpen,
hasSearch = false,
onOpen,
onClose,
onSelect,
onClear,
onSearchSeed,
listboxId,
}: UseComboboxOptions<T>): UseComboboxResult<T> {
const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
const getItemId = useCallback(
(index: number) => `${listboxId}-item-${index}`,
[listboxId],
);
const getEnabledIndices = useCallback(() => {
return selectableItems
.map((item, i) => (!item.disabled ? i : -1))
.filter(i => i >= 0);
}, [selectableItems]);
const findSelectedIndex = useCallback(() => {
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;
}
return enabledEdgeIndex(selectableItems, fromEnd);
},
[findSelectedIndex, selectableItems],
);
const closeAndReset = useCallback(() => {
setHighlightedIndex(-1);
onClose();
}, [onClose]);
const selectItem = useCallback(
(item: T) => {
if (isDisabled || item.disabled) {
return;
}
onSelect?.(item.value);
closeAndReset();
},
[isDisabled, onSelect, closeAndReset],
);
const onTriggerClick = useCallback(() => {
if (isDisabled) {
return;
}
if (isOpen) {
closeAndReset();
} else {
const didOpen = onOpen() !== false;
if (didOpen && !hasSearch) {
setHighlightedIndex(findOpeningIndex(false));
}
}
}, [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).
const highlightOnHover = useHighlightedOptionScroll({
isOpen,
highlightedIndex,
setHighlightedIndex,
getOptionId: getItemId,
});
const onItemMouseEnter = useCallback(
(item: T, index: number) => {
if (!item.disabled) {
highlightOnHover(index);
}
},
[highlightOnHover],
);
const onKeyDown = useCallback(
(e: React.KeyboardEvent) => {
if (isDisabled) {
return;
}
const enabledIndices = getEnabledIndices();
switch (e.key) {
case 'ArrowDown':
e.preventDefault();
if (!isOpen) {
if (onOpen() !== false) {
setHighlightedIndex(findOpeningIndex(false));
}
} else {
const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
const nextPos = Math.min(
currentEnabledPos + 1,
enabledIndices.length - 1,
);
setHighlightedIndex(enabledIndices[nextPos] ?? highlightedIndex);
}
break;
case 'ArrowUp':
e.preventDefault();
if (!isOpen) {
if (onOpen() !== false) {
setHighlightedIndex(findOpeningIndex(true));
}
} else {
const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
const prevPos = Math.max(currentEnabledPos - 1, 0);
setHighlightedIndex(enabledIndices[prevPos] ?? highlightedIndex);
}
break;
case ' ':
if (hasSearch) {
break;
}
// A space mid-typeahead extends the query instead of activating; the
// caller's useTypeahead claims it before this handler ever runs.
// falls through
case 'Enter':
e.preventDefault();
if (isOpen && highlightedIndex >= 0) {
const item = selectableItems[highlightedIndex];
if (item && !item.disabled) {
selectItem(item);
}
} else if (!isOpen) {
const didOpen = onOpen() !== false;
if (didOpen && !hasSearch) {
setHighlightedIndex(findOpeningIndex(false));
}
}
break;
case 'Escape':
if (isOpen) {
e.preventDefault();
closeAndReset();
}
break;
case 'Tab':
if (isOpen) {
closeAndReset();
}
break;
case 'Home':
e.preventDefault();
if (isOpen && enabledIndices.length > 0) {
setHighlightedIndex(enabledIndices[0]);
}
break;
case 'End':
e.preventDefault();
if (isOpen && enabledIndices.length > 0) {
setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
}
break;
// PageUp/PageDown mirror Home/End. In search mode Home/End stay on
// the input for caret movement (APG editable combobox), so these are
// the sanctioned substitute for jumping to the first/last option.
case 'PageUp':
e.preventDefault();
if (isOpen && enabledIndices.length > 0) {
setHighlightedIndex(enabledIndices[0]);
}
break;
case 'PageDown':
e.preventDefault();
if (isOpen && enabledIndices.length > 0) {
setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
}
break;
case 'Delete':
case 'Backspace':
// Keyboard equivalent of the clear button (comboboxes-2): clear the
// value from the closed trigger so clearing is not mouse-only. When
// hasSearch is active these keys must edit the search text instead,
// and when the popup is open arrow navigation owns interaction, so
// only handle the closed non-search case with a clearable value.
if (!hasSearch && !isOpen && onClear != null && value != null) {
e.preventDefault();
onClear();
}
break;
default:
// Keys land here only while the trigger holds focus — once the search
// input takes over it handles its own typing — so they belong in the
// query, including the ones racing the open.
if (
hasSearch &&
onSearchSeed &&
e.key.length === 1 &&
!e.ctrlKey &&
!e.metaKey
) {
if (isOpen || onOpen() !== false) {
onSearchSeed(e.key);
}
}
break;
}
},
[
isDisabled,
isOpen,
onOpen,
closeAndReset,
selectableItems,
highlightedIndex,
selectItem,
findOpeningIndex,
getEnabledIndices,
hasSearch,
onClear,
onSearchSeed,
value,
],
);
// ---------------------------------------------------------------------------
// 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,
getItemId,
onTriggerClick,
onKeyDown,
onItemSelect: selectItem,
onItemMouseEnter,
getFieldProps,
getListboxProps,
getOptionProps,
};
}