An open source design system that's fully customizable and agent ready
TypeScript
feat: XDSMultiSelector — multi-select dropdown (#1008) (#1013)
Cindy Zhange12a6fce991e
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.mdindex 49d6737d9b..6b1c597972 100644--- a/.claude/commands/create-component.md+++ b/.claude/commands/create-component.md@@ -1,6 +1,6 @@# Create XDS Component-Create a new XDS component following established patterns.+Create a new XDS component following the established protocols.## Component Name@@ -8,177 +8,31 @@ $ARGUMENTS## Instructions-Create a new component in `/packages/core/src/{ComponentName}/` with the following files:--### 1. {ComponentName}.tsx (Main Component)--Use this structure based on Button.tsx:--```tsx-/**- * @file {ComponentName}.tsx- * @input Uses React forwardRef, HTMLAttributes, ReactNode- * @output Exports {ComponentName} component, {ComponentName}Props, {ComponentName}Variant types- * @position Core implementation- *- * SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/{ComponentName}/{ComponentName}.doc.mjs- * - /packages/core/src/{ComponentName}/{ComponentName}.test.tsx- * - /packages/core/src/{ComponentName}/index.ts- * - /apps/storybook/stories/{ComponentName}.stories.tsx- */--import { forwardRef, useContext, type HTMLAttributes, type ReactNode } from 'react';-import * as stylex from '@stylexjs/stylex';-import {- colorTokens,- spacingTokens,- radiusTokens,- transitionTokens,- typographyTokens,-} from '../theme/tokens.stylex';-import { ThemeContext } from '../theme/ThemeContext';-import type { StyleXStyles } from '../theme/types';--// Define styles first-const styles = stylex.create({- base: {- // Base styles using tokens- },- disabled: {- cursor: 'not-allowed',- opacity: 0.5,- },-});--// Define variants - {ComponentName}Variant type will be derived from this-const variants = stylex.create({- default: {- // Variant styles using tokens- },-});--// Derive variant type from the variants object-export type {ComponentName}Variant = keyof typeof variants;--// =============================================================================-// Module Augmentation - Register variant type with ComponentStyles-// =============================================================================-// This allows themes to provide type-safe variant overrides for this component--declare module '../theme/types' {- interface ComponentStyles {- {componentName}?: {- variants?: Partial<Record<{ComponentName}Variant, StyleXStyles>>;- };- }-}--export interface {ComponentName}Props extends HTMLAttributes<HTMLElement> {- variant?: {ComponentName}Variant;- children: ReactNode;-}--export const {ComponentName} = forwardRef<HTMLElement, {ComponentName}Props>(- ({ variant = 'default', children, ...props }, ref) => {- // Get theme context for component-level variant overrides (optional)- const themeContext = useContext(ThemeContext);- const themeVariantOverride = themeContext?.theme.components?.{componentName}?.variants?.[variant];-- return (- <div- ref={ref}- {...stylex.props(- styles.base,- variants[variant],- themeVariantOverride- )}- {...props}- >- {children}- </div>- );- }-);--{ComponentName}.displayName = '{ComponentName}';-```--### 2. index.ts (Exports)--```tsx-export { {ComponentName} } from './{ComponentName}';-export type { {ComponentName}Props, {ComponentName}Variant } from './{ComponentName}';-```--### 3. {ComponentName}.doc.mjs--```js-/** @type {import('../docs-types').ComponentDoc} */--export const docs = {- name: '{ComponentName}',- description: 'Brief description of the component.',- features: ['Variants: list available variants'],- props: [- {- name: 'variant',- type: "'{variant1}' | '{variant2}'",- description: 'Visual style variant',- default: "'default'",- },- {- name: 'children',- type: 'ReactNode',- description: 'Component content',- required: true,- },- ],- examples: [- {- label: 'Basic',- code: `<{ComponentName} variant="default">Content</{ComponentName}>`,- },- ],- theming: {- componentKey: '{componentName}',- surfaces: [{name: 'root', description: 'Outer wrapper element'}],- },-};-```--### 4. Update /packages/core/src/index.ts--Add export for the new component:--```tsx-export * from './{ComponentName}';-```--## Key Patterns to Follow--1. **Derive types from StyleX objects**: Use `keyof typeof variants` for variant types-2. **Use tokens**: Import from `../theme/tokens.stylex` - never use hardcoded values-3. **SYNC comments**: List all files that need updating when the component changes-4. **Theme variant ingestion**: Use `ThemeContext` to apply theme-level variant overrides on top of defaults-5. **Module augmentation**: Use `declare module` to register the component's variant type with `ComponentStyles` - this keeps theme types decoupled from component imports--## Token Reference--Available tokens from `tokens.stylex`:--- `colorTokens`: accent, surface, textPrimary, hoverOverlay, pressedOverlay, focusOutline, negative, etc.-- `spacingTokens`: space0, space0_5, space1, space2, space3, space4, space5, space6, space7-- `radiusTokens`: rounded, container, element, content-- `transitionTokens`: fast, normal-- `typographyTokens`: fontFamilyBody, fontFamilyCode, fontFamilyHeading--## Reference--See the [Component Authoring Guide](https://github.com/facebookexperimental/xds/wiki/Component-Authoring-Guide) on the wiki for the complete Button implementation with advanced patterns like loading states and hover overlays.--## After Creation--1. Run `yarn workspace @xds/core build` to verify the build-2. Create stories in `/apps/storybook/stories/{ComponentName}.stories.tsx` (import from `@xds/core/{ComponentName}`)-3. Add tests in `/packages/core/src/{ComponentName}/{ComponentName}.test.tsx`+Follow the two-phase protocol documented on the XDS wiki:++1. **Specification Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Specification-Protocol+2. **Build Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Build-Protocol++### Quick reference++- Read the spec thoroughly — it's the contract+- Study sibling components in the same family for patterns+- Create files in `packages/core/src/{ComponentName}/`:+ - `XDS{ComponentName}.tsx` — main component+ - `XDS{ComponentName}.test.tsx` — unit tests+ - `{ComponentName}.doc.mjs` — typed docs (ComponentDoc)+ - `index.ts` — public exports+ - `README.md` — directory README (see Tokenizer/README.md for the format)+- Create `apps/storybook/stories/{ComponentName}.stories.tsx`+- Wire up: add to `packages/core/src/index.ts`+- Run `node scripts/sync-exports.js` to update package.json exports+- Run `yarn build && yarn test && yarn lint`++### Key conventions++- **API Conventions**: https://github.com/facebookexperimental/xds/wiki/API-Conventions+- **Theming**: Use `xdsClassName()` for theme targets — see https://github.com/facebookexperimental/xds/wiki/Theming-Infrastructure+- **Compose, don't rebuild** — use existing XDS components (XDSField, XDSIcon, etc.)+- **displayName** — always set it+- **:hover guards** — all `:hover` in `@media (hover: hover)`+- **Spacing/elevation tokens** — never raw px or boxShadow stringsdiff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsxnew file mode 100644index 0000000000..ca7fe4f410--- /dev/null+++ b/apps/storybook/stories/MultiSelector.stories.tsx@@ -0,0 +1,357 @@+import type {Meta, StoryObj} from '@storybook/react';+import {useState} from 'react';+import {XDSMultiSelector} from '@xds/core/MultiSelector';++const meta: Meta<typeof XDSMultiSelector> = {+ title: 'Form/XDSMultiSelector',+ component: XDSMultiSelector,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+ decorators: [+ Story => (+ <div style={{width: 300}}>+ <Story />+ </div>+ ),+ ],+ argTypes: {+ label: {control: 'text'},+ isLabelHidden: {control: 'boolean'},+ description: {control: 'text'},+ placeholder: {control: 'text'},+ size: {control: 'radio', options: ['sm', 'md', 'lg']},+ triggerDisplay: {+ control: 'radio',+ options: ['count', 'labels', 'badges'],+ },+ isDisabled: {control: 'boolean'},+ isOptional: {control: 'boolean'},+ isRequired: {control: 'boolean'},+ hasSelectAll: {control: 'boolean'},+ hasSearch: {control: 'boolean'},+ },+};++export default meta;+type Story = StoryObj<typeof XDSMultiSelector>;++// Basic with strings+export const Default: Story = {+ render: args => {+ const [value, setValue] = useState<string[]>(['Role', 'Created']);+ return (+ <XDSMultiSelector+ {...args}+ label={args.label ?? 'Columns'}+ options={args.options ?? ['Name', 'Email', 'Role', 'Status', 'Created']}+ value={value}+ onChange={setValue}+ />+ );+ },+ args: {+ placeholder: 'Select columns...',+ },+};++// With sections+export const Sections: Story = {+ render: () => {+ const [value, setValue] = useState<string[]>([]);+ return (+ <XDSMultiSelector+ label="Permissions"+ options={[+ {+ type: 'section',+ title: 'Read',+ options: [+ {value: 'read_posts', label: 'Read posts'},+ {value: 'read_comments', label: 'Read comments'},+ {value: 'read_users', label: 'Read users'},+ ],+ },+ {+ type: 'section',+ title: 'Write',+ options: [+ {value: 'write_posts', label: 'Write posts'},+ {value: 'write_comments', label: 'Write comments'},+ ],+ },+ ]}+ value={value}+ onChange={setValue}+ placeholder="Select permissions..."+ />+ );+ },+ decorators: [Story => <Story />],+};++// With Select All+export const SelectAll: Story = {+ render: () => {+ const [value, setValue] = useState<string[]>([]);+ return (+ <XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role', 'Status', 'Created', 'Updated']}+ value={value}+ onChange={setValue}+ hasSelectAll+ placeholder="Select columns..."+ />+ );+ },+ decorators: [Story => <Story />],+};++// Searchable+export const Searchable: Story = {+ render: () => {+ const [value, setValue] = useState<string[]>([]);+ return (+ <XDSMultiSelector+ label="Countries"+ options={[+ 'United States',+ 'United Kingdom',+ 'Canada',+ 'Australia',+ 'Germany',+ 'France',+ 'Japan',+ 'Brazil',+ 'India',+ 'Mexico',+ ]}+ value={value}+ onChange={setValue}+ hasSearch+ hasSelectAll+ placeholder="Select countries..."+ />+ );+ },+ decorators: [Story => <Story />],+};++// Trigger display modes+export const TriggerModes: Story = {+ render: () => {+ const [value1, setValue1] = useState<string[]>(['Name', 'Email']);+ const [value2, setValue2] = useState<string[]>(['Name', 'Email', 'Role']);+ const [value3, setValue3] = useState<string[]>([+ 'Name',+ 'Email',+ 'Role',+ 'Status',+ 'Created',+ ]);+ return (+ <div+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>+ <XDSMultiSelector+ label="Count (default)"+ options={['Name', 'Email', 'Role', 'Status', 'Created']}+ value={value1}+ onChange={setValue1}+ triggerDisplay="count"+ />+ <XDSMultiSelector+ label="Labels"+ options={['Name', 'Email', 'Role', 'Status', 'Created']}+ value={value2}+ onChange={setValue2}+ triggerDisplay="labels"+ />+ <XDSMultiSelector+ label="Badges"+ options={['Name', 'Email', 'Role', 'Status', 'Created']}+ value={value3}+ onChange={setValue3}+ triggerDisplay="badges"+ maxBadges={3}+ />+ </div>+ );+ },+ decorators: [Story => <Story />],+};++// Disabled items+export const DisabledItems: Story = {+ render: () => {+ const [value, setValue] = useState<string[]>(['admin']);+ return (+ <XDSMultiSelector+ label="Roles"+ options={[+ {value: 'admin', label: 'Admin', disabled: true},+ {value: 'editor', label: 'Editor'},+ {value: 'viewer', label: 'Viewer'},+ {value: 'guest', label: 'Guest'},+ ]}+ value={value}+ onChange={setValue}+ hasSelectAll+ placeholder="Select roles..."+ />+ );+ },+ decorators: [Story => <Story />],+};++// Status variants+export const Status: Story = {+ render: () => {+ const [value1, setValue1] = useState<string[]>([]);+ const [value2, setValue2] = useState<string[]>(['Email']);+ const [value3, setValue3] = useState<string[]>(['Name', 'Email']);+ return (+ <div+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>+ <XDSMultiSelector+ label="Error"+ options={['Name', 'Email', 'Role']}+ value={value1}+ onChange={setValue1}+ status={{type: 'error', message: 'Please select at least one column'}}+ placeholder="Select..."+ />+ <XDSMultiSelector+ label="Warning"+ options={['Name', 'Email', 'Role']}+ value={value2}+ onChange={setValue2}+ status={{type: 'warning', message: 'Email column has issues'}}+ />+ <XDSMultiSelector+ label="Success"+ options={['Name', 'Email', 'Role']}+ value={value3}+ onChange={setValue3}+ status={{type: 'success'}}+ />+ </div>+ );+ },+ decorators: [Story => <Story />],+};++// Size variants+export const Sizes: Story = {+ render: () => {+ const [value1, setValue1] = useState<string[]>([]);+ const [value2, setValue2] = useState<string[]>([]);+ const [value3, setValue3] = useState<string[]>([]);+ return (+ <div+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>+ <XDSMultiSelector+ label="Small"+ size="sm"+ options={['Name', 'Email', 'Role']}+ value={value1}+ onChange={setValue1}+ placeholder="Small (28px)"+ />+ <XDSMultiSelector+ label="Medium"+ size="md"+ options={['Name', 'Email', 'Role']}+ value={value2}+ onChange={setValue2}+ placeholder="Medium (32px)"+ />+ <XDSMultiSelector+ label="Large"+ size="lg"+ options={['Name', 'Email', 'Role']}+ value={value3}+ onChange={setValue3}+ placeholder="Large (36px)"+ />+ </div>+ );+ },+ decorators: [Story => <Story />],+};++// Form composition+export const FormComposition: Story = {+ render: () => {+ const [columns, setColumns] = useState<string[]>(['name', 'email']);+ const [filters, setFilters] = useState<string[]>([]);+ return (+ <div+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>+ <XDSMultiSelector+ label="Visible columns"+ description="Choose which columns to display in the table"+ options={[+ {value: 'name', label: 'Name'},+ {value: 'email', label: 'Email'},+ {value: 'role', label: 'Role'},+ {value: 'status', label: 'Status'},+ {value: 'created', label: 'Created at'},+ ]}+ value={columns}+ onChange={setColumns}+ hasSelectAll+ isRequired+ triggerDisplay="labels"+ />+ <XDSMultiSelector+ label="Status filter"+ description="Filter by status"+ options={['Active', 'Inactive', 'Pending', 'Archived']}+ value={filters}+ onChange={setFilters}+ isOptional+ triggerDisplay="badges"+ placeholder="All statuses"+ />+ </div>+ );+ },+ decorators: [Story => <Story />],+};++// Column visibility+export const ColumnVisibility: Story = {+ render: () => {+ const allColumns = [+ {value: 'name', label: 'Name'},+ {value: 'email', label: 'Email'},+ {value: 'role', label: 'Role'},+ {value: 'status', label: 'Status'},+ {value: 'created', label: 'Created'},+ {value: 'updated', label: 'Updated'},+ {value: 'actions', label: 'Actions'},+ ];+ const [visible, setVisible] = useState<string[]>([+ 'name',+ 'email',+ 'role',+ 'status',+ ]);+ return (+ <XDSMultiSelector+ label="Columns"+ isLabelHidden+ options={allColumns}+ value={visible}+ onChange={setVisible}+ hasSelectAll+ hasSearch+ triggerDisplay="count"+ placeholder="Columns"+ />+ );+ },+ decorators: [Story => <Story />],+};diff --git a/packages/core/package.json b/packages/core/package.jsonindex f1732472c7..6f7a1e5227 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -208,6 +208,12 @@"import": "./dist/MoreMenu/index.mjs","require": "./dist/MoreMenu/index.js"},+ "./MultiSelector": {+ "source": "./src/MultiSelector/index.ts",+ "types": "./dist/MultiSelector/index.d.ts",+ "import": "./dist/MultiSelector/index.mjs",+ "require": "./dist/MultiSelector/index.js"+ },"./NavIcon": {"source": "./src/NavIcon/index.ts","types": "./dist/NavIcon/index.d.ts",diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjsnew file mode 100644index 0000000000..3e66a29717--- /dev/null+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs@@ -0,0 +1,237 @@+/** @type {import('../docs-types').ComponentDoc} */++export const docs = {+ name: 'MultiSelector',+ description:+ 'Multi-select dropdown with checkboxes for choosing multiple items from a list. For small, finite sets like column toggles or filter facets — not a replacement for XDSTokenizer.',+ features: [+ 'Checkbox-based multi-select — dropdown stays open on toggle',+ 'Supports string items, object items with optional icon and disabled state, dividers, and labeled sections',+ 'Optional select-all with indeterminate state',+ 'Optional search filtering',+ 'Three trigger display modes: count, labels, badges',+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',+ 'Size variants: sm, md, lg',+ 'Full keyboard navigation with typeahead support',+ 'Accessible — role="combobox" trigger, role="listbox" with aria-multiselectable, real checkbox inputs',+ ],+ keyboard:+ '↑↓ navigate, Enter/Space toggle, Escape close, Home/End jump, A-Z typeahead (when search not shown).',+ accessibility: [+ 'Uses role="combobox" on the trigger button.',+ 'Dropdown listbox uses aria-multiselectable="true".',+ 'Each option uses role="option" with aria-selected.',+ 'Real XDSCheckboxInput for each item — no fake checkboxes.',+ 'Select-all checkbox rendered outside role="listbox".',+ 'Search input uses role="searchbox" with aria-controls.',+ ],+ theming: {+ targets: [+ {className: 'xds-multi-selector', visualProps: ['size', 'status']},+ ],+ },+ examples: [+ {+ label: 'Basic',+ code: `<XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role', 'Status']}+ value={selected}+ onChange={setSelected}+/>`,+ },+ {+ label: 'With select all and search',+ code: `<XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role', 'Status', 'Created']}+ value={selected}+ onChange={setSelected}+ hasSelectAll+ hasSearch+/>`,+ },+ {+ label: 'Badges trigger display',+ code: `<XDSMultiSelector+ label="Filters"+ options={['Active', 'Inactive', 'Pending', 'Archived']}+ value={selected}+ onChange={setSelected}+ triggerDisplay="badges"+ maxBadges={2}+/>`,+ },+ {+ label: 'Sections',+ code: `<XDSMultiSelector+ label="Permissions"+ options={[+ {type: 'section', title: 'Read', options: [+ {value: 'read_posts', label: 'Read posts'},+ {value: 'read_comments', label: 'Read comments'},+ ]},+ {type: 'section', title: 'Write', options: [+ {value: 'write_posts', label: 'Write posts'},+ {value: 'write_comments', label: 'Write comments'},+ ]},+ ]}+ value={selected}+ onChange={setSelected}+/>`,+ },+ ],+ components: [+ {+ name: 'XDSMultiSelector',+ description:+ 'Multi-select dropdown with checkboxes for choosing multiple items.',+ props: [+ {+ name: 'label',+ type: 'string',+ description: 'Label text for accessibility.',+ required: true,+ },+ {+ name: 'options',+ type: 'XDSMultiSelectorOptionType[]',+ description:+ 'Array of items — strings, objects with value/label/icon/disabled, dividers, or sections.',+ required: true,+ },+ {+ name: 'value',+ type: 'string[]',+ description: 'Currently selected values.',+ required: true,+ },+ {+ name: 'onChange',+ type: '(value: string[]) => void',+ description: 'Callback fired when the selection changes.',+ required: true,+ },+ {+ name: 'onChangeAction',+ type: '(value: string[]) => void | Promise<void>',+ description: 'Async action on change. Fires after onChange.',+ },+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text shown when no value is selected.',+ default: "'Select...'",+ },+ {+ name: 'size',+ type: "'sm' | 'md' | 'lg'",+ description: 'Size variant for the selector.',+ default: "'md'",+ },+ {+ name: 'triggerDisplay',+ type: "'count' | 'labels' | 'badges'",+ description: 'How to display selected items in the trigger.',+ default: "'count'",+ },+ {+ name: 'maxBadges',+ type: 'number',+ description:+ 'Maximum badges to show before "+N". Only for triggerDisplay="badges".',+ default: '3',+ },+ {+ name: 'hasSelectAll',+ type: 'boolean',+ description: 'Whether to show a select-all checkbox.',+ },+ {+ name: 'selectAllLabel',+ type: 'string',+ description: 'Label for the select-all checkbox.',+ default: "'Select all'",+ },+ {+ name: 'hasSearch',+ type: 'boolean',+ description: 'Whether to show a search input for filtering options.',+ },+ {+ name: 'searchPlaceholder',+ type: 'string',+ description: 'Placeholder text for the search input.',+ default: "'Search...'",+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Disables the selector.',+ },+ {+ name: 'isLabelHidden',+ type: 'boolean',+ description: 'Visually hides the label while keeping it accessible.',+ },+ {+ name: 'description',+ type: 'string',+ description: 'Helper text displayed below the label.',+ },+ {+ name: 'isOptional',+ type: 'boolean',+ description: 'Marks the field as optional.',+ },+ {+ name: 'isRequired',+ type: 'boolean',+ description: 'Marks the field as required.',+ },+ {+ name: 'isLoading',+ type: 'boolean',+ description: 'Shows a loading spinner in the trigger.',+ },+ {+ name: 'status',+ type: "{type: 'error' | 'warning' | 'success', message?: string}",+ description: 'Validation status with an optional message.',+ },+ {+ name: 'children',+ type: '(option: XDSMultiSelectorOptionData) => ReactNode',+ description: 'Custom render function for each option in the dropdown.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role']}+ value={selected}+ onChange={setSelected}+/>`,+ },+ {+ label: 'With select all',+ code: `<XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role']}+ value={selected}+ onChange={setSelected}+ hasSelectAll+/>`,+ },+ ],+ },+ ],+};diff --git a/packages/core/src/MultiSelector/README.md b/packages/core/src/MultiSelector/README.mdnew file mode 100644index 0000000000..a1c99ba729--- /dev/null+++ b/packages/core/src/MultiSelector/README.md@@ -0,0 +1,70 @@+# MultiSelector++Multi-select dropdown with checkboxes for choosing multiple items from a list.++<!-- SYNC: When files in this directory change, update this document. -->++## Overview++XDSMultiSelector is a checkbox dropdown for small, finite lists — column toggles, filter facets, permissions. For large/open sets with typeahead search, use XDSTokenizer instead.++- **Checkbox items** — real `XDSCheckboxInput` for each option+- **Select all** — optional toggle with indeterminate state+- **Search** — optional filter-in-place+- **Trigger display** — count, labels, or badge chips+- **Sections** — reuses `XDSSelector` option type model+- **Selected-first sort** — selected items sort to top on open (stable during interaction)++## Import++```tsx+import {XDSMultiSelector} from '@xds/core/MultiSelector';+```++## Usage++```tsx+<XDSMultiSelector+ label="Columns"+ options={['Name', 'Email', 'Role', 'Status']}+ value={selected}+ onChange={setSelected}+ hasSelectAll+/>+```++## Key Props++| Prop | Type | Default | Description |+| ---------------- | --------------------------------- | --------- | ----------------------------------------------- |+| `label` | `string` | required | Accessible label |+| `options` | `XDSMultiSelectorOptionType[]` | required | Items — strings, objects, dividers, or sections |+| `value` | `string[]` | required | Currently selected values |+| `onChange` | `(value: string[]) => void` | required | Selection change callback |+| `hasSelectAll` | `boolean` | `false` | Show select-all toggle |+| `hasSearch` | `boolean` | `false` | Show search/filter input |+| `triggerDisplay` | `'count' \| 'labels' \| 'badges'` | `'count'` | How trigger shows selections |+| `maxBadges` | `number` | `3` | Max badges before "+N" |+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |+| `status` | `{type, message?}` | — | Validation state |+| `isDisabled` | `boolean` | `false` | Disable the selector |+| `onChangeAction` | `(value) => Promise` | — | Async action with optimistic UI |++## Theming++The trigger renders `xdsClassName('multi-selector', {size, status})`. Theme authors+target these classes via `defineTheme({ components })`:++```ts+defineTheme({+ name: 'custom',+ components: {+ 'multi-selector': {+ base: {borderRadius: 'var(--radius-3)'},+ 'size:sm': {fontSize: '12px'},+ },+ },+});+```++See the [Theming Infrastructure wiki](https://github.com/facebookexperimental/xds/wiki/Theming-Infrastructure).diff --git a/packages/core/src/MultiSelector/XDSMultiSelector.test.tsx b/packages/core/src/MultiSelector/XDSMultiSelector.test.tsxnew file mode 100644index 0000000000..211918ffd2--- /dev/null+++ b/packages/core/src/MultiSelector/XDSMultiSelector.test.tsx@@ -0,0 +1,575 @@+/**+ * @file XDSMultiSelector.test.tsx+ * @input Uses vitest, @testing-library/react, @testing-library/user-event+ * @output Unit tests for XDSMultiSelector+ * @position Tests; validates XDSMultiSelector behavior+ *+ * SYNC: When XDSMultiSelector.tsx API changes, update these tests.+ */++import {describe, it, expect, vi, beforeEach} from 'vitest';+import {render, screen} from '@testing-library/react';+import userEvent from '@testing-library/user-event';+import {XDSMultiSelector} from './XDSMultiSelector';++// Mock showPopover and hidePopover methods since they're not implemented in jsdom+beforeEach(() => {+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {+ this.setAttribute('popover-open', '');+ const event = new Event('toggle', {bubbles: false});+ Object.defineProperty(event, 'newState', {value: 'open'});+ this.dispatchEvent(event);+ });+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {+ this.removeAttribute('popover-open');+ const event = new Event('toggle', {bubbles: false});+ Object.defineProperty(event, 'newState', {value: 'closed'});+ this.dispatchEvent(event);+ });+ const originalMatches = HTMLElement.prototype.matches;+ HTMLElement.prototype.matches = function (selector: string) {+ if (selector === ':popover-open') {+ return this.hasAttribute('popover-open');+ }+ return originalMatches.call(this, selector);+ };+});++// Helper: jsdom popover content is in the DOM but may not be+// "visible" in the accessibility tree. Use hidden: true to find it.+const h = {hidden: true} as const;++describe('XDSMultiSelector', () => {+ const defaultOptions = ['Apple', 'Banana', 'Orange'];++ it('renders with label', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );+ expect(screen.getByLabelText('Fruit')).toBeInTheDocument();+ });++ it('renders placeholder when no value selected', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ placeholder="Pick fruits..."+ />,+ );+ expect(screen.getByText('Pick fruits...')).toBeInTheDocument();+ });++ it('shows count display by default', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={['Apple', 'Banana']}+ onChange={() => {}}+ />,+ );+ expect(screen.getByText('2 selected')).toBeInTheDocument();+ });++ it('shows labels display', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={['Apple', 'Banana']}+ onChange={() => {}}+ triggerDisplay="labels"+ />,+ );+ expect(screen.getByText('Apple, Banana')).toBeInTheDocument();+ });++ it('shows labels display with overflow', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}+ value={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}+ onChange={() => {}}+ triggerDisplay="labels"+ />,+ );+ expect(screen.getByText('Apple, Banana, Orange, +2')).toBeInTheDocument();+ });++ it('opens dropdown on click', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );+ const trigger = screen.getByRole('combobox');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');++ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('toggles item on click without closing dropdown', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={onChange}+ />,+ );++ await user.click(screen.getByRole('combobox'));++ const options = screen.getAllByRole('option', h);+ await user.click(options[0]);++ expect(onChange).toHaveBeenCalledWith(['Apple']);+ // Dropdown should still be open+ expect(screen.getByRole('combobox')).toHaveAttribute(+ 'aria-expanded',+ 'true',+ );+ });++ it('deselects item when clicking selected item', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={['Apple', 'Banana']}+ onChange={onChange}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ await user.click(options[0]); // Click Apple to deselect++ expect(onChange).toHaveBeenCalledWith(['Banana']);+ });++ it('does not toggle disabled items', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={[+ {value: 'apple', label: 'Apple', disabled: true},+ {value: 'banana', label: 'Banana'},+ ]}+ value={[]}+ onChange={onChange}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ await user.click(options[0]); // Click disabled Apple++ expect(onChange).not.toHaveBeenCalled();+ });++ it('renders disabled state', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ isDisabled+ />,+ );+ expect(screen.getByRole('combobox')).toBeDisabled();+ });++ it('has correct ARIA attributes', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ isRequired+ />,+ );+ const trigger = screen.getByRole('combobox');+ expect(trigger).toHaveAttribute('aria-haspopup', 'listbox');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ expect(trigger).toHaveAttribute('aria-required', 'true');+ });++ it('renders listbox with aria-multiselectable', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const listbox = screen.getByRole('listbox', h);+ expect(listbox).toHaveAttribute('aria-multiselectable', 'true');+ });++ it('marks selected options with aria-selected', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={['Apple']}+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ expect(options[0]).toHaveAttribute('aria-selected', 'true');+ expect(options[1]).toHaveAttribute('aria-selected', 'false');+ });++ it('shows error status with aria-invalid', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ status={{type: 'error', message: 'Required'}}+ />,+ );+ const trigger = screen.getByRole('combobox');+ expect(trigger).toHaveAttribute('aria-invalid', 'true');+ expect(screen.getByText('Required')).toBeInTheDocument();+ });++ it('closes on Escape', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );++ const trigger = screen.getByRole('combobox');+ await user.click(trigger);+ expect(trigger).toHaveAttribute('aria-expanded', 'true');++ await user.keyboard('{Escape}');+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('supports keyboard navigation with ArrowDown/ArrowUp', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );++ const trigger = screen.getByRole('combobox');+ await user.click(trigger);++ await user.keyboard('{ArrowDown}');+ const activeId = trigger.getAttribute('aria-activedescendant');+ expect(activeId).toBeTruthy();+ });++ it('toggles item with Enter key', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={onChange}+ />,+ );++ const trigger = screen.getByRole('combobox');+ await user.click(trigger);+ await user.keyboard('{Enter}');+ expect(onChange).toHaveBeenCalledWith(['Apple']);+ });++ it('renders select-all checkbox when hasSelectAll', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ hasSelectAll+ />,+ );++ await user.click(screen.getByRole('combobox'));+ expect(screen.getByLabelText('Select all', h)).toBeInTheDocument();+ });++ it('select-all selects all enabled items', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={[+ {value: 'apple', label: 'Apple'},+ {value: 'banana', label: 'Banana', disabled: true},+ {value: 'orange', label: 'Orange'},+ ]}+ value={[]}+ onChange={onChange}+ hasSelectAll+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const selectAll = screen.getByLabelText('Select all', h);+ await user.click(selectAll);++ expect(onChange).toHaveBeenCalledWith(['apple', 'orange']);+ });++ it('select-all deselects all when all are selected', async () => {+ const user = userEvent.setup();+ const onChange = vi.fn();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={['Apple', 'Banana', 'Orange']}+ onChange={onChange}+ hasSelectAll+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const selectAll = screen.getByLabelText('Select all', h);+ await user.click(selectAll);++ expect(onChange).toHaveBeenCalledWith([]);+ });++ it('renders search input when hasSearch', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ hasSearch+ />,+ );++ await user.click(screen.getByRole('combobox'));+ expect(screen.getByRole('searchbox', h)).toBeInTheDocument();+ });++ it('filters options when searching', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ hasSearch+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const searchInput = screen.getByRole('searchbox', h);+ await user.type(searchInput, 'app');++ const options = screen.getAllByRole('option', h);+ expect(options).toHaveLength(1);+ });++ it('shows empty state when search has no results', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ hasSearch+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const searchInput = screen.getByRole('searchbox', h);+ await user.type(searchInput, 'xyz');++ expect(screen.getByText('No results found')).toBeInTheDocument();+ });++ it('renders with description', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ description="Choose your fruits"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ />,+ );+ expect(screen.getByText('Choose your fruits')).toBeInTheDocument();+ });++ it('supports data-testid', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ data-testid="fruit-selector"+ />,+ );+ expect(screen.getByTestId('fruit-selector')).toBeInTheDocument();+ });++ it('renders sections with dividers', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={[+ {value: 'apple', label: 'Apple'},+ {+ type: 'section',+ title: 'Citrus',+ options: [+ {value: 'orange', label: 'Orange'},+ {value: 'lemon', label: 'Lemon'},+ ],+ },+ ]}+ value={[]}+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ expect(options).toHaveLength(3);+ const group = screen.getByRole('group', h);+ expect(group).toHaveAttribute('aria-label', 'Citrus');+ });++ it('shows loading state with aria-busy', () => {+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ isLoading+ />,+ );+ expect(screen.getByRole('combobox')).toHaveAttribute('aria-busy', 'true');+ });++ it('renders with custom selectAllLabel', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={defaultOptions}+ value={[]}+ onChange={() => {}}+ hasSelectAll+ selectAllLabel="Check all"+ />,+ );++ await user.click(screen.getByRole('combobox'));+ expect(screen.getByLabelText('Check all', h)).toBeInTheDocument();+ });++ it('sorts selected items to top', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange']}+ value={['Orange']}+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ // Orange is selected so it should appear first+ expect(options[0]).toHaveAttribute('aria-selected', 'true');+ expect(options[0]).toHaveTextContent('Orange');+ expect(options[1]).toHaveTextContent('Apple');+ expect(options[2]).toHaveTextContent('Banana');+ });++ it('sorts selected items to top within sections', async () => {+ const user = userEvent.setup();+ render(+ <XDSMultiSelector+ label="Fruit"+ options={[+ {+ type: 'section',+ title: 'Citrus',+ options: [+ {value: 'orange', label: 'Orange'},+ {value: 'lemon', label: 'Lemon'},+ {value: 'lime', label: 'Lime'},+ ],+ },+ ]}+ value={['lime']}+ onChange={() => {}}+ />,+ );++ await user.click(screen.getByRole('combobox'));+ const options = screen.getAllByRole('option', h);+ // Lime is selected so it should appear first within the section+ expect(options[0]).toHaveTextContent('Lime');+ expect(options[1]).toHaveTextContent('Orange');+ expect(options[2]).toHaveTextContent('Lemon');+ });++ it('has displayName', () => {+ expect(XDSMultiSelector.displayName).toBe('XDSMultiSelector');+ });+});diff --git a/packages/core/src/MultiSelector/XDSMultiSelector.tsx b/packages/core/src/MultiSelector/XDSMultiSelector.tsxnew file mode 100644index 0000000000..60ccf2e4af--- /dev/null+++ b/packages/core/src/MultiSelector/XDSMultiSelector.tsx@@ -0,0 +1,1006 @@+'use client';++/**+ * @file XDSMultiSelector.tsx+ * @input Uses React, StyleX, useXDSPopover, XDSCheckboxInput, XDSField, XDSBadge, XDSIcon+ * @output Exports XDSMultiSelector component+ * @position Core implementation; consumed by index.ts+ *+ * SYNC: When modified, update:+ * - /packages/core/src/MultiSelector/MultiSelector.doc.mjs+ * - /packages/core/src/MultiSelector/index.ts+ */++import React, {+ useCallback,+ useId,+ useMemo,+ useOptimistic,+ useRef,+ useState,+ useTransition,+ type ReactNode,+} from 'react';+import * as stylex from '@stylexjs/stylex';+import {useXDSPopover} from '../Popover/useXDSPopover';+import {XDSIcon} from '../Icon';+import type {XDSIconName} from '../Icon';+import {+ XDSField,+ inputStatusBorderStyles,+ inputStatusHoverShadowStyles,+} from '../Field';+import {XDSDivider} from '../Divider';+import {XDSSpinner} from '../Spinner';+import {XDSCheckboxInput} from '../CheckboxInput';+import {XDSBadge} from '../Badge';+import {+ colorVars,+ sizeVars,+ spacingVars,+ radiusVars,+ shadowVars,+ durationVars,+ easeVars,+ typographyVars,+ fontWeightVars,+ typeScaleVars,+ borderVars,+} from '../theme/tokens.stylex';+import type {+ XDSMultiSelectorOptionType,+ XDSMultiSelectorOptionData,+ XDSMultiSelectorStatus,+} from './types';+import {+ isOptionData,+ isDivider,+ isSection,+ normalizeOption,+ getSelectableOptions,+} from '../Selector/utils';+import {useMultiCombobox} from './hooks';+import {xdsClassName, mergeProps} from '../utils';+import {XDSBaseProps} from '../XDSBaseProps';++const styles = stylex.create({+ // Trigger button+ trigger: {+ position: 'relative',+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'space-between',+ gap: spacingVars['--spacing-2'],+ width: '100%',+ paddingBlock: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ borderWidth: borderVars['--border-width'],+ borderStyle: 'solid',+ borderColor: {+ default: colorVars['--color-border-emphasized'],+ ':hover': {+ '@media (hover: hover)': colorVars['--color-border-emphasized'],+ },+ },+ borderRadius: radiusVars['--radius-element'],+ backgroundColor: colorVars['--color-background-surface'],+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-label-size'],+ lineHeight: typeScaleVars['--text-label-leading'],+ color: colorVars['--color-text-primary'],+ cursor: 'pointer',+ transitionProperty: 'border-color, outline, box-shadow',+ transitionDuration: durationVars['--duration-fast'],+ transitionTimingFunction: easeVars['--ease-standard'],+ boxShadow: {+ default: 'none',+ ':hover': {+ '@media (hover: hover)': shadowVars['--shadow-inset-hover'],+ },+ },+ outline: {+ default: 'none',+ ':focus': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,+ },+ outlineOffset: '0',+ },+ triggerDisabled: {+ cursor: 'not-allowed',+ opacity: 0.5,+ borderColor: colorVars['--color-border-emphasized'],+ },+ triggerPlaceholder: {+ color: colorVars['--color-text-secondary'],+ },+ triggerContent: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ flexGrow: 1,+ flexShrink: 1,+ flexBasis: 0,+ minWidth: 0,+ overflow: 'hidden',+ },+ triggerText: {+ overflow: 'hidden',+ textOverflow: 'ellipsis',+ whiteSpace: 'nowrap',+ },+ triggerBadges: {+ display: 'flex',+ flexWrap: 'wrap',+ gap: spacingVars['--spacing-1'],+ alignItems: 'center',+ },+ triggerOverflow: {+ flexShrink: 0,+ fontSize: typeScaleVars['--text-label-size'],+ color: colorVars['--color-text-secondary'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ },+ 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)',+ },+ triggerIconStatus: {+ transition: 'none',+ },++ // Dropdown container+ dropdown: {+ boxSizing: 'border-box',+ maxHeight: '300px',+ overflowY: 'auto',+ padding: spacingVars['--spacing-1'],+ },++ // Popover container (for anchor positioning)+ popover: {+ minWidth: 'anchor-size(width)',+ marginBlockStart: spacingVars['--spacing-1'],+ },++ // Search input+ searchWrapper: {+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+ searchInput: {+ boxSizing: 'border-box',+ width: '100%',+ paddingBlock: spacingVars['--spacing-1'],+ paddingInline: spacingVars['--spacing-2'],+ borderWidth: borderVars['--border-width'],+ borderStyle: 'solid',+ borderColor: colorVars['--color-border-emphasized'],+ borderRadius: radiusVars['--radius-element'],+ backgroundColor: colorVars['--color-background-surface'],+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-label-size'],+ color: colorVars['--color-text-primary'],+ outline: {+ default: 'none',+ ':focus': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,+ },+ outlineOffset: '0',+ },++ // Select-all wrapper+ selectAllWrapper: {+ cursor: 'pointer',+ },++ // Section divider with label+ sectionDivider: {+ marginBlock: spacingVars['--spacing-1'],+ },++ // Divider+ divider: {+ marginBlock: spacingVars['--spacing-1'],+ },++ // Individual item+ item: {+ boxSizing: 'border-box',+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ width: '100%',+ borderRadius: radiusVars['--radius-element'],+ cursor: 'pointer',+ backgroundColor: 'transparent',+ border: 'none',+ outline: 'none',+ },+ itemHighlighted: {+ backgroundColor: colorVars['--color-overlay-hover'],+ },+ itemDisabled: {+ opacity: 0.5,+ cursor: 'not-allowed',+ },++ // Empty state+ emptyState: {+ padding: spacingVars['--spacing-3'],+ textAlign: 'center',+ color: colorVars['--color-text-secondary'],+ fontFamily: typographyVars['--font-family-body'],+ fontSize: typeScaleVars['--text-label-size'],+ },+});++const sizeStyles = stylex.create({+ sm: {+ height: sizeVars['--size-element-sm'],+ },+ md: {+ height: sizeVars['--size-element-md'],+ },+ lg: {+ height: sizeVars['--size-element-lg'],+ },+});++const itemSizeStyles = stylex.create({+ sm: {+ padding: spacingVars['--spacing-1'],+ },+ md: {+ padding: spacingVars['--spacing-2'],+ },+ lg: {+ padding: spacingVars['--spacing-2'],+ },+});++const selectAllSizeStyles = stylex.create({+ sm: {+ paddingInline: spacingVars['--spacing-1'],+ paddingBlock: spacingVars['--spacing-0-5'],+ },+ md: {+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+ lg: {+ paddingInline: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-1'],+ },+});++const STATUS_ICON_MAP: Record<XDSMultiSelectorStatusType, XDSIconName> = {+ warning: 'warning',+ error: 'xCircle',+ success: 'checkCircle',+};++const STATUS_ICON_COLOR_MAP: Record<+ XDSMultiSelectorStatusType,+ 'warning' | 'negative' | 'positive'+> = {+ warning: 'warning',+ error: 'negative',+ success: 'positive',+};++export type XDSMultiSelectorSize = 'sm' | 'md' | 'lg';++export type XDSMultiSelectorStatusType = 'warning' | 'error' | 'success';++export type {XDSMultiSelectorStatus};++export interface XDSMultiSelectorProps<+ T extends XDSMultiSelectorOptionType = XDSMultiSelectorOptionType,+> extends Omit<XDSBaseProps, 'onChange' | 'defaultValue' | 'children'> {+ /**+ * Label text for the multi-selector (always rendered for accessibility).+ */+ label: string;++ /**+ * Whether to visually hide the label (still accessible to screen readers).+ * @default false+ */+ isLabelHidden?: boolean;++ /**+ * Description text displayed between the label and selector.+ */+ description?: string;++ /**+ * Whether the field is optional. Mutually exclusive with isRequired.+ * @default false+ */+ isOptional?: boolean;++ /**+ * Whether the field is required. Mutually exclusive with isOptional.+ * @default false+ */+ isRequired?: boolean;++ /**+ * Whether the selector is disabled.+ * @default false+ */+ isDisabled?: boolean;++ /**+ * The options to display in the selector.+ * Can be strings, objects, dividers, or sections.+ */+ options: T[];++ /**+ * The currently selected values.+ */+ value: string[];++ /**+ * Callback when selection changes.+ */+ onChange: (value: string[]) => void;++ /**+ * Async action on change. Fires after onChange.+ */+ onChangeAction?: (value: string[]) => void | Promise<void>;++ /**+ * Whether the selector is in a loading state.+ * @default false+ */+ isLoading?: boolean;++ /**+ * Placeholder text when no value is selected.+ * @default 'Select...'+ */+ placeholder?: string;++ /**+ * The size of the selector.+ * @default 'md'+ */+ size?: XDSMultiSelectorSize;++ /**+ * Status indicator for the selector.+ */+ status?: XDSMultiSelectorStatus;++ /**+ * Tooltip text to display in an info icon at the end of the label.+ */+ labelTooltip?: string;++ /**+ * Whether to show a "Select all" checkbox.+ * @default false+ */+ hasSelectAll?: boolean;++ /**+ * Label for the select-all checkbox.+ * @default 'Select all'+ */+ selectAllLabel?: string;++ /**+ * Whether to show a search input.+ * @default false+ */+ hasSearch?: boolean;++ /**+ * Placeholder text for the search input.+ * @default 'Search...'+ */+ searchPlaceholder?: string;++ /**+ * How to display selected items in the trigger.+ * - 'count': "3 selected"+ * - 'labels': "Name, Email, +3"+ * - 'badges': [Name] [Email] +2+ * @default 'count'+ */+ triggerDisplay?: 'count' | 'labels' | 'badges';++ /**+ * Maximum number of badges to show before showing "+N".+ * Only used when triggerDisplay is 'badges'.+ * @default 3+ */+ maxBadges?: number;++ /**+ * Custom render function for options.+ * Only called for selectable options (not dividers/sections).+ */+ children?: (option: XDSMultiSelectorOptionData) => ReactNode;++ /**+ * Test ID for testing frameworks.+ */+ 'data-testid'?: string;+}++/**+ * A multi-select dropdown component with checkboxes for choosing+ * multiple items from a list of options.+ *+ * @example+ * ```+ * <XDSMultiSelector+ * label="Columns"+ * options={['Name', 'Email', 'Role', 'Status']}+ * value={selectedColumns}+ * onChange={setSelectedColumns}+ * hasSelectAll+ * />+ * ```+ */+export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({+ label,+ isLabelHidden = false,+ description,+ isOptional = false,+ isRequired = false,+ isDisabled = false,+ options,+ value,+ onChange,+ onChangeAction,+ isLoading = false,+ placeholder = 'Select...',+ size = 'md',+ status,+ labelTooltip,+ hasSelectAll = false,+ selectAllLabel = 'Select all',+ hasSearch = false,+ searchPlaceholder = 'Search...',+ triggerDisplay = 'count',+ maxBadges = 3,+ children,+ 'data-testid': testId,+ xstyle,+ className,+ style,+}: XDSMultiSelectorProps<T>) {+ const triggerId = useId();+ const listboxId = useId();+ const descriptionId = useId();+ const statusMessageId = useId();+ const searchId = useId();+ const triggerRef = useRef<HTMLButtonElement>(null);+ const searchRef = useRef<HTMLInputElement>(null);++ const [searchQuery, setSearchQuery] = useState('');++ // Snapshot of which values were selected when the dropdown opened.+ // Used for sort partitioning so items don't jump during interaction.+ const selectedAtOpenRef = useRef<Set<string> | null>(null);++ const [, startTransition] = useTransition();+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);+ const isBusy = isLoading || optimisticValue !== value;++ // Build aria-describedby+ const ariaDescribedBy =+ [+ description ? descriptionId : null,+ status?.message ? statusMessageId : null,+ ]+ .filter(Boolean)+ .join(' ') || undefined;++ // Flatten options for keyboard navigation+ const selectableItems = useMemo(+ () => getSelectableOptions(options),+ [options],+ );++ // Filter items by search query+ const filteredItems = useMemo(() => {+ if (!searchQuery) return selectableItems;+ const query = searchQuery.toLowerCase();+ return selectableItems.filter(item =>+ (item.label ?? item.value).toLowerCase().includes(query),+ );+ }, [selectableItems, searchQuery]);++ // Layer for dropdown positioning+ const handleLayerHide = useCallback(() => {+ setSearchQuery('');+ selectedAtOpenRef.current = null;+ triggerRef.current?.focus();+ }, []);++ const popover = useXDSPopover({+ hasLightDismiss: true,+ onHide: handleLayerHide,+ hasCloseButton: false,+ hasAutoFocus: false,+ dialogLabel: `${label} options`,+ });++ // Handle toggle+ const handleToggle = useCallback(+ (itemValue: string) => {+ const newValue = optimisticValue.includes(itemValue)+ ? optimisticValue.filter(v => v !== itemValue)+ : [...optimisticValue, itemValue];++ onChange(newValue);+ if (onChangeAction) {+ startTransition(async () => {+ setOptimisticValue(newValue);+ await onChangeAction(newValue);+ });+ }+ },+ [+ optimisticValue,+ onChange,+ onChangeAction,+ startTransition,+ setOptimisticValue,+ ],+ );++ // Multi-select combobox behavior+ const {+ highlightedIndex,+ getItemId,+ onTriggerClick,+ onKeyDown,+ onItemMouseEnter,+ } = useMultiCombobox({+ selectableItems: filteredItems,+ isDisabled,+ isOpen: popover.isOpen,+ hasSearch,+ onOpen: useCallback(() => {+ // Snapshot which items are selected at open time — sort is stable during interaction+ selectedAtOpenRef.current = new Set(optimisticValue);++ popover.show();+ if (hasSearch) {+ // Focus search after popover opens+ requestAnimationFrame(() => {+ searchRef.current?.focus();+ });+ }+ }, [popover, hasSearch, filteredItems, optimisticValue]),+ onClose: popover.hide,+ onToggle: handleToggle,+ listboxId,+ });++ // Select-all logic+ const enabledItems = useMemo(+ () => filteredItems.filter(item => !item.disabled),+ [filteredItems],+ );++ const allEnabledSelected = useMemo(+ () =>+ enabledItems.length > 0 &&+ enabledItems.every(item => optimisticValue.includes(item.value)),+ [enabledItems, optimisticValue],+ );++ const someSelected = useMemo(+ () => enabledItems.some(item => optimisticValue.includes(item.value)),+ [enabledItems, optimisticValue],+ );++ const selectAllState: boolean | 'indeterminate' = allEnabledSelected+ ? true+ : someSelected+ ? 'indeterminate'+ : false;++ const handleSelectAll = useCallback(() => {+ let newValue: string[];+ if (allEnabledSelected) {+ // Deselect all enabled items, keep disabled items that are selected+ const enabledValues = new Set(enabledItems.map(item => item.value));+ newValue = optimisticValue.filter(v => !enabledValues.has(v));+ } else {+ // Select all enabled items+ const currentSet = new Set(optimisticValue);+ newValue = [...optimisticValue];+ for (const item of enabledItems) {+ if (!currentSet.has(item.value)) {+ newValue.push(item.value);+ }+ }+ }++ onChange(newValue);+ if (onChangeAction) {+ startTransition(async () => {+ setOptimisticValue(newValue);+ await onChangeAction(newValue);+ });+ }+ }, [+ allEnabledSelected,+ enabledItems,+ optimisticValue,+ onChange,+ onChangeAction,+ startTransition,+ setOptimisticValue,+ ]);++ // Build trigger display content+ const selectedLabels = useMemo(() => {+ return optimisticValue.map(v => {+ const item = selectableItems.find(i => i.value === v);+ return item?.label ?? v;+ });+ }, [optimisticValue, selectableItems]);++ const renderTriggerContent = useCallback(() => {+ if (optimisticValue.length === 0) {+ return <span {...stylex.props(styles.triggerText)}>{placeholder}</span>;+ }++ switch (triggerDisplay) {+ case 'count':+ return (+ <span {...stylex.props(styles.triggerText)}>+ {optimisticValue.length} selected+ </span>+ );++ case 'labels': {+ const displayed = selectedLabels.slice(0, 3);+ const remaining = selectedLabels.length - displayed.length;+ const text =+ remaining > 0+ ? `${displayed.join(', ')}, +${remaining}`+ : displayed.join(', ');+ return <span {...stylex.props(styles.triggerText)}>{text}</span>;+ }++ case 'badges': {+ const displayed = selectedLabels.slice(0, maxBadges);+ const remaining = selectedLabels.length - displayed.length;+ return (+ <span {...stylex.props(styles.triggerBadges)}>+ {displayed.map(label => (+ <XDSBadge key={label} label={label} variant="neutral" />+ ))}+ {remaining > 0 && (+ <span {...stylex.props(styles.triggerOverflow)}>+ +{remaining}+ </span>+ )}+ </span>+ );+ }+ }+ }, [optimisticValue, triggerDisplay, selectedLabels, placeholder, maxBadges]);++ // Render search input+ const renderSearch = useCallback(() => {+ if (!hasSearch) return null;+ return (+ <div {...stylex.props(styles.searchWrapper)}>+ <input+ ref={searchRef}+ id={searchId}+ role="searchbox"+ aria-controls={listboxId}+ aria-label="Search options"+ type="text"+ value={searchQuery}+ onChange={e => setSearchQuery(e.target.value)}+ onKeyDown={e => {+ // Let ArrowDown/Up/Escape propagate to parent handler+ if (+ e.key === 'ArrowDown' ||+ e.key === 'ArrowUp' ||+ e.key === 'Escape'+ ) {+ onKeyDown(e);+ }+ }}+ placeholder={searchPlaceholder}+ {...stylex.props(styles.searchInput)}+ />+ </div>+ );+ }, [+ hasSearch,+ searchId,+ listboxId,+ searchQuery,+ searchPlaceholder,+ onKeyDown,+ ]);++ // Render an individual item+ const renderItem = useCallback(+ (item: XDSMultiSelectorOptionData, flatIndex: number) => {+ const isHighlighted = flatIndex === highlightedIndex;+ const isSelected = optimisticValue.includes(item.value);++ return (+ <div+ key={item.value}+ id={getItemId(flatIndex)}+ role="option"+ aria-selected={isSelected}+ aria-disabled={item.disabled}+ onClick={() => {+ if (!item.disabled) {+ handleToggle(item.value);+ }+ }}+ onMouseEnter={() => onItemMouseEnter(item, flatIndex)}+ {...stylex.props(+ styles.item,+ itemSizeStyles[size],+ isHighlighted && styles.itemHighlighted,+ item.disabled && styles.itemDisabled,+ )}>+ <XDSCheckboxInput+ label={children ? '' : (item.label ?? item.value)}+ isLabelHidden={!!children}+ value={isSelected}+ onChange={() => {}}+ isDisabled={item.disabled}+ size={size === 'lg' ? 'md' : size}+ />+ {children && children(item)}+ </div>+ );+ },+ [+ children,+ highlightedIndex,+ optimisticValue,+ getItemId,+ handleToggle,+ onItemMouseEnter,+ size,+ ],+ );++ // Render all options (handling sections/dividers and search filtering)+ const renderOptions = useCallback(() => {+ // Use the open-time snapshot for sort partitioning (stable during interaction).+ // Falls back to live value when dropdown isn't open yet.+ const selectedSet = selectedAtOpenRef.current ?? new Set(optimisticValue);++ if (searchQuery) {+ // Sort filtered: selected-at-open first, then unselected+ const selected = filteredItems.filter(item =>+ selectedSet.has(item.value),+ );+ const unselected = filteredItems.filter(+ item => !selectedSet.has(item.value),+ );+ const sorted = [...selected, ...unselected];++ if (sorted.length === 0) {+ return <div {...stylex.props(styles.emptyState)}>No results found</div>;+ }+ return sorted.map((item, index) => renderItem(item, index));+ }++ // Normal rendering with selected-first sorting (using open-time snapshot)+ let flatIndex = 0;+ const elements: ReactNode[] = [];+ let pendingFlatItems: Array<{+ item: XDSMultiSelectorOptionData;+ }> = [];++ const flushFlatItems = () => {+ if (pendingFlatItems.length === 0) return;+ const selected = pendingFlatItems.filter(({item}) =>+ selectedSet.has(item.value),+ );+ const unselected = pendingFlatItems.filter(+ ({item}) => !selectedSet.has(item.value),+ );+ const sorted = [...selected, ...unselected];+ for (const {item} of sorted) {+ elements.push(renderItem(item, flatIndex));+ flatIndex++;+ }+ pendingFlatItems = [];+ };++ for (let i = 0; i < options.length; i++) {+ const option = options[i];++ if (isDivider(option)) {+ flushFlatItems();+ elements.push(+ <XDSDivider key={`divider-${i}`} xstyle={styles.divider} />,+ );+ } else if (isSection(option)) {+ flushFlatItems();+ // Sort within section: selected-at-open first+ const sectionOptions = option.options.map(opt => normalizeOption(opt));+ const selectedInSection = sectionOptions.filter(item =>+ selectedSet.has(item.value),+ );+ const unselectedInSection = sectionOptions.filter(+ item => !selectedSet.has(item.value),+ );+ const sortedSection = [...selectedInSection, ...unselectedInSection];++ const sectionItems: ReactNode[] = [];+ for (const item of sortedSection) {+ sectionItems.push(renderItem(item, flatIndex));+ flatIndex++;+ }+ if (option.title) {+ elements.push(+ <XDSDivider+ key={`section-divider-${i}`}+ label={option.title}+ xstyle={styles.sectionDivider}+ />,+ );+ }+ elements.push(+ <div key={`section-${i}`} role="group" aria-label={option.title}>+ {sectionItems}+ </div>,+ );+ } else if (isOptionData(option)) {+ pendingFlatItems.push({item: normalizeOption(option)});+ }+ }+ flushFlatItems();++ return elements;+ }, [options, renderItem, filteredItems, searchQuery, optimisticValue]);++ return (+ <XDSField+ label={label}+ isLabelHidden={isLabelHidden}+ description={description}+ inputID={triggerId}+ descriptionID={description ? descriptionId : undefined}+ isOptional={isOptional}+ isRequired={isRequired}+ isDisabled={isDisabled}+ status={+ status+ ? {+ type: status.type,+ message: status.message,+ messageID: status.message ? statusMessageId : undefined,+ }+ : undefined+ }+ labelTooltip={labelTooltip}>+ <button+ ref={el => {+ (+ triggerRef as React.MutableRefObject<HTMLButtonElement | null>+ ).current = el;+ popover.triggerRef(el);+ }}+ id={triggerId}+ type="button"+ role="combobox"+ aria-haspopup="listbox"+ aria-expanded={popover.isOpen}+ aria-controls={listboxId}+ aria-activedescendant={+ popover.isOpen && highlightedIndex >= 0+ ? getItemId(highlightedIndex)+ : undefined+ }+ aria-describedby={ariaDescribedBy}+ aria-required={isRequired ? 'true' : undefined}+ aria-invalid={status?.type === 'error' ? 'true' : undefined}+ aria-busy={isBusy || undefined}+ disabled={isDisabled}+ onClick={onTriggerClick}+ onKeyDown={onKeyDown}+ data-testid={testId}+ {...mergeProps(+ xdsClassName('multi-selector', {size, status: status?.type ?? null}),+ stylex.props(+ styles.trigger,+ sizeStyles[size],+ isDisabled && styles.triggerDisabled,+ optimisticValue.length === 0 && styles.triggerPlaceholder,+ status && inputStatusBorderStyles[status.type],+ status && inputStatusHoverShadowStyles[status.type],+ xstyle,+ ),+ className,+ style,+ )}>+ <span {...stylex.props(styles.triggerContent)}>+ {renderTriggerContent()}+ </span>+ {isBusy && <XDSSpinner size="sm" />}+ <span+ {...stylex.props(+ styles.triggerIcon,+ !status && popover.isOpen && styles.triggerIconOpen,+ status && styles.triggerIconStatus,+ )}>+ {status ? (+ <XDSIcon+ icon={STATUS_ICON_MAP[status.type]}+ size="sm"+ color={STATUS_ICON_COLOR_MAP[status.type]}+ />+ ) : (+ <XDSIcon icon="chevronDown" size="sm" color="inherit" />+ )}+ </span>+ </button>++ {popover.render(+ <div {...stylex.props(styles.dropdown)}>+ {renderSearch()}+ {hasSelectAll && (+ <>+ <div+ {...stylex.props(+ styles.selectAllWrapper,+ selectAllSizeStyles[size],+ )}+ onClick={handleSelectAll}>+ <XDSCheckboxInput+ label={selectAllLabel}+ value={selectAllState}+ onChange={() => {}}+ size={size === 'lg' ? 'md' : size}+ />+ </div>+ <XDSDivider xstyle={styles.divider} />+ </>+ )}+ <div+ id={listboxId}+ role="listbox"+ aria-multiselectable="true"+ aria-labelledby={triggerId}>+ {renderOptions()}+ </div>+ </div>,+ {+ placement: 'below',+ alignment: 'start',+ xstyle: styles.popover,+ },+ )}+ </XDSField>+ );+}++XDSMultiSelector.displayName = 'XDSMultiSelector';diff --git a/packages/core/src/MultiSelector/hooks.ts b/packages/core/src/MultiSelector/hooks.tsnew file mode 100644index 0000000000..88f49704d2--- /dev/null+++ b/packages/core/src/MultiSelector/hooks.ts@@ -0,0 +1,219 @@+'use client';++/**+ * @file hooks.ts+ * @input Uses React hooks, XDSMultiSelectorOptionData type+ * @output Exports useMultiCombobox hook+ * @position Internal hook; used by XDSMultiSelector.tsx+ *+ * SYNC: When modified, update:+ * - /packages/core/src/MultiSelector/index.ts+ */++import {useCallback, useRef, useState} from 'react';+import type {XDSMultiSelectorOptionData} from './types';++interface UseMultiComboboxOptions {+ selectableItems: XDSMultiSelectorOptionData[];+ isDisabled?: boolean;+ isOpen: boolean;+ hasSearch?: boolean;+ onOpen: () => void;+ onClose: () => void;+ onToggle: (itemValue: string) => void;+ listboxId: string;+}++interface UseMultiComboboxResult {+ highlightedIndex: number;+ setHighlightedIndex: (index: number) => void;+ getItemId: (index: number) => string;+ onTriggerClick: () => void;+ onKeyDown: (e: React.KeyboardEvent) => void;+ onItemMouseEnter: (item: XDSMultiSelectorOptionData, index: number) => void;+}++/**+ * Handles keyboard navigation and toggle logic for multi-select combobox.+ * Unlike useCombobox (single-select), toggling an item does NOT close the dropdown.+ */+export function useMultiCombobox({+ selectableItems,+ isDisabled = false,+ isOpen,+ hasSearch = false,+ onOpen,+ onClose,+ onToggle,+ listboxId,+}: UseMultiComboboxOptions): UseMultiComboboxResult {+ const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);+ const [typeahead, setTypeahead] = useState('');+ const typeaheadTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(+ undefined,+ );++ const getItemId = useCallback(+ (index: number) => `${listboxId}-item-${index}`,+ [listboxId],+ );++ const getEnabledIndices = useCallback(() => {+ return selectableItems+ .map((item, i) => (!item.disabled ? i : -1))+ .filter(i => i >= 0);+ }, [selectableItems]);++ const closeAndReset = useCallback(() => {+ setHighlightedIndex(-1);+ onClose();+ }, [onClose]);++ const onTriggerClick = useCallback(() => {+ if (isDisabled) return;+ if (isOpen) {+ closeAndReset();+ } else {+ onOpen();+ // If search is present, don't highlight any item (focus goes to search)+ if (!hasSearch) {+ setHighlightedIndex(0);+ }+ }+ }, [isDisabled, isOpen, onOpen, closeAndReset, hasSearch]);++ const onItemMouseEnter = useCallback(+ (item: XDSMultiSelectorOptionData, index: number) => {+ if (!item.disabled) {+ setHighlightedIndex(index);+ }+ },+ [],+ );++ const onKeyDown = useCallback(+ (e: React.KeyboardEvent) => {+ if (isDisabled) return;++ const enabledIndices = getEnabledIndices();++ switch (e.key) {+ case 'ArrowDown':+ e.preventDefault();+ if (!isOpen) {+ onOpen();+ setHighlightedIndex(0);+ } else {+ const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);+ const nextPos = Math.min(+ currentEnabledPos + 1,+ enabledIndices.length - 1,+ );+ setHighlightedIndex(enabledIndices[nextPos] ?? highlightedIndex);+ }+ break;++ case 'ArrowUp':+ e.preventDefault();+ if (!isOpen) {+ onOpen();+ setHighlightedIndex(selectableItems.length - 1);+ } else {+ const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);+ const prevPos = Math.max(currentEnabledPos - 1, 0);+ setHighlightedIndex(enabledIndices[prevPos] ?? highlightedIndex);+ }+ break;++ case 'Enter':+ case ' ':+ // Don't intercept Space when search input is focused+ if (e.key === ' ' && hasSearch) {+ break;+ }+ e.preventDefault();+ if (isOpen && highlightedIndex >= 0) {+ const item = selectableItems[highlightedIndex];+ if (item && !item.disabled) {+ onToggle(item.value);+ }+ } else if (!isOpen) {+ onOpen();+ if (!hasSearch) {+ setHighlightedIndex(0);+ }+ }+ break;++ case 'Escape':+ if (isOpen) {+ e.preventDefault();+ closeAndReset();+ }+ break;++ case 'Home':+ e.preventDefault();+ if (isOpen && enabledIndices.length > 0) {+ setHighlightedIndex(enabledIndices[0]);+ }+ break;++ case 'End':+ e.preventDefault();+ if (isOpen && enabledIndices.length > 0) {+ setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);+ }+ break;++ default:+ // Typeahead only when search is not present+ if (!hasSearch && e.key.length === 1 && !e.ctrlKey && !e.metaKey) {+ const newTypeahead = typeahead + e.key.toLowerCase();+ setTypeahead(newTypeahead);++ if (typeaheadTimeoutRef.current) {+ clearTimeout(typeaheadTimeoutRef.current);+ }+ typeaheadTimeoutRef.current = setTimeout(() => {+ setTypeahead('');+ }, 500);++ const matchIndex = selectableItems.findIndex(+ item =>+ !item.disabled &&+ item.label?.toLowerCase().startsWith(newTypeahead),+ );+ if (matchIndex >= 0) {+ if (!isOpen) {+ onOpen();+ }+ setHighlightedIndex(matchIndex);+ }+ }+ break;+ }+ },+ [+ isDisabled,+ isOpen,+ onOpen,+ closeAndReset,+ selectableItems,+ highlightedIndex,+ onToggle,+ getEnabledIndices,+ typeahead,+ hasSearch,+ ],+ );++ return {+ highlightedIndex,+ setHighlightedIndex,+ getItemId,+ onTriggerClick,+ onKeyDown,+ onItemMouseEnter,+ };+}diff --git a/packages/core/src/MultiSelector/index.ts b/packages/core/src/MultiSelector/index.tsnew file mode 100644index 0000000000..0b80bdeef5--- /dev/null+++ b/packages/core/src/MultiSelector/index.ts@@ -0,0 +1,22 @@+'use client';++/**+ * @file index.ts+ * @output Exports XDSMultiSelector and types+ * @position Public API entry point+ */++export {+ XDSMultiSelector,+ type XDSMultiSelectorProps,+ type XDSMultiSelectorSize,+ type XDSMultiSelectorStatusType,+} from './XDSMultiSelector';+export type {+ XDSMultiSelectorOptionType,+ XDSMultiSelectorOptionData,+ XDSMultiSelectorDivider,+ XDSMultiSelectorSection,+ XDSMultiSelectorStatus,+} from './types';+export {useMultiCombobox} from './hooks';diff --git a/packages/core/src/MultiSelector/types.ts b/packages/core/src/MultiSelector/types.tsnew file mode 100644index 0000000000..d7e43bed46--- /dev/null+++ b/packages/core/src/MultiSelector/types.ts@@ -0,0 +1,26 @@+/**+ * @file types.ts+ * @input Imports types from ../Selector/types+ * @output Re-exports Selector types with MultiSelector aliases+ * @position Type definitions; used by XDSMultiSelector.tsx and hooks.ts+ *+ * SYNC: When modified, update:+ * - /packages/core/src/MultiSelector/index.ts+ */++import type {+ XDSSelectorOptionData,+ XDSSelectorDivider,+ XDSSelectorSection,+ XDSSelectorOptionType,+} from '../Selector/types';++export type XDSMultiSelectorOptionData = XDSSelectorOptionData;+export type XDSMultiSelectorDivider = XDSSelectorDivider;+export type XDSMultiSelectorSection = XDSSelectorSection;+export type XDSMultiSelectorOptionType = XDSSelectorOptionType;++export interface XDSMultiSelectorStatus {+ type: 'warning' | 'error' | 'success';+ message?: string;+}diff --git a/packages/core/src/index.ts b/packages/core/src/index.tsindex 82661370f8..67d277e260 100644--- a/packages/core/src/index.ts+++ b/packages/core/src/index.ts@@ -42,6 +42,7 @@ export * from './Grid';export * from './Section';export * from './SegmentedControl';export * from './Selector';+export * from './MultiSelector';export * from './Icon';export * from './Text';export * from './TextInput';