An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file MultiSelector.tsx
* @input Uses React, StyleX, usePopover, useTooltip, CheckboxInput, Field, Badge, Icon, InputGroupContext
* @output Exports MultiSelector with input, secondary, and ghost trigger variants
* @position Core implementation; consumed by index.ts
*
* SYNC: When modified, update:
* - /packages/core/src/MultiSelector/MultiSelector.doc.mjs
* - /packages/core/src/MultiSelector/MultiSelector.test.tsx
* - /packages/core/src/MultiSelector/index.ts
* - /apps/storybook/stories/MultiSelector.stories.tsx
* - /apps/storybook/stories/InputGroup.stories.tsx
* - /packages/cli/assets/templates/blocks/components/MultiSelector/ (showcase blocks)
*/
import React, {
use,
useCallback,
useEffect,
useId,
useImperativeHandle,
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 type {IconName} from '../Icon';
import {
Field,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputWrapperStyles,
} from '../Field';
import {useKeepLayerOpenProps} from '../Layer/useLayer';
import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
import {InternalInputClearButton} from '../Field/InputClearButton';
import {Divider} from '../Divider';
import {Spinner} from '../Spinner';
import {PanelSearchInput} from '../Field/PanelSearchInput';
import {CheckboxInput} from '../CheckboxInput';
import type {IndicatorPosition} from '../Indicator';
import {Badge} from '../Badge';
import {
colorVars,
focusVars,
sizeVars,
spacingVars,
radiusVars,
durationVars,
easeVars,
typographyVars,
fontWeightVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import type {
MultiSelectorOptionType,
MultiSelectorOptionData,
MultiSelectorStatus,
} from './types';
import {
isOptionData,
isDivider,
isSection,
normalizeOption,
getSelectableOptions,
} from '../Selector/utils';
import {useMultiCombobox} from './hooks';
import {getInputARIA, isImeKeyEvent, mergeProps} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import {withholdCallerHandlers} from '../utils/disabledInteraction';
import {devWarn, warnOnce} from '../utils/devWarning';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {useKeyboardHighlight} from '../hooks/useKeyboardHighlight';
import {useAnnounce} from '../hooks/useAnnounce';
import {FOCUSABLE_SELECTOR} from '../hooks/focusableSelector';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import {
useFieldInputStyling,
type FieldInputBaseProps,
type FieldPartStyleProps,
} from '../Field/fieldParts';
import {useDevWarning} from '../hooks/useDevWarning';
import {composeEventHandlers} from '../utils/composeEventHandlers';
import {mergeRefs} from '../utils/mergeRefs';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import type {SizeValue} from '../utils/types';
import {useSize} from '../SizeContext/SizeContext';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.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 '../Selector/SelectorBottomSheet';
import {useSelectorPresentation} from '../Selector/useSelectorPresentation';
import {selectorPresentationStyles} from '../Selector/selectorPresentation.stylex';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/MultiSelector/MultiSelector.generated';
// Bundlers replace this value at build time. The declaration lets a product
// without Node's types type-check this file.
declare const process: {readonly env: {readonly NODE_ENV?: string}};
registerEnglishFallback(english);
// Sentinel value for the select-all item in keyboard navigation
const SELECT_ALL_VALUE = '__xds_select_all__';
// Value of the synthetic "Create <query>" row `hasCreate` offers. Never a real
// option value: picking it reports a `create` change, not a toggle.
const CREATE_VALUE_PREFIX = '__astryx_multi_selector_create__';
function isCreateValue(value: string): boolean {
return value.startsWith(CREATE_VALUE_PREFIX);
}
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'],
fontSize: typeScaleVars['--text-label-size'],
lineHeight: typeScaleVars['--text-label-leading'],
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/Selector. The button must not draw its own
// :focus-visible outline or the two stack into a doubled ring over the
// trigger.
outline: 'none',
borderRadius: radiusVars['--radius-element'],
},
triggerPlaceholder: {
color: colorVars['--color-text-secondary'],
},
triggerContent: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-1'],
flexGrow: 1,
flexShrink: 1,
flexBasis: 0,
minWidth: 0,
overflow: 'hidden',
},
triggerText: {
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
},
triggerBadges: {
display: 'flex',
flexWrap: 'wrap',
gap: spacingVars['--spacing-1'],
alignItems: 'center',
},
triggerOverflow: {
flexShrink: 0,
fontSize: typeScaleVars['--text-label-size'],
color: colorVars['--color-text-secondary'],
fontWeight: fontWeightVars['--font-weight-medium'],
},
// 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 `multi-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)',
},
triggerGhost: {
width: 'auto',
borderWidth: 0,
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)',
},
},
// Keep the input-family width contract while reusing ghost's borderless paint
// and the neutral resting fill used by secondary buttons.
triggerSecondary: {
borderWidth: 0,
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',
padding: spacingVars['--spacing-1'],
},
listbox: {
outline: 'none',
},
// Popover container (for anchor positioning)
popover: {
minWidth: 'anchor-size(width)',
},
// Select-all wrapper
selectAllWrapper: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
},
// 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',
gap: spacingVars['--spacing-2'],
width: '100%',
borderRadius: radiusVars['--radius-element'],
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
// Row typography lives here, not on the label span, so a theme override on
// the row target reaches both the fallback label and renderOption output
// (a declaration on the span would win over the inherited row value).
// Matches Selector, whose option row owns its typography the same way.
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
fontWeight: fontWeightVars['--font-weight-medium'],
color: colorVars['--color-text-primary'],
backgroundColor: 'transparent',
borderWidth: 0,
borderStyle: 'none',
outline: 'none',
},
itemHighlighted: {
backgroundColor: colorVars['--color-overlay-hover'],
},
itemDisabled: {
opacity: 0.5,
color: colorVars['--color-text-disabled'],
cursor: 'default',
},
// Decorative checkbox (non-interactive, purely visual)
checkboxDecorative: {
pointerEvents: 'none',
display: 'flex',
flexShrink: 0,
},
// Pushed to the row's far edge rather than sitting against the label, which
// is what an end-positioned control means here. The row is not
// `space-between` (a truncating label plus a trailing control is what wants
// the auto margin), and `renderOption` content is not wrapped in a growing
// span, so the margin has to live on the checkbox itself.
checkboxDecorativeEnd: {
marginInlineStart: 'auto',
},
// Label text for items (rendered outside checkbox for correct click
// behavior). Typography is inherited from the row; this only handles
// truncation.
itemLabel: {
minWidth: 0,
overflow: 'hidden',
textOverflow: 'ellipsis',
whiteSpace: 'nowrap',
},
// Grid rows (spec:AST-058): the row carries today's option chrome (padding,
// radius, highlight); its two cells split it into the option's click
// target and the action's slot. The action cell is a real cell for the
// active-descendant ring, drawn with the shared focus-outline parts because
// no element inside the popup has DOM focus.
gridRow: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
},
optionCell: {
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
flexGrow: 1,
flexShrink: 1,
minWidth: 0,
alignSelf: 'stretch',
},
actionCell: {
display: 'flex',
alignItems: 'center',
flexShrink: 0,
borderRadius: radiusVars['--radius-element'],
},
// The standard ring, from the focus tokens themselves: inside
// `stylex.create` StyleX resolves an imported `defineVars` group, and a
// plain object such as `FOCUS_OUTLINE_PARTS` compiles to variables nothing
// defines.
actionCellActive: {
outlineWidth: focusVars['--focus-outline-width'],
outlineStyle: focusVars['--focus-outline-style'],
outlineColor: focusVars['--focus-outline-color'],
outlineOffset: focusVars['--focus-outline-offset'],
},
// Empty state
emptyState: {
padding: spacingVars['--spacing-3'],
textAlign: 'center',
color: colorVars['--color-text-secondary'],
fontFamily: typographyVars['--font-family-body'],
fontSize: typeScaleVars['--text-label-size'],
},
});
const sizeStyles = stylex.create({
sm: {
height: sizeVars['--size-element-sm'],
},
md: {
height: sizeVars['--size-element-md'],
},
lg: {
height: sizeVars['--size-element-lg'],
},
});
const itemSizeStyles = stylex.create({
sm: {
padding: spacingVars['--spacing-1'],
},
md: {
paddingBlock: spacingVars['--spacing-1-5'],
paddingInline: spacingVars['--spacing-2'],
},
lg: {
padding: spacingVars['--spacing-2'],
},
});
const selectAllSizeStyles = stylex.create({
sm: {
paddingInline: spacingVars['--spacing-1'],
paddingBlock: spacingVars['--spacing-0-5'],
},
md: {
paddingInline: spacingVars['--spacing-2'],
paddingBlock: spacingVars['--spacing-1'],
},
lg: {
paddingInline: spacingVars['--spacing-2'],
paddingBlock: spacingVars['--spacing-1'],
},
});
const RENDER_TRIGGER_PARTS_MESSAGE =
'`container*` and `control*` styling props have no effect with `renderTrigger`: ' +
'no Field box or control box renders. Style the control you render instead.';
const STATUS_ICON_MAP: Record<MultiSelectorStatusType, IconName> = {
warning: 'warning',
error: 'error',
success: 'success',
};
const STATUS_ICON_COLOR_MAP: Record<
MultiSelectorStatusType,
'warning' | 'error' | 'success'
> = {
warning: 'warning',
error: 'error',
success: 'success',
};
const STATUS_BUTTON_LABEL_KEY: Record<MultiSelectorStatusType, string> = {
warning: '@astryx.input.statusButton.warning',
error: '@astryx.input.statusButton.error',
success: '@astryx.input.statusButton.success',
};
export type MultiSelectorSize = 'sm' | 'md' | 'lg';
export type MultiSelectorVariant = 'input' | 'secondary' | 'ghost';
export type MultiSelectorPresentation = AdaptivePresentation;
export type MultiSelectorStatusType = 'warning' | 'error' | 'success';
export type {MultiSelectorStatus};
/**
* Props the `renderTrigger` render prop hands to the control the caller
* renders.
* Spread them onto that control: it becomes the panel's anchor, the element
* focus returns to, and the control that announces the panel's state.
*/
export interface MultiSelectorRenderTriggerProps extends Omit<
FieldInputBaseProps,
| keyof FieldPartStyleProps
| 'id'
| 'onClick'
| 'onKeyDown'
| 'onFocus'
| 'aria-haspopup'
| 'aria-expanded'
| 'aria-controls'
| 'aria-busy'
| 'aria-readonly'
> {
/**
* Attaches the control as the panel's anchor and focus-return target, and
* forwards it to the selector's own `ref`.
*/
ref: (element: HTMLElement | null) => void;
/** The id the field would have given its own button. */
id: string;
/**
* Opening handlers, present only when there is a panel to open. A
* read-only selector withholds them, so spreading these props onto a
* control gives it no opener rather than a dead one.
*/
onClick?: (event: React.MouseEvent<HTMLElement>) => void;
onKeyDown?: (event: React.KeyboardEvent<HTMLElement>) => void;
onFocus: (event: React.FocusEvent<HTMLElement>) => void;
/**
* Disclosure state. A read-only selector has no surface to disclose, so
* `aria-haspopup` and `aria-controls` are absent and `aria-expanded` is
* `false` (`spec:AST-011` FR4).
*/
'aria-haspopup'?: 'listbox' | 'grid' | 'dialog';
'aria-expanded': boolean;
'aria-controls'?: string;
'aria-busy': boolean | undefined;
/**
* `true` when the selector is read-only, so the caller's control can show
* that state the way its own design calls for.
*/
'aria-readonly'?: boolean;
}
/**
* Imperative control surface for MultiSelector, accessed via the `handleRef`
* prop. Methods drive the same popover machinery as the built-in trigger, so
* they respect focus restoration, light dismiss, and Escape. Pair with
* `onOpenChange` to observe every open and close, including the ones the
* selector performs itself. Same shape as `ComplexSelectorHandle`.
*/
export interface MultiSelectorHandle {
/** Open the panel. No-op when disabled, read-only, or already open. */
open(): void;
/** Close the panel. Restores focus to the trigger. */
close(): void;
/** Toggle the panel open or closed. */
toggle(): void;
/** Whether the panel is currently open. Reads live state. */
isOpen(): boolean;
}
/**
* What kind of change an `onChange` call reports. Only a creation is reported
* today; a plain toggle, clear, or select-all passes no descriptor, so a
* one-argument `onChange` keeps working unchanged.
*/
export type MultiSelectorChange = {
/** The person picked the `Create "<query>"` row of a search. */
type: 'create';
/** The trimmed query, which is also the new entry appended to `value`. */
query: string;
};
export interface MultiSelectorSelectedItem {
value: string;
label: string;
}
export interface MultiSelectorProps<
T extends MultiSelectorOptionType = MultiSelectorOptionType,
> extends Omit<FieldInputBaseProps, 'onChange' | 'defaultValue'> {
/**
* Label text for the multi-selector (always rendered for accessibility).
*/
label: string;
/**
* Ref to the trigger: the button that carries the combobox role, the
* accessible name, and the value — or, with `renderTrigger`, the caller's
* control.
*/
ref?: React.Ref<HTMLElement>;
/**
* Click handler on the trigger (or, with `renderTrigger`, the caller's
* control). It runs after the built-in toggle and cannot cancel it.
*/
onClick?: React.MouseEventHandler<HTMLElement>;
/**
* Focus handler on the trigger. It runs before the selector's own focus
* handling.
*/
onFocus?: React.FocusEventHandler<HTMLElement>;
/**
* Key handler on the trigger. 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 values stay visible, focusable, and included in form
* submission, and retain their 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
* ```
* <MultiSelector
* label="Columns"
* options={columns}
* value={selected}
* onChange={setSelected}
* isDisabled
* disabledMessage="Select a table first"
* />
* ```
*/
disabledMessage?: string;
/**
* The options to display in the selector.
* Can be strings, objects, dividers, or sections.
*/
options: T[];
/**
* The currently selected values.
*/
value: string[];
/**
* The HTML name attribute for form submissions. When set, hidden inputs
* carry one entry per selected value under this name, matching how a
* native multi-select serializes.
*/
htmlName?: string;
/**
* Callback when selection changes. A creation (`hasCreate`) arrives with
* a descriptor as the second argument and the typed text appended to
* `value`; the caller adds the matching option and accepts the value in the
* same update. Every other change passes no descriptor.
*/
onChange: (value: string[], change?: MultiSelectorChange) => void;
/**
* Async action on change. Fires after onChange.
*/
changeAction?: (value: string[]) => void | Promise<void>;
/**
* 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.
* @default 'md'
*/
size?: MultiSelectorSize;
/**
* 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)
* - 'ghost': borderless, transparent trigger matching ghost buttons
* @default 'input'
*/
variant?: MultiSelectorVariant;
/**
* Status indicator for the selector.
*/
status?: MultiSelectorStatus;
/**
* 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 and 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.
*/
startIcon?: ReactNode | IconType;
/**
* Whether to show a clear button when values are selected.
* When clicked, resets the value to an empty array and returns focus to the trigger.
* @default false
*/
hasClear?: boolean;
/**
* Whether to show a "Select all" checkbox.
* @default false
*/
hasSelectAll?: boolean;
/**
* Label for the select-all checkbox.
* @default 'Select all'
*/
selectAllLabel?: string;
/**
* Whether to show a search input.
* @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;
/**
* With `hasSearch`, offer a `Create "<query>"` row first in the list when the
* trimmed query equals no option's label under the search's own matching
* (case-insensitive). Picking it, or Enter with nothing highlighted, calls
* `onChange` with the query appended to `value` and a `{type: 'create',
* query}` descriptor, then clears the search. The caller MUST add an option
* for the new value in that same update; the component does not mint
* options. Nothing is offered while `isLoading`. Setting this without
* `hasSearch` warns in development and offers nothing.
* @default false
*/
hasCreate?: boolean;
/**
* How to display selected items in the trigger.
* - 'count': "3 selected"
* - 'labels': "Name, Email, +3"
* - 'badges': [Name] [Email] +2
* @default 'count'
*/
triggerDisplay?: 'count' | 'labels' | 'badges';
/**
* Formats the trigger text when triggerDisplay is 'count' or 'labels'.
* Receives the selected items (value plus resolved label, in selection
* order) and returns the full trigger text; the count is `items.length`.
* Not called when nothing is selected — the placeholder shows instead — and
* not called for triggerDisplay 'badges', which renders Badge elements
* rather than text.
* @default the translated `@astryx.multiSelector.selectedCount` message ("2 selected") for 'count', "A, B, C, +N" for 'labels'
*/
formatValue?: (items: MultiSelectorSelectedItem[]) => string;
/**
* Maximum number of badges to show before showing "+N".
* Only used when triggerDisplay is 'badges'.
* @default 3
*/
maxBadges?: number;
/**
* Custom render function for options.
* Only called for selectable options (not dividers/sections or the select-all row).
*/
renderOption?: (option: MultiSelectorOptionData) => ReactNode;
/**
* Which edge of the option row carries the checkbox.
*
* @default 'start'
*/
indicatorPosition?: IndicatorPosition;
/**
* 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?: MultiSelectorPresentation;
/**
* Whether the dropdown starts open on mount.
* Useful for showcases and previews.
* @default false
*/
isDefaultOpen?: boolean;
/**
* Render the control the panel hangs off — a glyph in a list row, a chip,
* an icon button — instead of the selector's own field and button. Spread
* the given props onto it; the listbox is then anchored to and labelled by
* that control, and `label` names the listbox for assistive technology.
* The field chrome (`Field`, status, clear button, spinner) is not
* rendered; the caller owns the opener. Pair with `handleRef` to open the
* panel from a keystroke elsewhere.
*
* Hover and pressed paint stay yours. The open state reaches your control
* as `aria-expanded` on the given props, so style it from the rendered
* attribute. A pressed look keyed to `:active` is not a substitute:
* `:active` does not behave the same under a coarse pointer, which is why
* menu rows drop coarse-pointer `:active` paint entirely.
*
* A read-only selector has no panel to open, so the disclosure attributes
* and the opening handlers are withheld: your control reports
* `aria-expanded="false"` and points at nothing.
*
* @example
* ```
* <MultiSelector
* label="Labels"
* renderTrigger={props => <IconButton icon="tag" label="Labels" {...props} />}
* …
* />
* ```
*
* @example
* ```
* // Styling the open state from the rendered attribute:
* // .my-trigger[aria-expanded='true'] { background: var(--color-overlay-pressed); }
* ```
*/
renderTrigger?: (props: MultiSelectorRenderTriggerProps) => ReactNode;
/**
* Imperative handle for opening and closing the panel. Prefer `handleRef`
* over mirroring open state in the parent — the selector owns its
* visibility, and imperative calls avoid the focus-management pitfalls of
* syncing an external `isOpen` prop.
*/
handleRef?: React.Ref<MultiSelectorHandle>;
/**
* Called whenever the panel opens or closes, however it happened — the
* trigger, the keyboard, a light dismiss, Escape, or the imperative handle.
*/
onOpenChange?: (isOpen: boolean) => void;
/**
* Test ID for testing frameworks, set on the trigger button (or, with
* `renderTrigger`, the caller's control).
*/
'data-testid'?: string;
}
// Whether any declared option — at any depth of sections, before any query
// filters it — carries an action. Presence only: the node is never read
// (spec:AST-058 FR2, DEC-5).
function hasDeclaredAction(options: MultiSelectorOptionType[]): boolean {
for (const option of options) {
if (isSection(option)) {
if (
option.options.some(
opt => typeof opt !== 'string' && opt.action != null,
)
) {
return true;
}
} else if (
typeof option !== 'string' &&
isOptionData(option) &&
option.action != null
) {
return true;
}
}
return false;
}
// 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 normalizeLabel(label: string): string {
return label.toLowerCase();
}
function optionMatchesQuery(
option: MultiSelectorOptionData,
query: string,
): boolean {
if (!query) {
return true;
}
return normalizeLabel(option.label ?? option.value).includes(
normalizeLabel(query),
);
}
// "Already exists" for the create row uses the filter's own normalization, so
// a label the filter shows as an exact match is never offered for creation,
// and a label the filter cannot surface for this query is never a dead end.
function hasLabel(items: MultiSelectorOptionData[], query: string): boolean {
const wanted = normalizeLabel(query);
return items.some(
item => normalizeLabel(item.label ?? item.value) === wanted,
);
}
// 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: MultiSelectorOptionData[],
query: string,
): MultiSelectorOptionData[] {
if (!query) {
return items;
}
return items.filter(item => optionMatchesQuery(item, query));
}
/**
* A multi-select dropdown component with checkboxes for choosing
* multiple items from a list of options.
*
* @example
* ```
* <MultiSelector
* label="Columns"
* options={['Name', 'Email', 'Role', 'Status']}
* value={selectedColumns}
* onChange={setSelectedColumns}
* hasSelectAll
* />
* ```
*/
export function MultiSelector<T extends MultiSelectorOptionType>({
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,
hasClear = false,
hasSelectAll = false,
selectAllLabel: selectAllLabelFromProps,
hasSearch = false,
searchPlaceholder: searchPlaceholderFromProps,
emptyText: emptyTextFromProps,
emptySearchText: emptySearchTextFromProps,
hasCreate = false,
triggerDisplay = 'count',
formatValue,
maxBadges = 3,
renderOption,
indicatorPosition = 'start',
presentation = 'popover',
isDefaultOpen = false,
renderTrigger,
handleRef,
onOpenChange,
htmlName,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
id,
onClick,
onFocus,
onKeyDown: onKeyDownProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
...restProps
}: MultiSelectorProps<T>) {
const inputGroup = useInputGroup();
const inputGroupState = use(InputGroupInternalContext);
const isDisabled = isDisabledProp || inputGroupState.isDisabled;
const {rest, container} = useFieldInputStyling('MultiSelector', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
useDevWarning(
'MultiSelector',
RENDER_TRIGGER_PARTS_MESSAGE,
renderTrigger != null &&
(containerXstyle != null ||
containerClassName != null ||
containerStyle != null ||
controlXstyle != null ||
controlClassName != null ||
controlStyle != null),
);
const t = useComponentTranslator();
const pressable = usePressFeedback();
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const placeholder =
placeholderFromProps ?? t('@astryx.multiSelector.selectPlaceholder');
const selectAllLabel =
selectAllLabelFromProps ?? t('@astryx.multiSelector.selectAll');
const searchPlaceholder =
searchPlaceholderFromProps ?? t('@astryx.multiSelector.searchPlaceholder');
const emptyText = emptyTextFromProps ?? t('@astryx.multiSelector.empty');
const emptySearchText =
emptySearchTextFromProps ?? t('@astryx.multiSelector.emptySearchResults');
const size = useSize(sizeProp, 'md');
const effectiveStatusVariant =
variant !== 'input' && statusVariant === 'attached'
? 'detached'
: statusVariant;
const isEffectivelyReadOnly = isReadOnly && !isDisabled;
const generatedTriggerId = useId();
// A caller's `id` lands on the trigger, so the label and listbox wiring
// must use that same value.
const triggerId = id ?? generatedTriggerId;
const listboxId = useId();
const descriptionId = useId();
const statusMessageId = useId();
const fieldLabelId = useId();
const inputLabelId = useId();
const readOnlyDescriptionId = useId();
const searchId = useId();
// Read by the live region above so it speaks what this element renders.
const emptyStateRef = useRef<HTMLDivElement>(null);
const triggerRef = useRef<HTMLElement>(null);
// A hover moves the highlight too, but the focus ring follows the shared
// interaction modality (architecture:interaction-modality INV1): it is read
// whenever a key or the pointer moves the highlight, so an action cell
// highlighted after pointer input keeps the hover treatment and no ring.
const triggerModality = useInteractionModalityTracking();
const readModality = triggerModality.readModality;
const triggerButtonRef = useMergedRefs<HTMLElement>(
triggerRef,
triggerModality.ref,
ref,
);
const searchRef = useRef<HTMLInputElement>(null);
const listboxRef = useRef<HTMLDivElement>(null);
const [searchQuery, setSearchQuery] = useState('');
// 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;
// Snapshot of which values were selected when the dropdown opened.
// Stored as state (not a ref) so sortedItems recomputes exactly once on open,
// then stays frozen until the menu closes.
const [selectedAtOpen, setSelectedAtOpen] = useState<Set<string> | null>(
null,
);
const [, startTransition] = useTransition();
const [optimisticValue, setOptimisticValue] = useOptimistic(value);
const isBusy = isLoading || optimisticValue !== value;
// The busy Spinner is decorative; this control announces its busy start
// (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), triggerRef);
// Disabled-reason tooltip listeners attach to the existing trigger container.
// The trigger stays focusable via aria-disabled. Trigger guards and the value
// commit guards below block activation, including from an already-open panel.
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 selectableItems = useMemo(
() => getSelectableOptions(options),
[options],
);
// Grid mode (spec:AST-058 FR2, DEC-5): decided from the declared options,
// and latched — once a grid, a grid for the life of the instance, so a
// query that filters the actioned option out, or options that arrive after
// a loading state, never flip the role under a screen reader.
const hasActions = useMemo(() => hasDeclaredAction(options), [options]);
const [isGrid, setIsGrid] = useState(hasActions);
if (hasActions && !isGrid) {
setIsGrid(true);
}
// The one half-configuration a single switch cannot rule out: creation
// needs a query to create from. Say so rather than offer nothing in silence.
useEffect(() => {
if (hasCreate && !hasSearch && process.env.NODE_ENV !== 'production') {
devWarn(
'MultiSelector',
'`hasCreate` needs `hasSearch`: the create row is minted from the ' +
'typed query, so without a search input nothing is offered.',
);
}
}, [hasCreate, hasSearch]);
// Announce selection-count changes politely (comboboxes-7 announce path).
// Toggling options / select-all previously produced no audible feedback.
const announce = useAnnounce();
const announceSelection = useCallback(
(nextValue: string[]) => {
const total = selectableItems.length;
const selectableSet = new Set(selectableItems.map(item => item.value));
const selectedCount = nextValue.filter(v => selectableSet.has(v)).length;
if (selectedCount === 0) {
announce(t('@astryx.multiSelector.selectionCleared'));
} else if (total > 0 && selectedCount === total) {
announce(t('@astryx.multiSelector.allSelected'));
} else {
announce(
t('@astryx.multiSelector.selectionCount', {
count: selectedCount,
total,
}),
);
}
},
[announce, selectableItems, t],
);
// Filter items by search query
const filteredItems = useMemo(
() => filterOptionsByQuery(selectableItems, searchQuery),
[selectableItems, searchQuery],
);
// Single source of truth for item order. Both the hook (keyboard navigation)
// and renderOptions (DOM rendering) consume this list — no independent sorting.
// Selected-at-open items are placed first within each group/section, and the
// same walk applies while searching so group structure survives filtering
// (only matching items are kept; the query is empty in non-search mode).
// The query the create row would mint, or null when there is none to offer:
// no `hasCreate`, no search, options still loading (a label that is a moment
// from arriving must not be offered as new), nothing typed, or an option
// already carries that label — `Tokenizer.hasCreate`'s rule.
const canCreate = hasCreate && hasSearch && !isLoading;
const getCreateQuery = useCallback(
(query: string): string | null => {
if (!canCreate) {
return null;
}
const trimmed = query.trim();
if (trimmed === '') {
return null;
}
return hasLabel(selectableItems, trimmed) ? null : trimmed;
},
[canCreate, selectableItems],
);
const createQuery = useMemo(
() => getCreateQuery(searchQuery),
[getCreateQuery, searchQuery],
);
const sortedItems = useMemo(() => {
// Closed, the list keeps the order it opens in, so an index picked
// before it opens (the opening highlight, a typed match) names the same
// option after the selected options move to the top.
const selectedSet = selectedAtOpen ?? new Set(optimisticValue);
const result: MultiSelectorOptionData[] = [];
let pendingFlat: MultiSelectorOptionData[] = [];
const orderSelectedFirst = (items: MultiSelectorOptionData[]) => {
const selected = items.filter(item => selectedSet.has(item.value));
const unselected = items.filter(item => !selectedSet.has(item.value));
return [...selected, ...unselected];
};
const flushFlat = () => {
if (pendingFlat.length === 0) {
return;
}
result.push(...orderSelectedFirst(pendingFlat));
pendingFlat = [];
};
for (const option of options) {
if (isDivider(option)) {
flushFlat();
} else if (isSection(option)) {
flushFlat();
const sectionOptions = option.options
.map(opt => normalizeOption(opt))
.filter(opt => optionMatchesQuery(opt, searchQuery));
result.push(...orderSelectedFirst(sectionOptions));
} else if (isOptionData(option)) {
const normalized = normalizeOption(option);
if (optionMatchesQuery(normalized, searchQuery)) {
pendingFlat.push(normalized);
}
}
}
flushFlat();
if (hasSelectAll) {
result.unshift({value: SELECT_ALL_VALUE, label: selectAllLabel});
}
if (createQuery != null) {
// First row, before select-all: the row the typed text asked for.
result.unshift({
value: `${CREATE_VALUE_PREFIX}${createQuery}`,
label: t('@astryx.multiSelector.createOption', {query: createQuery}),
});
}
return result;
}, [
searchQuery,
options,
selectedAtOpen,
optimisticValue,
hasSelectAll,
selectAllLabel,
createQuery,
t,
]);
// Layer for dropdown positioning
const hasExternalTrigger = renderTrigger != null;
// The open handlers defer their focus move by a frame, so a panel closed
// inside that frame would otherwise be focused after it has gone — the
// person loses focus to a surface that is no longer there. The pending
// frame is cancelled on hide.
const openFocusFrameRef = useRef<number | null>(null);
const cancelOpenFocus = useCallback(() => {
if (openFocusFrameRef.current != null) {
cancelAnimationFrame(openFocusFrameRef.current);
openFocusFrameRef.current = null;
}
}, []);
const handleLayerHide = useCallback(() => {
cancelOpenFocus();
setSearchQuery('');
setSelectedAtOpen(null);
// Clear any lingering result count when the popover closes so stale status
// text does not linger in the a11y tree.
announce('');
onOpenChange?.(false);
}, [announce, onOpenChange, cancelOpenFocus]);
const handleLayerShow = useCallback(() => {
// Snapshot selection only after the surface actually opens; a same-gesture
// rejection must not prepare state for an opening that never happened.
setSelectedAtOpen(new Set(optimisticValue));
if (hasSearch) {
openFocusFrameRef.current = requestAnimationFrame(() => {
openFocusFrameRef.current = null;
searchRef.current?.focus();
});
} else if (hasExternalTrigger) {
// The caller's anchor may not take focus (a glyph in a link row), so
// the listbox owns the keyboard while the panel is open.
openFocusFrameRef.current = requestAnimationFrame(() => {
openFocusFrameRef.current = null;
listboxRef.current?.focus();
});
}
onOpenChange?.(true);
}, [hasSearch, hasExternalTrigger, optimisticValue, onOpenChange]);
const surface = useSelectorPresentation({
presentation,
onHide: handleLayerHide,
onShow: handleLayerShow,
triggerRef,
triggerModality,
isFocusReturnAlways: hasExternalTrigger,
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: 'multi-selector-popup',
},
});
const {popover} = surface;
const hideSurface = surface.hide;
const isSurfaceOpen = surface.isOpen;
// AR2: the caller's control must carry its own name. Checked against the
// rendered DOM in development, never by reading the node.
useEffect(() => {
if (!isGrid || !isSurfaceOpen) {
return;
}
const panel = listboxRef.current;
if (panel == null) {
return;
}
for (const cell of Array.from(
panel.querySelectorAll<HTMLElement>('[data-multi-selector-action-cell]'),
)) {
const control = cell.querySelector<HTMLElement>(
'button, a, input, [role="button"], [tabindex]',
);
if (control == null) {
continue;
}
const named =
(control.getAttribute('aria-label') ?? '').trim() !== '' ||
control.hasAttribute('aria-labelledby') ||
(control.textContent ?? '').trim() !== '' ||
(control.getAttribute('title') ?? '').trim() !== '';
if (!named) {
warnOnce(
'multi-selector:unnamed-action',
'MultiSelector',
'An option `action` renders a control with no accessible name. Give ' +
'it a label: a screen reader reaches it through the action cell ' +
'and has nothing to read.',
);
break;
}
}
});
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]);
const canOpen = !isDisabled && !isEffectivelyReadOnly;
useImperativeHandle(
handleRef,
() => ({
open: () => {
if (canOpen && !surface.isOpen) {
surface.show();
}
},
close: () => surface.hide(),
toggle: () => {
if (surface.isOpen) {
surface.hide();
} else if (canOpen) {
surface.show();
}
},
isOpen: () => surface.isOpen,
}),
[canOpen, surface],
);
// Announce the filtered result count from the query-change handler (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. The count, the create row and the
// empty panel's message state one thing, how the search ended, so they go
// through the search's own `hasReplace` announcer: one the next keystroke
// replaces before it is exposed is withdrawn rather than joined
// (`spec:AST-086` FR9, FR13), and keystrokes arriving within one frame,
// from a scanner, dictation or automation, say only the last query's.
// Selection changes keep the plain announcer above, so they still join.
const announceSearch = useAnnounce({hasReplace: true});
const handleSearchChange = useCallback(
(nextQuery: string) => {
setSearchQuery(nextQuery);
if (nextQuery.length === 0) {
// Emptying the query clears the region rather than announcing a count.
announceSearch('');
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) {
announceSearch('');
return;
}
const count = filterOptionsByQuery(selectableItems, nextQuery).length;
if (count === 0) {
const nextCreateQuery = getCreateQuery(nextQuery);
if (nextCreateQuery != null) {
// The create row is the one result on screen, so the panel is not
// empty and the rendered-message route below stays silent; say the
// row.
announceSearch(
t('@astryx.multiSelector.createOption', {query: nextCreateQuery}),
);
return;
}
// 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;
}
announceSearch(t('@astryx.multiSelector.resultCount', {count}));
},
[announceSearch, isLoading, selectableItems, getCreateQuery, t],
);
// 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.
//
// `realItemCount` mirrors renderOptions exactly: the select-all sentinel
// and the create row ride in `sortedItems`, in that order from the top,
// but neither is an option anybody can match. A create row is a result of
// its own, so a panel showing one is not empty.
const hasCreateRow = createQuery != null;
const leadingCount = (hasCreateRow ? 1 : 0) + (hasSelectAll ? 1 : 0);
const realItemCount = sortedItems.length - leadingCount;
const isPanelEmpty =
surface.isOpen && !isLoading && realItemCount === 0 && !hasCreateRow;
// Through the search's announcer: the empty panel is how the search ended,
// so it and the count replace each other while not yet exposed
// (`spec:AST-086` FR13).
useAnnounceRenderedText(emptyStateRef, isPanelEmpty, searchQuery, {
announce: announceSearch,
});
// Handle toggle
// Clear all selected values. Shared by the clear button and the keyboard
// Delete/Backspace path so clearing is reachable without a mouse.
const clearValues = useCallback(() => {
if (isDisabled) {
return;
}
onChange([]);
announceSelection([]);
if (changeAction) {
startTransition(async () => {
setOptimisticValue([]);
await changeAction([]);
});
}
}, [
isDisabled,
onChange,
changeAction,
startTransition,
setOptimisticValue,
announceSelection,
]);
// Whether there is at least one selected value (clearing is meaningful).
const hasValue = optimisticValue.length > 0;
const handleClear = useCallback(
(e: React.MouseEvent) => {
e.stopPropagation(); // Don't open dropdown
clearValues();
// A keyboard activation (detail 0) leaves focus on the clear button,
// which unmounts once the value is empty and would drop focus to <body>;
// hand it to the trigger. A pointer press never focuses the button, so
// there is no focus to repair, and moving it would pull focus out of an
// open list's search input.
if (e.detail === 0) {
triggerRef.current?.focus();
}
},
[clearValues],
);
const handleToggle = useCallback(
(itemValue: string) => {
if (isDisabled) {
return;
}
const newValue = optimisticValue.includes(itemValue)
? optimisticValue.filter(v => v !== itemValue)
: [...optimisticValue, itemValue];
onChange(newValue);
announceSelection(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[
isDisabled,
optimisticValue,
onChange,
changeAction,
startTransition,
setOptimisticValue,
announceSelection,
],
);
// Select-all logic
const enabledItems = useMemo(
() => filteredItems.filter(item => !item.disabled),
[filteredItems],
);
const allEnabledSelected = useMemo(
() =>
enabledItems.length > 0 &&
enabledItems.every(item => optimisticValue.includes(item.value)),
[enabledItems, optimisticValue],
);
const someSelected = useMemo(
() => enabledItems.some(item => optimisticValue.includes(item.value)),
[enabledItems, optimisticValue],
);
const selectAllState: boolean | 'indeterminate' = allEnabledSelected
? true
: someSelected
? 'indeterminate'
: false;
const handleSelectAll = useCallback(() => {
if (isDisabled) {
return;
}
let newValue: string[];
if (allEnabledSelected) {
// Deselect all enabled items, keep disabled items that are selected
const enabledValues = new Set(enabledItems.map(item => item.value));
newValue = optimisticValue.filter(v => !enabledValues.has(v));
} else {
// Select all enabled items
const currentSet = new Set(optimisticValue);
newValue = [...optimisticValue];
for (const item of enabledItems) {
if (!currentSet.has(item.value)) {
newValue.push(item.value);
}
}
}
onChange(newValue);
announceSelection(newValue);
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
}, [
isDisabled,
allEnabledSelected,
enabledItems,
optimisticValue,
onChange,
changeAction,
startTransition,
setOptimisticValue,
announceSelection,
]);
// Picking the create row: the typed text joins the value and the caller is
// told it is a creation on the channel it already listens to, so adding the
// option and accepting the value are one update. The search is cleared so
// the option the caller adds is visible.
const commitCreate = useCallback(
(query: string) => {
if (isDisabled) {
return;
}
const newValue = optimisticValue.includes(query)
? optimisticValue
: [...optimisticValue, query];
onChange(newValue, {type: 'create', query});
setSearchQuery('');
announce(t('@astryx.multiSelector.optionCreated', {label: query}));
if (changeAction) {
startTransition(async () => {
setOptimisticValue(newValue);
await changeAction(newValue);
});
}
},
[
isDisabled,
optimisticValue,
onChange,
changeAction,
startTransition,
setOptimisticValue,
announce,
t,
],
);
// Route toggle: select-all sentinel → handleSelectAll, the create row →
// commitCreate, everything else → handleToggle
const handleNavigableToggle = useCallback(
(itemValue: string) => {
if (itemValue === SELECT_ALL_VALUE) {
handleSelectAll();
} else if (isCreateValue(itemValue)) {
commitCreate(itemValue.slice(CREATE_VALUE_PREFIX.length));
} else {
handleToggle(itemValue);
}
},
[handleSelectAll, handleToggle, commitCreate],
);
// Multi-select combobox behavior — index-based, matching useCombobox pattern.
// sortedItems is the single source of truth for item order.
const getActionCellIdForActivate = useCallback(
(index: number) => `${listboxId}-item-${index}-action`,
[listboxId],
);
const {
highlightedIndex,
highlightedCell,
getItemId,
getActionCellId,
activeDescendantId,
onTriggerClick,
onKeyDown: onComboboxKeyDown,
onItemMouseEnter: onComboboxItemMouseEnter,
setHighlightedIndex,
} = useMultiCombobox({
selectableItems: sortedItems,
isDisabled: isDisabled || isEffectivelyReadOnly,
isOpen: surface.isOpen,
hasSearch,
onOpen: useCallback(() => surface.show(), [surface]),
onClose: surface.hide,
onToggle: handleNavigableToggle,
onClear: hasClear ? clearValues : undefined,
hasValue,
listboxId,
isGrid,
rowHasAction: useCallback(
(index: number) => sortedItems[index]?.action != null,
[sortedItems],
),
onActivateAction: useCallback(
(index: number) => {
// Fire the caller's control as a press would: the first focusable
// thing in the action cell. Reading the rendered DOM, not the node.
const cell = document.getElementById(getActionCellIdForActivate(index));
const control = cell?.querySelector<HTMLElement>(
'button, a, input, [role="button"], [tabindex]',
);
control?.click();
},
[getActionCellIdForActivate],
),
});
// A new query is a new list: the old highlight's index would name another
// row, or one past the end, so it is cleared. With no row highlighted, Left
// and Right stay the search field's caret keys. Adjusted during render
// rather than in an effect.
const [highlightedQuery, setHighlightedQuery] = useState(searchQuery);
if (highlightedQuery !== searchQuery) {
setHighlightedQuery(searchQuery);
setHighlightedIndex(-1);
}
const {isKeyboardHighlight, onKeyDown, onItemMouseEnter} =
useKeyboardHighlight(
readModality,
onComboboxKeyDown,
onComboboxItemMouseEnter,
);
// The trigger button owns its click so a consumer `onClick`, which lands on
// the button, composes after the built-in toggle. A press elsewhere in the
// control box (padding, start icon, chevron) still opens the panel.
const handleTriggerButtonClick = useCallback(() => {
onTriggerClick();
}, [onTriggerClick]);
const handleControlBoxClick = useCallback(
(event: React.MouseEvent<HTMLDivElement>) => {
if (triggerRef.current?.contains(event.target as Node)) {
return;
}
// Route the press through the trigger so it behaves exactly like a
// press on the trigger itself, caller `onClick` included.
triggerRef.current?.click();
},
[],
);
// Highlight scrolling (and its hover/keyboard split) lives in useMultiCombobox.
// Build trigger display content
const selectedItems = useMemo(() => {
return optimisticValue.map(v => {
const item = selectableItems.find(i => i.value === v);
return {value: v, label: item?.label ?? v};
});
}, [optimisticValue, selectableItems]);
const selectedLabels = useMemo(
() => selectedItems.map(item => item.label),
[selectedItems],
);
const renderTriggerContent = useCallback(() => {
if (optimisticValue.length === 0) {
return <span {...stylex.props(styles.triggerText)}>{placeholder}</span>;
}
switch (triggerDisplay) {
case 'count':
return (
<span {...stylex.props(styles.triggerText)}>
{formatValue?.(selectedItems) ??
t('@astryx.multiSelector.selectedCount', {
count: optimisticValue.length,
})}
</span>
);
case 'labels': {
const displayed = selectedLabels.slice(0, 3);
const remaining = selectedLabels.length - displayed.length;
const text =
remaining > 0
? `${displayed.join(', ')}, +${remaining}`
: displayed.join(', ');
return (
<span {...stylex.props(styles.triggerText)}>
{formatValue?.(selectedItems) ?? text}
</span>
);
}
case 'badges': {
const displayed = selectedLabels.slice(0, maxBadges);
const remaining = selectedLabels.length - displayed.length;
return (
<span {...stylex.props(styles.triggerBadges)}>
{displayed.map(label => (
<Badge key={label} label={label} variant="neutral" />
))}
{remaining > 0 && (
<span {...stylex.props(styles.triggerOverflow)}>
+{remaining}
</span>
)}
</span>
);
}
}
}, [
optimisticValue,
triggerDisplay,
selectedItems,
selectedLabels,
placeholder,
formatValue,
maxBadges,
t,
]);
// 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.multiSelector.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.multiSelector.searchOptions'),
})}
{...themeProps('multi-selector-search')}
// When hasSearch is set, focus moves into this input on open, so it —
// not the trigger — must be the combobox reporting the highlighted
// option via aria-activedescendant (comboboxes-4).
role="combobox"
aria-expanded={surface.isOpen}
aria-controls={listboxId}
aria-autocomplete="list"
aria-activedescendant={activeDescendantId}
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 toggle the highlighted option.
// See utils/ime.ts.
if (isImeKeyEvent(e.nativeEvent)) {
return;
}
if (
e.key === 'Enter' &&
highlightedIndex < 0 &&
createQuery != null
) {
// Nothing highlighted and the typed text matches no option:
// Enter mints it, as it does in Tokenizer.
e.preventDefault();
commitCreate(createQuery);
return;
}
// Arrow keys navigate options; Enter toggles; Escape closes.
// Space and Home/End are left to the input (type a space / move
// the caret) per the 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;
}
// In a grid with a row highlighted, Left/Right move between the
// row's cells (APG combobox with grid popup); with no row
// highlighted they keep moving the caret.
if (
isGrid &&
highlightedIndex >= 0 &&
(e.key === 'ArrowLeft' || e.key === 'ArrowRight')
) {
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,
highlightedIndex,
activeDescendantId,
isGrid,
createQuery,
commitCreate,
t,
]);
// Render an individual item (index-based)
const renderItem = useCallback(
(item: MultiSelectorOptionData, flatIndex: number) => {
const isHighlighted = flatIndex === highlightedIndex;
const isSelectAll = item.value === SELECT_ALL_VALUE;
// The create row is a plain labelled option: no checkbox, never
// selected, and the caller's `renderOption` does not see it.
const isCreate = isCreateValue(item.value);
const isSelected = isSelectAll
? allEnabledSelected
: !isCreate && optimisticValue.includes(item.value);
const checkboxValue = isSelectAll ? selectAllState : isSelected;
// aria-selected="mixed" is invalid on role="option", and the tri-state
// checkbox is inert/decorative, so the indeterminate state must be
// conveyed through the option's accessible name (WCAG 4.1.2).
const isPartiallySelected =
isSelectAll && selectAllState === 'indeterminate';
const checkbox = isCreate ? null : (
<div
inert
{...stylex.props(
styles.checkboxDecorative,
indicatorPosition === 'end' && styles.checkboxDecorativeEnd,
)}>
<CheckboxInput
label=""
isLabelHidden
value={checkboxValue}
onChange={() => {}}
isDisabled={item.disabled}
size={size === 'lg' ? 'md' : size}
/>
</div>
);
const content = (
<>
{indicatorPosition === 'start' && checkbox}
{renderOption && !isSelectAll && !isCreate ? (
renderOption(item)
) : (
<span {...stylex.props(styles.itemLabel)}>
{item.label ?? item.value}
</span>
)}
{indicatorPosition === 'end' && checkbox}
</>
);
const toggle = () => {
if (!item.disabled) {
handleNavigableToggle(item.value);
}
};
return (
<div
key={item.value}
id={getItemId(flatIndex)}
role={isGrid ? 'row' : 'option'}
aria-selected={isSelected}
aria-label={
isPartiallySelected
? t('@astryx.multiSelector.selectAllPartiallySelected', {
label: selectAllLabel,
})
: undefined
}
// In a grid the row is named by its option cell alone, so the
// caller's control is never folded into the row's name
// (spec:AST-058 AR2).
aria-labelledby={
isGrid && !isPartiallySelected
? `${getItemId(flatIndex)}-option`
: undefined
}
aria-disabled={item.disabled}
// In a grid the option cell is the click target, so a press on the
// action cell never toggles (spec:AST-058 FR4).
onClick={isGrid ? undefined : toggle}
onMouseEnter={
isGrid ? undefined : () => onItemMouseEnter(item, flatIndex)
}
{...mergeProps(
// One target for every dropdown row, carrying the row's size and
// runtime state so a theme can express "selected option at large"
// or restyle just the Select All row (`.select-all`) without
// reaching for structural selectors.
themeProps('multi-selector-option', {
size,
'select-all': isSelectAll ? 'select-all' : null,
selected: isSelected ? 'selected' : null,
disabled: item.disabled ? 'disabled' : null,
}),
stylex.props(
styles.item,
isSelectAll ? selectAllSizeStyles[size] : itemSizeStyles[size],
isSelectAll && styles.selectAllWrapper,
isHighlighted && styles.itemHighlighted,
item.disabled && styles.itemDisabled,
isGrid && styles.gridRow,
),
)}>
{isGrid ? (
<>
<div
role="gridcell"
id={`${getItemId(flatIndex)}-option`}
onClick={toggle}
onMouseEnter={() => onItemMouseEnter(item, flatIndex, 'option')}
{...stylex.props(styles.optionCell)}>
{content}
</div>
<div
role="gridcell"
id={getActionCellId(flatIndex)}
data-multi-selector-action-cell=""
onMouseEnter={
item.action != null
? () => onItemMouseEnter(item, flatIndex, 'action')
: undefined
}
{...stylex.props(
styles.actionCell,
isHighlighted &&
highlightedCell === 'action' &&
isKeyboardHighlight &&
styles.actionCellActive,
)}>
{isSelectAll || isCreate ? null : item.action}
</div>
</>
) : (
content
)}
</div>
);
},
[
isGrid,
highlightedCell,
isKeyboardHighlight,
getActionCellId,
renderOption,
indicatorPosition,
highlightedIndex,
optimisticValue,
allEnabledSelected,
selectAllState,
selectAllLabel,
getItemId,
handleNavigableToggle,
onItemMouseEnter,
size,
t,
],
);
// Render all options. Uses sortedItems as the single source of truth for
// item order — no independent sorting here. Structural elements (dividers,
// section headers) come from the original options prop.
const renderOptions = useCallback(() => {
const elements: ReactNode[] = [];
let cursor = 0;
// The create row is the first row: the row the typed text asked for.
if (hasCreateRow) {
elements.push(renderItem(sortedItems[cursor], cursor));
cursor++;
}
// Show select-all only when there are real items to select. It reads as
// the first row of the list, not a section of its own — no divider under
// it (the checkbox column already lines it up with the options below).
if (hasSelectAll) {
if (realItemCount > 0) {
elements.push(renderItem(sortedItems[cursor], cursor));
}
// Skip the select-all sentinel when there are no real items
cursor++;
}
// Empty state — no real items to show. 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.
// While isLoading the options have not arrived yet, so asserting either
// message would be a claim the component cannot make; the trigger's
// spinner covers it.
// A create row is a result of its own, so the empty state stays out.
if (realItemCount === 0 && !isLoading && !hasCreateRow) {
elements.push(
<div
key="empty"
ref={emptyStateRef}
role="presentation"
{...mergeProps(
themeProps('multi-selector-empty-state'),
stylex.props(styles.emptyState),
)}>
{searchQuery ? emptySearchText : emptyText}
</div>,
);
return elements;
}
// Consume items from sortedItems in order, interleaving structural elements
// (dividers, section headers) from the options prop. While searching, only
// matching items are present in sortedItems, so a section consumes just its
// matches and is skipped entirely when none match — no header left standing
// over nothing, and the cursor stays aligned with the combobox indices.
const isSearching = Boolean(searchQuery);
let pendingCount = 0;
const flushPending = () => {
for (let j = 0; j < pendingCount; j++) {
elements.push(renderItem(sortedItems[cursor], cursor));
cursor++;
}
pendingCount = 0;
};
for (let i = 0; i < options.length; i++) {
const option = options[i];
if (isDivider(option)) {
flushPending();
// A standalone divider between groups would orphan itself once its
// neighbors are filtered out, so skip it while searching.
if (!isSearching) {
// 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)) {
flushPending();
const matchCount = isSearching
? option.options.filter(opt =>
optionMatchesQuery(normalizeOption(opt), searchQuery),
).length
: option.options.length;
if (matchCount === 0) {
continue;
}
const sectionItems: ReactNode[] = [];
for (let j = 0; j < matchCount; j++) {
sectionItems.push(renderItem(sortedItems[cursor], cursor));
cursor++;
}
// 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={isGrid ? 'rowgroup' : 'group'}
aria-label={option.title}>
{option.title && (
<div
aria-hidden="true"
{...mergeProps(
themeProps('multi-selector-section-heading'),
stylex.props(styles.sectionHeading),
)}>
{option.title}
</div>
)}
{sectionItems}
</div>,
);
} else if (isOptionData(option)) {
if (
!isSearching ||
optionMatchesQuery(normalizeOption(option), searchQuery)
) {
pendingCount++;
}
}
}
flushPending();
return elements;
}, [
options,
renderItem,
sortedItems,
realItemCount,
searchQuery,
hasSelectAll,
isLoading,
emptyText,
emptySearchText,
isGrid,
hasCreateRow,
]);
// 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;
// With the caller's own trigger, `label` names the listbox directly: the
// anchor may carry no text of its own (a glyph in a link row).
const listboxLabelProps = hasExternalTrigger
? {'aria-label': label}
: {'aria-labelledby': triggerId};
// In a bottom sheet, or hung off a caller's anchor that may not take focus,
// the listbox itself owns the keyboard.
const listboxOwnsKeyboard =
surface.activePresentation === 'bottom-sheet' || hasExternalTrigger;
const panelContent = hasSearch ? (
<div {...stylex.props(styles.searchPanel)}>
{renderSearch()}
<Divider />
<div {...stylex.props(styles.dropdown)}>
<div
ref={listboxRef}
id={listboxId}
role={isGrid ? 'grid' : 'listbox'}
aria-multiselectable="true"
{...listboxLabelProps}
{...stylex.props(styles.listbox)}>
{renderOptions()}
</div>
</div>
</div>
) : (
<div {...stylex.props(styles.dropdown)}>
<div
ref={listboxRef}
id={listboxId}
role={isGrid ? 'grid' : 'listbox'}
aria-multiselectable="true"
// The bottom sheet is rendered in a modal layer, so Chromium cannot
// reliably compute this listbox's name from the trigger outside that
// layer. Name only this no-search sheet directly from the component's
// existing label; searchable sheets and popovers retain their current
// trigger relationship.
{...(surface.activePresentation === 'bottom-sheet'
? {'aria-label': label}
: listboxLabelProps)}
aria-activedescendant={activeDescendantId}
tabIndex={listboxOwnsKeyboard ? 0 : undefined}
onKeyDown={listboxOwnsKeyboard ? onKeyDown : undefined}
{...stylex.props(styles.listbox)}>
{renderOptions()}
</div>
</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: 'below',
alignment: 'start',
offset: spacingVars['--spacing-1'],
xstyle: styles.popover,
});
}
// 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,
id: triggerId,
// A caller's description is kept alongside the field's own.
'aria-describedby':
[ariaDescribedByProp, ariaDescribedBy].filter(Boolean).join(' ') ||
undefined,
'aria-labelledby': triggerLabelledBy,
'aria-required': isEffectivelyRequired ? 'true' : undefined,
'aria-invalid': status?.type === 'error' ? 'true' : undefined,
'aria-busy': isBusy || undefined,
// Newly forwarded handlers compose component first: the built-in toggle
// and keyboard model always run. `onFocus` keeps its existing caller-first
// order.
onKeyDown: isDisabled
? onKeyDown
: composeEventHandlers(onKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
},
onClick: isDisabled
? event => {
event.preventDefault();
event.stopPropagation();
}
: composeEventHandlers(handleTriggerButtonClick, onClick),
tabIndex: 0,
...stylex.props(
styles.trigger,
isEffectivelyReadOnly && styles.triggerReadOnly,
),
};
if (renderTrigger != null) {
// Anchor-only mode: the caller renders the opener and spreads these props
// on it. No Field, no status, no clear button — the caller owns the
// control; the selector owns the panel, its anchor, and focus return.
const triggerProps: MultiSelectorRenderTriggerProps = {
// Base props reach the caller's control, the primary semantic control
// in this mode; the selector's own wiring below wins over them.
...rest,
'aria-describedby': ariaDescribedByProp,
// Only a caller value is handed back, so a control that names itself
// with its own aria-labelledby before spreading keeps it.
...(ariaLabelledByProp != null
? {'aria-labelledby': ariaLabelledByProp}
: null),
ref: mergeRefs<HTMLElement>(
el => {
popover.triggerRef(el);
triggerRef.current = el;
// A control that takes no focus has nowhere for focus to return to
// when the panel closes, and focus would land on the body — the
// person loses their place in the page. Making it programmatically
// focusable repairs the return without putting it in the tab order,
// which is the caller's decision to make. It does not make the
// control openable from the keyboard: only a real control does
// that, which is what the warning below is for.
if (el != null && !el.matches(FOCUSABLE_SELECTOR)) {
el.tabIndex = -1;
}
},
triggerModality.ref,
ref,
),
id: triggerId,
onClick: isEffectivelyReadOnly
? onClick
: composeEventHandlers(onTriggerClick, onClick),
onKeyDown: isEffectivelyReadOnly
? onKeyDownProp
: composeEventHandlers(onKeyDown, onKeyDownProp),
onFocus: event => {
onFocus?.(event);
surface.onTriggerFocus(event);
},
// A read-only selector has no selection surface to open, so it must
// not advertise one: `spec:AST-011` FR4. Telling a screen-reader user
// "collapsed, has popup" on a control that cannot open leaves them
// pressing Enter with nothing happening and no way to tell the value
// is read-only rather than the control broken. The field path below
// already respects this; the anchor-only path must not regress it.
'aria-haspopup': isEffectivelyReadOnly
? undefined
: surface.activePresentation === 'bottom-sheet'
? 'dialog'
: isGrid
? 'grid'
: 'listbox',
'aria-expanded': isEffectivelyReadOnly ? false : surface.isOpen,
'aria-controls': isEffectivelyReadOnly ? undefined : listboxId,
'aria-busy': isBusy || undefined,
// Withholding the disclosure attributes stops the control lying about
// a panel, but leaves it silent about WHY it does not open. The field
// path says so through its own chrome; the caller's control has none,
// so the state is handed over for it to present.
'aria-readonly': isEffectivelyReadOnly || undefined,
};
return (
<>
{renderTrigger(triggerProps)}
{htmlName != null &&
!isDisabled &&
value.map(v => (
<input key={v} type="hidden" name={htmlName} value={v} />
))}
{selectionSurface}
</>
);
}
const multiSelectorContent = (
<>
<div
ref={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={handleControlBoxClick}
{...pressable}
{...(inputGroup ? inputGroupItemProps : undefined)}
{...mergeProps(
themeProps('multi-selector', {
variant,
size,
status: status?.type ?? null,
disabled: isDisabled ? 'disabled' : null,
readonly: isEffectivelyReadOnly ? 'readonly' : null,
}),
stylex.props(
inputWrapperStyles.base,
styles.triggerContainer,
sizeStyles[size],
variant === 'secondary' && styles.triggerSecondary,
variant === 'ghost' && styles.triggerGhost,
variant !== 'input' && interactionOverlayStyles.backgroundImage,
variant !== 'input' && focusOutlineStyles.focusWithin,
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,
optimisticValue.length === 0 && 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,
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}
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'
: isGrid
? 'grid'
: 'listbox'
}
aria-expanded={isEffectivelyReadOnly ? false : surface.isOpen}
aria-controls={isEffectivelyReadOnly ? undefined : listboxId}
aria-readonly={isEffectivelyReadOnly || undefined}
aria-activedescendant={
!isEffectivelyReadOnly && !hasSearch
? activeDescendantId
: undefined
}
// A disabled trigger keeps its tab stop and says so through
// aria-disabled (`spec:AST-085` FR1); the isDisabled guards in
// useMultiCombobox block every way of opening it.
aria-disabled={isDisabled ? 'true' : undefined}>
<span {...stylex.props(styles.triggerContent)}>
{renderTriggerContent()}
</span>
</button>
{/* A disabled selector submits no value (`spec:AST-085` FR3). */}
{htmlName != null &&
!isDisabled &&
value.map(v => (
<input key={v} type="hidden" name={htmlName} value={v} />
))}
{isBusy && <Spinner size="sm" aria-hidden="true" />}
{hasClear &&
value.length > 0 &&
!isDisabled &&
!isEffectivelyReadOnly && (
<InternalInputClearButton
{...keepOpenProps}
label={t('@astryx.multiSelector.clearAll', {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('multi-selector-indicator-icon', {
state: surface.isOpen ? 'expanded' : 'collapsed',
})}
/>
) : null}
</div>
{selectionSurface}
{showStatusTooltip && statusTooltip.renderTooltip(status?.message ?? '')}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</>
);
if (inputGroup) {
return multiSelectorContent;
}
return (
<Field
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={triggerId}
labelID={ariaLabelledByProp != null ? 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}>
{multiSelectorContent}
</Field>
);
}
MultiSelector.displayName = 'MultiSelector';