Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(core): add ComplexSelector (#4659)

Cindy Zhangef91556d338e
diff --git a/.changeset/complex-selector.md b/.changeset/complex-selector.md
new file mode 100644
index 0000000000..3851361cc5
--- /dev/null
+++ b/.changeset/complex-selector.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] ComplexSelector: add a rich custom selector shell with accessible button/popover behavior, async change actions, and optional grid keyboard navigation.
+@cixzhang
diff --git a/apps/storybook/stories/ComplexSelector.stories.tsx b/apps/storybook/stories/ComplexSelector.stories.tsx
new file mode 100644
index 0000000000..797fb63bea
--- /dev/null
+++ b/apps/storybook/stories/ComplexSelector.stories.tsx
@@ -0,0 +1,730 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {useEffect, useMemo, useState} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';
+import {Button} from '@astryxdesign/core/Button';
+import {Text} from '@astryxdesign/core/Text';
+import {TextInput} from '@astryxdesign/core/TextInput';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Token} from '@astryxdesign/core/Token';
+import {TreeList, type TreeListItemData} from '@astryxdesign/core/TreeList';
+import {useGridFocus} from '@astryxdesign/core/hooks';
+import {
+ borderVars,
+ colorVars,
+ durationVars,
+ easeVars,
+ fontWeightVars,
+ radiusVars,
+ shadowVars,
+ spacingVars,
+ typeScaleVars,
+} from '@astryxdesign/core/theme/tokens.stylex';
+
+const GRID_CELL_SELECTOR = '[role="gridcell"]';
+
+const meta: Meta<typeof ComplexSelector> = {
+ title: 'Core/ComplexSelector',
+ component: ComplexSelector,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'centered',
+ docs: {
+ description: {
+ component:
+ 'A high-level selector shell for rich custom content. The component owns the field, trigger, popover, focus restore, and async changeAction flow while consumers render the content. Custom content should use Astryx focus hooks where appropriate and be evaluated against WCAG 2.2.',
+ },
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof ComplexSelector>;
+
+type Fruit = 'Apple' | 'Pear' | 'Peach' | 'Plum';
+type Ripeness = 'Crisp' | 'Tender' | 'Juicy' | 'Peak';
+
+type FruitValue = {
+ fruit: Fruit;
+ ripeness: Ripeness;
+};
+
+const fruits: Array<{
+ id: Fruit;
+ emoji: string;
+ description: string;
+}> = [
+ {id: 'Apple', emoji: '🍎', description: 'Bright and balanced'},
+ {id: 'Pear', emoji: '🍐', description: 'Soft floral sweetness'},
+ {id: 'Peach', emoji: 'πŸ‘', description: 'Round summer flavor'},
+ {id: 'Plum', emoji: '🟣', description: 'Jammy and tart'},
+];
+
+const ripenessLevels: Array<{
+ id: Ripeness;
+ shortLabel: string;
+ description: string;
+}> = [
+ {id: 'Crisp', shortLabel: 'C', description: 'Snappy bite'},
+ {id: 'Tender', shortLabel: 'T', description: 'Easy bite'},
+ {id: 'Juicy', shortLabel: 'J', description: 'Full juice'},
+ {id: 'Peak', shortLabel: 'P', description: 'Most intense'},
+];
+
+type DestinationValue = {
+ id: string;
+ label: string;
+ path: string;
+};
+
+interface DestinationNode {
+ id: string;
+ label: string;
+ path: string;
+ kind: 'folder' | 'space' | 'team';
+ isExpanded?: boolean;
+ children?: DestinationNode[];
+}
+
+const destinationTree: DestinationNode[] = [
+ {
+ id: 'workspace',
+ label: 'Workspace',
+ path: '/Workspace',
+ kind: 'space',
+ children: [
+ {
+ id: 'workspace-research',
+ label: 'Research',
+ path: '/Workspace/Research',
+ kind: 'folder',
+ children: [
+ {
+ id: 'workspace-research-field-notes',
+ label: 'Field notes',
+ path: '/Workspace/Research/Field notes',
+ kind: 'folder',
+ },
+ {
+ id: 'workspace-research-interviews',
+ label: 'Interviews',
+ path: '/Workspace/Research/Interviews',
+ kind: 'folder',
+ },
+ ],
+ },
+ {
+ id: 'workspace-roadmap',
+ label: 'Roadmap',
+ path: '/Workspace/Roadmap',
+ kind: 'folder',
+ },
+ ],
+ },
+ {
+ id: 'teams',
+ label: 'Teams',
+ path: '/Teams',
+ kind: 'space',
+ children: [
+ {
+ id: 'teams-design-systems',
+ label: 'Design systems',
+ path: '/Teams/Design systems',
+ kind: 'team',
+ children: [
+ {
+ id: 'teams-design-systems-components',
+ label: 'Components',
+ path: '/Teams/Design systems/Components',
+ kind: 'folder',
+ },
+ {
+ id: 'teams-design-systems-accessibility',
+ label: 'Accessibility',
+ path: '/Teams/Design systems/Accessibility',
+ kind: 'folder',
+ },
+ ],
+ },
+ {
+ id: 'teams-growth',
+ label: 'Growth',
+ path: '/Teams/Growth',
+ kind: 'team',
+ },
+ ],
+ },
+ {
+ id: 'archive',
+ label: 'Archive',
+ path: '/Archive',
+ kind: 'space',
+ children: [
+ {
+ id: 'archive-2025',
+ label: '2025 projects',
+ path: '/Archive/2025 projects',
+ kind: 'folder',
+ },
+ ],
+ },
+];
+
+const categoryTree: DestinationNode[] = [
+ {
+ id: 'produce',
+ label: 'Produce',
+ path: 'Produce',
+ kind: 'space',
+ children: [
+ {
+ id: 'produce-fruit',
+ label: 'Fruit',
+ path: 'Produce / Fruit',
+ kind: 'folder',
+ children: [
+ {
+ id: 'produce-fruit-citrus',
+ label: 'Citrus',
+ path: 'Produce / Fruit / Citrus',
+ kind: 'folder',
+ },
+ {
+ id: 'produce-fruit-stone',
+ label: 'Stone fruit',
+ path: 'Produce / Fruit / Stone fruit',
+ kind: 'folder',
+ },
+ ],
+ },
+ {
+ id: 'produce-vegetables',
+ label: 'Vegetables',
+ path: 'Produce / Vegetables',
+ kind: 'folder',
+ },
+ ],
+ },
+ {
+ id: 'pantry',
+ label: 'Pantry',
+ path: 'Pantry',
+ kind: 'space',
+ children: [
+ {
+ id: 'pantry-grains',
+ label: 'Grains',
+ path: 'Pantry / Grains',
+ kind: 'folder',
+ },
+ {
+ id: 'pantry-snacks',
+ label: 'Snacks',
+ path: 'Pantry / Snacks',
+ kind: 'folder',
+ },
+ ],
+ },
+];
+
+const styles = stylex.create({
+ wrapper: {
+ width: 340,
+ },
+ fruitContent: {
+ width: 500,
+ padding: spacingVars['--spacing-2'],
+ },
+ treeContent: {
+ width: 420,
+ padding: spacingVars['--spacing-3'],
+ },
+ intro: {
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ thinkingSurface: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-1'],
+ },
+ thinkingRow: {
+ display: 'grid',
+ gridTemplateColumns: 'minmax(156px, 1fr) repeat(4, 56px)',
+ alignItems: 'center',
+ columnGap: spacingVars['--spacing-1'],
+ minHeight: 48,
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ borderRadius: radiusVars['--radius-container'],
+ backgroundColor: {
+ default: 'transparent',
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-background-muted'],
+ },
+ ':focus-within': colorVars['--color-background-muted'],
+ },
+ },
+ fruitSummary: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ minWidth: 0,
+ },
+ fruitEmoji: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 28,
+ height: 28,
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-background-muted'],
+ fontSize: 17,
+ flexShrink: 0,
+ },
+ fruitText: {
+ display: 'flex',
+ flexDirection: 'column',
+ minWidth: 0,
+ },
+ fruitName: {
+ color: colorVars['--color-text-primary'],
+ fontSize: typeScaleVars['--text-label-size'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ fruitDescription: {
+ color: colorVars['--color-text-secondary'],
+ fontSize: typeScaleVars['--text-supporting-size'],
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ levelButton: {
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-full'],
+ backgroundColor: colorVars['--color-background-card'],
+ color: colorVars['--color-text-secondary'],
+ minHeight: 30,
+ paddingInline: spacingVars['--spacing-2'],
+ fontFamily: 'inherit',
+ fontSize: typeScaleVars['--text-supporting-size'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ cursor: 'pointer',
+ opacity: 0.68,
+ transitionProperty:
+ 'opacity, background-color, border-color, color, box-shadow',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ outline: {
+ default: 'none',
+ ':focus-visible': `2px solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: 2,
+ ':hover': {
+ '@media (hover: hover)': {
+ opacity: 1,
+ borderColor: colorVars['--color-border-emphasized'],
+ color: colorVars['--color-text-primary'],
+ },
+ },
+ },
+ selectedLevelButton: {
+ opacity: 1,
+ borderColor: colorVars['--color-accent'],
+ backgroundColor: colorVars['--color-accent'],
+ color: colorVars['--color-on-accent'],
+ boxShadow: shadowVars['--shadow-low'],
+ },
+ keyboardHint: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ paddingBlockStart: spacingVars['--spacing-3'],
+ borderBlockStartWidth: borderVars['--border-width'],
+ borderBlockStartStyle: 'solid',
+ borderBlockStartColor: colorVars['--color-border'],
+ },
+ searchArea: {
+ marginBlockEnd: spacingVars['--spacing-3'],
+ },
+ treePanel: {
+ maxHeight: 280,
+ overflow: 'auto',
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border'],
+ borderRadius: radiusVars['--radius-container'],
+ padding: spacingVars['--spacing-1'],
+ },
+ selectedSummary: {
+ marginBlockStart: spacingVars['--spacing-3'],
+ paddingBlockStart: spacingVars['--spacing-3'],
+ borderBlockStartWidth: borderVars['--border-width'],
+ borderBlockStartStyle: 'solid',
+ borderBlockStartColor: colorVars['--color-border'],
+ },
+ emptyState: {
+ padding: spacingVars['--spacing-3'],
+ color: colorVars['--color-text-secondary'],
+ textAlign: 'center',
+ },
+});
+
+function formatFruitValue(value: FruitValue) {
+ return `${value.fruit} Β· ${value.ripeness}`;
+}
+
+function formatDestinationValue(value: DestinationValue) {
+ return value.path;
+}
+
+function nodeMatchesQuery(node: DestinationNode, normalizedQuery: string) {
+ return (
+ node.label.toLowerCase().includes(normalizedQuery) ||
+ node.path.toLowerCase().includes(normalizedQuery)
+ );
+}
+
+function filterDestinationTree(
+ nodes: DestinationNode[],
+ query: string,
+): DestinationNode[] {
+ const normalizedQuery = query.trim().toLowerCase();
+ const result: DestinationNode[] = [];
+
+ for (const node of nodes) {
+ const filteredChildren = node.children
+ ? filterDestinationTree(node.children, query)
+ : undefined;
+ const isMatch =
+ normalizedQuery.length === 0 || nodeMatchesQuery(node, normalizedQuery);
+
+ if (!isMatch && (!filteredChildren || filteredChildren.length === 0)) {
+ continue;
+ }
+
+ result.push({
+ ...node,
+ isExpanded: normalizedQuery.length > 0 || node.children != null,
+ children: filteredChildren,
+ });
+ }
+
+ return result;
+}
+
+function toTreeListItems(
+ nodes: DestinationNode[],
+ selectedId: string,
+ onSelect: (value: DestinationValue) => void,
+): TreeListItemData[] {
+ return nodes.map(node => {
+ const hasChildren = node.children != null && node.children.length > 0;
+ return {
+ id: node.id,
+ label: node.label,
+ description: node.path,
+ isExpanded: hasChildren,
+ isSelected: !hasChildren && node.id === selectedId,
+ endContent:
+ node.kind === 'team' ? (
+ <Token label="Team" size="sm" color="blue" />
+ ) : undefined,
+ onClick: hasChildren
+ ? undefined
+ : () => onSelect({id: node.id, label: node.label, path: node.path}),
+ children: hasChildren
+ ? toTreeListItems(node.children ?? [], selectedId, onSelect)
+ : undefined,
+ };
+ });
+}
+
+function FruitRipenessMatrix({
+ value,
+ onChange,
+}: {
+ value: FruitValue;
+ onChange: (value: FruitValue) => void;
+}) {
+ const {gridRef, handleKeyDown, handleFocus, focusCell} =
+ useGridFocus<HTMLDivElement>({
+ columns: ripenessLevels.length,
+ cellSelector: GRID_CELL_SELECTOR,
+ hasRovingTabIndex: true,
+ });
+
+ useEffect(() => {
+ const rowIndex = fruits.findIndex(fruit => fruit.id === value.fruit);
+ const columnIndex = ripenessLevels.findIndex(
+ level => level.id === value.ripeness,
+ );
+ requestAnimationFrame(() => {
+ focusCell(
+ rowIndex >= 0 && columnIndex >= 0
+ ? rowIndex * ripenessLevels.length + columnIndex
+ : 0,
+ );
+ });
+ }, [focusCell, value]);
+
+ return (
+ <div
+ ref={gridRef}
+ role="grid"
+ aria-label="Fruit ripeness choices"
+ onKeyDown={handleKeyDown}
+ onFocus={handleFocus}
+ {...stylex.props(styles.thinkingSurface)}>
+ {fruits.map(fruit => (
+ <div key={fruit.id} role="row" {...stylex.props(styles.thinkingRow)}>
+ <div role="rowheader" {...stylex.props(styles.fruitSummary)}>
+ <span aria-hidden="true" {...stylex.props(styles.fruitEmoji)}>
+ {fruit.emoji}
+ </span>
+ <span {...stylex.props(styles.fruitText)}>
+ <span {...stylex.props(styles.fruitName)}>{fruit.id}</span>
+ <span {...stylex.props(styles.fruitDescription)}>
+ {fruit.description}
+ </span>
+ </span>
+ </div>
+ {ripenessLevels.map(level => {
+ const nextValue = {fruit: fruit.id, ripeness: level.id};
+ const isSelected =
+ value.fruit === fruit.id && value.ripeness === level.id;
+
+ return (
+ <button
+ key={`${fruit.id}-${level.id}`}
+ type="button"
+ role="gridcell"
+ aria-label={`${fruit.id}, ${level.id}: ${level.description}`}
+ aria-selected={isSelected || undefined}
+ tabIndex={isSelected ? 0 : -1}
+ onClick={() => onChange(nextValue)}
+ {...stylex.props(
+ styles.levelButton,
+ isSelected && styles.selectedLevelButton,
+ )}>
+ {level.shortLabel}
+ </button>
+ );
+ })}
+ </div>
+ ))}
+ </div>
+ );
+}
+
+function TreeSearchContent({
+ label,
+ value,
+ tree,
+ searchPlaceholder,
+ onChange,
+ close,
+}: {
+ label: string;
+ value: DestinationValue;
+ tree: DestinationNode[];
+ searchPlaceholder: string;
+ onChange: (value: DestinationValue) => void;
+ close: () => void;
+}) {
+ const [query, setQuery] = useState('');
+ const filteredTree = useMemo(
+ () => filterDestinationTree(tree, query),
+ [query, tree],
+ );
+ const treeItems = useMemo(
+ () =>
+ toTreeListItems(filteredTree, value.id, nextValue => {
+ onChange(nextValue);
+ close();
+ }),
+ [close, filteredTree, onChange, value.id],
+ );
+
+ return (
+ <VStack gap={3}>
+ <div {...stylex.props(styles.searchArea)}>
+ <TextInput
+ label={`Search ${label}`}
+ isLabelHidden
+ value={query}
+ onChange={setQuery}
+ hasClear
+ placeholder={searchPlaceholder}
+ />
+ </div>
+ <div {...stylex.props(styles.treePanel)}>
+ {treeItems.length > 0 ? (
+ <TreeList items={treeItems} density="compact" />
+ ) : (
+ <div role="status" {...stylex.props(styles.emptyState)}>
+ <Text type="supporting" color="secondary">
+ No matching destinations.
+ </Text>
+ </div>
+ )}
+ </div>
+ <div {...stylex.props(styles.selectedSummary)}>
+ <HStack gap={2} wrap="wrap">
+ <Text type="supporting" color="secondary">
+ Current:
+ </Text>
+ <Token label={value.path} size="sm" color="blue" />
+ </HStack>
+ </div>
+ </VStack>
+ );
+}
+
+export const FruitRipenessGrid: Story = {
+ name: 'Fruit ripeness selector',
+ render: () => {
+ const [value, setValue] = useState<FruitValue>({
+ fruit: 'Apple',
+ ripeness: 'Juicy',
+ });
+
+ return (
+ <VStack gap={4} xstyle={styles.wrapper}>
+ <ComplexSelector<FruitValue>
+ label="Fruit blend"
+ description="Choose a fruit and ripeness level in one selector. Arrow down preserves the ripeness column."
+ value={value}
+ onChange={setValue}
+ triggerLabel={formatFruitValue(value)}
+ contentXstyle={styles.fruitContent}>
+ {(selectedValue, onChange, close) => (
+ <div>
+ <div {...stylex.props(styles.intro)}>
+ <Text type="supporting" color="secondary">
+ Pick a blend profile. The compact pills mirror a hover-rich
+ selector while staying available to keyboard users.
+ </Text>
+ </div>
+
+ <FruitRipenessMatrix
+ value={selectedValue}
+ onChange={nextValue => {
+ onChange(nextValue);
+ close();
+ }}
+ />
+
+ <div {...stylex.props(styles.keyboardHint)}>
+ <HStack gap={2} wrap="wrap">
+ <Text type="supporting" color="secondary">
+ Try keyboard:
+ </Text>
+ <Text type="supporting">↓ from Apple J lands on Pear J.</Text>
+ </HStack>
+ </div>
+ </div>
+ )}
+ </ComplexSelector>
+ </VStack>
+ );
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'A fruit-themed stand-in for a rich two-axis selector. ComplexSelector owns the trigger, popover, focus restore, and change flow; the custom content owns its grid semantics.',
+ },
+ },
+ },
+};
+
+export const TreeListWithSearch: Story = {
+ name: 'Tree list with search',
+ render: () => {
+ const [value, setValue] = useState<DestinationValue>({
+ id: 'teams-design-systems-accessibility',
+ label: 'Accessibility',
+ path: '/Teams/Design systems/Accessibility',
+ });
+
+ return (
+ <VStack gap={4} xstyle={styles.wrapper}>
+ <ComplexSelector<DestinationValue>
+ label="Project destination"
+ description="Search and browse nested folders from one selector."
+ value={value}
+ onChange={setValue}
+ triggerLabel={formatDestinationValue(value)}
+ contentXstyle={styles.treeContent}>
+ {(selectedValue, onChange, close) => (
+ <TreeSearchContent
+ label="destinations"
+ value={selectedValue}
+ tree={destinationTree}
+ searchPlaceholder="Search folders or teams"
+ onChange={onChange}
+ close={close}
+ />
+ )}
+ </ComplexSelector>
+ </VStack>
+ );
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'A complex selector that combines TextInput search with TreeList hierarchy. TreeList owns tree keyboard navigation while ComplexSelector owns the trigger and popover shell. Evaluate the composed content against WCAG 2.2 keyboard, focus, name/role, label, and contrast criteria.',
+ },
+ },
+ },
+};
+
+export const CategoryTreeSelector: Story = {
+ name: 'Category tree selector',
+ render: () => {
+ const [value, setValue] = useState<DestinationValue>({
+ id: 'produce-fruit-citrus',
+ label: 'Citrus',
+ path: 'Produce / Fruit / Citrus',
+ });
+
+ return (
+ <VStack gap={4} xstyle={styles.wrapper}>
+ <ComplexSelector<DestinationValue>
+ label="Product category"
+ description="Search or browse a category tree."
+ value={value}
+ onChange={setValue}
+ triggerLabel={value.path}
+ contentXstyle={styles.treeContent}>
+ {(selectedValue, onChange, close) => (
+ <TreeSearchContent
+ label="categories"
+ value={selectedValue}
+ tree={categoryTree}
+ searchPlaceholder="Search categories"
+ onChange={onChange}
+ close={close}
+ />
+ )}
+ </ComplexSelector>
+ <Button label="Save category" variant="primary" />
+ </VStack>
+ );
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'A second tree-search example showing the same ComplexSelector shell with different hierarchical data and a form action nearby. The custom content relies on TreeList focus behavior and should be checked against WCAG 2.2.',
+ },
+ },
+ },
+};
diff --git a/internal/vibe-tests/test-sets/complex-selector.json b/internal/vibe-tests/test-sets/complex-selector.json
new file mode 100644
index 0000000000..481fc29d43
--- /dev/null
+++ b/internal/vibe-tests/test-sets/complex-selector.json
@@ -0,0 +1,33 @@
+{
+ "name": "complex-selector",
+ "prompts": [
+ {
+ "id": "cs-1",
+ "category": "complex-selector",
+ "prompt": "Build a fruit picker where users choose both a fruit and a ripeness level in one control. The closed control should show the current choice. When opened, it should be easy to move across ripeness levels and move down to the same ripeness for the next fruit using the keyboard.",
+ "expectedComponents": ["ComplexSelector"],
+ "complexity": "complex"
+ },
+ {
+ "id": "cs-2",
+ "category": "complex-selector",
+ "prompt": "Create a project destination picker. Users open one field, search destinations, browse nested folders, and choose a folder. The popup should support keyboard navigation and should close after a folder is selected.",
+ "expectedComponents": ["ComplexSelector", "TextInput", "TreeList"],
+ "complexity": "complex"
+ },
+ {
+ "id": "cs-3",
+ "category": "complex-selector",
+ "prompt": "Build a deadline picker field for a task form. Opening the field should let users choose a preset like Today or Next week, or choose a custom date and time before applying the selection.",
+ "expectedComponents": ["ComplexSelector", "DateInput", "TimeInput"],
+ "complexity": "complex"
+ },
+ {
+ "id": "cs-4",
+ "category": "complex-selector",
+ "prompt": "Make a snack selector field. Users can choose Apple, Banana, or Orange, but there should also be an Other option that reveals a text input for a custom snack before applying it.",
+ "expectedComponents": ["ComplexSelector", "TextInput", "RadioList"],
+ "complexity": "moderate"
+ }
+ ]
+}
diff --git a/packages/core/package.json b/packages/core/package.json
index a17c8f0ee0..36e0f05bbf 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -202,6 +202,11 @@
"types": "./dist/CommandPalette/index.d.ts",
"default": "./dist/CommandPalette/index.js"
},
+ "./ComplexSelector": {
+ "source": "./src/ComplexSelector/index.ts",
+ "types": "./dist/ComplexSelector/index.d.ts",
+ "default": "./dist/ComplexSelector/index.js"
+ },
"./ContextMenu": {
"source": "./src/ContextMenu/index.ts",
"types": "./dist/ContextMenu/index.d.ts",
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
new file mode 100644
index 0000000000..670894fa5e
--- /dev/null
+++ b/packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
@@ -0,0 +1,179 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
+
+export const docs = {
+ name: 'ComplexSelector',
+ displayName: 'Complex Selector',
+ group: 'Selector',
+ category: 'Data Input',
+ keywords: [
+ 'selector',
+ 'picker',
+ 'popover',
+ 'dialog',
+ 'custom',
+ 'rich',
+ 'matrix',
+ 'grid',
+ ],
+ theming: {
+ targets: [
+ {className: 'astryx-complex-selector', visualProps: ['size', 'status']},
+ {
+ className: 'astryx-complex-selector-indicator-icon',
+ states: ['state'],
+ },
+ ],
+ },
+ components: [
+ {
+ name: 'ComplexSelector',
+ displayName: 'Complex Selector',
+ description:
+ 'A field and dialog-popover shell for custom selector content.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for accessibility and the field label.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'Value',
+ description: 'Current controlled value.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: Value) => void',
+ description: 'Called when custom content commits a new value.',
+ },
+ {
+ name: 'changeAction',
+ type: '(value: Value) => void | Promise<void>',
+ description:
+ 'Async action after onChange. ComplexSelector exposes optimistic value and busy state while pending.',
+ },
+ {
+ name: 'children',
+ type: '(value: Value, onChange: (value: Value) => void, close: () => void, state: ComplexSelectorRenderState) => ReactNode',
+ description:
+ 'Custom dialog content. Receives positional value, onChange, close, and state helpers.',
+ required: true,
+ },
+ {
+ name: 'triggerLabel',
+ type: 'ReactNode',
+ description: 'Label/content shown in the closed trigger.',
+ },
+ {
+ name: 'placeholder',
+ type: 'ReactNode',
+ description: 'Placeholder shown when triggerLabel is omitted.',
+ default: "'Select...'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the selector.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Shows loading state on the trigger.',
+ },
+ {
+ name: 'status',
+ type: "{type: 'warning' | 'error' | 'success', message?: string}",
+ description: 'Validation status.',
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Trigger and field size.',
+ default: "'md'",
+ },
+ {
+ name: 'width',
+ type: 'SizeValue',
+ description: 'Width of the field.',
+ },
+ {
+ name: 'placement',
+ type: "'above' | 'below' | 'start' | 'end'",
+ description: 'Popup placement.',
+ default: "'below'",
+ },
+ {
+ name: 'contentXstyle',
+ type: 'StyleXStyles',
+ description: 'StyleX styles for the popup content container.',
+ },
+ ],
+ },
+ ],
+ usage: {
+ description:
+ 'Use ComplexSelector when a selection needs richer custom content than a Selector option row. It is intentionally one component: ComplexSelector owns the field, trigger, popover, focus restore, and changeAction flow, while the content render prop owns the selector-specific accessible structure.',
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Compose the dialog content from the appropriate accessible structure for the job: RadioList for a simple choice, Calendar/date inputs for date picking, TreeList or a searchable list for hierarchy, or a custom grid when two-dimensional arrow navigation is useful.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use the provided onChange helper from children; it already calls both onChange and changeAction and updates optimistic busy state.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Call close() from custom content when a selection should dismiss the popup. Keep it open for multi-step content or freeform entry flows.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Use Astryx focus hooks for custom content: useGridFocus for two-dimensional grids, useTreeFocus through TreeList for hierarchies, and useListFocus for custom linear collections.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Evaluate custom content against WCAG 2.2: keyboard operation, focus visible/not obscured, names and roles, labels/instructions, target size, and contrast/non-text contrast are especially relevant for selector popovers.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Do not rebuild trigger ARIA, popover focus management, or changeAction handling in product code.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Do not use ComplexSelector for a plain single-column text list; use Selector instead.',
+ },
+ ],
+ },
+};
+
+export const docsDense = {
+ name: 'ComplexSelector',
+ displayName: 'Complex Selector',
+ group: 'Selector',
+ category: 'Data Input',
+ description:
+ 'Field+dialog-popover shell for rich custom selectors. Content gets value/onChange/close/state; content owns semantics. Use focus hooks and evaluate custom content against WCAG 2.2.',
+ propDescriptions: {
+ label: 'Accessible field label.',
+ value: 'Controlled value.',
+ onChange: 'Commit value.',
+ changeAction: 'Async action after onChange; drives optimistic value/busy.',
+ children:
+ 'Render custom dialog content from (value,onChange,close,state).',
+ triggerLabel: 'Closed trigger label/content.',
+ placement: 'Popup placement.',
+ accessibility:
+ 'Custom content must provide its own accessible structure. Use focus hooks and evaluate against WCAG 2.2.',
+ },
+};
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.test.tsx b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
new file mode 100644
index 0000000000..7e0cd62003
--- /dev/null
+++ b/packages/core/src/ComplexSelector/ComplexSelector.test.tsx
@@ -0,0 +1,156 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file ComplexSelector.test.tsx
+ * @input Uses vitest, Testing Library, user-event
+ * @output Unit tests for ComplexSelector
+ * @position Tests; validates custom content, async actions, and dialog composition
+ *
+ * SYNC: When ComplexSelector.tsx API changes, update these tests.
+ */
+
+import {describe, expect, it, vi} from 'vitest';
+import {render, screen, waitFor} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {ComplexSelector} from './ComplexSelector';
+
+type FruitValue = {
+ fruit: 'Apple' | 'Banana';
+ ripeness: 'Crisp' | 'Ripe' | 'Juicy';
+};
+
+const FRUITS = ['Apple', 'Banana'] as const;
+const RIPENESS = ['Crisp', 'Ripe', 'Juicy'] as const;
+const h = {hidden: true} as const;
+
+function FruitGrid({
+ value,
+ onChange,
+}: {
+ value: FruitValue;
+ onChange: (value: FruitValue) => void;
+}) {
+ return (
+ <div role="grid" aria-label="Fruit blend choices">
+ {FRUITS.flatMap(fruit =>
+ RIPENESS.map(ripeness => {
+ const isSelected =
+ value.fruit === fruit && value.ripeness === ripeness;
+ return (
+ <button
+ key={`${fruit}-${ripeness}`}
+ type="button"
+ role="gridcell"
+ aria-label={`${fruit} ${ripeness}`}
+ aria-selected={isSelected || undefined}
+ onClick={() => onChange({fruit, ripeness})}>
+ {fruit} {ripeness}
+ </button>
+ );
+ }),
+ )}
+ </div>
+ );
+}
+
+function FruitComplexSelector({
+ value,
+ onChange,
+ changeAction,
+}: {
+ value: FruitValue;
+ onChange: (value: FruitValue) => void;
+ changeAction?: (value: FruitValue) => void | Promise<void>;
+}) {
+ return (
+ <ComplexSelector
+ label="Fruit blend"
+ value={value}
+ onChange={onChange}
+ changeAction={changeAction}
+ triggerLabel={`${value.fruit} ${value.ripeness}`}>
+ {(value, onChange, close) => (
+ <FruitGrid
+ value={value}
+ onChange={nextValue => {
+ onChange(nextValue);
+ close();
+ }}
+ />
+ )}
+ </ComplexSelector>
+ );
+}
+
+describe('ComplexSelector', () => {
+ it('renders custom content with value and commits through onChange', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+
+ render(
+ <FruitComplexSelector
+ value={{fruit: 'Apple', ripeness: 'Ripe'}}
+ onChange={onChange}
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+ await user.click(
+ screen.getByRole('gridcell', {name: 'Banana Juicy', ...h}),
+ );
+
+ expect(onChange).toHaveBeenCalledWith({fruit: 'Banana', ripeness: 'Juicy'});
+ expect(screen.getByRole('button', {name: 'Fruit blend'})).toHaveAttribute(
+ 'aria-expanded',
+ 'false',
+ );
+ });
+
+ it('runs changeAction through the provided onChange helper', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ const changeAction = vi.fn();
+
+ render(
+ <FruitComplexSelector
+ value={{fruit: 'Apple', ripeness: 'Ripe'}}
+ onChange={onChange}
+ changeAction={changeAction}
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Fruit blend'}));
+ await user.click(
+ screen.getByRole('gridcell', {name: 'Banana Crisp', ...h}),
+ );
+
+ expect(onChange).toHaveBeenCalledWith({fruit: 'Banana', ripeness: 'Crisp'});
+ await waitFor(() => {
+ expect(changeAction).toHaveBeenCalledWith({
+ fruit: 'Banana',
+ ripeness: 'Crisp',
+ });
+ });
+ });
+
+ it('passes a close helper to composed content', async () => {
+ const user = userEvent.setup();
+
+ render(
+ <ComplexSelector label="Fruit blend" value="Apple" triggerLabel="Apple">
+ {(_value, _onChange, close) => (
+ <button type="button" onClick={close}>
+ Done
+ </button>
+ )}
+ </ComplexSelector>,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Fruit blend'});
+ await user.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ await user.click(screen.getByRole('button', {name: 'Done', ...h}));
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+});
diff --git a/packages/core/src/ComplexSelector/ComplexSelector.tsx b/packages/core/src/ComplexSelector/ComplexSelector.tsx
new file mode 100644
index 0000000000..d165b5feac
--- /dev/null
+++ b/packages/core/src/ComplexSelector/ComplexSelector.tsx
@@ -0,0 +1,429 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ComplexSelector.tsx
+ * @input Uses React, StyleX, Field, usePopover
+ * @output Exports ComplexSelector component for custom selector surfaces
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/ComplexSelector/ComplexSelector.doc.mjs
+ * - /packages/core/src/ComplexSelector/ComplexSelector.test.tsx
+ * - /packages/core/src/ComplexSelector/index.ts
+ * - /apps/storybook/stories/ComplexSelector.stories.tsx
+ */
+
+import React, {
+ useCallback,
+ useId,
+ useOptimistic,
+ useTransition,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {Field, inputWrapperStyles, type FieldStatusVariant} from '../Field';
+import {Icon} from '../Icon';
+import {Spinner} from '../Spinner';
+import {useTranslator} from '../i18n';
+import {layerAnimations} from '../Layer/layerAnimations.stylex';
+import {usePopover} from '../Popover/usePopover';
+import {
+ colorVars,
+ durationVars,
+ easeVars,
+ radiusVars,
+ sizeVars,
+ spacingVars,
+ typographyVars,
+ typeScaleVars,
+} from '../theme/tokens.stylex';
+import {mergeProps} from '../utils';
+import type {SizeValue} from '../utils/types';
+import {themeProps} from '../utils/themeProps';
+
+const styles = stylex.create({
+ 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: {
+ default: typeScaleVars['--text-label-size'],
+ '@media (pointer: coarse)': `max(1rem, ${typeScaleVars['--text-label-size']})`,
+ },
+ lineHeight: typeScaleVars['--text-label-leading'],
+ color: colorVars['--color-text-primary'],
+ cursor: 'pointer',
+ },
+ 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: 'pointer',
+ outline: 'none',
+ borderRadius: radiusVars['--radius-element'],
+ },
+ triggerText: {
+ flexGrow: 1,
+ minWidth: 0,
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ textAlign: 'start',
+ },
+ placeholder: {
+ color: colorVars['--color-text-secondary'],
+ },
+ triggerIcon: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 16,
+ height: 16,
+ transitionProperty: 'transform',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ transformOrigin: 'center',
+ color: colorVars['--color-icon-secondary'],
+ },
+ triggerIconOpen: {
+ transform: 'rotate(180deg)',
+ },
+ popover: {
+ minWidth: 'anchor-size(width)',
+ marginBlockStart: spacingVars['--spacing-1'],
+ },
+ content: {
+ boxSizing: 'border-box',
+ maxHeight: 'min(480px, calc(100vh - 32px))',
+ overflow: 'auto',
+ padding: spacingVars['--spacing-3'],
+ },
+ sm: {
+ minHeight: sizeVars['--size-element-sm'],
+ },
+ md: {
+ minHeight: sizeVars['--size-element-md'],
+ },
+ lg: {
+ minHeight: sizeVars['--size-element-lg'],
+ },
+ disabled: {
+ cursor: 'not-allowed',
+ },
+ focusRing: {
+ ':focus-within': {
+ outline: `2px solid ${colorVars['--color-accent']}`,
+ outlineOffset: '2px',
+ },
+ },
+});
+
+export type ComplexSelectorSize = 'sm' | 'md' | 'lg';
+
+export interface ComplexSelectorRenderState {
+ /** Whether the selector surface is open. */
+ isOpen: boolean;
+ /** Whether changeAction/isLoading is pending. */
+ isBusy: boolean;
+ /** ID of the trigger button. */
+ triggerId: string;
+ /** ID of the popup content container. */
+ contentId: string;
+}
+
+export interface ComplexSelectorStatus {
+ type: 'warning' | 'error' | 'success';
+ message?: string;
+}
+
+export interface ComplexSelectorProps<Value> extends Omit<
+ BaseProps<HTMLDivElement>,
+ 'children' | 'onChange'
+> {
+ /** Label text for accessibility and the field label. */
+ label: string;
+ /** Current controlled value. */
+ value: Value;
+ /** Called when custom content commits a new value. */
+ onChange?: (value: Value) => void;
+ /** Optional async action after onChange; drives optimistic UI. */
+ changeAction?: (value: Value) => void | Promise<void>;
+ /** Custom selector surface content rendered inside a dialog popover. */
+ children: (
+ value: Value,
+ onChange: (value: Value) => void,
+ close: () => void,
+ state: ComplexSelectorRenderState,
+ ) => ReactNode;
+ /** Label/content shown in the closed trigger. */
+ triggerLabel?: ReactNode;
+ /** Placeholder shown when triggerLabel is omitted. */
+ placeholder?: ReactNode;
+ /** Whether to visually hide the field label. */
+ isLabelHidden?: boolean;
+ /** Helper text displayed below the label. */
+ description?: string;
+ /** Marks the field optional. */
+ isOptional?: boolean;
+ /** Marks the field required. */
+ isRequired?: boolean;
+ /** Disables the selector. */
+ isDisabled?: boolean;
+ /** Shows loading state on the trigger. */
+ isLoading?: boolean;
+ /** Validation status. */
+ status?: ComplexSelectorStatus;
+ /** Status placement. */
+ statusVariant?: FieldStatusVariant;
+ /** Tooltip text displayed next to the label. */
+ labelTooltip?: string;
+ /** Trigger and field size. */
+ size?: ComplexSelectorSize;
+ /** Width of the field. */
+ width?: SizeValue;
+ /** Popup placement. */
+ placement?: 'above' | 'below' | 'start' | 'end';
+ /** StyleX styles for the popup content container. */
+ contentXstyle?: StyleXStyles;
+ /** Test ID for the trigger container. */
+ 'data-testid'?: string;
+}
+
+/**
+ * A selector shell for rich, custom selection surfaces.
+ *
+ * ComplexSelector owns the field, trigger, popover, focus restore, and async
+ * change action flow. Consumers provide the dialog content as a render function,
+ * using the supplied `value`, `onChange`, and `close` helpers to compose the
+ * right accessible structure for the custom selector.
+ *
+ * @example
+ * ```
+ * <ComplexSelector
+ * label="Fruit"
+ * value={value}
+ * onChange={setValue}
+ * triggerLabel={`${value.fruit} ${value.ripeness}`}>
+ * {(value, onChange, close) => (
+ * <FruitGrid
+ * value={value}
+ * onChange={nextValue => {
+ * onChange(nextValue);
+ * close();
+ * }}
+ * />
+ * )}
+ * </ComplexSelector>
+ * ```
+ */
+export function ComplexSelector<Value>({
+ label,
+ value,
+ onChange,
+ changeAction,
+ children,
+ triggerLabel,
+ placeholder: placeholderFromProps,
+ isLabelHidden = false,
+ description,
+ isOptional = false,
+ isRequired = false,
+ isDisabled = false,
+ isLoading = false,
+ status,
+ statusVariant = 'attached',
+ labelTooltip,
+ size = 'md',
+ width,
+ placement = 'below',
+ contentXstyle,
+ xstyle,
+ className,
+ style,
+ 'data-testid': testId,
+ ...props
+}: ComplexSelectorProps<Value>) {
+ const t = useTranslator();
+ const placeholder = placeholderFromProps ?? t('@astryx.selector.placeholder');
+
+ const triggerId = useId();
+ const labelId = useId();
+ const contentId = useId();
+ const descriptionId = useId();
+ const statusMessageId = useId();
+ const ariaDescribedBy =
+ [
+ description ? descriptionId : null,
+ status?.message ? statusMessageId : null,
+ ]
+ .filter((id): id is string => id != null)
+ .join(' ') || undefined;
+
+ const [isPending, startTransition] = useTransition();
+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+ const isBusy = isLoading || isPending;
+
+ const popover = usePopover({
+ dialogLabel: label,
+ hasCloseButton: false,
+ hasAutoFocus: true,
+ onHide: () => {
+ document.getElementById(triggerId)?.focus();
+ },
+ });
+
+ const commitValue = useCallback(
+ (nextValue: Value) => {
+ onChange?.(nextValue);
+ if (changeAction) {
+ startTransition(async () => {
+ setOptimisticValue(nextValue);
+ await changeAction(nextValue);
+ });
+ }
+ },
+ [changeAction, onChange, setOptimisticValue, startTransition],
+ );
+
+ const triggerContent = triggerLabel ?? placeholder;
+
+ const content = (
+ <div id={contentId} {...stylex.props(styles.content, contentXstyle)}>
+ {children(optimisticValue, commitValue, popover.hide, {
+ isOpen: popover.isOpen,
+ isBusy,
+ triggerId,
+ contentId,
+ })}
+ </div>
+ );
+
+ const selectorContent = (
+ <>
+ <div
+ ref={popover.triggerRef}
+ data-testid={testId}
+ {...props}
+ onClick={() => {
+ if (!isDisabled) {
+ popover.toggle();
+ }
+ }}
+ {...mergeProps(
+ themeProps('complex-selector', {
+ size,
+ status: status?.type ?? null,
+ }),
+ stylex.props(
+ inputWrapperStyles.base,
+ styles.triggerContainer,
+ styles[size],
+ styles.focusRing,
+ isDisabled && inputWrapperStyles.disabled,
+ isDisabled && styles.disabled,
+ triggerLabel == null && styles.placeholder,
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <button
+ id={triggerId}
+ type="button"
+ aria-haspopup="dialog"
+ aria-expanded={popover.isOpen}
+ aria-controls={contentId}
+ aria-describedby={ariaDescribedBy}
+ aria-labelledby={labelId}
+ aria-required={isRequired ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-busy={isBusy || undefined}
+ disabled={isDisabled}
+ onKeyDown={event => {
+ if (event.key === 'ArrowDown' && !popover.isOpen && !isDisabled) {
+ event.preventDefault();
+ popover.show();
+ }
+ }}
+ {...stylex.props(styles.trigger)}>
+ <span {...stylex.props(styles.triggerText)}>{triggerContent}</span>
+ </button>
+ {isBusy && <Spinner size="sm" />}
+ <span
+ {...stylex.props(
+ styles.triggerIcon,
+ popover.isOpen && styles.triggerIconOpen,
+ )}>
+ <Icon
+ icon="chevronDown"
+ size="sm"
+ color="inherit"
+ {...themeProps('complex-selector-indicator-icon', {
+ state: popover.isOpen ? 'expanded' : 'collapsed',
+ })}
+ />
+ </span>
+ </div>
+
+ {popover.render(content, {
+ placement,
+ alignment: 'start',
+ xstyle: [styles.popover, layerAnimations[placement]],
+ })}
+ </>
+ );
+
+ return (
+ <Field
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={triggerId}
+ descriptionID={description ? descriptionId : undefined}
+ labelID={labelId}
+ 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}>
+ {selectorContent}
+ </Field>
+ );
+}
+
+ComplexSelector.displayName = 'ComplexSelector';
diff --git a/packages/core/src/ComplexSelector/index.ts b/packages/core/src/ComplexSelector/index.ts
new file mode 100644
index 0000000000..182e9a1e5b
--- /dev/null
+++ b/packages/core/src/ComplexSelector/index.ts
@@ -0,0 +1,17 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file index.ts
+ * @output Exports ComplexSelector and types
+ * @position Public API entry point
+ */
+
+export {
+ ComplexSelector,
+ type ComplexSelectorProps,
+ type ComplexSelectorRenderState,
+ type ComplexSelectorSize,
+ type ComplexSelectorStatus,
+} from './ComplexSelector';
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 8e2b78c1ff..d29ee10c58 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -33,6 +33,7 @@ export * from './Calendar';
export * from './Center';
export * from './CodeBlock';
export * from './CommandPalette';
+export * from './ComplexSelector';
export * from './Chat';
export * from './Markdown';
export * from './Citation';