An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file Tokenizer.tsx
* @input Uses React, BaseTypeahead, Field, Token, useAnnounce,
* useAdaptivePresentation, and TokenizerBottomSheet (lazy)
* @output Exports Tokenizer multi-select typeahead component
* @position Composed component; forwards DOM ref and exposes focus control via
* handleRef. The `presentation` prop swaps the inline combobox for a field
* box whose trigger opens TokenizerBottomSheet.
*
* SYNC: When modified, update:
* - /packages/core/src/Tokenizer/index.ts
* - /packages/core/src/Tokenizer/TokenizerBottomSheet.tsx (sheet presentation)
* - /apps/storybook/stories/Tokenizer.stories.tsx
* - /packages/cli/assets/templates/blocks/components/Tokenizer/ (showcase blocks)
*/
import React, {
lazy,
Suspense,
use,
useCallback,
useEffect,
useId,
useImperativeHandle,
useMemo,
useRef,
useState,
type ComponentType,
type ReactNode,
type RefObject,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
BusyIndicatorLaneProvider,
createBusyIndicatorLane,
useIsBusy,
type BusyIndicatorLane,
} from '../Typeahead/busyIndicatorLane';
import {TrailingKeyDownContext} from '../Typeahead/trailingKeyDown';
import {CommittedChoicesKeyContext} from '../Typeahead/committedChoicesKey';
import {
type FieldInputBaseProps,
useFieldInputStyling,
} from '../Field/fieldParts';
import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {hasInteractiveAncestor} from '../hooks/useClickableContainer';
import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';
import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
import {
type AdaptivePresentation,
useAdaptivePresentation,
} from '../hooks/useAdaptivePresentation';
import {useIsHydrating} from '../hooks/useIsHydrating';
import {VisuallyHidden} from '../VisuallyHidden';
import {warnOnce} from '../utils/devWarning';
import type {SizeValue} from '../utils/types';
import {BaseTypeahead} from '../Typeahead/BaseTypeahead';
import {useSize} from '../SizeContext/SizeContext';
import {
Field,
InputClearButton,
type InputStatus,
inputWrapperStyles,
inputStatusBorderStyles,
inputStatusHoverShadowStyles,
inputStatusFocusWithinStyles,
} from '../Field';
import {Token} from '../Token';
import {Spinner} from '../Spinner';
import {SpinnerOwnerContext} from '../Spinner/SpinnerOwnerContext';
import {useEndLaneReserve} from './useEndLaneReserve';
import {renderIconSlot, type IconType} from '../Icon';
import {OverflowList} from '../OverflowList';
import {useLayer} from '../Layer/useLayer';
import {useTooltip} from '../Tooltip';
import {useAnnounce} from '../hooks/useAnnounce';
import {
colorVars,
spacingVars,
sizeVars,
typeScaleVars,
} from '../theme/tokens.stylex';
import type {
SearchContext,
SearchableItem,
SearchSource,
} from '../Typeahead/types';
import {composeEventHandlers, mergeProps} from '../utils';
import {joinAriaIDs} from '../utils/inputAria';
import {isFocusDetached} from '../utils/isFocusDetached';
import {themeProps} from '../utils/themeProps';
import type {SheetDraftChange} from '../internal/sheetDraft';
import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
import {useResolvedRequired} from '../hooks/useResolvedRequired';
import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
import {
registerEnglishFallback,
useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Tokenizer/Tokenizer.generated';
import {isRenderable} from '../utils/isRenderable';
registerEnglishFallback(english);
// Re-export status types for convenience
export type {
InputStatus as TokenizerStatus,
InputStatusType as TokenizerStatusType,
} from '../Field';
// =============================================================================
// Types
// =============================================================================
/**
* Change metadata for onChange callback.
*/
export type TokenizerChange<T extends SearchableItem> =
| {item: T; type: 'add'}
| {item: T; type: 'create'}
| {item: T; type: 'remove'}
| {type: 'reorder'};
export type TokenizerSize = 'sm' | 'md' | 'lg';
/**
* Controls overflow behavior when tokens exceed the available width.
* - `'none'`: All tokens wrap normally (default).
* - `'unfocusedInline'`: Shows a single line with "+ N more" when unfocused, expands inline on focus.
* - `'unfocusedLayer'`: Shows a single line with "+ N more" when unfocused, expands as an overlay on focus.
*/
export type TokenizerOverflowBehavior =
'none' | 'unfocusedInline' | 'unfocusedLayer';
/**
* Imperative handle for Tokenizer handleRef.
*/
export interface TokenizerHandle {
/** Focus the typeahead input. */
focus(): void;
/** Blur the typeahead input. */
blur(): void;
}
export interface TokenizerProps<T extends SearchableItem> extends Omit<
FieldInputBaseProps<HTMLInputElement>,
'onChange' | 'onFocus' | 'onBlur' | 'onKeyDown'
> {
/**
* Key handler. Runs after the built-in key handling, so it observes every key
* and cannot cancel navigation, selection, or token editing. It receives keys
* on the combobox input and on the field's other controls (the clear button
* and tokens).
*/
onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
/** Accessible label (required). */
label: string;
/** Visually hide the label. @default false */
isLabelHidden?: boolean;
/** Helper text. */
description?: string;
/** Required field. @default false */
isRequired?: boolean;
/** Optional field. @default false */
isOptional?: boolean;
/** Validation status. */
status?: InputStatus;
/**
* How the status message is placed relative to the input.
* - 'attached': message overlaps directly below the input (bordered treatment)
* - 'detached': message floats below as a separate element with spacing
* - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
* @default 'attached'
*/
statusVariant?: FieldStatusPlacement;
/**
* Icon to display at the start of the input.
* Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
*/
startIcon?: ReactNode | IconType;
/**
* 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 `xstyle`/`className`/`style`.
*/
width?: SizeValue;
/** Label tooltip. */
labelTooltip?: string;
/** Search source providing items. */
searchSource: SearchSource<T>;
/** Currently selected items. */
value: T[];
/**
* The HTML name attribute for form submissions. When set, hidden inputs
* carry one entry per selected item's id under this name.
*/
htmlName?: string;
/** Callback when selection changes. Includes change metadata. */
onChange: (items: T[], change: TokenizerChange<T>) => void;
/** Render function for dropdown items. Default: TypeaheadItem. */
renderItem?: (item: T) => ReactNode;
/** Render function for selected tokens. Default: Token with label + onRemove. */
renderToken?: (item: T, onRemove: () => void) => ReactNode;
/** Max number of selections. */
maxEntries?: number;
/** Placeholder text (shown when no tokens selected). */
placeholder?: string;
/** Show results on focus before typing. @default false */
hasEntriesOnFocus?: boolean;
/** Max dropdown items. @default 10 */
maxMenuItems?: number;
/** Fixed dropdown width in pixels. Never shrinks below the input width. */
menuWidth?: number;
/**
* Minimum query length before the search source is queried. Below it no
* search runs and the menu stays closed — useful for remote sources where
* one or two characters match too much to be worth fetching.
*
* With `hasCreate`, the "Create" entry rides on the search results, so it
* also waits for the threshold.
*
* @default 1
*/
minQueryLength?: number;
/**
* Content shown when the query matched nothing (`spec:AST-056` FR1).
* Takes a `ReactNode`, so a dead end can carry a link or a create row.
*
* The message is announced in a polite live region as the text it renders,
* read from the DOM, so an element is announced as written and anything
* marked `aria-hidden` is left out of both. Content that renders no text
* announces nothing, matching the screen.
*
* `null` means "not given", exactly as `undefined` does, so it falls
* through to the default. Pass an empty string to render nothing.
*
* @default 'No results found'
*/
emptySearchText?: ReactNode;
/**
* Whether the input is disabled. The disabled input keeps its tab stop: it
* is announced as disabled (`aria-disabled`), is read-only, and opens and
* picks nothing. With `tokenOverflowBehavior="unfocusedLayer"` and no
* `disabledMessage`, the input is natively disabled and out of the tab order.
* @default false
*/
isDisabled?: boolean;
/**
* Explains why the tokenizer is disabled. When set together with
* `isDisabled`, the tokenizer shows a tooltip with this text on hover and
* keyboard focus, and the input stays focusable (via `aria-disabled`) so the
* reason is discoverable by keyboard and assistive technology. Input stays
* blocked.
*
* Use this instead of wrapping a disabled tokenizer in `Tooltip`, so the
* reason is attached to the field itself.
*/
disabledMessage?: string;
/** Show clear button (clears all tokens). @default false */
hasClear?: boolean;
/**
* Content to display at the end of the input row.
* Useful for buttons, result counts, or other controls.
*/
endContent?: ReactNode;
/** Auto-focus on mount. @default false */
hasAutoFocus?: boolean;
/** Input size. @default 'md' */
size?: TokenizerSize;
/**
* Controls how tokens overflow when the container is too narrow.
* - `'none'`: Tokens wrap to multiple lines (default).
* - `'unfocusedInline'`: Single line with "+ N more" when unfocused; expands inline on focus.
* - `'unfocusedLayer'`: Single line with "+ N more" when unfocused; expands as overlay on focus.
* @default 'none'
*/
tokenOverflowBehavior?: TokenizerOverflowBehavior;
/**
* Debounce delay in ms before triggering search after typing.
* Set to 0 for synchronous/local search sources that don't need debouncing.
* @default 150
*/
debounceMs?: number;
/**
* Allow users to create new tokens from free-text input.
* When true, pressing Enter with text in the input commits the typed value
* as a new token — even if the search source returned no results.
* @default false
*/
hasCreate?: boolean;
/** Query change callback. */
onChangeQuery?: (query: string) => void;
/** Fires when focus enters the tokenizer from outside. */
onFocus?: (e: React.FocusEvent) => void;
/** Fires when focus leaves the tokenizer entirely. */
onBlur?: (e: React.FocusEvent) => void;
/**
* How the field presents its choices.
* - `'popover'`: the inline combobox with its anchored suggestion menu, on
* every device.
* - `'bottom-sheet'`: a field showing the selected tokens, whose trigger
* opens one tall modal sheet: a search row on top, full-width checkbox rows that
* keep their place while the sheet is open, a create row with
* `hasCreate`, and a footer pinned in every state with a confirmed Clear
* all and Save. The sheet edits a draft: `onChange` fires once, when Save
* commits it, and a swipe, scrim or Escape close of a changed draft asks
* before discarding. Suited to compact touch screens, where the inline
* combobox competes with the software keyboard.
* - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
* otherwise the popover — the same resolution Selector uses. The server
* render and the hydrating render are the popover.
*
* In the sheet presentation the field's box keeps the inline field's box,
* theming target and focus ring, and holds the trigger, the tokens and
* `endContent`. The trigger is the control: `ref`, `id`, `aria-*`, and
* `data-*` reach it. `endContent` renders at the field's
* inline end and `renderToken` renders the field's tokens, as in the inline
* field. `renderItem`, `hasClear` (the sheet has its own Clear all),
* `hasEntriesOnFocus`, `menuWidth`, `tokenOverflowBehavior` (the field
* wraps its tokens), and `hasAutoFocus` have no surface to act on and warn
* once in development. Pass `'popover'` to keep the inline field and those
* props on every device.
* @default 'adaptive'
*/
presentation?: TokenizerPresentation;
/**
* Ref forwarded to the control: the combobox input in the popover
* presentation, the trigger button in the sheet presentation. This type
* keeps its released input element; the component itself also accepts a
* `Ref<HTMLInputElement | HTMLButtonElement>`, the type to use where the
* sheet can present.
*/
ref?: React.Ref<HTMLInputElement>;
/** Imperative handle ref for focus/blur control. */
handleRef?: React.Ref<TokenizerHandle>;
}
/** How Tokenizer presents its choices; see `TokenizerProps.presentation`. */
export type TokenizerPresentation = AdaptivePresentation;
/**
* The props the component accepts: `TokenizerProps`, whose `ref` keeps its
* released input type, with a `ref` that also accepts the sheet
* presentation's trigger button. `TokenizerProps` stays the declared props
* type, so `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>,
* …>` and `ComponentProps<typeof Tokenizer>` keep their released shapes.
*/
type TokenizerAcceptedProps<T extends SearchableItem> = Omit<
TokenizerProps<T>,
'ref'
> & {
/**
* Ref forwarded to the control: the combobox input in the popover
* presentation, the trigger button in the sheet presentation.
*/
ref?: React.Ref<HTMLInputElement | HTMLButtonElement>;
};
// =============================================================================
// Styles
// =============================================================================
// How far the end lane sits from the field's inline-end border, named once
// because the input's reserve is derived from the same value.
const END_LANE_INSET = spacingVars['--spacing-2'];
const TOKEN_ROW_INSET = `calc(${spacingVars['--spacing-1']} - 1px)`;
// Kept in sync with useEndLaneReserve: wrapperWithTokens reads the custom
// property directly, to keep token rows and the input short of the lane.
const END_LANE_RESERVE_VAR = '--_tokenizer-end-lane-reserve';
const styles = stylex.create({
wrapper: {
position: 'relative',
flexWrap: 'wrap',
gap: spacingVars['--spacing-1'],
cursor: {
default: 'text',
':is(:disabled,[aria-disabled="true"])': 'default',
},
height: 'auto',
},
wrapperWithTokens: {
// Override padding for border concentricity: token border-radius
// (radius-1: 4px) sits concentric with wrapper border-radius
// (radius-2: 8px) when inset = radius-2 - radius-1 - border
// = 8 - 4 - 1 = 3px.
paddingBlock: TOKEN_ROW_INSET,
paddingInline: TOKEN_ROW_INSET,
// The end lane is out of flow, so tokens would wrap under it. Every row
// stops short of the measured lane instead; with no lane up the variable
// is absent and this is the ordinary inset.
paddingInlineEnd: `calc(${TOKEN_ROW_INSET} + var(${END_LANE_RESERVE_VAR}, 0px))`,
// Row gap must match paddingBlock so wrapped rows look evenly spaced.
rowGap: TOKEN_ROW_INSET,
},
startIconWithTokens: {
// Restore the default 8px inline-start inset when tokens are present,
// since wrapperWithTokens reduces padding to 3px for border concentricity.
marginInlineStart: `calc(${spacingVars['--spacing-2']} - ${spacingVars['--spacing-1']} + 1px)`,
position: 'relative',
zIndex: 1,
},
token: {
display: 'flex',
flexShrink: 0,
// A renderToken wrapper sizes to its content; cap it at the row so the
// pill inside truncates instead of running past the field.
maxWidth: '100%',
position: 'relative',
zIndex: 1,
},
endSection: {
position: 'absolute',
// Match the field's inline padding (inputWrapperStyles.base uses
// spacing-2) so end content (clear button, resultCount) lines up with
// the text/start-icon inset instead of hugging the border at ~3px.
insetInlineEnd: END_LANE_INSET,
display: 'flex',
alignItems: 'center',
gap: spacingVars['--spacing-2'],
flexShrink: 0,
zIndex: 1,
},
idleSpinner: {
// Hides the Spinner's own box too, which a theme may paint, and covers
// engines without content-visibility. Both keep the box's size.
visibility: 'hidden',
// Skips the ring's rendering, and with it the infinite arc animation,
// while the root keeps its own explicit, themed width and height.
contentVisibility: 'hidden',
},
inputAtMax: {
width: 0,
minWidth: 0,
flex: '0 0 0',
padding: 0,
opacity: 0,
position: 'absolute',
},
inputCompact: {
position: 'relative',
boxSizing: 'border-box',
zIndex: 0,
// The input follows the last token in flow, so a focused empty input's
// caret sits where typed text will start. Empty, it asks only for that
// inset, and only while focused and editable: blurred or read-only (a
// disabled field with a disabledMessage stays focusable), it claims no
// room at all, not even the column gap, so it never grows the field a
// blank row. Typing restores the full editing width, which may wrap.
minWidth: {
default: '40px',
':placeholder-shown': 0,
},
flex: {
default: '1 1 40px',
':placeholder-shown': '1 1 0px',
},
width: 0,
marginInlineStart: {
default: 0,
':placeholder-shown:is(:not(:focus), :read-only)': `calc(-1 * ${spacingVars['--spacing-1']})`,
},
// Restore normal text inset when input follows tokens, since the
// wrapper padding is reduced for border concentricity.
paddingInlineStart: {
default: `calc(${spacingVars['--spacing-2']} - ${spacingVars['--spacing-1']} + 1px)`,
':placeholder-shown:is(:not(:focus), :read-only)': 0,
},
// wrapperWithTokens already keeps the in-flow input short of the lane.
paddingInlineEnd: 0,
},
truncatedWrapper: {
flexWrap: 'nowrap',
overflow: 'hidden',
},
layerPopover: {
// Top-layer popover: match the anchor width exactly so the expanded
// tokenizer looks like an in-place expansion, overlapping the
// placeholder from its top edge.
width: 'anchor-size(width)',
},
overflowText: {
flexShrink: 0,
whiteSpace: 'nowrap',
fontSize: typeScaleVars['--text-supporting-size'],
color: colorVars['--color-text-secondary'],
paddingInline: spacingVars['--spacing-1'],
},
// The sheet presentation's field: the inline field's own control box. A
// button cannot contain controls, so the trigger, the tokens and the end lane
// are siblings in this box. `endContent` and a custom token can then hold their
// own controls. There is no input to type into, so the cursor says "press".
sheetField: {
width: '100%',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
},
// The box carries no aria-disabled: that would expose a caller's operable
// `endContent` as disabled. The trigger carries it, so the box keys its
// disabled cursor on the prop.
sheetFieldDisabled: {
cursor: 'default',
},
// With tokens, the button covers the box beneath them. A tap on a token or
// on empty space then opens the sheet. The box draws the focus ring, so the
// button draws none.
sheetTrigger: {
appearance: 'none',
flexGrow: 1,
alignSelf: 'stretch',
display: 'flex',
alignItems: 'center',
minWidth: 0,
padding: 0,
margin: 0,
borderWidth: 0,
borderStyle: 'none',
backgroundColor: 'transparent',
fontFamily: 'inherit',
fontSize: 'inherit',
lineHeight: 'inherit',
color: 'inherit',
textAlign: 'start',
cursor: {
default: 'pointer',
':is(:disabled,[aria-disabled="true"])': 'default',
},
outline: 'none',
},
sheetTriggerWithTokens: {
position: 'absolute',
inset: 0,
},
// An aria-disabled button gets no system disabled paint in forced colors;
// GrayText is the platform's disabled affordance there. Defaults repeat the
// base values, since StyleX merges per property.
sheetTriggerDisabled: {
borderColor: {
default: colorVars['--color-border-emphasized'],
'@media (forced-colors: active)': 'GrayText',
},
color: {
default: null,
'@media (forced-colors: active)': 'GrayText',
},
},
sheetTriggerPlaceholder: {
color: colorVars['--color-text-secondary'],
// Match the input's text inset so the placeholder sits where the typed
// query would.
paddingInline: spacingVars['--spacing-1'],
},
sheetTriggerPlaceholderDisabled: {
color: {
default: colorVars['--color-text-secondary'],
'@media (forced-colors: active)': 'GrayText',
},
},
// A Token authors its own color, which forced colors replace with
// CanvasText; GrayText marks the tokens of a disabled trigger as disabled.
// The default repeats Token's own default color.
sheetTokenDisabled: {
color: {
default: colorVars['--color-text-primary'],
'@media (forced-colors: active)': 'GrayText',
},
},
});
const sizeStyles = stylex.create({
sm: {minHeight: sizeVars['--size-element-sm']},
md: {minHeight: sizeVars['--size-element-md']},
lg: {minHeight: sizeVars['--size-element-lg']},
});
const endSectionSizeStyles = stylex.create({
sm: {
top: `calc(${sizeVars['--size-element-sm']} / 2 - 1px)`,
transform: 'translateY(-50%)',
},
md: {
top: `calc(${sizeVars['--size-element-md']} / 2 - 1px)`,
transform: 'translateY(-50%)',
},
lg: {
top: `calc(${sizeVars['--size-element-lg']} / 2 - 1px)`,
transform: 'translateY(-50%)',
},
});
const truncatedSizeStyles = stylex.create({
sm: {height: sizeVars['--size-element-sm']},
md: {height: sizeVars['--size-element-md']},
lg: {height: sizeVars['--size-element-lg']},
});
const layerPlaceholderSizeStyles = stylex.create({
sm: {height: sizeVars['--size-element-sm']},
md: {height: sizeVars['--size-element-md']},
lg: {height: sizeVars['--size-element-lg']},
});
// =============================================================================
// Component
// =============================================================================
// Sentinel prefix for creatable items — used to distinguish
// "Create: X" suggestions from real search results.
const CREATABLE_ID_PREFIX = '__xds_create__';
// The touch sheet (BottomSheet, its gestures, the confirmation dialog, and
// the empty state) only renders for the bottom-sheet presentation. Loading it
// on demand keeps it out of pages whose tokenizers stay inline combobox fields
// (`component:Tokenizer` PR6).
// One import promise, shared by the preload and the lazy element: the sheet
// presentation loads its chunk as soon as it is active, so the first press
// does not wait for the network, while nothing of the sheet is rendered until
// a press (`architecture:component-style-authoring` INV7).
const loadTokenizerBottomSheet = async () => import('./TokenizerBottomSheet');
const LazyTokenizerBottomSheet = lazy(async () =>
loadTokenizerBottomSheet().then(module => ({
default: module.TokenizerBottomSheet,
})),
);
/**
* Hosts the lazily loaded sheet. Renders nothing on the server or in the
* render that hydrates server HTML: a lazy component that has not loaded yet
* would leave server markup incomplete and abort hydration. The closed sheet
* has no visible markup, so it first renders right after hydration.
*/
function TokenizerSheetHost<T extends SearchableItem>(
props: TokenizerBottomSheetProps<T>,
) {
const isHydrating = useIsHydrating();
if (isHydrating) {
return null;
}
// `lazy` erases the component's type parameter; the module exports the
// generic component this props type belongs to.
const Sheet = LazyTokenizerBottomSheet as unknown as ComponentType<
TokenizerBottomSheetProps<T>
>;
return (
<Suspense fallback={null}>
<Sheet {...props} />
</Suspense>
);
}
/**
* Multi-select input with token chips and typeahead search.
*
* Composes BaseTypeahead for search and Token for selected items.
* Tokens render inline before the text input. Selecting an item adds a token
* and clears the query. Backspace on empty input removes the last token.
*
* @example
* ```
* const [members, setMembers] = useState<UserItem[]>([]);
* <Tokenizer
* label="Team members"
* searchSource={userSource}
* value={members}
* onChange={(items, change) => {
* setMembers(items);
* if (change.type === 'add') {
* console.log('Added:', change.item.label);
* }
* }}
* placeholder="Search people..."
* />
* <Tokenizer
* label="Tags"
* searchSource={tagSource}
* value={tags}
* onChange={(items) => setTags(items)}
* renderToken={(item, onRemove) => (
* <Token
* label={item.label}
* color={item.auxiliaryData.color}
* onRemove={onRemove}
* />
* )}
* maxEntries={5}
* />
* ```
*/
/**
* The field's inline-end lane: the busy Spinner, then `endContent`, then the
* clear button — pinned to the field's first row while tokens wrap below it.
*
* A separate component so that subscribing to the busy state re-renders THIS
* and nothing else. Subscribed from `Tokenizer`, a search transition
* re-rendered every selected token twice — twenty tokens meant forty renders
* per search for one glyph none of them contain.
*
* Renders nothing when the lane would be empty, so `useEndLaneReserve` sees no
* element, publishes no width, and the input keeps its full content box.
*
* With `hasBusySlot` the Spinner stays mounted while idle, unrendered, not
* animating and out of the accessibility tree, so its box keeps the themed
* Spinner's own size.
* Token rows reserve the lane's measured width, so a Spinner that came and
* went with the search would re-wrap them, and widen a content-sized field,
* on every search.
*/
function EndLane({
lane,
laneRef,
laneXStyle,
loadingLabel,
anchorRef,
hasStaticContent,
hasBusySlot,
children,
}: {
lane: BusyIndicatorLane;
laneRef: (node: HTMLElement | null) => void;
laneXStyle: stylex.StyleXStyles[];
loadingLabel: string;
anchorRef: RefObject<Element | null>;
hasStaticContent: boolean;
hasBusySlot: boolean;
children: ReactNode;
}) {
const isBusy = useIsBusy(lane);
// The search Spinner stays named (family:input-fields FR7) but is not a
// live region; the field announces each search's busy start instead
// (spec:AST-086 FR8).
useBusyAnnouncement(isBusy, loadingLabel, anchorRef);
if (!isBusy && !hasStaticContent && !hasBusySlot) {
return null;
}
return (
<div ref={laneRef} {...stylex.props(laneXStyle)}>
{(isBusy || hasBusySlot) && (
// Named, never live: the tokenizer announces its search.
<SpinnerOwnerContext value={true}>
<Spinner
// Remounts when a search starts, so the ring syncs its phase on
// mount exactly as a newly shown Spinner did before.
key={isBusy ? 'busy' : 'idle'}
size="sm"
aria-label={loadingLabel}
role="img"
aria-hidden={isBusy ? undefined : true}
xstyle={isBusy ? undefined : styles.idleSpinner}
/>
</SpinnerOwnerContext>
)}
{children}
</div>
);
}
// Keep this overload first. TypeScript resolves `ComponentProps<typeof
// Tokenizer>` against the last overload, so that type stays the released
// props. Every call matches this one, so a ref typed for both controls is
// accepted.
export function Tokenizer<T extends SearchableItem>(
props: TokenizerAcceptedProps<T>,
): React.JSX.Element;
export function Tokenizer<T extends SearchableItem>(
props: TokenizerProps<T>,
): React.JSX.Element;
export function Tokenizer<T extends SearchableItem>({
label,
isLabelHidden = false,
description,
isRequired = false,
isOptional = false,
status,
statusVariant = 'attached',
startIcon,
labelTooltip,
searchSource,
value,
onChange,
renderItem,
renderToken,
maxEntries,
placeholder,
hasEntriesOnFocus,
maxMenuItems,
menuWidth,
minQueryLength,
emptySearchText,
isDisabled = false,
htmlName,
disabledMessage,
hasClear = false,
endContent,
hasAutoFocus,
size: sizeProp,
tokenOverflowBehavior = 'none',
debounceMs,
hasCreate = false,
onChangeQuery,
onFocus,
onBlur,
width,
containerXstyle,
containerClassName,
containerStyle,
controlXstyle,
controlClassName,
controlStyle,
ref,
handleRef,
onKeyDown,
presentation = 'adaptive',
id: idProp,
'aria-describedby': ariaDescribedByProp,
'aria-labelledby': ariaLabelledByProp,
...restProps
}: TokenizerProps<T> | TokenizerAcceptedProps<T>): React.JSX.Element {
const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
containerXstyle,
containerClassName,
containerStyle,
});
// A caller's onClick arrives through the base props; the sheet trigger
// composes it with its own open handler rather than letting either win.
const {onClick: callerOnClick, ...restWithoutClick} = rest;
const t = useComponentTranslator();
const size = useSize(sizeProp, 'md');
const generatedInputId = useId();
const inputId = idProp ?? generatedInputId;
const fieldLabelId = useId();
const descriptionId = useId();
const statusMessageId = useId();
// A caller aria-labelledby names the input together with the field's own
// label, which it would otherwise replace.
const fieldLabelledBy =
ariaLabelledByProp != null
? joinAriaIDs(fieldLabelId, ariaLabelledByProp)
: undefined;
const inputRef = useRef<HTMLInputElement>(null);
const wrapperRef = useRef<HTMLDivElement>(null);
// `adaptive` resolves through the policy the selection controls share. An
// open sheet keeps its presentation until it closes. A resolution change
// during a task does not replace the open surface.
const resolvedPresentation = useAdaptivePresentation(presentation);
const [isSheetOpen, setIsSheetOpen] = useState(false);
// Latched for the sheet's lifetime: a sheet stays presented after it closes
// until BottomSheet has run its exit and handed focus back to the trigger.
// Without the latch, `adaptive` resolving to `popover` mid-session (a phone
// turned to landscape) would unmount the sheet and the trigger it returns
// focus to in the same render, dropping focus to the page body
// (`component:Tokenizer` FR16).
const [isSheetPresented, setIsSheetPresented] = useState(false);
const isSheetPresentation =
isSheetOpen || isSheetPresented || resolvedPresentation === 'bottom-sheet';
// Preload the sheet's chunk while the sheet presentation is active, so the
// first press opens without waiting for the network; nothing renders.
useEffect(() => {
if (isSheetPresentation) {
void loadTokenizerBottomSheet();
}
}, [isSheetPresentation]);
const triggerRef = useRef<HTMLButtonElement>(null);
// The sheet's query between presentations: the sheet is in the DOM only
// from a press until its exit completes, and a close the field forces
// keeps the query (FR18). The ref follows every report; the press
// snapshots it into the state the next presentation starts from.
const sheetQueryRef = useRef('');
const [sheetInitialQuery, setSheetInitialQuery] = useState('');
const handleSheetQueryChange = useCallback(
(query: string) => {
sheetQueryRef.current = query;
onChangeQuery?.(query);
},
[onChangeQuery],
);
// Save's one report. The sheet announced each edit as it happened, so
// nothing is announced here; a field that is disabled at Save reports
// nothing.
const handleSheetCommit = useCallback(
(items: T[], change: SheetDraftChange<T>) => {
if (!isDisabled) {
onChange(items, change);
}
},
[isDisabled, onChange],
);
// Set around a focus move the field makes itself — a presentation swap
// handing focus from one control to the other — so the receiving control
// does not report it as focus entering from outside.
const isHandingOffFocusRef = useRef(false);
// Whether the caller has been told focus entered the field in this visit,
// so `onBlur` is never reported without its `onFocus`: in Safari a click
// or tap does not focus a button, so a pointer-opened sheet reports no
// entry, and the one focus the trigger then gets — BottomSheet's return
// focus — is the entry to report.
const hasReportedFocusRef = useRef(false);
// When a presentation swap removes the focused control (the latch
// releasing into the popover, or `adaptive` changing while the sheet is
// closed), the new presentation's control takes the focus over, so focus
// never lands on the page body (`component:Tokenizer` FR16, `spec:AST-085`
// FR4). Both controls' callback refs own the hand-off
// (`architecture:react-component-runtime` INV6): the detaching control
// notes that it held focus — it is still in the document then, so this also
// covers a control focused before hydration (`hasAutoFocus`), which no focus
// event reported — and the attaching control takes it.
const isFocusPendingHandOffRef = useRef(false);
const handOffFocusRef = useCallback((node: HTMLElement | null) => {
if (node == null) {
return;
}
const takesFocus = isFocusPendingHandOffRef.current;
isFocusPendingHandOffRef.current = false;
if (takesFocus && isFocusDetached(node.ownerDocument)) {
isHandingOffFocusRef.current = true;
node.focus();
isHandingOffFocusRef.current = false;
}
return () => {
if (node.ownerDocument.activeElement === node) {
isFocusPendingHandOffRef.current = true;
}
};
}, []);
// The trigger's accessible description names the selected tokens: the
// button's children are tokens whose own content assistive technology
// leaves out of a button's name (`spec:AST-020` FR1).
const triggerTokensId = useId();
// Each rendered token's id, for the trigger's description; the item id is
// an arbitrary string, so it is encoded rather than used as is.
const tokenElementId = (itemId: string) =>
`${triggerTokensId}-${encodeURIComponent(itemId)}`;
// Props that describe the inline combobox have no surface in the sheet
// presentation. Say so once in development rather than dropping them
// silently (`architecture:public-component-api` INV3).
const inertSheetProps = isSheetPresentation
? (
[
['renderItem', renderItem],
['hasClear', hasClear || undefined],
['hasEntriesOnFocus', hasEntriesOnFocus || undefined],
['menuWidth', menuWidth],
['tokenOverflowBehavior', tokenOverflowBehavior],
['hasAutoFocus', hasAutoFocus || undefined],
] as const
)
.filter(([, v]) => v !== undefined && v !== 'none')
.map(([name]) => name)
: [];
const inertSheetPropsKey = inertSheetProps.join(',');
useEffect(() => {
if (inertSheetPropsKey === '') {
return;
}
warnOnce(
`tokenizer:sheet-inert:${inertSheetPropsKey}`,
'Tokenizer',
`\`${inertSheetProps.join('`, `')}\` ${
inertSheetProps.length === 1 ? 'has' : 'have'
} no surface in the bottom-sheet presentation and ${
inertSheetProps.length === 1 ? 'is' : 'are'
} not rendered there. Pass \`presentation="popover"\` to keep the inline field on every device.`,
);
// eslint-disable-next-line @eslint-react/exhaustive-deps -- keyed by the joined names
}, [inertSheetPropsKey]);
// A field that becomes disabled cannot keep its sheet open, and must not
// reopen it when re-enabled (`component:Tokenizer` FR17). Adjusted in the
// render that sees the change, not an effect, so no frame shows both.
const [wasDisabled, setWasDisabled] = useState(isDisabled);
// A sheet that was open when the field became disabled stays mounted,
// closed, so it runs its exit and hands focus back to the trigger; a field
// that is disabled from the start mounts no sheet.
const [keepsSheetWhileDisabled, setKeepsSheetWhileDisabled] = useState(false);
if (isDisabled !== wasDisabled) {
setWasDisabled(isDisabled);
if (isDisabled && isSheetOpen) {
setIsSheetOpen(false);
setKeepsSheetWhileDisabled(true);
}
if (!isDisabled) {
setKeepsSheetWhileDisabled(false);
}
}
// Disabled-reason tooltip. The tooltip listeners attach to the input wrapper
// and the typeahead input stays perceivable via aria-disabled instead of the
// disabled attribute. Input is blocked by the isDisabled guards in
// BaseTypeahead and handleWrapperClick.
const showsDisabledMessage = isDisabled && !!disabledMessage;
const disabledMessageTooltip = useTooltip({
placement: 'above',
// The wrapper is not naturally focusable; focusin bubbles up from the
// input, so always attach focus listeners.
focusTrigger: 'always',
isEnabled: showsDisabledMessage,
});
// The inline field's wrapper holds every control a swap removes with the
// input — a token's Remove button, the inline Clear all — so it notes focus
// anywhere inside it for the hand-off above. It also anchors the
// disabled-message tooltip, whose handlers are gated internally by
// isEnabled, so attaching unconditionally is safe.
const tooltipAnchorRef = disabledMessageTooltip.ref;
const wrapperCallbackRef = useCallback(
(el: HTMLDivElement | null) => {
wrapperRef.current = el;
tooltipAnchorRef(el);
if (el == null) {
return;
}
return () => {
if (el.contains(el.ownerDocument.activeElement)) {
isFocusPendingHandOffRef.current = true;
}
wrapperRef.current = null;
tooltipAnchorRef(null);
};
},
[tooltipAnchorRef],
);
// A swap also removes `endContent` and a custom token's remove. If focus is
// in the box when it detaches, the new control takes it. The box also anchors
// the disabled-message tooltip.
const sheetFieldCallbackRef = useCallback(
(el: HTMLDivElement | null) => {
tooltipAnchorRef(el);
if (el == null) {
return;
}
return () => {
if (el.contains(el.ownerDocument.activeElement)) {
isFocusPendingHandOffRef.current = true;
}
tooltipAnchorRef(null);
};
},
[tooltipAnchorRef],
);
// The sheet presentation has no input; the public ref reaches the trigger,
// the control it stands for (`family:input-fields` FR10). The
// disabled-message tooltip anchors to the field box around it, as it
// anchors to the inline field's wrapper.
const triggerMergedRef = useMergedRefs<HTMLButtonElement>(
triggerRef,
ref as React.Ref<HTMLButtonElement> | undefined,
handOffFocusRef,
);
useImperativeHandle(handleRef, () => ({
focus() {
(isSheetPresentation ? triggerRef : inputRef).current?.focus();
},
blur() {
(isSheetPresentation ? triggerRef : inputRef).current?.blur();
},
}));
// Focus-within state for overflow truncation
// Reported by BaseTypeahead so the indicator can live in this field's own
// end lane, beside endContent and the clear button.
// The base owns the busy state; this field only paints it. Held in a store
// rather than this component's state — held here, a search transition
// re-rendered every selected token twice, for a glyph no token contains.
// See busyIndicatorLane.tsx.
const busyLane = useMemo(() => createBusyIndicatorLane(), []);
// What sits in the end lane varies most here — a spinner, arbitrary
// `endContent`, a clear button, or all three — so its width is measured
// rather than assumed, and the input reserves it.
const [laneRef, laneReserve] = useEndLaneReserve(END_LANE_INSET);
// `laneRef` publishes the lane's width, so token rows and the placeholder
// stop short of it. `sheetLaneRef` tells a tap in the lane from a tap on the
// field.
const sheetLaneRef = useRef<HTMLDivElement | null>(null);
const sheetLaneMergedRef = useMergedRefs<HTMLDivElement>(
laneRef,
sheetLaneRef,
);
// A composing component can lock tokens (PowerSearch's read-only filters
// and read-only field). No remove path removes a locked token.
const isItemRemovable = use(TokenizerItemRemovableContext);
const canRemoveItem = useCallback(
(item: T) => isItemRemovable?.(item) ?? true,
[isItemRemovable],
);
// The half of the lane's contents this component knows about. The busy half
// is the leaf's own business — folding it in here would mean reading the
// busy state during this render, which is exactly the re-render the store
// exists to avoid.
const hasClearButton = hasClear && !isDisabled && value.some(canRemoveItem);
const hasStaticEndLane = Boolean(endContent || hasClearButton);
const [isFocusedWithin, setIsFocusedWithin] = useState(false);
const isTruncated =
!isFocusedWithin && tokenOverflowBehavior !== 'none' && value.length > 0;
// Layer for unfocusedLayer mode — promotes expanded content to the top layer
// so it isn't clipped by ancestor overflow.
const isLayerMode = tokenOverflowBehavior === 'unfocusedLayer';
const layer = useLayer({mode: 'context'});
const layerContentRef = useRef<HTMLDivElement>(null);
// Anchor the layer to the placeholder element
const placeholderRef = useCallback(
(el: HTMLElement | null) => {
if (isLayerMode) {
layer.ref(el);
}
},
[isLayerMode, layer],
);
// For the layer variant, focus can be in either the placeholder or the
// popover content. We track both to decide when focus has truly left.
const isFocusInTokenizer = useCallback(
(target: Node | null): boolean => {
if (!target) {
return false;
}
if (wrapperRef.current?.contains(target)) {
return true;
}
if (layerContentRef.current?.contains(target)) {
return true;
}
// Also check the popover element itself (the layer wrapper)
const popoverEl = document.getElementById(layer.id);
if (popoverEl?.contains(target)) {
return true;
}
return false;
},
[layer.id],
);
const handleFocusCapture = useCallback(
(e: React.FocusEvent) => {
const comingFromOutside = !isFocusInTokenizer(e.relatedTarget);
setIsFocusedWithin(true);
if (isLayerMode) {
layer.show();
}
if (comingFromOutside) {
if (!isHandingOffFocusRef.current) {
hasReportedFocusRef.current = true;
onFocus?.(e);
}
// Redirect to the input so the user doesn't have to tab through
// every token remove button.
if (e.target !== inputRef.current) {
inputRef.current?.focus();
}
}
},
[isLayerMode, layer, isFocusInTokenizer, onFocus],
);
const handleBlurCapture = useCallback(
(e: React.FocusEvent) => {
if (!isFocusInTokenizer(e.relatedTarget)) {
hasReportedFocusRef.current = false;
// Focus left the field: no hand-off is owed any more.
isFocusPendingHandOffRef.current = false;
setIsFocusedWithin(false);
onBlur?.(e);
if (isLayerMode) {
layer.hide();
}
}
},
[isLayerMode, layer, isFocusInTokenizer, onBlur],
);
const isAtMax = maxEntries != null && value.length >= maxEntries;
// Filter out already-selected items from search results. Keyed by the ids,
// not the array: an equal new `value` array on every render keeps the
// filtered source, and the key tells an open list to reload only when the
// committed values really change (FR13).
const selectedIdKey = useMemo(
() => JSON.stringify(value.map(item => item.id)),
[value],
);
const selectedIds = useMemo(
() => new Set<string>(JSON.parse(selectedIdKey) as string[]),
[selectedIdKey],
);
// Tells an open list to reload when the committed values change, or to
// close once they reach the limit (FR13, FR15).
const committedChoices = useMemo(
() => ({key: selectedIdKey, ids: selectedIds, isAtLimit: isAtMax}),
[selectedIdKey, selectedIds, isAtMax],
);
// Selected labels, lowercased, for the Create entry's duplicate check. The
// typed text is a label, not an id: real selections usually carry an opaque
// id (`usr_123` under the label "Alice"), so comparing the text against ids
// alone misses an already-tokenized label — and the search results cannot
// catch it either, because filteredSource has already removed the selected
// item from them. The result was a "Create Alice" entry that, when picked,
// added a second "Alice" token under a different id.
const selectedLabels = useMemo(
() => new Set(value.map(item => item.label.toLowerCase())),
[value],
);
const filteredSource: SearchSource<T> = useMemo(
() => ({
// Committed values leave every list, partial or final
// (component:Tokenizer FR13, spec:AST-092 FR1).
search: async (query: string, context?: SearchContext<T>) => {
const results = await searchSource.search(
query,
context && {
update: items =>
context.update(items.filter(item => !selectedIds.has(item.id))),
},
);
return results.filter(item => !selectedIds.has(item.id));
},
bootstrap: async () => {
const results = await searchSource.bootstrap();
return results.filter(item => !selectedIds.has(item.id));
},
// BaseTypeahead cancels this wrapper, not the caller's source. Pass the
// call on, so the caller can stop its request.
cancel: () => searchSource.cancel?.(),
}),
[searchSource, selectedIds],
);
/**
* The "Create X" entry. It is derived from the typed text, not fetched for
* it, so it is offered through `__queryEntries` rather than appended to the
* search results — which is what keeps it available when the query is too
* short to search. `minQueryLength` is there to avoid a fetch too broad to
* be worth making; creating `QA` costs no fetch, and a field that can
* create it should not stop being able to.
*/
const createEntries = useCallback(
(query: string, results: T[]): T[] => {
const trimmed = query.trim();
if (!hasCreate || trimmed === '') {
return [];
}
const alreadyExists =
selectedIds.has(trimmed) ||
selectedLabels.has(trimmed.toLowerCase()) ||
results.some(
item => item.label.toLowerCase() === trimmed.toLowerCase(),
);
if (alreadyExists) {
return [];
}
return [
{
id: `${CREATABLE_ID_PREFIX}${trimmed}`,
label: t('@astryx.tokenizer.create', {value: trimmed}),
auxiliaryData: {__createdValue: trimmed},
} as unknown as T,
];
},
[hasCreate, selectedIds, selectedLabels, t],
);
const emptySource: SearchSource<T> = useMemo(
() => ({
search: async () => [],
bootstrap: async () => [],
}),
[],
);
// Announce token add/remove politely via a persistent live region.
// Announce token add/remove politely. `useAnnounce` follows where this
// call is made (`spec:AST-086` FR14): the inline field's words go to the
// shared channel, or into the modal that encloses the field. The sheet's
// own changes are announced from inside the sheet, where FR14 routes them
// into the sheet's dialog; the handlers below stay silent for those.
const announce = useAnnounce();
// Handle adding an item — detect creatable synthetic items
const handleAdd = useCallback(
(item: T | null, options?: {silent?: boolean}): boolean => {
if (isDisabled || !item) {
return false;
}
if (isAtMax) {
return false;
}
// Detect "Create: X" synthetic items from the creatable source
if (
hasCreate &&
typeof item.id === 'string' &&
item.id.startsWith(CREATABLE_ID_PREFIX)
) {
const createdValue = item.id.slice(CREATABLE_ID_PREFIX.length);
// Same domain fix as createEntries: the created value names itself by
// label, so a selection carrying an opaque id with that label is also a
// duplicate, not just one whose id happens to equal the text.
if (
selectedIds.has(createdValue) ||
selectedLabels.has(createdValue.toLowerCase())
) {
return false;
}
const base = {id: createdValue, label: createdValue};
const realItem = base as T;
const newItems = [...value, realItem];
onChange(newItems, {item: realItem, type: 'create'});
if (!options?.silent) {
announce(t('@astryx.tokenizer.tokenAdded', {label: createdValue}));
}
return true;
}
if (selectedIds.has(item.id)) {
return false;
}
const newItems = [...value, item];
onChange(newItems, {item, type: 'add'});
if (!options?.silent) {
announce(t('@astryx.tokenizer.tokenAdded', {label: item.label}));
}
return true;
},
[
value,
onChange,
isDisabled,
isAtMax,
selectedIds,
selectedLabels,
hasCreate,
announce,
t,
],
);
// Handle removing an item. Single removal path: both Backspace on an empty
// input and the per-token remove buttons route through here, so the
// announcement covers both.
const handleRemove = useCallback(
(item: T, options?: {silent?: boolean}): boolean => {
if (isDisabled || !canRemoveItem(item)) {
return false;
}
const newItems = value.filter(v => v.id !== item.id);
onChange(newItems, {item, type: 'remove'});
if (!options?.silent) {
announce(t('@astryx.tokenizer.tokenRemoved', {label: item.label}));
}
inputRef.current?.focus();
return true;
},
[value, onChange, isDisabled, canRemoveItem, announce, t],
);
// A composing component that words its own Clear all (PowerSearch) provides
// its words; otherwise the field's own (component:Tokenizer AR7).
const clearAllMessage =
use(TokenizerClearAllMessageContext) ?? t('@astryx.tokenizer.allRemoved');
const handleClearAll = useCallback(
(options?: {silent?: boolean}) => {
const removedItems = value.filter(canRemoveItem);
if (isDisabled || removedItems.length === 0) {
return;
}
// onChange names one item. Clear all names the last one it removes.
const lastRemovedItem = removedItems[removedItems.length - 1];
onChange(
value.filter(item => !canRemoveItem(item)),
{item: lastRemovedItem, type: 'remove'},
);
// Focus moves to the input, so the emptied selection is announced, in
// the sheet's words (WCAG 4.1.3). The sheet announces its own Clear all.
if (!options?.silent) {
announce(clearAllMessage);
}
inputRef.current?.focus();
},
[value, onChange, isDisabled, canRemoveItem, announce, clearAllMessage],
);
// Handle backspace on empty input — remove last token
const handleKeyDown = useCallback(
(e: React.KeyboardEvent<HTMLInputElement>) => {
if (
e.key === 'Backspace' &&
e.currentTarget.value === '' &&
value.length > 0
) {
e.preventDefault();
const lastItem = value[value.length - 1];
handleRemove(lastItem);
}
},
[value, handleRemove],
);
// Click wrapper to focus input
const handleWrapperClick = useCallback(() => {
if (!isDisabled) {
if (isLayerMode) {
// The input always lives in the popover. Show it and focus.
layer.show();
setIsFocusedWithin(true);
// The input is already mounted in the popover (not conditional),
// so we can focus it directly.
inputRef.current?.focus();
} else {
inputRef.current?.focus();
}
}
}, [isDisabled, isLayerMode, layer]);
const ariaDescribedBy =
[
description ? descriptionId : null,
status?.message ? statusMessageId : null,
showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
]
.filter(Boolean)
.join(' ') || undefined;
const sizeStyle = sizeStyles[size];
// Render tokens
const tokens = value.map(item => {
const onRemoveItem = () => handleRemove(item);
if (renderToken) {
return (
<span key={item.id} {...stylex.props(styles.token)}>
{renderToken(item, onRemoveItem)}
</span>
);
}
return (
<Token
key={item.id}
label={item.label}
size={size}
onRemove={isDisabled || !canRemoveItem(item) ? undefined : onRemoveItem}
isDisabled={isDisabled}
xstyle={styles.token}
/>
);
});
// Self-authored position styles (positioning: 'custom' below): explicit
// anchor() insets pin the expanded layer over the field itself.
// `left` is physical, so this popover does not yet mirror in RTL —
// known follow-up from #3389.
const popoverOverrideStyle: React.CSSProperties = {
top: 'anchor(top)',
left: 'anchor(start)',
};
const wrapperContent = (
<div
ref={wrapperCallbackRef}
role="group"
aria-label={label}
onClick={handleWrapperClick}
onFocusCapture={handleFocusCapture}
onBlurCapture={handleBlurCapture}
// Keys on the field's other controls (clear button, tokens) reach a
// consumer onKeyDown here; keys on the input reach it through
// TrailingKeyDownContext after the built-in handling.
onKeyDown={event => {
if (event.target !== inputRef.current) {
onKeyDown?.(event);
}
}}
{...mergeProps(
themeProps('tokenizer', {
size,
status: status?.type,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
styles.wrapper,
value.length > 0 && styles.wrapperWithTokens,
isTruncated ? truncatedSizeStyles[size] : sizeStyle,
isTruncated && styles.truncatedWrapper,
isDisabled && inputWrapperStyles.disabled,
isDisabled && inputDisabledFocusStyles.nestedRing,
status && inputStatusBorderStyles[status.type],
status && !isDisabled && inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{isRenderable(startIcon as ReactNode) && (
<span {...stylex.props(value.length > 0 && styles.startIconWithTokens)}>
{renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
</span>
)}
{isTruncated ? (
<OverflowList
gap={1}
behavior="observeParent"
overflowRenderer={items => (
<span {...stylex.props(styles.overflowText)}>
+{items.length} more
</span>
)}>
{tokens}
</OverflowList>
) : (
tokens
)}
{/* The base reports its busy state through this lane, so the
indicator lands in the end controls below beside the clear
button rather than as a second one inside the base. */}
<BusyIndicatorLaneProvider value={busyLane}>
<TrailingKeyDownContext value={onKeyDown}>
<CommittedChoicesKeyContext value={committedChoices}>
<BaseTypeahead
{...rest}
ref={useMergedRefs(
inputRef,
// The ref type admits the sheet's trigger too; in this
// presentation it receives the input.
ref as React.Ref<HTMLInputElement> | undefined,
handOffFocusRef,
)}
searchSource={isAtMax ? emptySource : filteredSource}
value={null}
onChange={handleAdd}
renderItem={renderItem}
// A space keeps :placeholder-shown available as the CSS-only empty
// query signal without painting placeholder text beside tokens.
placeholder={value.length === 0 ? placeholder : ' '}
hasEntriesOnFocus={isAtMax ? false : hasEntriesOnFocus}
maxMenuItems={maxMenuItems}
menuWidth={menuWidth}
minQueryLength={minQueryLength}
emptySearchText={emptySearchText}
isDisabled={isDisabled}
// A disabled field keeps its tab stop (spec:AST-085 FR1), except in
// unfocusedLayer mode, where the input lives in a layer a disabled
// field never opens; how that field takes focus is undecided.
isFocusableDisabled={
showsDisabledMessage || (isDisabled && !isLayerMode)
}
hasAutoFocus={hasAutoFocus}
inputId={inputId}
ariaLabelledBy={fieldLabelledBy}
ariaDescribedBy={
[ariaDescribedByProp, ariaDescribedBy]
.filter(Boolean)
.join(' ') || undefined
}
onChangeQuery={onChangeQuery}
// The resolved required state reaches the combobox, also when a
// FormLayout default hides the visible marker (component:FormLayout
// FR5, AR2).
aria-required={isEffectivelyRequired || rest['aria-required']}
// An error status is exposed on the combobox as on every other field
// (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
// aria-required / aria-invalid still applies.
aria-invalid={status?.type === 'error' || rest['aria-invalid']}
__queryEntries={createEntries}
debounceMs={debounceMs}
onKeyDown={handleKeyDown}
anchorRef={wrapperRef}
size={size}
inputXStyle={[
isAtMax || isTruncated
? styles.inputAtMax
: value.length > 0
? styles.inputCompact
: undefined,
// With tokens, wrapperWithTokens reserves the lane for every row.
// This rule is only for an empty Tokenizer; it still resolves to
// zero until the lane publishes a width.
!(isAtMax || isTruncated || value.length > 0) && laneReserve,
]}
/>
</CommittedChoicesKeyContext>
</TrailingKeyDownContext>
</BusyIndicatorLaneProvider>
{htmlName != null &&
!isDisabled &&
value.map(item => (
<input key={item.id} type="hidden" name={htmlName} value={item.id} />
))}
<EndLane
lane={busyLane}
laneRef={laneRef}
laneXStyle={[styles.endSection, endSectionSizeStyles[size]]}
loadingLabel={t('@astryx.typeahead.loading')}
anchorRef={wrapperRef}
hasStaticContent={hasStaticEndLane}
// Wherever a search can run beside tokens: enabled and below
// maxEntries. A collapsed overflow row keeps it too, since a search
// started while focused can settle after focus leaves.
hasBusySlot={value.length > 0 && !isDisabled && !isAtMax}>
{endContent}
{hasClearButton && (
<InputClearButton
label={t('@astryx.tokenizer.clearAll')}
onClick={e => {
e.stopPropagation();
handleClearAll();
}}
/>
)}
</EndLane>
</div>
);
// A `renderToken` token's own remove control in the sheet field removes at
// once, as it does in the inline field. Its control leaves with it, so
// focus moves to the trigger.
const handleSheetTokenRemove = (item: T) => {
if (handleRemove(item)) {
triggerRef.current?.focus();
}
};
// A tap on a token, the placeholder or empty space opens the sheet, as a tap
// on the trigger does. The trigger, `endContent` and a custom token's
// controls handle their own clicks.
const handleSheetFieldClick = (event: React.MouseEvent<HTMLDivElement>) => {
const trigger = triggerRef.current;
const target = event.target;
if (trigger == null || !(target instanceof Element)) {
return;
}
if (
trigger.contains(target) ||
sheetLaneRef.current?.contains(target) ||
hasInteractiveAncestor(target, event.currentTarget)
) {
return;
}
trigger.click();
};
// The caller's onFocus and onBlur report focus entering and leaving the whole
// box, as for the inline wrapper. A move between the trigger, `endContent`
// and a custom token's controls stays inside the field.
const handleSheetFieldFocus = (event: React.FocusEvent<HTMLDivElement>) => {
// BottomSheet focuses the trigger only after its exit completes; that
// focus is the signal that the retained sheet can leave. If the
// resolution moved to the popover meanwhile, the inline input takes the
// focus over once it mounts.
const isReturningFromSheet =
(event.target as EventTarget) === triggerRef.current &&
!isSheetOpen &&
isSheetPresented;
if (isReturningFromSheet) {
setIsSheetPresented(false);
}
const relatedTarget = event.relatedTarget;
if (
relatedTarget instanceof Node &&
event.currentTarget.contains(relatedTarget)
) {
return;
}
// Focus that returns from the field's own sheet, or that a presentation swap
// hands over, does not enter from outside. The caller's onFocus stays quiet
// for it (`family:input-fields` FR10).
const isInsideTheField =
(isReturningFromSheet && hasReportedFocusRef.current) ||
isHandingOffFocusRef.current;
if (!isInsideTheField) {
hasReportedFocusRef.current = true;
onFocus?.(event);
}
};
const handleSheetFieldBlur = (event: React.FocusEvent<HTMLDivElement>) => {
// Focus moving into the sheet, or to another control in the box, is
// still the field's. Only a blur to somewhere else reports.
const relatedTarget = event.relatedTarget;
if (
isSheetOpen ||
(relatedTarget instanceof Node &&
event.currentTarget.contains(relatedTarget))
) {
return;
}
hasReportedFocusRef.current = false;
isFocusPendingHandOffRef.current = false;
onBlur?.(event);
};
let tokenizerContent: ReactNode;
if (isSheetPresentation) {
tokenizerContent = (
<>
<div
ref={sheetFieldCallbackRef}
onClick={handleSheetFieldClick}
onFocus={handleSheetFieldFocus}
onBlur={handleSheetFieldBlur}
{...mergeProps(
themeProps('tokenizer', {
size,
status: status?.type,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
styles.wrapper,
styles.sheetField,
isDisabled && styles.sheetFieldDisabled,
// The field keeps the inline field's height for its size step,
// as Selector's bottom-sheet trigger does; the sheet's own rows
// and search field carry the touch-sized targets.
sizeStyles[size],
value.length > 0 && styles.wrapperWithTokens,
isDisabled && inputWrapperStyles.disabled,
isDisabled && styles.sheetTriggerDisabled,
status && inputStatusBorderStyles[status.type],
status &&
!isDisabled &&
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{isRenderable(startIcon as ReactNode) && (
<span
{...stylex.props(value.length > 0 && styles.startIconWithTokens)}>
{renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
</span>
)}
<button
// The field-level pass-through props (`data-*`, `aria-*`) were typed
// for the inline input; here the control is a button.
{...(restWithoutClick as React.ButtonHTMLAttributes<HTMLButtonElement>)}
ref={triggerMergedRef}
type="button"
id={inputId}
aria-labelledby={fieldLabelledBy}
aria-haspopup="dialog"
aria-expanded={isSheetOpen}
aria-disabled={isDisabled || undefined}
// The description follows the inline input's order: the caller's
// ids, the field description, the status message, then the
// disabled reason (`spec:AST-085` FR5). The hidden count and the
// token labels follow, each by id. The algorithm separates
// referenced elements, so no list punctuation is written here
// (AR6). A default token is display-only and is its own label. A
// custom token can hold controls, so a hidden copy of its item
// label stands in.
aria-describedby={
[
ariaDescribedByProp,
ariaDescribedBy,
value.length > 0 ? triggerTokensId : null,
...value.map(item => tokenElementId(item.id)),
]
.filter(Boolean)
.join(' ') || undefined
}
// The open runs first and the caller's onClick after it, as the
// inline input composes its click: a caller observes the click but
// cannot cancel the field's own handling
// (`family:input-fields` FR10).
onClick={composeEventHandlers<React.MouseEvent<HTMLButtonElement>>(
() => {
if (isDisabled) {
return;
}
setIsSheetPresented(true);
setSheetInitialQuery(sheetQueryRef.current);
setIsSheetOpen(true);
},
// Typed for the input by the base props; here the control is the
// trigger button, and the handler only reads the event.
callerOnClick as unknown as
React.MouseEventHandler<HTMLButtonElement> | undefined,
)}
onKeyDown={onKeyDown}
{...stylex.props(
styles.sheetTrigger,
value.length > 0 && styles.sheetTriggerWithTokens,
// With no token the placeholder stops short of the end lane, as
// the inline input's text does.
value.length === 0 && laneReserve,
)}>
{value.length === 0 && (
<span
{...stylex.props(
styles.sheetTriggerPlaceholder,
isDisabled && styles.sheetTriggerPlaceholderDisabled,
)}>
{placeholder ?? ''}
</span>
)}
</button>
{value.map(item =>
renderToken ? (
<span key={item.id} {...stylex.props(styles.token)}>
{renderToken(item, () => handleSheetTokenRemove(item))}
</span>
) : (
<Token
key={item.id}
id={tokenElementId(item.id)}
label={item.label}
size={size}
isDisabled={isDisabled}
xstyle={isDisabled ? styles.sheetTokenDisabled : undefined}
/>
),
)}
{isRenderable(endContent) && (
<div
ref={sheetLaneMergedRef}
{...stylex.props(styles.endSection, endSectionSizeStyles[size])}>
{endContent}
</div>
)}
</div>
{value.length > 0 && (
<VisuallyHidden id={triggerTokensId}>
{t('@astryx.tokenizer.selectedCount', {count: value.length})}
</VisuallyHidden>
)}
{renderToken != null &&
value.map(item => (
<span key={item.id} id={tokenElementId(item.id)} hidden>
{item.label}
</span>
))}
{/* Form carriers, gated exactly as the inline branch gates its own: a
disabled field submits nothing. */}
{htmlName != null &&
!isDisabled &&
value.map(item => (
<input
key={item.id}
type="hidden"
name={htmlName}
value={item.id}
/>
))}
{/* Mounted from the press until the sheet's exit has completed and
focus is back on the trigger (`isSheetPresented`): at rest the
field renders its trigger alone — no closed dialog, rows, search
field or confirmation in the DOM (INV7). */}
{(isSheetOpen || isSheetPresented) &&
(!isDisabled || keepsSheetWhileDisabled) && (
<TokenizerSheetHost
isOpen={isSheetOpen}
onOpenChange={setIsSheetOpen}
finalFocusRef={triggerRef}
initialQuery={sheetInitialQuery}
label={label}
searchSource={searchSource}
value={value}
maxEntries={maxEntries}
hasCreate={hasCreate}
maxMenuItems={maxMenuItems ?? 10}
minQueryLength={minQueryLength ?? 1}
debounceMs={debounceMs ?? 150}
emptySearchText={emptySearchText}
onCommit={handleSheetCommit}
onChangeQuery={handleSheetQueryChange}
/>
)}
</>
);
} else if (isLayerMode) {
const placeholderSizeStyle = layerPlaceholderSizeStyles[size];
tokenizerContent = (
<>
<div
ref={placeholderRef}
onClick={handleWrapperClick}
{...mergeProps(
themeProps('tokenizer', {
size,
status: status?.type,
disabled: isDisabled ? 'disabled' : null,
}),
stylex.props(
inputWrapperStyles.base,
inputWrapperStyles.textField,
styles.wrapper,
value.length > 0 && styles.wrapperWithTokens,
placeholderSizeStyle,
isTruncated && styles.truncatedWrapper,
isDisabled && inputWrapperStyles.disabled,
status && inputStatusBorderStyles[status.type],
status &&
!isDisabled &&
inputStatusHoverShadowStyles[status.type],
status && inputStatusFocusWithinStyles[status.type],
controlXstyle,
),
controlClassName,
controlStyle,
)}>
{isTruncated && (
<>
{isRenderable(startIcon as ReactNode) &&
renderIconSlot(startIcon, {
size: 'sm',
color: 'secondary',
})}
<OverflowList
gap={1}
behavior="observeParent"
overflowRenderer={items => (
<span {...stylex.props(styles.overflowText)}>
+{items.length} more
</span>
)}>
{tokens}
</OverflowList>
</>
)}
</div>
{layer.render(
<div
ref={layerContentRef}
onFocusCapture={handleFocusCapture}
onBlurCapture={handleBlurCapture}>
{wrapperContent}
</div>,
{
positioning: 'custom',
xstyle: styles.layerPopover,
style: popoverOverrideStyle,
},
)}
</>
);
} else {
tokenizerContent = wrapperContent;
}
return (
<Field
{...container}
label={label}
isLabelHidden={isLabelHidden}
description={description}
inputID={inputId}
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={statusVariant}
labelTooltip={labelTooltip}
width={width}>
{tokenizerContent}
{showsDisabledMessage &&
disabledMessageTooltip.renderTooltip(disabledMessage)}
</Field>
);
}
Tokenizer.displayName = 'Tokenizer';