An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Selector.tsx
* @input Uses React, StyleX, adaptive selection surfaces, theme-resolved
* indicators, Field, and InputGroup context
* @output Exports Selector with input, secondary, and ghost trigger treatments, content-derived option-mark layout, and token-sized single-line triggers
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update:
* - /docs/specs/components/Selector/Selector.spec.md
* - /packages/core/src/Selector/Selector.doc.mjs
* - /packages/core/src/Selector/Selector.test.tsx
* - /packages/core/src/Selector/index.ts
* - /apps/storybook/stories/Selector.stories.tsx
* - /apps/storybook/stories/InputGroup.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Selector/ (showcase blocks)
*/
import React, {
memo,
use,
useCallback,
useEffect,
useId,
useMemo,
useOptimistic,
useRef,
useState,
useTransition,
type ReactNode,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {useTooltip} from '../Tooltip';
import {Icon, renderIconSlot, type IconType} from '../Icon';
import {useIndicator} from '../Indicator';
import type {IndicatorPosition} from '../Indicator';
import type {IndicatorComponent, IndicatorMap} from '../Indicator/types';
import type {IconName} from '../Icon';
import {
Field,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputWrapperStyles,
} from '../Field';
import {Divider} from '../Divider';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {reducedMotionFadeConsts} from '../motion/reducedMotion.stylex';
import {useKeepLayerOpenProps, type LayerPlacement} from '../Layer/useLayer';
import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
import {InternalInputClearButton} from '../Field/InputClearButton';
import {Spinner} from '../Spinner';
import {PanelSearchInput} from '../Field/PanelSearchInput';
import {useKeyboardHighlight} from '../hooks/useKeyboardHighlight';
import {useAnnounce} from '../hooks/useAnnounce';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {
colorVars,
sizeVars,
spacingVars,
radiusVars,
durationVars,
easeVars,
typographyVars,
fontWeightVars,
typeScaleVars,
borderVars,
focusVars,
} from '../theme/tokens.stylex';
import type {SelectorOptionType, SelectorOptionData} from './types';
import {isOptionData, isDivider, isSection, normalizeOption} from './utils';
import {getSelectableOptionEntries} from './selectableOptionEntries';
import {useCombobox, useSelectedItemOverlayMargin} from './hooks';
import {useMenuPress} from '../hooks/useMenuPress';
import {useMenuOverflow} from '../DropdownMenu/useMenuOverflow';
import {useTypeahead} from '../hooks/useTypeahead';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {SelectorOption} from './SelectorOption';
import {SelectorRowLayoutContext} from './SelectorRowLayoutContext';
import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {warnOnce} from '../utils/devWarning';
import {useSize} from '../SizeContext/SizeContext';
import {
useFieldInputStyling,
type FieldInputBaseProps,
} from '../Field/fieldParts';
import {composeEventHandlers} from '../utils/composeEventHandlers';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import type {SizeValue} from '../utils/types';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {
focusOwnerProps,
focusWithinOwner,
} from '../privateAttributes/focusOwner.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
import {useInputGroup} from '../InputGroup/InputGroupContext';
import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
import {VisuallyHidden} from '../VisuallyHidden';
import type {AdaptivePresentation} from '../hooks/useAdaptivePresentation';
import {SelectorBottomSheet} from './SelectorBottomSheet';
import {useSelectorPresentation} from './useSelectorPresentation';
import {selectorPresentationStyles} from './selectorPresentation.stylex';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Selector/Selector.generated';
registerEnglishFallback(english);
/**
* A guess, confirmed by the open measure: more options than this overflow
* the popover listbox's 300 px block size even at 24 px rows, under the
* smallest default row (28 px). A wrong guess (a theme with shorter rows, a
* taller bottom sheet) costs only the measure's correction.
*/
const MOST_ROWS_THAT_FIT = 12;
// Private runtime state. No app or theme sets it.
const OVERLAY_MARGIN_PROPERTY = '--_selector-overlay-margin';
const styles = stylex.create({
// Trigger container — the enhanced click target wrapping the combobox button and clear button as siblings
triggerContainer: {
position: 'relative',
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
gap: spacingVars['--spacing-2'],
width: '100%',
paddingBlock: spacingVars['--spacing-2'],
paddingInline: spacingVars['--spacing-3'],
fontFamily: typographyVars['--font-family-body'],
// The 16px floor is iOS-only: iOS Safari zooms the page when a focused
// control sits under 16px, and only iOS WebKit implements
// -webkit-touch-callout to key the coarse-pointer floor to it.
fontSize: {
default: typeScaleVars['--text-label-size'],
'@media (pointer: coarse)': {
'@supports (-webkit-touch-callout: none)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
},
},
// The line box is set per size in sizeStyles below, where it can be capped
// to what that size token holds.
color: colorVars['--color-text-primary'],
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
},
// Trigger button — the actual combobox button, visually integrated with the container
trigger: {
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
gap: spacingVars['--spacing-2'],
flexGrow: 1,
flexShrink: 1,
flexBasis: 0,
minWidth: 0,
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
fontFamily: 'inherit',
fontSize: 'inherit',
lineHeight: 'inherit',
color: 'inherit',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
// The wrapper (inputWrapperStyles.base) renders the focus ring via
// :focus-within when this button is focused, matching TextInput/NumberInput.
// The button must not draw its own :focus-visible outline or the two stack
// into a doubled ring over the trigger.
outline: 'none',
},
triggerPlaceholder: {
color: colorVars['--color-text-secondary'],
},
triggerLabel: {
flexGrow: 1,
minWidth: 0,
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
textAlign: 'start',
},
// Inside an InputGroup the group's own height is the row, and the trigger
// takes it: `height: 100%` from `groupStyles.inGroup` can only govern if the
// trigger stops asserting a floor of its own — otherwise a control sized
// above its group (`<InputGroup size="md"><Selector size="lg">`) grows the
// row it was supposed to sit in. The padding goes with it: the row is
// already the size token, and the value box is centred in it. The line box
// likewise stops reading the control's own size token (sizeStyles caps it
// there), so grouped triggers keep one line box whatever their `size`.
triggerInGroup: {
minHeight: 0,
paddingBlock: 0,
lineHeight: `max(${spacingVars['--spacing-5']}, 20px, 1rem)`,
},
// Wrapper for `renderValue` output. Takes the free width and clips
// horizontally so a long value ellipsizes rather than widening the trigger;
// vertically the content sizes the control, which the size styles below
// handle.
triggerValue: {
flexGrow: 1,
minWidth: 0,
overflow: 'hidden',
textAlign: 'start',
},
// Inside an InputGroup the row height is the group's, so the trigger clamps
// its own value box to that row rather than asking the value to fit it: any
// node is cut off at the row's edge instead of bleeding through the border
// over whatever sits above and below the group. The rows the system draws
// itself never reach the cut — the row-layout context folds them onto one
// line first (SelectorRowLayoutContext).
//
// The clamp is a percentage, not the size token, because a group can be a
// different size than the control inside it; the row is whatever the group
// made it. That needs a definite height to resolve against, which is what
// stretching the button provides.
triggerButtonInGroup: {
alignSelf: 'stretch',
},
triggerValueInGroup: {
maxHeight: '100%',
},
// Only what Icon does not already provide: `size="sm"` gives the 16px box
// and `color` the token, but the glyph still must not shrink inside the flex
// trigger.
triggerIcon: {
flexShrink: 0,
},
// Rotation lives on the chevron glyph itself (passed through `xstyle`), not
// on the layout wrapper above, so the icon's `selector-indicator-icon` theme
// target and the open/closed transform sit on one element — a theme can
// restyle the mark and its rotation through a single selector. The wrapper
// keeps only layout. The status branch renders a different icon, so it never
// picks these up and needs no transition opt-out.
triggerIconRotation: {
transitionProperty: 'transform',
transitionDuration: durationVars['--duration-fast'],
transitionTimingFunction: easeVars['--ease-standard'],
transformOrigin: 'center',
},
triggerIconOpen: {
transform: 'rotate(180deg)',
},
// Ghost has no borders, so its spacing row never overshoots the token; it
// keeps the uncapped line box from before the sizeStyles cap.
triggerGhost: {
width: 'auto',
borderWidth: 0,
lineHeight: `max(${spacingVars['--spacing-5']}, 20px, 1rem)`,
backgroundColor: 'transparent',
boxShadow: {
default: 'none',
':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
{
'@media (hover: hover)': 'none',
},
':focus-within': 'none',
},
fontWeight: fontWeightVars['--font-weight-medium'],
transitionProperty:
'background-image, background-color, color, opacity, transform',
transform: {
default: 'scale(1)',
// A mouse press; under a coarse pointer the touch press model writes
// `data-astryx-press` instead (see interactionOverlay.stylex.ts).
':active': {
default: 'scale(0.98)',
'@media (pointer: coarse)': 'scale(1)',
},
'[data-astryx-press="on"]': 'scale(0.98)',
},
},
// Secondary is ghost's chrome with the resting fill of a secondary
// button (`--color-neutral`): no border, no shadow, content width, so a
// selector in a nav reads as the sibling of the secondary buttons and
// segmented controls beside it instead of as a form field. The hover and
// pressed answers still come from the shared interaction overlay, layered
// over the fill via backgroundImage.
triggerSecondary: {
width: 'auto',
borderWidth: 0,
lineHeight: `max(${spacingVars['--spacing-5']}, 20px, 1rem)`,
backgroundColor: colorVars['--color-neutral'],
boxShadow: {
default: 'none',
':hover:not(:focus-within):where(:not(:disabled,[aria-disabled="true"]))':
{
'@media (hover: hover)': 'none',
},
':focus-within': 'none',
},
fontWeight: fontWeightVars['--font-weight-medium'],
transitionProperty:
'background-image, background-color, color, opacity, transform',
transform: {
default: 'scale(1)',
':active': {
default: 'scale(0.98)',
'@media (pointer: coarse)': 'scale(1)',
},
'[data-astryx-press="on"]': 'scale(0.98)',
},
},
triggerGhostDisabled: {
backgroundImage: 'none',
transform: {
default: 'none',
':active': 'none',
'[data-astryx-press="on"]': 'none',
},
},
triggerReadOnly: {
cursor: 'default',
},
triggerGhostReadOnly: {
backgroundImage: 'none',
transform: {
default: 'none',
':active': 'none',
'[data-astryx-press="on"]': 'none',
},
},
// Clear button
statusButton: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
color: 'inherit',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
borderRadius: radiusVars['--radius-element'],
},
// A panel with a search field, capped as a whole.
searchPanel: {
display: 'flex',
flexDirection: 'column',
// No taller than its layer's block-size cap, which folds in the software
// keyboard's. The search field's row keeps its height, and the list takes
// what is left.
maxHeight: stylex.firstThatWorks(
`calc(${layerViewportInset.maxBlockSize})`,
`calc(${layerViewportInset.maxBlockSizeFallback})`,
),
},
// Dropdown container
dropdown: {
boxSizing: 'border-box',
// In a search panel, the list shrinks below its content to fit the cap.
minHeight: 0,
// 300 px, and no taller than its layer's block-size cap, which folds in
// the software keyboard's: the list ends above the keyboard with the
// layer.
maxHeight: stylex.firstThatWorks(
`min(300px, ${layerViewportInset.maxBlockSize})`,
`min(300px, ${layerViewportInset.maxBlockSizeFallback})`,
),
overflowY: 'auto',
outline: 'none',
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-1'],
opacity: 1,
// Under Reduce Motion the list appears at once on a fine pointer, and
// takes the shared cross-fade on a coarse one.
transitionProperty: 'opacity',
transitionDuration: {
default: durationVars['--duration-fast'],
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
reducedMotionFadeConsts.duration,
'@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
'0s',
},
transitionTimingFunction: {
default: 'ease',
'@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
reducedMotionFadeConsts.easing,
},
},
dropdownInput: {
// The input trigger's text inset includes its border. Mirror that extra
// pixel in the menu; the borderless secondary/ghost variants need no correction.
paddingInline: `calc(${spacingVars['--spacing-1']} + ${borderVars['--border-width']})`,
},
// Scroll ownership by the browser's own signal, as the menus declare it: a
// list whose options fit keeps every one-finger move, so a slide over the
// options stays a slide; one that scrolls lets the browser pan it vertically
// and cancel the press when it does. Both leave a two-finger pinch to the
// browser, so the page stays zoomable over an open list.
touchPinchZoom: {
touchAction: 'pinch-zoom',
},
touchPanYPinchZoom: {
touchAction: 'pan-y pinch-zoom',
overscrollBehavior: 'contain',
},
// Same correction for the search row's gutter, so the search field and the
// option rows share one left edge.
searchRowInput: {
paddingInline: `calc(${spacingVars['--spacing-1']} + ${borderVars['--border-width']})`,
},
dropdownHidden: {
opacity: 0,
// A longhand: the shorthand would lose to the list's longhands.
transitionProperty: 'none',
},
// Popover container (for anchor positioning)
popover: {
minWidth: 'anchor-size(width)',
},
// Empty state
emptyState: {
padding: spacingVars['--spacing-3'],
textAlign: 'center',
color: colorVars['--color-text-secondary'],
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
},
// Section heading. Plain secondary text, no rules — the same treatment
// DropdownMenu and CommandPaletteGroup already use for a group heading in a
// panel list. A labeled Divider (line–text–line) reads as a separator, and
// next to the search row's own divider it stacked two rules a few pixels
// apart.
sectionHeading: {
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-2'],
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-supporting-size'],
lineHeight: typeScaleVars['--text-supporting-leading'],
color: colorVars['--color-text-secondary'],
userSelect: 'none',
},
// Divider
divider: {
marginBlock: spacingVars['--spacing-1'],
},
// Individual item
item: {
boxSizing: 'border-box',
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
gap: spacingVars['--spacing-2'],
width: '100%',
padding: spacingVars['--spacing-2'],
borderRadius: radiusVars['--radius-element'],
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
color: colorVars['--color-text-primary'],
backgroundColor: 'transparent',
borderWidth: 0,
borderStyle: 'none',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
textAlign: 'start',
outlineStyle: 'none',
},
itemContent: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
flex: 1,
minWidth: 0,
},
// The wrapper keeps a visible mark at either logical position and lets a
// replacement indicator grow beyond the default 1rem minimum. When the
// resolved indicator draws nothing, `:empty` removes the wrapper from layout
// instead of reserving blank space. Selected and unselected labels may
// therefore shift or have different available width by design (AST-004).
itemMarkColumn: {
display: 'inline-flex',
alignItems: 'center',
justifyContent: 'center',
flexShrink: 0,
minWidth: '1rem',
':empty': {
display: 'none',
},
},
itemCheckmark: {
flexShrink: 0,
width: 16,
height: 16,
color: colorVars['--color-icon-primary'],
},
itemHighlighted: {
backgroundColor: colorVars['--color-overlay-hover'],
},
// The fill alone does not reach 3:1 against the listbox. After keyboard
// input, the active option also draws the standard focus ring, inside the
// row by its own width, as a focused menu row does.
itemKeyboardHighlighted: {
outlineWidth: focusVars['--focus-outline-width'],
outlineStyle: focusVars['--focus-outline-style'],
outlineColor: focusVars['--focus-outline-color'],
outlineOffset: `calc(-1 * ${focusVars['--focus-outline-width']})`,
},
itemSelected: {
fontWeight: fontWeightVars['--font-weight-medium'],
},
itemDisabled: {
opacity: 0.5,
cursor: 'default',
},
});
// The trigger is sized by PADDING, not by a fixed height, so it is the size
// token plus one text line for each extra line the value uses: 28/32/36 for
// one line, 48/52/56 for two with the default tokens, where the token and a
// text line are both multiples of 4 and the trigger lines up with the Buttons
// and inputs beside it. No prop picks the height — the content does.
//
// The line box is `--spacing-5`, floored at the 20px clear control and 1rem
// icons. When that row would not fit inside the size token's borders, it is
// capped at what the token holds, so a spacing scale taller than the token
// cannot push a one-line trigger past it. The cap never goes below 1.5em of
// the trigger's own font — the type scale's loosest target leading, a
// conservative bound above a label's glyph extent — so label text too large
// for the token keeps room rather than being clipped. Line box and padding
// read the same value; nothing changes wherever the row already fit. Ghost and
// grouped triggers keep the uncapped line box. `renderValue` content inherits
// this row like the built-in label; content that sets a larger font should set
// its own line height, as it must at any spacing scale.
// Keep these calculations inline: a consumer's Babel preset can lower a
// module-scope helper to a function expression before StyleX evaluates this
// object, and StyleX cannot constant-evaluate that transformed helper.
const sizeStyles = stylex.create({
sm: {
minHeight: sizeVars['--size-element-sm'],
lineHeight: `max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-sm']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem)`,
paddingBlock: `calc((${sizeVars['--size-element-sm']} - max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-sm']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem) - 2 * ${borderVars['--border-width']}) / 2)`,
},
md: {
minHeight: sizeVars['--size-element-md'],
lineHeight: `max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-md']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem)`,
paddingBlock: `calc((${sizeVars['--size-element-md']} - max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-md']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem) - 2 * ${borderVars['--border-width']}) / 2)`,
},
lg: {
minHeight: sizeVars['--size-element-lg'],
lineHeight: `max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-lg']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem)`,
paddingBlock: `calc((${sizeVars['--size-element-lg']} - max(min(${spacingVars['--spacing-5']}, max(${sizeVars['--size-element-lg']} - 2 * ${borderVars['--border-width']}, 1.5em)), 20px, 1rem) - 2 * ${borderVars['--border-width']}) / 2)`,
},
});
/**
* Size-specific overrides for dropdown list items.
* Matches the pattern used by DropdownMenuItem so that
* an `sm` selector renders compact list items, `md`/`lg` use
* the base padding defined in `styles.item`.
*/
const itemSizeStyles = stylex.create({
sm: {
paddingBlock: spacingVars['--spacing-1'],
paddingInline: spacingVars['--spacing-2'],
},
md: {
paddingBlock: spacingVars['--spacing-1-5'],
},
lg: {},
});
const STATUS_ICON_MAP: Record<SelectorStatusType, IconName> = {
warning: 'warning',
error: 'error',
success: 'success',
};
const STATUS_ICON_COLOR_MAP: Record<
SelectorStatusType,
'warning' | 'error' | 'success'
> = {
warning: 'warning',
error: 'error',
success: 'success',
};
const STATUS_BUTTON_LABEL_KEY: Record<SelectorStatusType, string> = {
warning: '@astryx.input.statusButton.warning',
error: '@astryx.input.statusButton.error',
success: '@astryx.input.statusButton.success',
};
export type SelectorSize = 'sm' | 'md' | 'lg';
export type SelectorVariant = 'input' | 'secondary' | 'ghost';
export type SelectorPresentation = AdaptivePresentation;
export type SelectorStatusType = 'warning' | 'error' | 'success';
export interface SelectorStatus {
/**
* The type of status to display.
*/
type: SelectorStatusType;
/**
* Optional message to display below the input.
*/
message?: string;
}
interface SelectorPropsBase<
T extends SelectorOptionType = SelectorOptionType,
> extends Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'> {
/**
* Label text for the selector (always rendered for accessibility).
*/
label: string;
/**
* Ref to the trigger button: the element that carries the combobox role,
* the accessible name, and the value.
*/
ref?: React.Ref<HTMLButtonElement>;
/**
* Click handler on the trigger button. It runs before the selector toggles
* its surface (the press then reaches the control box), and calling
* `preventDefault()` does not keep the surface closed.
*/
onClick?: React.MouseEventHandler<HTMLElement>;
/**
* Focus handler on the trigger button. It runs before the selector's own
* focus handling.
*/
onFocus?: React.FocusEventHandler<HTMLElement>;
/**
* Key handler on the trigger button. It runs after the built-in keyboard
* model and is skipped for keys that model handles and cancels.
*/
onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
/**
* Whether to visually hide the label (still accessible to screen readers).
* @default false
*/
isLabelHidden?: boolean;
/**
* Description text displayed between the label and selector.
*/
description?: string;
/**
* Whether the field is optional. Mutually exclusive with isRequired.
* @default false
*/
isOptional?: boolean;
/**
* Whether the field is required. Mutually exclusive with isOptional.
* @default false
*/
isRequired?: boolean;
/**
* Whether the selector is disabled.
* @default false
*/
isDisabled?: boolean;
/**
* Whether the selector is read-only.
* The selected value stays visible, focusable, and included in form
* submission, and retains its combobox identity with `aria-readonly`. The
* selection surface and editing affordances are removed.
* Unlike `isDisabled`, a read-only selector is not dimmed and keeps its
* value in form submission. `isDisabled` takes precedence when both are set.
* @default false
*/
isReadOnly?: boolean;
/**
* Explains why the selector is disabled. When set together with
* `isDisabled`, the selector shows a tooltip with this text on hover and
* keyboard focus, and the trigger stays focusable (via `aria-disabled`)
* so the reason is discoverable by keyboard and assistive technology.
* Activation stays blocked.
*
* Use this instead of wrapping a disabled selector in `Tooltip`, so the
* reason is attached to the trigger itself.
*
* @example
* ```
* <Selector
* label="Owner"
* options={owners}
* isDisabled
* disabledMessage="You need the Editor role to change this"
* />
* ```
*/
disabledMessage?: string;
/**
* The options to display in the selector.
* Can be strings, objects, dividers, or sections.
*/
options: T[];
// value, onChange, changeAction, and hasClear are in the discriminated union below
/**
* Whether the selector is in a loading state.
* @default false
*/
isLoading?: boolean;
/**
* Placeholder text when no value is selected.
* @default 'Select...'
*/
placeholder?: string;
/**
* The size of the selector.
* - 'sm': Compact size
* - 'md': Default size
* @default 'md'
*/
size?: SelectorSize;
/**
* Visual style of the selector trigger.
* - 'input': bordered input-style trigger for forms
* - 'secondary': matches the theme's secondary buttons (borderless and
* neutral-filled by default), for navs and toolbars where the selector
* sits beside secondary actions
* - 'ghost': borderless trigger matching ghost buttons, for toolbars
* @default 'input'
*/
variant?: SelectorVariant;
/**
* Status indicator for the selector.
* When set, displays a colored border and status icon.
* If message is provided, displays a message box below the selector.
*/
status?: SelectorStatus;
/**
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the bordered input (input variant only)
* - 'detached': message floats below as a separate element with spacing
* - 'tooltip': message is exposed from the on-field status icon
* @default 'attached' for input selectors; 'detached' for secondary/ghost selectors
*/
statusVariant?: FieldStatusPlacement;
/**
* Width of the field. Numbers are treated as pixels, strings are used as-is
* (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
* stay aligned, unlike setting width via `controlXstyle`/`controlClassName`/`controlStyle`.
*/
width?: SizeValue;
/**
* Tooltip text to display in an info icon at the end of the label.
*/
labelTooltip?: string;
/**
* Icon displayed at the start of the selector trigger. Takes precedence over
* the selected option's own `icon`, which the trigger otherwise renders.
*/
startIcon?: ReactNode | IconType;
/**
* Custom render function for options.
* Only called for selectable options (not dividers/sections).
*/
renderOption?: (option: SelectorOptionData) => ReactNode;
/**
* Custom render function for the selected option inside the closed trigger.
* Only called when something is selected; the placeholder is unaffected.
*
* Passing this does not change the trigger's height — what it draws does. A
* one-line value measures exactly the `size` token, so the control still
* lines up with the Buttons and inputs beside it; each further line of
* content adds one text line. Inside an `InputGroup` the group owns the row
* height: the trigger clamps its value box to that row, so a `SelectorOption`
* folds onto one line and ellipsizes, and anything taller than the row is cut
* off at it rather than bleeding over the rows above and below.
*
* @example
* ```
* renderValue={option => (
* <SelectorOption
* icon={option.icon}
* label={option.label}
* description={option.description}
* />
* )}
* ```
*/
renderValue?: (option: SelectorOptionData) => ReactNode;
/**
* Which logical edge of the option row carries a rendered selection mark. An
* empty mark consumes no space, so selected and unselected labels may shift or
* have different available width. `end` is the house convention shared with
* Typeahead and CommandPalette.
*
* @default 'end'
*/
indicatorPosition?: IndicatorPosition;
/**
* Whether to show a search input for filtering options.
* @default false
*/
hasSearch?: boolean;
/**
* Placeholder text for the search input.
* @default 'Search...'
*/
searchPlaceholder?: string;
/**
* Content shown in the panel when there are no options to show, and
* announced in a polite live region when the panel opens. Not shown while
* `isLoading` — the options have not arrived yet.
* @default 'No options'
*/
emptyText?: ReactNode;
/**
* Content shown in the panel when a search query matches no options, and
* announced in a polite live region at the same time.
*
* The panel message is `role="presentation"`, so the live region is the
* only route to assistive tech. It announces the text this content renders,
* read from the DOM, so an element is announced as written and anything
* marked `aria-hidden` is left out of both.
* @default 'No results found'
*/
emptySearchText?: ReactNode;
/**
* Position placement relative to the trigger.
*
* Omit to use the selector's default selected-item overlay behavior: the
* selected item is positioned over the trigger and clamped to the viewport.
* Set a placement to opt into explicit layer positioning (for example,
* `placement="above"` for bottom-fixed toolbars).
*/
placement?: LayerPlacement;
/**
* How the option list is presented.
* - 'popover': anchored to the trigger
* - 'bottom-sheet': modal sheet suited to compact touch screens
* - 'adaptive': bottom sheet on compact coarse-pointer screens, otherwise popover
* @default 'popover'
*/
presentation?: SelectorPresentation;
/**
* Whether the dropdown starts open on mount.
* Useful for showcases and previews.
* @default false
*/
isDefaultOpen?: boolean;
/**
* The HTML name attribute for form submissions. When set, a hidden input
* carries the selected value under this name, matching how a native
* select serializes.
*/
htmlName?: string;
/**
* Test ID for testing frameworks.
*/
'data-testid'?: string;
}
/**
* Without `hasClear`, the selector always has a string value (or undefined for placeholder).
* With `hasClear`, the value can be `null` and onChange receives `null` on clear.
*/
type SelectorPropsNonClearable<
T extends SelectorOptionType = SelectorOptionType,
> = SelectorPropsBase<T> & {
hasClear?: false;
value?: string;
onChange?: (value: string) => void;
changeAction?: (value: string) => void | Promise<void>;
};
type SelectorPropsClearable<T extends SelectorOptionType = SelectorOptionType> =
SelectorPropsBase<T> & {
/**
* Whether to show a clear button when a value is selected.
* When clicked, resets the value to `null` and returns focus to the trigger.
*
* When enabled, `value` and `onChange` widen to include `null`.
*/
hasClear: true;
value: string | null;
onChange?: (value: string | null) => void;
changeAction?: (value: string | null) => void | Promise<void>;
};
export type SelectorProps<T extends SelectorOptionType = SelectorOptionType> =
SelectorPropsNonClearable<T> | SelectorPropsClearable<T>;
/**
* Default option renderer
*/
function DefaultOption({option}: {option: SelectorOptionData}) {
return (
<SelectorOption
icon={option.icon}
label={option.label ?? option.value}
description={option.description}
/>
);
}
interface SelectorOptionRowProps {
item: SelectorOptionData;
flatIndex: number;
id: string;
isHighlighted: boolean;
/** The highlight came from keyboard input, so the row draws the focus ring. */
isKeyboardHighlighted: boolean;
isSelected: boolean;
size: SelectorSize;
indicatorPosition: IndicatorPosition;
renderOption: ((option: SelectorOptionData) => ReactNode) | undefined;
SelectionMark: IndicatorComponent<IndicatorMap['check']>;
onSelect: (item: SelectorOptionData) => void;
/** `isActive`: the option was already the highlighted one when entered. */
onHover: (
item: SelectorOptionData,
flatIndex: number,
isActive: boolean,
) => void;
}
/**
* Keep each prop stable across renders that do not change this row. A new
* `onSelect` or `renderOption` re-renders every row.
*/
const SelectorOptionRow = memo(function SelectorOptionRow({
item,
flatIndex,
id,
isHighlighted,
isKeyboardHighlighted,
isSelected,
size,
indicatorPosition,
renderOption,
SelectionMark,
onSelect,
onHover,
}: SelectorOptionRowProps) {
/*
* Rendered UNCONDITIONALLY, with the state passed down: the default
* check draws nothing when unchecked, but a theme that replaces the
* `check` indicator with a radio needs the unselected state to draw
* its empty circle. `{isSelected && …}` would make that impossible.
*
* `selector-check` stays the stable target for the mark's position
* in the row; the indicator owns what the mark looks like.
*/
const mark = (
<span {...stylex.props(styles.itemMarkColumn)}>
<SelectionMark
state={isSelected ? 'checked' : 'unchecked'}
size="sm"
isDisabled={item.disabled ?? false}
{...themeProps('selector-check')}
/>
</span>
);
const optionContent = (
<span {...stylex.props(styles.itemContent)}>
{renderOption ? renderOption(item) : <DefaultOption option={item} />}
</span>
);
return (
<div
id={id}
role="option"
aria-selected={isSelected}
aria-disabled={item.disabled}
onClick={() => onSelect(item)}
onMouseEnter={() => onHover(item, flatIndex, isHighlighted)}
{...mergeProps(
// Stable theme target on the option row itself, mirroring
// `multi-selector-option`: it carries the row's size and runtime
// state so a theme can express "selected option at large" or
// restyle a given row density without structural selectors. The
// row's padding is split across a base and a per-size override (the
// default `md` trims the block axis), so `size` is what a theme
// needs to reach it. Named `-option-row` because `selector-option`
// is the public SelectorOption content primitive, not this row.
themeProps('selector-option-row', {
size,
selected: isSelected ? 'selected' : null,
disabled: item.disabled ? 'disabled' : null,
}),
stylex.props(
styles.item,
itemSizeStyles[size],
isHighlighted && styles.itemHighlighted,
isKeyboardHighlighted && styles.itemKeyboardHighlighted,
isSelected && styles.itemSelected,
item.disabled && styles.itemDisabled,
),
)}>
{indicatorPosition === 'start' ? (
<>
{mark}
{optionContent}
</>
) : (
<>
{optionContent}
{mark}
</>
)}
</div>
);
});
// Case-insensitive substring match for a single option. The one predicate used
// by both the flat filter (count + keyboard nav) and the grouped renderer, so
// what is shown while searching stays in lockstep with the announced count.
function optionMatchesQuery(
option: SelectorOptionData,
query: string,
): boolean {
if (!query) {
return true;
}
return (option.label ?? option.value)
.toLowerCase()
.includes(query.toLowerCase());
}
// Case-insensitive substring filter over the selectable options. Shared by the
// `filteredItems` memo (rendering) and the search-change handler, which needs
// the count for the *next* query synchronously to announce it exactly once per
// keystroke rather than reacting to state in an effect.
function filterOptionsByQuery(
items: SelectorOptionData[],
query: string,
): SelectorOptionData[] {
if (!query) {
return items;
}
return items.filter(item => optionMatchesQuery(item, query));
}
/**
* New option objects with the same values and enabled states give the same
* signature, so they do not move the highlight.
*/
function optionSignature(
items: ReadonlyArray<{value: string; disabled?: boolean}>,
): string {
return items
.map(item => `${item.disabled === true ? '-' : '+'}${item.value}`)
.join('\u0000');
}
/**
* The index in `next` of the option highlighted at `index` in `previous`.
* When that option is gone or disabled, the highlight moves to the next
* remaining enabled option. With none after it, it moves to the previous
* one. -1 means none remains.
*/
function followHighlight(
previous: ReadonlyArray<{value: string; disabled?: boolean}>,
next: ReadonlyArray<{value: string; disabled?: boolean}>,
index: number,
): number {
const enabledIndexOf = (value: string | undefined) =>
value == null
? -1
: next.findIndex(item => item.value === value && item.disabled !== true);
const stayed = enabledIndexOf(previous[index]?.value);
if (stayed >= 0) {
return stayed;
}
for (let after = index + 1; after < previous.length; after++) {
const found = enabledIndexOf(previous[after]?.value);
if (found >= 0) {
return found;
}
}
// The highlight can sit past the end of the list it was set in: a hover
// applied after the list shrank. Start from the list's own last option.
for (
let before = Math.min(index, previous.length) - 1;
before >= 0;
before--
) {
const found = enabledIndexOf(previous[before]?.value);
if (found >= 0) {
return found;
}
}
return -1;
}
/**
* A selector/dropdown component for choosing from a list of options.
*
* @example
* ```
* <Selector
* label="Fruit"
* options={['Apple', 'Banana', 'Orange']}
* value={fruit}
* onChange={setFruit}
* placeholder="Select a fruit..."
* />
* ```
*/
export function Selector<T extends SelectorOptionType>(
props: SelectorProps<T>,
) {
const t = useComponentTranslator();
const pressable = usePressFeedback();
const {
label,
isLabelHidden = false,
description,
isOptional = false,
isRequired = false,
isDisabled: isDisabledProp = false,
isReadOnly = false,
disabledMessage,
options,
value,
onChange,
changeAction,
isLoading = false,
placeholder: placeholderFromProps,
size: sizeProp,
variant = 'input',
status,
statusVariant = 'attached',
labelTooltip,
startIcon,
htmlName,
renderOption,
renderValue,
indicatorPosition = 'end',
hasSearch = false,
searchPlaceholder: searchPlaceholderFromProps,
emptyText: emptyTextFromProps,
emptySearchText: emptySearchTextFromProps,
placement,
presentation = 'popover',
isDefaultOpen = false,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
onFocus,
onKeyDown: onKeyDownProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
hasClear: hasClearProp,
id,
...restProps
} = props as SelectorPropsClearable<T>;
const inputGroup = useInputGroup();
const inputGroupState = use(InputGroupInternalContext);
const isDisabled = isDisabledProp || inputGroupState.isDisabled;
const {rest, container} = useFieldInputStyling('Selector', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
const searchPlaceholder =
searchPlaceholderFromProps ?? t('@astryx.selector.searchPlaceholder');
const emptyText = emptyTextFromProps ?? t('@astryx.selector.empty');
const emptySearchText =
emptySearchTextFromProps ?? t('@astryx.selector.emptySearchResults');
const hasClear = hasClearProp === true;
const size = useSize(sizeProp, 'md');
const effectiveStatusVariant =
variant !== 'input' && statusVariant === 'attached'
? 'detached'
: statusVariant;
const isEffectivelyReadOnly = isReadOnly && !isDisabled;
// Normalize null to undefined for internal use (null is the clear sentinel)
const normalizedValue = value === null ? undefined : value;
const generatedTriggerId = useId();
// A caller's `id` lands on the trigger either way, so the internal identity
// has to be that same value or the label and listbox point at nothing.
const triggerId = id ?? generatedTriggerId;
const listboxId = useId();
// Read by the live region above so it speaks what this element renders.
const emptyStateRef = useRef<HTMLDivElement>(null);
const descriptionId = useId();
const statusMessageId = useId();
const fieldLabelId = useId();
const inputLabelId = useId();
const readOnlyDescriptionId = useId();
const searchId = useId();
const valueTextId = useId();
// Measure from the same outer control that usePopover anchors to; using the
// shorter inner button makes every size's selected row land too low.
const anchorRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLElement>(null);
const triggerModality = useInteractionModalityTracking();
const triggerButtonRef = useMergedRefs<HTMLButtonElement>(
triggerRef as React.Ref<HTMLButtonElement>,
triggerModality.ref,
ref,
);
const searchRef = useRef<HTMLInputElement>(null);
const [searchQuery, setSearchQuery] = useState('');
// Mirrors searchQuery for the seed path, which runs before focus reaches the
// input and so cannot read the rendered state.
const searchQueryRef = useRef('');
// A typed query shows the search row's clear (✕) button, which becomes
// the next tab stop after the search input.
const hasQuery = searchQuery.length > 0;
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(normalizedValue);
const isBusy = isLoading || optimisticValue !== normalizedValue;
// The busy Spinner is decorative; this control announces its busy start
// (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
const announce = useAnnounce();
// Disabled-reason tooltip. The container receives hover and bubbled focus
// while the trigger stays focusable via aria-disabled. Opening and selection
// are guarded independently, including options in an already-open surface.
const showsDisabledMessage = isDisabled && !!disabledMessage;
const disabledMessageTooltip = useTooltip({
placement: 'above',
// The container div is not naturally focusable; focusin bubbles up from
// the trigger button, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
const statusTooltip = useTooltip({
placement: 'above',
isEnabled: effectiveStatusVariant === 'tooltip' && !!status?.message,
});
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
inputLabelId,
[
description ? descriptionId : null,
!inputGroup && effectiveStatusVariant !== 'tooltip' && status?.message
? statusMessageId
: null,
effectiveStatusVariant === 'tooltip' && status?.message
? statusTooltip.describedBy
: null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
isEffectivelyReadOnly ? readOnlyDescriptionId : null,
],
inputGroup,
);
// A caller aria-labelledby names the trigger together with the field's own
// label (the Field label standalone, the group and input labels in a group).
const triggerLabelledBy =
ariaLabelledByProp != null
? joinAriaIDs(ariaLabelledBy ?? fieldLabelId, ariaLabelledByProp)
: ariaLabelledBy;
// Flatten options for keyboard navigation
const selectableEntries = useMemo(
() => getSelectableOptionEntries(options),
[options],
);
const selectableItems = useMemo(
() => selectableEntries.map(entry => entry.item),
[selectableEntries],
);
// Rows need the same item object on every render, or their memo fails.
const normalizedOf = useMemo(
() => new Map(selectableEntries.map(entry => [entry.source, entry.item])),
[selectableEntries],
);
// `action` is declared on the shared option type for `MultiSelector`;
// this listbox has not adopted it, so it renders the option without the
// control and says so (spec:AST-058 FR9) rather than nesting a control in
// an option.
useEffect(() => {
if (selectableItems.some(item => item.action != null)) {
warnOnce(
'selector:option-action',
'Selector',
'An option carries `action`, which Selector does not render yet; the ' +
'option is shown without it. MultiSelector renders option actions.',
);
}
}, [selectableItems]);
// Filter items by search query
const filteredItems = useMemo(
() => filterOptionsByQuery(selectableItems, searchQuery),
[selectableItems, searchQuery],
);
// Find selected item and its index for positioning
const selectedItemIndex = useMemo(() => {
return selectableItems.findIndex(item => item.value === optimisticValue);
}, [selectableItems, optimisticValue]);
const selectedItem = useMemo(() => {
return selectedItemIndex >= 0
? selectableItems[selectedItemIndex]
: undefined;
}, [selectableItems, selectedItemIndex]);
// Ref for listbox to measure selected item position
const listboxRef = useRef<HTMLDivElement>(null);
// The trigger may name the active option only once the listbox holding it
// is in the document. The bottom sheet loads its surface on first open, so
// the trigger expands a moment before its options exist.
const [isListboxMounted, setIsListboxMounted] = useState(false);
const attachListbox = useCallback((node: HTMLDivElement | null) => {
listboxRef.current = node;
setIsListboxMounted(node != null);
}, []);
// Typeahead is defined below (it needs the popover), but closing and clearing
// must drop its pending buffer — otherwise a stale prefix survives the reset
// window and poisons the next keystroke ("Dog" then "c" would search "dc").
const resetTypeaheadRef = useRef<() => void>(() => {});
// Layer for dropdown positioning
const handleLayerHide = useCallback(() => {
setSearchQuery('');
searchQueryRef.current = '';
resetTypeaheadRef.current();
// Clear any lingering result count when the popover closes so stale status
// text does not linger in the a11y tree.
announce('');
}, [announce]);
const handleLayerShow = useCallback(() => {
if (hasSearch) {
requestAnimationFrame(() => {
const input = searchRef.current;
if (input) {
input.focus();
// When typing seeded the query, place the caret after it so the user
// keeps typing where they left off.
input.setSelectionRange(input.value.length, input.value.length);
}
});
}
}, [hasSearch]);
const surface = useSelectorPresentation({
presentation,
onHide: handleLayerHide,
onShow: handleLayerShow,
triggerRef,
triggerModality,
popoverOptions: {
hasLightDismiss: true,
hasCloseButton: false,
hasAutoFocus: false,
// The popup's own role="listbox" is the exposed semantics; the trigger
// keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.
role: 'none',
// The theme target belongs on the SURFACE that paints the popup, which
// `usePopover` owns — not on the scrolling list inside it.
surfaceTarget: 'selector-popup',
// The entrance runs on the surface: an anchored layer lays out again on
// each frame its own style animates.
xstyle: layerAnimations[placement ?? 'below'],
},
});
const {popover} = surface;
const hideSurface = surface.hide;
const isSurfaceOpen = surface.isOpen;
const keepOpenProps = useKeepLayerOpenProps(popover.id, popover.isOpen);
// Open dropdown on mount when isDefaultOpen is true and interaction is allowed.
useEffect(() => {
if (isDefaultOpen && !isEffectivelyReadOnly) {
surface.show();
}
// eslint-disable-next-line @eslint-react/exhaustive-deps -- mount-only: isDefaultOpen is not reactive
}, []);
// Read-only is controlled by caller policy, so an already-open surface must
// close when that policy changes. The presentation controller keeps a sheet
// mounted through its exit and lets BottomSheet return final focus.
useEffect(() => {
if (isEffectivelyReadOnly && isSurfaceOpen) {
hideSurface();
}
}, [isEffectivelyReadOnly, isSurfaceOpen, hideSurface]);
// Announce the filtered result count from the query-change handlers (matching
// BaseTypeahead) rather than a reactive effect: computing the count for the
// next query here fires the announcement exactly once per keystroke and does
// not re-speak on unrelated re-renders. Split out from handleSearchChange so
// the type-to-open seed below reaches the same live region — a query the user
// typed is a query however it arrived.
const announceSearchResults = useCallback(
(nextQuery: string) => {
if (nextQuery.length === 0) {
// Emptying the query clears the region rather than announcing a count.
announce('');
return;
}
// While isLoading the panel deliberately shows nothing, so announcing a
// result would put a claim in the one channel the screen has gone quiet
// for.
if (isLoading) {
announce('');
return;
}
const count = filterOptionsByQuery(selectableItems, nextQuery).length;
if (count === 0) {
// The empty panel is announced from the rendered message below, not
// from here. Two speakers for one transition would say it twice, and
// this one cannot cover an empty result that arrives after the
// keystroke — an async load landing with nothing that matches.
return;
}
announce(t('@astryx.selector.resultCount', {count}));
},
[announce, isLoading, selectableItems, t],
);
const handleSearchChange = useCallback(
(nextQuery: string) => {
setSearchQuery(nextQuery);
searchQueryRef.current = nextQuery;
announceSearchResults(nextQuery);
},
[announceSearchResults],
);
// The panel's empty message is role="presentation" — role="listbox" permits
// only option and group children — so this region is its only route to
// assistive tech, and the region has to say what the panel says. Both
// `emptyText` and `emptySearchText` take a ReactNode, so the words are read
// off the rendered element rather than guessed from the prop: a caller who
// puts a link in the dead end is announced their link, not a default
// (`spec:AST-056` AR1).
//
// Watching the rendered STATE rather than the keystroke also covers the
// case the old keystroke-time announcement could not: a fetch that lands
// with nothing matching an active query left the message on screen and the
// region silent.
const isPanelEmpty =
surface.isOpen && !isLoading && filteredItems.length === 0;
useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery);
// Calculate offset to position selected item over trigger. Explicit
// placement opts out of the selector-specific overlay behavior and uses the
// standard layer positioning API instead.
const shouldOverlaySelectedItem = placement == null && !hasSearch;
const {marginBlockStart: rawMarginBlockStart, isPositioned: rawIsPositioned} =
useSelectedItemOverlayMargin({
isOpen: popover.isOpen && shouldOverlaySelectedItem,
selectedItemIndex,
listboxId,
listboxRef,
anchorRef,
});
const isPositioned = shouldOverlaySelectedItem ? rawIsPositioned : true;
const popoverPlacement = placement ?? 'below';
const overlayMargin =
shouldOverlaySelectedItem && rawMarginBlockStart != null
? rawMarginBlockStart
: null;
const overlayMarginProperty: Record<string, string> =
overlayMargin == null ? {} : {[OVERLAY_MARGIN_PROPERTY]: overlayMargin};
const popoverOffsetStyle: React.CSSProperties | undefined =
overlayMargin == null
? undefined
: {
...overlayMarginProperty,
marginBlockStart: `var(${OVERLAY_MARGIN_PROPERTY})`,
};
// Clear the current value. Shared by the clear button and the keyboard
// Delete/Backspace path so clearing is reachable without a mouse.
const clearValue = useCallback(() => {
resetTypeaheadRef.current();
onChange?.(null);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(undefined);
await changeAction(null);
});
}
}, [onChange, changeAction, startTransition, setOptimisticValue]);
// Type-to-find appends to the query rather than replacing it: characters
// typed before focus reaches the search input must not be dropped. The ref
// is what makes that safe without a state updater — it advances
// synchronously, so a second character seeded in the same tick still sees
// the first, and the announcement can be computed here rather than inside a
// setState callback.
const appendSearchQuery = useCallback(
(char: string) => {
const nextQuery = searchQueryRef.current + char;
searchQueryRef.current = nextQuery;
setSearchQuery(nextQuery);
announceSearchResults(nextQuery);
},
[announceSearchResults],
);
const commitValue = useCallback(
(newValue: string) => {
// A surface or pointer gesture can outlive the enabled state that opened
// it. Enforce current availability before callbacks or optimistic state.
if (isDisabled || isEffectivelyReadOnly) {
return;
}
onChange?.(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[
isDisabled,
isEffectivelyReadOnly,
onChange,
changeAction,
startTransition,
setOptimisticValue,
],
);
// Selector behavior (keyboard nav, selection)
const {
highlightedIndex,
setHighlightedIndex,
getItemId,
onTriggerClick: comboboxTriggerClick,
onKeyDown: comboboxKeyDown,
onItemSelect,
onItemMouseEnter: comboboxItemMouseEnter,
} = useCombobox({
selectableItems: filteredItems,
// The optimistic value, not the raw prop: with a pending changeAction the
// prop still holds the old selection, so the popup would open with the
// highlight on it and Delete/Backspace could clear a value the action has
// already replaced.
value: optimisticValue,
isDisabled: isDisabled || isEffectivelyReadOnly,
isOpen: surface.isOpen,
hasSearch,
onOpen: useCallback(() => surface.show(), [surface]),
onClose: surface.hide,
onSelect: commitValue,
onClear: hasClear ? clearValue : undefined,
onSearchSeed: appendSearchQuery,
listboxId,
});
// Only after keyboard input does the active option draw the focus ring; a
// pointer highlight keeps the fill alone, as a focused menu row does.
// Modality changes only on a key or a press, so a hover alone still reads
// as keyboard. The option the mouse enters therefore draws no ring until a
// key moves the highlight again. Entering the option that is already
// active, as when a key scrolls it under a still mouse, changes nothing.
const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
const keyDownAfterHover = useCallback(
(e: React.KeyboardEvent) => {
setHoveredIndex(null);
comboboxKeyDown(e);
},
[comboboxKeyDown],
);
const mouseEnterOption = useCallback(
(item: SelectorOptionData, index: number, isActive: boolean) => {
if (!isActive) {
setHoveredIndex(index);
}
comboboxItemMouseEnter(item, index);
},
[comboboxItemMouseEnter],
);
const {
isKeyboardHighlight: isHighlightFromKeyboard,
noteHighlightMove,
onKeyDown,
onItemMouseEnter,
} = useKeyboardHighlight(
triggerModality.readModality,
keyDownAfterHover,
mouseEnterOption,
);
const onTriggerClick = useCallback(() => {
comboboxTriggerClick();
noteHighlightMove();
}, [comboboxTriggerClick, noteHighlightMove]);
// A new query is a new list: the old highlight's index would name another
// option, or one past the end. Adjusted during render rather than in an
// effect.
const [highlightedQuery, setHighlightedQuery] = useState(searchQuery);
if (highlightedQuery !== searchQuery) {
setHighlightedQuery(searchQuery);
setHighlightedIndex(-1);
}
// The highlight follows its option by value when the options move or
// reload, so it never names whatever option now sits at its old index.
// Adjusted during render, as the query reset above.
const highlightSignature = optionSignature(filteredItems);
const [highlightedList, setHighlightedList] = useState({
signature: highlightSignature,
items: filteredItems,
});
if (highlightedList.signature !== highlightSignature) {
setHighlightedList({signature: highlightSignature, items: filteredItems});
if (highlightedQuery === searchQuery && highlightedIndex >= 0) {
const followed = followHighlight(
highlightedList.items,
filteredItems,
highlightedIndex,
);
setHighlightedIndex(followed);
// The hovered row moves with its option too, so the ring keeps showing
// only a highlight that keyboard input set.
if (hoveredIndex != null) {
if (hoveredIndex === highlightedIndex) {
setHoveredIndex(followed >= 0 ? followed : null);
} else {
const hoveredValue = highlightedList.items[hoveredIndex]?.value;
const moved = filteredItems.findIndex(
item => item.value === hoveredValue,
);
// A follow that lands the keyboard highlight on the hovered option
// keeps it a keyboard highlight.
setHoveredIndex(moved >= 0 && moved !== followed ? moved : null);
}
}
}
}
// Type-to-select, shared with the other collections (menus, listboxes).
// Open, it walks the highlight — aria-activedescendant announces each match.
// Closed, it commits the match like a native select, which changes the value
// without opening the popup or moving focus, so nothing else would prompt
// assistive tech to re-read the trigger: announce it explicitly.
const typeahead = useTypeahead({
getItemLabels: () => selectableItems.map(item => item.label ?? item.value),
isDisabled: index => selectableItems[index]?.disabled === true,
// Cycle onward from the highlight when open, from the committed selection
// when closed — the optimistic one, so a pending changeAction cannot strand
// cycling on the first match. -1 means nothing is selected or highlighted,
// which the hook reads as "search from the top".
getCurrentIndex: () =>
surface.isOpen ? highlightedIndex : selectedItemIndex,
onMatch: index => {
const item = selectableItems[index];
if (surface.isOpen) {
setHighlightedIndex(index);
} else if (item.value !== optimisticValue) {
commitValue(item.value);
announce(item.label ?? item.value);
}
},
});
resetTypeaheadRef.current = typeahead.reset;
// The press model for the listbox: the option under a finger's or
// a mouse's RELEASE is the one picked, and the highlight follows a held
// pointer through `highlightedIndex` — DOM focus stays on the trigger, as a
// combobox's must. A mouse released outside dismisses the list; a finger
// leaves it open.
const optionIndexFromRow = useCallback((row: HTMLElement): number => {
const match = /-item-(\d+)$/.exec(row.id);
return match == null ? -1 : Number(match[1]);
}, []);
// Re-measured when the option set changes; the count is the dependency.
// A list longer than the most rows that can fit cannot fit, so it starts
// as a scroll container and the open measure only confirms it.
const listboxHasOverflow = useMenuOverflow(
listboxRef,
filteredItems.length,
surface.isOpen,
filteredItems.length > MOST_ROWS_THAT_FIT,
);
const listboxPress = useMenuPress({
menuRef: listboxRef,
itemSelector: '[role="option"]:not([aria-disabled="true"])',
onHighlight: row => {
if (row == null) {
setHighlightedIndex(-1);
return;
}
// The hover path, not the raw setter: a pointer-driven highlight must
// never scroll the option into view, or the rows move under the
// stationary finger and the highlight runs away (the same rule hover
// follows).
const index = optionIndexFromRow(row);
const item = filteredItems[index];
if (item != null) {
// A press is pointer input, even on the active option.
onItemMouseEnter(item, index, false);
}
},
onActivate: row => {
const item = filteredItems[optionIndexFromRow(row)];
if (item != null) {
onItemSelect(item);
}
},
onDismiss: surface.hide,
});
const handleTriggerKeyDown = useCallback(
(e: React.KeyboardEvent) => {
if (isDisabled || isEffectivelyReadOnly) {
return;
}
noteHighlightMove();
setHoveredIndex(null);
// With hasSearch the query input owns typing, so type-to-select is off.
if (!hasSearch && typeahead.onKeyDown(e)) {
e.preventDefault();
return;
}
onKeyDown(e);
},
[
isDisabled,
isEffectivelyReadOnly,
hasSearch,
typeahead,
onKeyDown,
noteHighlightMove,
],
);
// Highlight scrolling (and its hover/keyboard split) lives in useCombobox.
// Handle clear button click
const handleClear = useCallback(
(e: React.MouseEvent) => {
e.stopPropagation(); // Don't open dropdown
clearValue();
// A keyboard activation (detail 0) leaves focus on the clear button,
// which unmounts once the value is null and would drop focus to <body>;
// hand it to the trigger as `hasClear` documents. A pointer press never
// focuses the button, so there is no focus to repair, and moving it
// would pull it out of an open list's search input.
if (e.detail === 0) {
triggerRef.current?.focus();
}
},
[clearValue],
);
// Render search input
const renderSearch = useCallback(() => {
if (!hasSearch) {
return null;
}
return (
<PanelSearchInput
ref={searchRef}
id={searchId}
// The search row is the panel's header: a magnifier, a borderless
// input, and the shared clear (✕) button. It deliberately does NOT
// render a bordered TextInput — the popup is already a bordered
// surface, and a field inside it drew a second box within that box.
label={t('@astryx.selector.searchOptions')}
// Same accessible name the TextInput's built-in clear produced
// ("Clear Search options"), so the affordance keeps its name while its
// chrome changes.
clearLabel={t('@astryx.textInput.clearLabel', {
label: t('@astryx.selector.searchOptions'),
})}
{...themeProps('selector-search')}
xstyle={
surface.activePresentation === 'popover' &&
variant === 'input' &&
styles.searchRowInput
}
// When hasSearch is set, focus moves into this input on open, so it —
// not the trigger — must be the combobox that reports the highlighted
// option via aria-activedescendant (comboboxes-4). A bare searchbox
// left the highlight silent to screen readers.
role="combobox"
aria-expanded={surface.isOpen}
aria-controls={listboxId}
aria-autocomplete="list"
aria-activedescendant={
surface.isOpen && highlightedIndex >= 0
? getItemId(highlightedIndex)
: undefined
}
value={searchQuery}
onValueChange={handleSearchChange}
onContainerKeyDown={e => {
// The clear (✕) button lives inside the row, after the input in DOM
// order. When it is focused and the user tabs forward there is
// nothing else in the popup, so dismiss it (Shift+Tab returns to the
// input natively). Key events originating on the input are handled on
// the input below; ignore them here so we don't double-dismiss.
if (e.target === searchRef.current) {
return;
}
if (e.key === 'Tab' && !e.shiftKey) {
onKeyDown(e);
}
}}
onKeyDown={e => {
// An in-progress IME composition uses these same keys (Enter to
// commit the candidate, Escape/Arrows to navigate the candidate
// window); the composing keydown fires before compositionend, so
// without this guard a Korean/Japanese/Chinese user committing a
// syllable with Enter would instead select the highlighted option.
// See utils/ime.ts.
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
// Arrow keys navigate options; Enter selects; Escape closes.
// Home/End are left to the input for caret movement (APG editable
// combobox); PageUp/PageDown are the sanctioned substitute for
// jumping to the first/last option.
if (
e.key === 'ArrowDown' ||
e.key === 'ArrowUp' ||
e.key === 'PageUp' ||
e.key === 'PageDown' ||
e.key === 'Enter' ||
e.key === 'Escape'
) {
onKeyDown(e);
return;
}
// Tab: when a query is showing the clear (✕) button, forward-tab
// moves focus to it (keeping the popup open) so the affordance is
// keyboard-reachable. Every other Tab dismisses the popup as usual.
if (e.key === 'Tab' && (e.shiftKey || !hasQuery)) {
onKeyDown(e);
}
}}
placeholder={searchPlaceholder}
/>
);
}, [
hasSearch,
searchId,
listboxId,
searchQuery,
hasQuery,
searchPlaceholder,
handleSearchChange,
onKeyDown,
surface.isOpen,
surface.activePresentation,
highlightedIndex,
getItemId,
variant,
t,
]);
// The single-selection mark, resolved from the theme once per render. A
// theme that maps `check` to another indicator (a radio, say) changes every
// selected-option mark in the app through this one lookup.
const SelectionMark = useIndicator('check');
// Render an individual item
const renderItem = useCallback(
(item: SelectorOptionData, flatIndex: number) => (
<SelectorOptionRow
key={item.value}
item={item}
flatIndex={flatIndex}
id={getItemId(flatIndex)}
isHighlighted={flatIndex === highlightedIndex}
isKeyboardHighlighted={
flatIndex === highlightedIndex &&
isHighlightFromKeyboard &&
flatIndex !== hoveredIndex
}
isSelected={item.value === normalizedValue}
size={size}
indicatorPosition={indicatorPosition}
renderOption={renderOption}
SelectionMark={SelectionMark}
onSelect={onItemSelect}
onHover={onItemMouseEnter}
/>
),
[
renderOption,
indicatorPosition,
highlightedIndex,
isHighlightFromKeyboard,
hoveredIndex,
size,
normalizedValue,
getItemId,
onItemSelect,
onItemMouseEnter,
SelectionMark,
],
);
// Render all options (handling sections/dividers)
const renderOptions = useCallback(() => {
const isSearching = hasSearch && Boolean(searchQuery);
// Nothing to show — either the query matched nothing, or no options were
// given at all. Both render the same slot with different copy. While
// isLoading the options have not arrived yet, so asserting either would be
// a claim the component cannot make; the trigger's spinner covers it.
if (filteredItems.length === 0 && !isLoading) {
// role="presentation" keeps the message out of the listbox's
// accessibility tree (role="listbox" only permits option/group
// children); the no-results outcome is announced via the
// result-count live region instead.
return [
<div
key="empty"
ref={emptyStateRef}
role="presentation"
{...mergeProps(
themeProps('selector-empty-state'),
stylex.props(styles.emptyState),
)}>
{isSearching ? emptySearchText : emptyText}
</div>,
];
}
let flatIndex = 0;
const elements: ReactNode[] = [];
for (let i = 0; i < options.length; i++) {
const option = options[i];
if (isDivider(option)) {
// While searching, a standalone divider between groups would orphan
// itself once its neighbors are filtered out, so skip it.
if (isSearching) {
continue;
}
// role="listbox" only permits option/group children; the divider
// carries no information the options don't, so it's hidden from the
// accessibility tree entirely rather than exposing role="separator"
// as a disallowed listbox child (axe aria-required-children).
elements.push(
<Divider
key={`divider-${i}`}
aria-hidden="true"
xstyle={styles.divider}
/>,
);
} else if (isSection(option)) {
const sectionItems: ReactNode[] = [];
for (const opt of option.options) {
const normalized = normalizedOf.get(opt) ?? normalizeOption(opt);
if (isSearching && !optionMatchesQuery(normalized, searchQuery)) {
continue;
}
sectionItems.push(renderItem(normalized, flatIndex));
flatIndex++;
}
// Hide a group entirely (header + wrapper) when none of its items
// match the query, so no header is left standing over nothing.
if (sectionItems.length === 0) {
continue;
}
// The heading lives INSIDE the group and is aria-hidden: the group
// already carries the title as its accessible name, so exposing the
// text again would announce it twice. This also keeps role="listbox"'s
// children to option/group only — the old labeled Divider sat in the
// listbox as a stray role="separator".
elements.push(
<div key={`section-${i}`} role="group" aria-label={option.title}>
{option.title && (
<div
aria-hidden="true"
{...mergeProps(
themeProps('selector-section-heading'),
stylex.props(styles.sectionHeading),
)}>
{option.title}
</div>
)}
{sectionItems}
</div>,
);
} else if (isOptionData(option)) {
const normalized = normalizedOf.get(option) ?? normalizeOption(option);
if (isSearching && !optionMatchesQuery(normalized, searchQuery)) {
continue;
}
elements.push(renderItem(normalized, flatIndex));
flatIndex++;
}
}
return elements;
}, [
options,
normalizedOf,
renderItem,
hasSearch,
searchQuery,
filteredItems,
isLoading,
emptyText,
emptySearchText,
]);
// The detached message box renders its own leading status icon, so the
// on-field icon would duplicate it — keep the chevron indicator instead.
const showStatusIcon =
status != null && effectiveStatusVariant !== 'detached';
const showStatusTooltip =
status != null && effectiveStatusVariant === 'tooltip' && !!status.message;
// Two lines cannot fit inside an InputGroup: the group pins the row height,
// and the trigger clamps its value box to one line so nothing bleeds through
// its border (styles.triggerValueInGroup). The clamp holds for any node; the
// context is what lets the rows the system draws itself reflow into that one
// line — label and description side by side — instead of being cut off at
// it. Outside a group the caller's own row decides, and the trigger's
// padding sizes it to whatever that draws.
const rowLayout = inputGroup ? 'inline' : 'stacked';
// What the closed trigger shows for the current selection: the option's icon
// and label. `startIcon` wins over the option's own icon so a caller who
// pins a field icon does not get two.
const valueContent =
selectedItem && renderValue ? (
<SelectorRowLayoutContext value={rowLayout}>
<span
id={valueTextId}
{...stylex.props(
styles.triggerValue,
inputGroup && styles.triggerValueInGroup,
)}>
{renderValue(selectedItem)}
</span>
</SelectorRowLayoutContext>
) : (
<>
{!startIcon &&
selectedItem?.icon != null &&
renderIconSlot(selectedItem.icon, {size: 'sm', color: 'secondary'})}
<span id={valueTextId} {...stylex.props(styles.triggerLabel)}>
{selectedItem?.label ?? placeholder}
</span>
</>
);
// A screen reader announces no value for a button. So the searchable
// trigger's name holds the value text after the label. A standalone label
// needs an id for this reference. A caller aria-label stays the name's first
// part: the trigger refers to itself. A caller aria-labelledby outranks it,
// as it does on the combobox shape.
const callerAriaLabel = (rest as {'aria-label'?: string})['aria-label'];
const triggerNameLabelId =
callerAriaLabel != null && ariaLabelledByProp == null
? triggerId
: (triggerLabelledBy ?? (inputGroup ? undefined : fieldLabelId));
const isValueInTriggerName =
hasSearch &&
!isEffectivelyReadOnly &&
triggerNameLabelId != null &&
(selectedItem != null || placeholder != null);
const panelContent = hasSearch ? (
<div {...stylex.props(styles.searchPanel)}>
{renderSearch()}
<Divider />
<div
ref={attachListbox}
id={listboxId}
role="listbox"
aria-label={label}
{...listboxPress.menuProps}
{...stylex.props(
styles.dropdown,
listboxHasOverflow
? styles.touchPanYPinchZoom
: styles.touchPinchZoom,
surface.activePresentation === 'popover' &&
variant === 'input' &&
styles.dropdownInput,
)}>
{renderOptions()}
</div>
</div>
) : (
<div
ref={attachListbox}
id={listboxId}
role="listbox"
{...listboxPress.menuProps}
// The trigger shows the value, so it cannot name the list.
// A modal sheet removes an outside label from the accessibility tree.
// The label element also holds the required marker and the tooltip.
aria-label={label}
aria-activedescendant={
surface.isOpen && highlightedIndex >= 0
? getItemId(highlightedIndex)
: undefined
}
tabIndex={surface.activePresentation === 'bottom-sheet' ? 0 : undefined}
onKeyDown={
surface.activePresentation === 'bottom-sheet'
? handleTriggerKeyDown
: undefined
}
{...stylex.props(
styles.dropdown,
listboxHasOverflow ? styles.touchPanYPinchZoom : styles.touchPinchZoom,
surface.activePresentation === 'popover' &&
variant === 'input' &&
styles.dropdownInput,
surface.activePresentation === 'popover' &&
!isPositioned &&
styles.dropdownHidden,
)}>
{renderOptions()}
</div>
);
let selectionSurface: ReactNode = null;
if (surface.activePresentation === 'bottom-sheet') {
if (!isEffectivelyReadOnly || surface.isSheetPresented) {
selectionSurface = (
<SelectorBottomSheet
isOpen={surface.isSheetOpen}
onOpenChange={surface.onSheetOpenChange}
finalFocusRef={triggerRef}
initialFocusRef={hasSearch ? searchRef : listboxRef}
label={label}>
{panelContent}
</SelectorBottomSheet>
);
}
} else if (!isEffectivelyReadOnly) {
selectionSurface = popover.render(panelContent, {
placement: popoverPlacement,
alignment: 'start',
// The system's standard menu clearance, except in overlay mode:
// there the measured negative margin owns the block geometry and
// the menu is meant to sit on the trigger, not clear it.
offset: shouldOverlaySelectedItem
? undefined
: spacingVars['--spacing-1'],
xstyle: styles.popover,
style: popoverOffsetStyle,
});
}
// A disabled trigger stays focusable but, like a natively disabled button,
// runs no caller event handler other than focus and blur, and a press on it
// reaches no handler at all (`spec:AST-085` FR2).
const callerProps = withholdCallerHandlers(rest, isDisabled);
const triggerSharedProps: React.HTMLAttributes<HTMLElement> = {
...callerProps,
onClick: isDisabled
? event => {
event.preventDefault();
event.stopPropagation();
}
: rest.onClick,
id: triggerId,
// A caller's description is kept alongside the field's own.
'aria-describedby':
[ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
undefined,
'aria-labelledby': isValueInTriggerName
? joinAriaIDs(triggerNameLabelId, valueTextId)
: triggerLabelledBy,
'aria-required': isEffectivelyRequired ? 'true' : undefined,
'aria-invalid': status?.type === 'error' ? 'true' : undefined,
'aria-busy': isBusy || undefined,
// The built-in keyboard model runs first; a caller handler sees the keys
// it leaves uncancelled. A caller `onClick` arrives through `rest` and
// runs on the trigger before the press bubbles to the control box's
// toggle, as it always has.
onKeyDown: isDisabled
? handleTriggerKeyDown
: composeEventHandlers(handleTriggerKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
},
tabIndex: 0,
...stylex.props(
styles.trigger,
isEffectivelyReadOnly && styles.triggerReadOnly,
inputGroup && styles.triggerButtonInGroup,
),
};
const selectorContent = (
<>
<div
ref={el => {
anchorRef.current = el;
popover.triggerRef(el);
// Anchor + hover/focus listeners for the disabled-message tooltip.
// Handlers are gated internally by isEnabled, and anchor names
// compose, so attaching unconditionally is safe.
disabledMessageTooltip.ref(el);
}}
onClick={onTriggerClick}
{...pressable}
{...(inputGroup ? inputGroupItemProps : undefined)}
{...mergeProps(
themeProps('selector', {
variant,
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
readonly: isEffectivelyReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
styles.triggerContainer,
sizeStyles[size],
variant === 'ghost' && styles.triggerGhost,
variant === 'secondary' && styles.triggerSecondary,
variant !== 'input' && interactionOverlayStyles.backgroundImage,
// Rings for the trigger button only. The clear and status
// buttons ring themselves.
variant !== 'input' &&
!surface.isTriggerFocusRingSuppressed &&
focusWithinOwner,
surface.isTriggerFocusRingSuppressed &&
selectorPresentationStyles.pointerRestoredFocus,
isDisabled && inputWrapperStyles.disabled,
variant === 'input' &&
isDisabled &&
!surface.isTriggerFocusRingSuppressed &&
inputDisabledFocusStyles.ring,
isEffectivelyReadOnly && styles.triggerReadOnly,
variant !== 'input' && isDisabled && styles.triggerGhostDisabled,
variant !== 'input' &&
isEffectivelyReadOnly &&
styles.triggerGhostReadOnly,
!selectedItem && styles.triggerPlaceholder,
variant === 'input' &&
status &&
inputStatusBorderStyles[status.type],
variant === 'input' &&
status &&
!isDisabled &&
inputStatusHoverShadowStyles[status.type],
// Grouped secondary triggers keep their neutral fill but take the
// group's row height, connected edge radii, and focus stacking.
variant !== 'ghost' && inputGroup && groupStyles.inGroup,
inputGroup && styles.triggerInGroup,
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{startIcon &&
renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
{inputGroup && (
<VisuallyHidden id={inputLabelId}>{label}</VisuallyHidden>
)}
{isEffectivelyReadOnly && (
<VisuallyHidden id={readOnlyDescriptionId}>
{t('@astryx.input.readOnly')}
</VisuallyHidden>
)}
<button
{...triggerSharedProps}
ref={triggerButtonRef}
{...focusOwnerProps}
type="button"
// The read-only trigger stays a combobox even when hasSearch is set:
// no search input is rendered in that state, and preserving the role
// keeps the control's programmatic identity stable. Editable search
// mode still moves combobox semantics to the popup input.
role={isEffectivelyReadOnly || !hasSearch ? 'combobox' : undefined}
aria-haspopup={
isEffectivelyReadOnly
? undefined
: surface.activePresentation === 'bottom-sheet'
? 'dialog'
: 'listbox'
}
aria-expanded={isEffectivelyReadOnly ? false : surface.isOpen}
aria-controls={isEffectivelyReadOnly ? undefined : listboxId}
aria-readonly={isEffectivelyReadOnly || undefined}
aria-activedescendant={
!isEffectivelyReadOnly &&
!hasSearch &&
surface.isOpen &&
isListboxMounted &&
highlightedIndex >= 0
? getItemId(highlightedIndex)
: undefined
}
// A disabled trigger keeps its tab stop and says so through
// aria-disabled (`spec:AST-085` FR1); the isDisabled guards in
// useCombobox block every way of opening it.
aria-disabled={isDisabled ? 'true' : undefined}>
{valueContent}
</button>
{/* A disabled selector submits no value (`spec:AST-085` FR3). */}
{htmlName != null && !isDisabled && (
<input type="hidden" name={htmlName} value={value ?? ''} />
)}
{isBusy && <Spinner size="sm" aria-hidden="true" />}
{hasClear && value != null && !isDisabled && !isEffectivelyReadOnly && (
<InternalInputClearButton
{...keepOpenProps}
label={t('@astryx.selector.clearLabel', {label})}
onClick={handleClear}
/>
)}
{/*
No wrapper span: Icon's own span already provides the 16px box (`sm`)
and the icon color, so the status glyph and the chevron are each
directly targetable instead of sharing one untargetable parent — and
the two affordances stop sharing a node.
*/}
{showStatusIcon ? (
showStatusTooltip ? (
<button
ref={statusTooltip.ref}
type="button"
aria-label={t(STATUS_BUTTON_LABEL_KEY[status.type])}
aria-describedby={statusTooltip.describedBy}
{...keepOpenProps}
onClick={e => e.stopPropagation()}
{...stylex.props(
focusOutlineStyles.focusVisible,
styles.statusButton,
)}>
<Icon
icon={STATUS_ICON_MAP[status.type]}
size="sm"
color={STATUS_ICON_COLOR_MAP[status.type]}
xstyle={styles.triggerIcon}
/>
</button>
) : (
<Icon
icon={STATUS_ICON_MAP[status.type]}
size="sm"
color={STATUS_ICON_COLOR_MAP[status.type]}
xstyle={styles.triggerIcon}
/>
)
) : !isEffectivelyReadOnly ? (
<Icon
icon="chevronDown"
size="sm"
color="secondary"
// The rotation rides on the glyph, alongside the box and color
// the wrapper used to provide, so one element carries the mark,
// its open/closed transform, and the theme target.
xstyle={[
styles.triggerIcon,
styles.triggerIconRotation,
surface.isOpen && styles.triggerIconOpen,
]}
// Stable theme target on the chevron glyph itself, so a theme can
// restyle just this icon (color, size, hover) — and its
// open/closed state — via `defineTheme`. Same-element rules in
// @layer astryx-theme win over the icon's own base color/size,
// which a button-level target could not reach.
{...themeProps('selector-indicator-icon', {
state: surface.isOpen ? 'expanded' : 'collapsed',
})}
/>
) : null}
</div>
{selectionSurface}
{showStatusTooltip && statusTooltip.renderTooltip(status?.message ?? '')}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
);
if (inputGroup) {
return selectorContent;
}
return (
<Field
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={triggerId}
labelID={
ariaLabelledByProp != null || isValueInTriggerName
? fieldLabelId
: undefined
}
descriptionID={description ? descriptionId : undefined}
isOptional={isOptional}
isRequired={isRequired}
isDisabled={isDisabled}
status={
status
? {
type: status.type,
message: status.message,
messageID: status.message ? statusMessageId : undefined,
}
: undefined
}
statusVariant={effectiveStatusVariant}
labelTooltip={labelTooltip}
width={width}
{...container}>
{selectorContent}
</Field>
);
}
Selector.displayName = 'Selector';