An open source design system that's fully customizable and agent ready
TypeScript
refactor(Selector): rename items → options across API (#479)
Cindy Zhangd08de6f74903
diff --git a/apps/storybook/stories/FormLayout.stories.tsx b/apps/storybook/stories/FormLayout.stories.tsxindex 582ca71751..aaa9cb5b7f 100644--- a/apps/storybook/stories/FormLayout.stories.tsx+++ b/apps/storybook/stories/FormLayout.stories.tsx@@ -93,7 +93,7 @@ export const HorizontalLabels: Story = {label="Timezone"value={timezone}onChange={v => setTimezone(v as string)}- items={[+ options={[{label: 'Pacific Time', value: 'America/Los_Angeles'},{label: 'Eastern Time', value: 'America/New_York'},{label: 'UTC', value: 'UTC'},@@ -131,7 +131,7 @@ export const MixedControls: Story = {label="Role"value={role}onChange={v => setRole(v as string)}- items={[+ options={[{label: 'Viewer', value: 'viewer'},{label: 'Editor', value: 'editor'},{label: 'Admin', value: 'admin'},diff --git a/apps/storybook/stories/Selector.stories.tsx b/apps/storybook/stories/Selector.stories.tsxindex acf995945d..1821768869 100644--- a/apps/storybook/stories/Selector.stories.tsx+++ b/apps/storybook/stories/Selector.stories.tsx@@ -1,6 +1,6 @@import type {Meta, StoryObj} from '@storybook/react';import {useState} from 'react';-import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';+import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';import {UserIcon, CogIcon, BellIcon} from '@heroicons/react/24/outline';const meta: Meta<typeof XDSSelector> = {@@ -30,10 +30,10 @@ const meta: Meta<typeof XDSSelector> = {control: 'text',description: 'Description text displayed between label and selector',},- items: {+ options: {control: 'object',description:- 'Array of items to display. Can be strings, objects, dividers, or sections.',+ 'Array of options to display. Can be strings, objects, dividers, or sections.',},value: {control: 'text',@@ -61,9 +61,9 @@ const meta: Meta<typeof XDSSelector> = {description: 'Whether the field is required',},children: {- description: 'Optional render function for custom item rendering',+ description: 'Optional render function for custom option rendering',table: {- type: {summary: '(item: XDSSelectorItemData) => ReactNode'},+ type: {summary: '(item: XDSSelectorOptionData) => ReactNode'},},},'data-testid': {@@ -84,8 +84,8 @@ export const Default: Story = {<XDSSelector{...args}label={args.label ?? 'Fruit'}- items={- args.items ?? ['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']+ options={+ args.options ?? ['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}value={value}onChange={setValue}@@ -106,7 +106,7 @@ export const HiddenLabel: Story = {{...args}label="Fruit"isLabelHidden- items={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}+ options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}value={value}onChange={setValue}placeholder="Select a fruit..."@@ -124,7 +124,7 @@ export const WithDescription: Story = {{...args}label="Fruit"description="Choose your favorite fruit from the list"- items={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}+ options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}value={value}onChange={setValue}placeholder="Select a fruit..."@@ -141,7 +141,7 @@ export const WithObjects: Story = {<XDSSelector{...args}label="Fruit"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},{value: 'orange', label: 'Orange', disabled: true},@@ -165,7 +165,7 @@ export const WithIcons: Story = {<XDSSelector{...args}label="Settings"- items={[+ options={[{value: 'profile', label: 'Profile', icon: UserIcon},{value: 'settings', label: 'Settings', icon: CogIcon},{value: 'notifications', label: 'Notifications', icon: BellIcon},@@ -188,13 +188,13 @@ export const WithSections: Story = {<XDSSelector{...args}label="Fruit"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},{type: 'section',title: 'Citrus',- items: [+ options: [{value: 'orange', label: 'Orange'},{value: 'lemon', label: 'Lemon'},{value: 'lime', label: 'Lime'},@@ -203,7 +203,7 @@ export const WithSections: Story = {{type: 'section',title: 'Tropical',- items: [+ options: [{value: 'mango', label: 'Mango'},{value: 'pineapple', label: 'Pineapple'},],@@ -232,12 +232,12 @@ export const CustomRender: Story = {<XDSSelector{...args}label="User"- items={users}+ options={users}value={value}onChange={setValue}placeholder="Select a user...">{user => (- <XDSSelectorItem+ <XDSSelectorOptionicon={UserIcon}label={user.label}description={(user as (typeof users)[number]).email}@@ -260,7 +260,7 @@ export const SizeVariants: Story = {<XDSSelectorlabel="Small"size="sm"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value1}onChange={setValue1}placeholder="Small size (28px)"@@ -268,7 +268,7 @@ export const SizeVariants: Story = {<XDSSelectorlabel="Medium"size="md"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value2}onChange={setValue2}placeholder="Medium size (32px)"@@ -276,7 +276,7 @@ export const SizeVariants: Story = {<XDSSelectorlabel="Large"size="lg"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value3}onChange={setValue3}placeholder="Large size (36px)"@@ -298,7 +298,7 @@ export const WithStatus: Story = {style={{display: 'flex', flexDirection: 'column', gap: 16, width: 250}}><XDSSelectorlabel="Error status"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},]}@@ -309,7 +309,7 @@ export const WithStatus: Story = {/><XDSSelectorlabel="Warning status"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},]}@@ -319,7 +319,7 @@ export const WithStatus: Story = {/><XDSSelectorlabel="Success status"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},]}@@ -344,7 +344,7 @@ export const OptionalRequired: Story = {<XDSSelectorlabel="Optional field"isOptional- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value1}onChange={setValue1}placeholder="Select a fruit..."@@ -352,7 +352,7 @@ export const OptionalRequired: Story = {<XDSSelectorlabel="Required field"isRequired- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value2}onChange={setValue2}placeholder="Select a fruit..."@@ -367,7 +367,7 @@ export const OptionalRequired: Story = {export const Disabled: Story = {args: {label: 'Fruit',- items: ['Apple', 'Banana', 'Orange'],+ options: ['Apple', 'Banana', 'Orange'],value: 'Apple',isDisabled: true,placeholder: 'Select a fruit...',@@ -382,7 +382,7 @@ export const PreSelected: Story = {<XDSSelector{...args}label="Fruit"- items={['Apple', 'Banana', 'Orange', 'Mango']}+ options={['Apple', 'Banana', 'Orange', 'Mango']}value={value}onChange={setValue}/>@@ -407,14 +407,14 @@ export const AllVariations: Story = {}}><XDSSelectorlabel="Default"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value1}onChange={setValue1}placeholder="Select..."/><XDSSelectorlabel="Pre-selected"- items={[+ options={[{value: 'apple', label: 'Apple'},{value: 'banana', label: 'Banana'},]}@@ -423,7 +423,7 @@ export const AllVariations: Story = {/><XDSSelectorlabel="With disabled option"- items={[+ options={[{value: 'apple', label: 'Apple', disabled: true},{value: 'banana', label: 'Banana'},]}@@ -433,7 +433,7 @@ export const AllVariations: Story = {/><XDSSelectorlabel="Disabled selector"- items={['Apple', 'Banana']}+ options={['Apple', 'Banana']}value={value4}onChange={setValue4}isDisableddiff --git a/internal/vibe-tests/selector-naming-test/prompts.json b/internal/vibe-tests/selector-naming-test/prompts.jsonnew file mode 100644index 0000000000..c547111c29--- /dev/null+++ b/internal/vibe-tests/selector-naming-test/prompts.json@@ -0,0 +1,66 @@+{+ "name": "selector-naming",+ "description": "Vibe test comparing 'items' vs 'options' naming for XDSSelector child elements",+ "variants": [+ "items",+ "options"+ ],+ "prompts": [+ {+ "id": "sel-1",+ "category": "form-select",+ "prompt": "Build a user registration form with fields for name, email, and a country selector dropdown with at least 10 countries grouped by continent.",+ "tests": "Basic selector with sections/groups, form integration",+ "notes": "Tests whether the LLM naturally uses items or options for grouped data"+ },+ {+ "id": "sel-2",+ "category": "form-select",+ "prompt": "Create a shipping method selector for a checkout page. Show three options: Standard (free, 5-7 days), Express ($9.99, 2-3 days), and Overnight ($24.99, next day). Each should show the name, price, and delivery time.",+ "tests": "Rich items/options with descriptions, custom rendering",+ "notes": "Tests custom render pattern \u2014 does the LLM use the children render prop correctly?"+ },+ {+ "id": "sel-3",+ "category": "form-select",+ "prompt": "Build a settings form where users pick their preferred language from a dropdown, their timezone from another dropdown, and their notification preference (All, Important Only, None) from a third.",+ "tests": "Multiple selectors in one form, simple string values",+ "notes": "Tests repeated selector usage \u2014 does naming stay consistent?"+ },+ {+ "id": "sel-4",+ "category": "action-menu",+ "prompt": "Create a project status updater. Show a selector with status values: To Do, In Progress, In Review, Done, and Blocked. Each status should have a colored icon. The current status should be displayed as a badge next to the selector.",+ "tests": "Items/options with icons, integration with other components",+ "notes": "Tests icon integration and whether naming causes confusion with badge/status components"+ },+ {+ "id": "sel-5",+ "category": "command-palette",+ "prompt": "Build a command palette style component where users can select an action from categorized groups: File actions (New, Open, Save), Edit actions (Cut, Copy, Paste), and View actions (Zoom In, Zoom Out, Full Screen). Use dividers between groups.",+ "tests": "Sections, dividers, non-form context",+ "notes": "Tests whether 'options' causes confusion in non-<select> contexts like command palettes"+ },+ {+ "id": "sel-6",+ "category": "filter",+ "prompt": "Create a data table filter bar with three selector dropdowns: Priority (Low, Medium, High, Critical), Assignee (list of team member names), and Status (Open, Closed, In Progress). Show a 'Clear Filters' button that resets all selectors.",+ "tests": "Multiple selectors as filters, controlled state, reset pattern",+ "notes": "Tests whether the LLM correctly manages controlled state across multiple selectors"+ },+ {+ "id": "sel-7",+ "category": "form-select",+ "prompt": "Build a role assignment form. Show a list of team members, each with a selector to assign their role: Viewer, Editor, Admin, or Owner. Disabled members should have their selector disabled too. Include validation \u2014 at least one Admin must be selected.",+ "tests": "Disabled items/options, validation, dynamic selector per row",+ "notes": "Tests disabled state and whether naming affects how the LLM handles item-level vs selector-level disabled"+ },+ {+ "id": "sel-8",+ "category": "form-select",+ "prompt": "Create a font picker dropdown that shows font names rendered in their actual font. Group fonts into categories: Sans-serif (Inter, Roboto, Open Sans), Serif (Georgia, Merriweather, Playfair Display), and Monospace (Fira Code, JetBrains Mono, Source Code Pro).",+ "tests": "Custom rendering with sections, rich visual content",+ "notes": "Tests custom children render prop with sections \u2014 complex composition"+ }+ ]+}\ No newline at end of filediff --git a/internal/vibe-tests/selector-naming-test/variant-a-items.md b/internal/vibe-tests/selector-naming-test/variant-a-items.mdnew file mode 100644index 0000000000..6ab404eef7--- /dev/null+++ b/internal/vibe-tests/selector-naming-test/variant-a-items.md@@ -0,0 +1,113 @@+# XDSSelector — Dropdown Selector Component++A dropdown selector for choosing from a list of items. Supports simple strings, rich items with icons/descriptions, sections, and dividers.++## Import++```tsx+import {XDSSelector, XDSSelectorItem} from '@xds/core';+```++## Basic Usage++```tsx+// Simple string items+<XDSSelector+ label="Fruit"+ items={['Apple', 'Banana', 'Orange']}+ value={fruit}+ onChange={setFruit}+ placeholder="Select a fruit..."+/>++// Rich items with icons and descriptions+<XDSSelector+ label="Status"+ items={[+ { value: 'active', label: 'Active', icon: 'checkCircle' },+ { value: 'paused', label: 'Paused', icon: 'pause' },+ { value: 'archived', label: 'Archived', icon: 'archive' },+ ]}+ value={status}+ onChange={setStatus}+/>++// Sections and dividers+<XDSSelector+ label="Action"+ items={[+ { type: 'section', title: 'Edit', items: [+ { value: 'cut', label: 'Cut' },+ { value: 'copy', label: 'Copy' },+ ]},+ { type: 'divider' },+ { type: 'section', title: 'View', items: [+ { value: 'zoom-in', label: 'Zoom In' },+ { value: 'zoom-out', label: 'Zoom Out' },+ ]},+ ]}+ value={action}+ onChange={setAction}+/>+```++## Custom Item Rendering++```tsx+<XDSSelector+ label="User"+ items={users.map(u => ({value: u.id, label: u.name, icon: 'user'}))}+ value={selectedUser}+ onChange={setSelectedUser}>+ {item => (+ <XDSSelectorItem+ icon={item.icon}+ label={item.label}+ description={item.email}+ />+ )}+</XDSSelector>+```++## Props++### XDSSelector++| Prop | Type | Default | Description |+| -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |+| label | string | required | Label text (always rendered for a11y) |+| items | Array<string \| ItemData \| Divider \| Section> | required | The items to display |+| value | string | — | Currently selected value |+| onChange | (value: string) => void | — | Selection change callback |+| onChangeAction | (value: string) => Promise<void> | — | Async action on change |+| placeholder | string | 'Select...' | Placeholder when nothing selected |+| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |+| isDisabled | boolean | false | Disabled state |+| isLabelHidden | boolean | false | Visually hide label |+| description | string | — | Help text below label |+| isOptional | boolean | false | Show optional indicator |+| isRequired | boolean | false | Show required indicator |+| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |+| children | (item: ItemData) => ReactNode | — | Custom item renderer |++### XDSSelectorItem (for custom rendering)++| Prop | Type | Description |+| ----------- | ----------- | ------------------ |+| icon | XDSIconType | Leading icon |+| label | ReactNode | Primary text |+| description | ReactNode | Secondary text |+| children | ReactNode | Additional content |++### Item Types++```ts+type ItemData = {+ value: string;+ label?: string;+ disabled?: boolean;+ icon?: XDSIconType;+};+type Divider = {type: 'divider'};+type Section = {type: 'section'; title?: string; items: ItemData[]};+```diff --git a/internal/vibe-tests/selector-naming-test/variant-b-options.md b/internal/vibe-tests/selector-naming-test/variant-b-options.mdnew file mode 100644index 0000000000..104ebf0f04--- /dev/null+++ b/internal/vibe-tests/selector-naming-test/variant-b-options.md@@ -0,0 +1,113 @@+# XDSSelector — Dropdown Selector Component++A dropdown selector for choosing from a list of options. Supports simple strings, rich options with icons/descriptions, sections, and dividers.++## Import++```tsx+import {XDSSelector, XDSSelectorOption} from '@xds/core';+```++## Basic Usage++```tsx+// Simple string options+<XDSSelector+ label="Fruit"+ options={['Apple', 'Banana', 'Orange']}+ value={fruit}+ onChange={setFruit}+ placeholder="Select a fruit..."+/>++// Rich options with icons and descriptions+<XDSSelector+ label="Status"+ options={[+ { value: 'active', label: 'Active', icon: 'checkCircle' },+ { value: 'paused', label: 'Paused', icon: 'pause' },+ { value: 'archived', label: 'Archived', icon: 'archive' },+ ]}+ value={status}+ onChange={setStatus}+/>++// Sections and dividers+<XDSSelector+ label="Action"+ options={[+ { type: 'section', title: 'Edit', options: [+ { value: 'cut', label: 'Cut' },+ { value: 'copy', label: 'Copy' },+ ]},+ { type: 'divider' },+ { type: 'section', title: 'View', options: [+ { value: 'zoom-in', label: 'Zoom In' },+ { value: 'zoom-out', label: 'Zoom Out' },+ ]},+ ]}+ value={action}+ onChange={setAction}+/>+```++## Custom Option Rendering++```tsx+<XDSSelector+ label="User"+ options={users.map(u => ({value: u.id, label: u.name, icon: 'user'}))}+ value={selectedUser}+ onChange={setSelectedUser}>+ {option => (+ <XDSSelectorOption+ icon={option.icon}+ label={option.label}+ description={option.email}+ />+ )}+</XDSSelector>+```++## Props++### XDSSelector++| Prop | Type | Default | Description |+| -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------- |+| label | string | required | Label text (always rendered for a11y) |+| options | Array<string \| OptionData \| Divider \| Section> | required | The options to display |+| value | string | — | Currently selected value |+| onChange | (value: string) => void | — | Selection change callback |+| onChangeAction | (value: string) => Promise<void> | — | Async action on change |+| placeholder | string | 'Select...' | Placeholder when nothing selected |+| size | 'sm' \| 'md' \| 'lg' | 'md' | Trigger size |+| isDisabled | boolean | false | Disabled state |+| isLabelHidden | boolean | false | Visually hide label |+| description | string | — | Help text below label |+| isOptional | boolean | false | Show optional indicator |+| isRequired | boolean | false | Show required indicator |+| status | { type: 'warning' \| 'error' \| 'success', message?: string } | — | Validation status |+| children | (option: OptionData) => ReactNode | — | Custom option renderer |++### XDSSelectorOption (for custom rendering)++| Prop | Type | Description |+| ----------- | ----------- | ------------------ |+| icon | XDSIconType | Leading icon |+| label | ReactNode | Primary text |+| description | ReactNode | Secondary text |+| children | ReactNode | Additional content |++### Option Types++```ts+type OptionData = {+ value: string;+ label?: string;+ disabled?: boolean;+ icon?: XDSIconType;+};+type Divider = {type: 'divider'};+type Section = {type: 'section'; title?: string; options: OptionData[]};+```diff --git a/internal/vibe-tests/src/universal-eval.ts b/internal/vibe-tests/src/universal-eval.tsindex 7a803a8dd5..01ade1ec59 100644--- a/internal/vibe-tests/src/universal-eval.ts+++ b/internal/vibe-tests/src/universal-eval.ts@@ -115,7 +115,7 @@ function discoverXDSComponents(): Set<string> {'XDSRadioListItem','XDSSection','XDSSelector',- 'XDSSelectorItem',+ 'XDSSelectorOption','XDSSkeleton','XDSSlider','XDSSpinner',diff --git a/packages/core/src/Pagination/XDSPagination.tsx b/packages/core/src/Pagination/XDSPagination.tsxindex 088bb65344..5eff85da39 100644--- a/packages/core/src/Pagination/XDSPagination.tsx+++ b/packages/core/src/Pagination/XDSPagination.tsx@@ -537,7 +537,7 @@ export const XDSPagination = forwardRef<HTMLElement, XDSPaginationProps>(<XDSSelectorlabel="Items per page"isLabelHidden- items={pageSizeOptions.map(opt => String(opt))}+ options={pageSizeOptions.map(opt => String(opt))}value={String(pageSize)}onChange={handlePageSizeChange}size={buttonSize}diff --git a/packages/core/src/Selector/README.md b/packages/core/src/Selector/README.mdindex 6926b29348..50c757acd6 100644--- a/packages/core/src/Selector/README.md+++ b/packages/core/src/Selector/README.md@@ -5,20 +5,20 @@ Dropdown selector for choosing from a list of options. Follows XDS input convent## Usage```tsx-import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';+import {XDSSelector, XDSSelectorOption} from '@xds/core/Selector';// Basic usage (label is required)<XDSSelectorlabel="Fruit"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value}onChange={setValue}/>-// With object items (supports disabled, icons)+// With object options (supports disabled, icons)<XDSSelectorlabel="Settings"- items={[+ options={[{value: 'profile', label: 'Profile', icon: UserIcon},{value: 'settings', label: 'Settings', icon: CogIcon, disabled: true},]}@@ -29,9 +29,9 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';// Sections (automatically include labeled dividers)<XDSSelectorlabel="Fruit"- items={[+ options={[{value: 'apple', label: 'Apple'},- {type: 'section', title: 'Citrus', items: [+ {type: 'section', title: 'Citrus', options: [{value: 'orange', label: 'Orange'},]},]}@@ -39,13 +39,13 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';onChange={setValue}/>-// Custom rendering with XDSSelectorItem-<XDSSelector label="User" items={users} value={value} onChange={setValue}>- {user => (- <XDSSelectorItem+// Custom rendering with XDSSelectorOption+<XDSSelector label="User" options={users} value={value} onChange={setValue}>+ {option => (+ <XDSSelectorOptionicon={UserIcon}- label={user.label}- description={user.email}+ label={option.label}+ description={option.email}/>)}</XDSSelector>@@ -55,7 +55,7 @@ import {XDSSelector, XDSSelectorItem} from '@xds/core/Selector';label="Fruit"isRequiredstatus={{type: 'error', message: 'Required'}}- items={['Apple', 'Banana']}+ options={['Apple', 'Banana']}value={value}onChange={setValue}/>@@ -68,28 +68,28 @@ Dropdown selector for choosing from a list of options.```tsx<XDSSelectorlabel="Fruit"- items={['Apple', 'Banana', 'Orange']}+ options={['Apple', 'Banana', 'Orange']}value={value}onChange={setValue}/>```-| Prop | Type | Description |-| --------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------- |-| `label` | `string` | **Required.** Label text for accessibility |-| `items` | `XDSSelectorOption[]` | **Required.** Array of items (strings, objects, dividers, sections) |-| `value` | `string` | Selected value |-| `onChange` | `(value: string) => void` | Selection callback |-| `placeholder` | `string` | Placeholder text (default: `'Select...'`) |-| `size` | `'sm' \| 'md' \| 'lg'` | Size variant (default: `'md'`) |-| `isDisabled` | `boolean` | Disable selector |-| `isLabelHidden` | `boolean` | Visually hide label |-| `description` | `string` | Helper text below label |-| `isOptional` / `isRequired` | `boolean` | Field requirement indicators |-| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | Status with optional message |-| `children` | `(item: XDSSelectorItemData) => ReactNode` | Custom item renderer |--## Item Types+| Prop | Type | Description |+| --------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------- |+| `label` | `string` | **Required.** Label text for accessibility |+| `options` | `XDSSelectorOptionType[]` | **Required.** Array of options (strings, objects, dividers, sections) |+| `value` | `string` | Selected value |+| `onChange` | `(value: string) => void` | Selection callback |+| `placeholder` | `string` | Placeholder text (default: `'Select...'`) |+| `size` | `'sm' \| 'md' \| 'lg'` | Size variant (default: `'md'`) |+| `isDisabled` | `boolean` | Disable selector |+| `isLabelHidden` | `boolean` | Visually hide label |+| `description` | `string` | Helper text below label |+| `isOptional` / `isRequired` | `boolean` | Field requirement indicators |+| `status` | `{type: 'error'\|'warning'\|'success', message?: string}` | Status with optional message |+| `children` | `(option: XDSSelectorOptionData) => ReactNode` | Custom option renderer |++## Option Types```tsx// String - converted to {value: 'Apple', label: 'Apple'}@@ -101,27 +101,27 @@ Dropdown selector for choosing from a list of options.// Divider - horizontal separator{type: 'divider'}-// Section - grouped items with labeled divider-{type: 'section', title: 'Group Name', items: [...]}+// Section - grouped options with labeled divider+{type: 'section', title: 'Group Name', options: [...]}```-### XDSSelectorItem+### XDSSelectorOption-Helper for custom item rendering:+Helper for custom option rendering:```tsx-<XDSSelectorItem+<XDSSelectorOptionicon={UserIcon}label="Primary text"description="Secondary"/>```-| Prop | Type | Default | Description |-| ------------- | ------------- | ------- | --------------------------------- |-| `icon` | `XDSIconType` | — | Icon before the label |-| `label` | `ReactNode` | — | Primary label text (required) |-| `description` | `ReactNode` | — | Secondary description text |+| Prop | Type | Default | Description |+| ------------- | ------------- | ------- | ----------------------------- |+| `icon` | `XDSIconType` | — | Icon before the label |+| `label` | `ReactNode` | — | Primary label text (required) |+| `description` | `ReactNode` | — | Secondary description text |## Keyboarddiff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsxindex 13257800c6..3928db8537 100644--- a/packages/core/src/Selector/XDSSelector.tsx+++ b/packages/core/src/Selector/XDSSelector.tsx@@ -41,16 +41,16 @@ import {fontWeightVars,lineHeightVars,} from '../theme/tokens.stylex';-import {type XDSSelectorOption, type XDSSelectorItemData} from './types';+import {type XDSSelectorOptionType, type XDSSelectorOptionData} from './types';import {- isItemData,+ isOptionData,isDivider,isSection,- normalizeItem,- getSelectableItems,+ normalizeOption,+ getSelectableOptions,} from './utils';import {useCombobox, useSelectedItemOffset} from './hooks';-import {XDSSelectorItem} from './XDSSelectorItem';+import {XDSSelectorOption} from './XDSSelectorOption';import {ThemeContext} from '../theme/ThemeContext';import type {StyleXStyles as ThemeStyleXStyles} from '../theme/types';@@ -257,7 +257,7 @@ declare module '../theme/types' {}}export interface XDSSelectorProps<- T extends XDSSelectorOption = XDSSelectorOption,+ T extends XDSSelectorOptionType = XDSSelectorOptionType,> {/*** Label text for the selector (always rendered for accessibility).@@ -294,10 +294,10 @@ export interface XDSSelectorProps<isDisabled?: boolean;/**- * The items to display in the selector.+ * The options to display in the selector.* Can be strings, objects, dividers, or sections.*/- items: T[];+ options: T[];/*** The currently selected value.@@ -347,10 +347,10 @@ export interface XDSSelectorProps<labelTooltip?: string;/**- * Custom render function for items.- * Only called for selectable items (not dividers/sections).+ * Custom render function for options.+ * Only called for selectable options (not dividers/sections).*/- children?: (item: XDSSelectorItemData) => ReactNode;+ children?: (option: XDSSelectorOptionData) => ReactNode;/*** Test ID for testing frameworks.@@ -359,10 +359,15 @@ export interface XDSSelectorProps<}/**- * Default item renderer+ * Default option renderer*/-function DefaultItem({item}: {item: XDSSelectorItemData}) {- return <XDSSelectorItem icon={item.icon} label={item.label ?? item.value} />;+function DefaultOption({option}: {option: XDSSelectorOptionData}) {+ return (+ <XDSSelectorOption+ icon={option.icon}+ label={option.label ?? option.value}+ />+ );}/**@@ -372,21 +377,21 @@ function DefaultItem({item}: {item: XDSSelectorItemData}) {* ```* <XDSSelector* label="Fruit"- * items={['Apple', 'Banana', 'Orange']}+ * options={['Apple', 'Banana', 'Orange']}* value={fruit}* onChange={setFruit}* placeholder="Select a fruit..."* />* ```*/-export function XDSSelector<T extends XDSSelectorOption>({+export function XDSSelector<T extends XDSSelectorOptionType>({label,isLabelHidden = false,description,isOptional = false,isRequired = false,isDisabled = false,- items,+ options,value,onChange,onChangeAction,@@ -421,8 +426,11 @@ export function XDSSelector<T extends XDSSelectorOption>({.filter(Boolean).join(' ') || undefined;- // Flatten items for keyboard navigation- const selectableItems = useMemo(() => getSelectableItems(items), [items]);+ // Flatten options for keyboard navigation+ const selectableItems = useMemo(+ () => getSelectableOptions(options),+ [options],+ );// Find selected item and its index for positioningconst selectedItemIndex = useMemo(() => {@@ -489,7 +497,7 @@ export function XDSSelector<T extends XDSSelectorOption>({// Render an individual itemconst renderItem = useCallback(- (item: XDSSelectorItemData, flatIndex: number) => {+ (item: XDSSelectorOptionData, flatIndex: number) => {const isHighlighted = flatIndex === highlightedIndex;const isSelected = item.value === value;@@ -509,7 +517,7 @@ export function XDSSelector<T extends XDSSelectorOption>({item.disabled && styles.itemDisabled,)}><span {...stylex.props(styles.itemContent)}>- {children ? children(item) : <DefaultItem item={item} />}+ {children ? children(item) : <DefaultOption option={item} />}</span>{isSelected && <XDSIcon icon="check" size="sm" color="accent" />}</div>@@ -530,8 +538,8 @@ export function XDSSelector<T extends XDSSelectorOption>({let flatIndex = 0;const elements: ReactNode[] = [];- for (let i = 0; i < items.length; i++) {- const option = items[i];+ for (let i = 0; i < options.length; i++) {+ const option = options[i];if (isDivider(option)) {elements.push(@@ -539,8 +547,8 @@ export function XDSSelector<T extends XDSSelectorOption>({);} else if (isSection(option)) {const sectionItems: ReactNode[] = [];- for (const item of option.items) {- sectionItems.push(renderItem(normalizeItem(item), flatIndex));+ for (const opt of option.options) {+ sectionItems.push(renderItem(normalizeOption(opt), flatIndex));flatIndex++;}// Render divider with label before the group@@ -558,14 +566,14 @@ export function XDSSelector<T extends XDSSelectorOption>({{sectionItems}</div>,);- } else if (isItemData(option)) {- elements.push(renderItem(normalizeItem(option), flatIndex));+ } else if (isOptionData(option)) {+ elements.push(renderItem(normalizeOption(option), flatIndex));flatIndex++;}}return elements;- }, [items, renderItem, listboxId]);+ }, [options, renderItem, listboxId]);return (<XDSFielddiff --git a/packages/core/src/Selector/XDSSelectorItem.tsx b/packages/core/src/Selector/XDSSelectorItem.tsxindex b5b6078278..d20481ff73 100644--- a/packages/core/src/Selector/XDSSelectorItem.tsx+++ b/packages/core/src/Selector/XDSSelectorItem.tsx@@ -1,110 +1,10 @@/*** @file XDSSelectorItem.tsx- * @output Exports XDSSelectorItem component for custom item rendering- * @position Sub-component; used by XDSSelector and consumers for custom items+ * @deprecated Use XDSSelectorOption from './XDSSelectorOption' instead+ * @output Re-exports XDSSelectorOption as XDSSelectorItem for backward compatibility*/-import type {ReactNode} from 'react';-import * as stylex from '@stylexjs/stylex';-import type {StyleXStyles} from '@stylexjs/stylex';-import {XDSIcon} from '../Icon';-import type {XDSIconType} from '../Icon';-import {XDSText} from '../Text';-import {spacingVars} from '../theme/tokens.stylex';--const styles = stylex.create({- root: {- display: 'flex',- alignItems: 'center',- gap: spacingVars['--spacing-2'],- flex: 1,- minWidth: 0,- },- content: {- display: 'flex',- flexDirection: 'column',- flex: 1,- minWidth: 0,- },-});--export interface XDSSelectorItemProps {- /**- * Icon to display before the label.- */- icon?: XDSIconType;-- /**- * Primary label text.- */- label: ReactNode;-- /**- * Secondary description text displayed below the label.- */- description?: ReactNode;-- /**- * Additional content to render after the label/description.- */- children?: ReactNode;-- /**- * StyleX styles for the root container.- */- xstyle?: StyleXStyles;-}--/**- * A helper component for rendering custom selector items with consistent styling.- *- * Use this inside the `children` render prop of XDSSelector to create- * custom item layouts while maintaining design system consistency.- *- * @example- * ```- * <XDSSelector- * label="User"- * items={users}- * value={value}- * onChange={setValue}>- * {item => (- * <XDSSelectorItem- * icon={UserIcon}- * label={item.label}- * description={item.email}- * />- * )}- * </XDSSelector>- * ```- */-export function XDSSelectorItem({- icon,- label,- description,- children,- xstyle,-}: XDSSelectorItemProps) {- return (- <span {...stylex.props(styles.root, xstyle)}>- {icon && <XDSIcon icon={icon} size="sm" color="secondary" />}- <span {...stylex.props(styles.content)}>- {typeof label === 'string' ? (- <XDSText type="body" maxLines={1}>- {label}- </XDSText>- ) : (- label- )}- {description && (- <XDSText type="supporting" maxLines={1}>- {description}- </XDSText>- )}- </span>- {children}- </span>- );-}--XDSSelectorItem.displayName = 'XDSSelectorItem';+export {+ XDSSelectorOption as XDSSelectorItem,+ type XDSSelectorOptionProps as XDSSelectorItemProps,+} from './XDSSelectorOption';diff --git a/packages/core/src/Selector/XDSSelectorOption.tsx b/packages/core/src/Selector/XDSSelectorOption.tsxnew file mode 100644index 0000000000..45e9d20a14--- /dev/null+++ b/packages/core/src/Selector/XDSSelectorOption.tsx@@ -0,0 +1,115 @@+/**+ * @file XDSSelectorOption.tsx+ * @output Exports XDSSelectorOption component for custom option rendering+ * @position Sub-component; used by XDSSelector and consumers for custom options+ */++import type {ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import type {StyleXStyles} from '@stylexjs/stylex';+import {XDSIcon} from '../Icon';+import type {XDSIconType} from '../Icon';+import {XDSText} from '../Text';+import {spacingVars} from '../theme/tokens.stylex';++const styles = stylex.create({+ root: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ flex: 1,+ minWidth: 0,+ },+ content: {+ display: 'flex',+ flexDirection: 'column',+ flex: 1,+ minWidth: 0,+ },+});++export interface XDSSelectorOptionProps {+ /**+ * Icon to display before the label.+ */+ icon?: XDSIconType;++ /**+ * Primary label text.+ */+ label: ReactNode;++ /**+ * Secondary description text displayed below the label.+ */+ description?: ReactNode;++ /**+ * Additional content to render after the label/description.+ */+ children?: ReactNode;++ /**+ * StyleX styles for the root container.+ */+ xstyle?: StyleXStyles;+}++/**+ * A helper component for rendering custom selector options with consistent styling.+ *+ * Use this inside the `children` render prop of XDSSelector to create+ * custom option layouts while maintaining design system consistency.+ *+ * @example+ * ```+ * <XDSSelector+ * label="User"+ * options={users}+ * value={value}+ * onChange={setValue}>+ * {option => (+ * <XDSSelectorOption+ * icon={UserIcon}+ * label={option.label}+ * description={option.email}+ * />+ * )}+ * </XDSSelector>+ * ```+ */+export function XDSSelectorOption({+ icon,+ label,+ description,+ children,+ xstyle,+}: XDSSelectorOptionProps) {+ return (+ <span {...stylex.props(styles.root, xstyle)}>+ {icon && <XDSIcon icon={icon} size="sm" color="secondary" />}+ <span {...stylex.props(styles.content)}>+ {typeof label === 'string' ? (+ <XDSText type="body" maxLines={1}>+ {label}+ </XDSText>+ ) : (+ label+ )}+ {description && (+ <XDSText type="supporting" maxLines={1}>+ {description}+ </XDSText>+ )}+ </span>+ {children}+ </span>+ );+}++XDSSelectorOption.displayName = 'XDSSelectorOption';++/**+ * @deprecated Use XDSSelectorOption instead (renamed from XDSSelectorItem)+ */+export const XDSSelectorItem = XDSSelectorOption;diff --git a/packages/core/src/Selector/hooks.ts b/packages/core/src/Selector/hooks.tsindex 4d7b86de58..f2824bbeb3 100644--- a/packages/core/src/Selector/hooks.ts+++ b/packages/core/src/Selector/hooks.ts@@ -6,7 +6,7 @@import {useCallback, useLayoutEffect, useRef, useState} from 'react';import type {RefObject} from 'react';-import type {XDSSelectorItemData} from './types';+import type {XDSSelectorOptionData} from './types';// =============================================================================// useSelectedItemOffset - Position dropdown to center selected item over trigger@@ -93,7 +93,7 @@ export function useSelectedItemOffset({// =============================================================================interface UseComboboxOptions {- selectableItems: XDSSelectorItemData[];+ selectableItems: XDSSelectorOptionData[];value?: string;isDisabled?: boolean;isOpen: boolean;@@ -109,8 +109,8 @@ interface UseComboboxResult {getItemId: (index: number) => string;onTriggerClick: () => void;onKeyDown: (e: React.KeyboardEvent) => void;- onItemSelect: (item: XDSSelectorItemData) => void;- onItemMouseEnter: (item: XDSSelectorItemData, index: number) => void;+ onItemSelect: (item: XDSSelectorOptionData) => void;+ onItemMouseEnter: (item: XDSSelectorOptionData, index: number) => void;}/**@@ -153,7 +153,7 @@ export function useCombobox({}, [onClose]);const selectItem = useCallback(- (item: XDSSelectorItemData) => {+ (item: XDSSelectorOptionData) => {if (item.disabled) return;onSelect?.(item.value);closeAndReset();@@ -173,7 +173,7 @@ export function useCombobox({}, [isDisabled, isOpen, onOpen, closeAndReset, findSelectedIndex]);const onItemMouseEnter = useCallback(- (item: XDSSelectorItemData, index: number) => {+ (item: XDSSelectorOptionData, index: number) => {if (!item.disabled) {setHighlightedIndex(index);}diff --git a/packages/core/src/Selector/index.ts b/packages/core/src/Selector/index.tsindex ea394ffb53..03392cbca2 100644--- a/packages/core/src/Selector/index.ts+++ b/packages/core/src/Selector/index.ts@@ -11,18 +11,29 @@ export {type XDSSelectorStatus,type XDSSelectorStatusType,} from './XDSSelector';-export {XDSSelectorItem, type XDSSelectorItemProps} from './XDSSelectorItem';-export type {+export {XDSSelectorOption,- XDSSelectorItemData,+ type XDSSelectorOptionProps,+} from './XDSSelectorOption';+export type {+ XDSSelectorOptionType,+ XDSSelectorOptionData,XDSSelectorDivider,XDSSelectorSection,} from './types';export {- isItemData,+ isOptionData,isDivider,isSection,- normalizeItem,- getSelectableItems,+ normalizeOption,+ getSelectableOptions,} from './utils';export {useCombobox, useSelectedItemOffset} from './hooks';++// Backward compatibility — deprecated exports+export {XDSSelectorItem, type XDSSelectorItemProps} from './XDSSelectorItem';+export type {+ XDSSelectorOption as XDSSelectorOptionLegacy,+ XDSSelectorItemData,+} from './types';+export {isItemData, normalizeItem, getSelectableItems} from './utils';diff --git a/packages/core/src/Selector/types.ts b/packages/core/src/Selector/types.tsindex ce2900655f..1a3029df9e 100644--- a/packages/core/src/Selector/types.ts+++ b/packages/core/src/Selector/types.ts@@ -7,9 +7,9 @@import type {XDSIconType} from '../Icon';/**- * A selectable item in the selector+ * A selectable option in the selector*/-export type XDSSelectorItemData = {+export type XDSSelectorOptionData = {value: string;label?: string;disabled?: boolean;@@ -17,26 +17,37 @@ export type XDSSelectorItemData = {};/**- * A divider between items+ * A divider between options*/export type XDSSelectorDivider = {type: 'divider';};/**- * A section/group of items with optional title+ * A section/group of options with optional title*/export type XDSSelectorSection = {type: 'section';title?: string;- items: XDSSelectorItemData[];+ options: XDSSelectorOptionData[];};/**- * Union of all option types+ * Union of all option types passed to the `options` prop.+ * Can be a plain string, option data object, divider, or section.*/-export type XDSSelectorOption =+export type XDSSelectorOptionType =| string- | XDSSelectorItemData+ | XDSSelectorOptionData| XDSSelectorDivider| XDSSelectorSection;++/**+ * @deprecated Use XDSSelectorOptionType instead+ */+export type XDSSelectorOption = XDSSelectorOptionType;++/**+ * @deprecated Use XDSSelectorOptionData instead+ */+export type XDSSelectorItemData = XDSSelectorOptionData;diff --git a/packages/core/src/Selector/utils.ts b/packages/core/src/Selector/utils.tsindex bc54ec5158..5aaa79b99b 100644--- a/packages/core/src/Selector/utils.ts+++ b/packages/core/src/Selector/utils.ts@@ -5,18 +5,18 @@*/import type {- XDSSelectorOption,- XDSSelectorItemData,+ XDSSelectorOptionType,+ XDSSelectorOptionData,XDSSelectorDivider,XDSSelectorSection,} from './types';/**- * Type guard: check if option is a selectable item (string or ItemData)+ * Type guard: check if option is a selectable option (string or OptionData)*/-export function isItemData(- option: XDSSelectorOption,-): option is XDSSelectorItemData | string {+export function isOptionData(+ option: XDSSelectorOptionType,+): option is XDSSelectorOptionData | string {if (typeof option === 'string') return true;return !('type' in option);}@@ -25,7 +25,7 @@ export function isItemData(* Type guard: check if option is a divider*/export function isDivider(- option: XDSSelectorOption,+ option: XDSSelectorOptionType,): option is XDSSelectorDivider {return (typeof option === 'object' && 'type' in option && option.type === 'divider'@@ -36,7 +36,7 @@ export function isDivider(* Type guard: check if option is a section*/export function isSection(- option: XDSSelectorOption,+ option: XDSSelectorOptionType,): option is XDSSelectorSection {return (typeof option === 'object' && 'type' in option && option.type === 'section'@@ -44,11 +44,11 @@ export function isSection(}/**- * Normalize string or item to consistent shape+ * Normalize string or option to consistent shape*/-export function normalizeItem(- option: string | XDSSelectorItemData,-): XDSSelectorItemData {+export function normalizeOption(+ option: string | XDSSelectorOptionData,+): XDSSelectorOptionData {if (typeof option === 'string') {return {value: option, label: option};}@@ -59,23 +59,38 @@ export function normalizeItem(}/**- * Get all selectable items from options (flattening sections)+ * Get all selectable options (flattening sections)*/-export function getSelectableItems(- options: XDSSelectorOption[],-): XDSSelectorItemData[] {- const items: XDSSelectorItemData[] = [];+export function getSelectableOptions(+ options: XDSSelectorOptionType[],+): XDSSelectorOptionData[] {+ const result: XDSSelectorOptionData[] = [];for (const option of options) {- if (isItemData(option)) {- items.push(normalizeItem(option));+ if (isOptionData(option)) {+ result.push(normalizeOption(option));} else if (isSection(option)) {- for (const item of option.items) {- items.push(normalizeItem(item));+ for (const opt of option.options) {+ result.push(normalizeOption(opt));}}// Skip dividers}- return items;+ return result;}++/**+ * @deprecated Use isOptionData instead+ */+export const isItemData = isOptionData;++/**+ * @deprecated Use normalizeOption instead+ */+export const normalizeItem = normalizeOption;++/**+ * @deprecated Use getSelectableOptions instead+ */+export const getSelectableItems = getSelectableOptions;