Skip to content

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.tsx
index 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.tsx
index 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
+ <XDSSelectorOption
icon={UserIcon}
label={user.label}
description={(user as (typeof users)[number]).email}
@@ -260,7 +260,7 @@ export const SizeVariants: Story = {
<XDSSelector
label="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 = {
<XDSSelector
label="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 = {
<XDSSelector
label="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}}>
<XDSSelector
label="Error status"
- items={[
+ options={[
{value: 'apple', label: 'Apple'},
{value: 'banana', label: 'Banana'},
]}
@@ -309,7 +309,7 @@ export const WithStatus: Story = {
/>
<XDSSelector
label="Warning status"
- items={[
+ options={[
{value: 'apple', label: 'Apple'},
{value: 'banana', label: 'Banana'},
]}
@@ -319,7 +319,7 @@ export const WithStatus: Story = {
/>
<XDSSelector
label="Success status"
- items={[
+ options={[
{value: 'apple', label: 'Apple'},
{value: 'banana', label: 'Banana'},
]}
@@ -344,7 +344,7 @@ export const OptionalRequired: Story = {
<XDSSelector
label="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 = {
<XDSSelector
label="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 = {
}}>
<XDSSelector
label="Default"
- items={['Apple', 'Banana', 'Orange']}
+ options={['Apple', 'Banana', 'Orange']}
value={value1}
onChange={setValue1}
placeholder="Select..."
/>
<XDSSelector
label="Pre-selected"
- items={[
+ options={[
{value: 'apple', label: 'Apple'},
{value: 'banana', label: 'Banana'},
]}
@@ -423,7 +423,7 @@ export const AllVariations: Story = {
/>
<XDSSelector
label="With disabled option"
- items={[
+ options={[
{value: 'apple', label: 'Apple', disabled: true},
{value: 'banana', label: 'Banana'},
]}
@@ -433,7 +433,7 @@ export const AllVariations: Story = {
/>
<XDSSelector
label="Disabled selector"
- items={['Apple', 'Banana']}
+ options={['Apple', 'Banana']}
value={value4}
onChange={setValue4}
isDisabled
diff --git a/internal/vibe-tests/selector-naming-test/prompts.json b/internal/vibe-tests/selector-naming-test/prompts.json
new file mode 100644
index 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 file
diff --git a/internal/vibe-tests/selector-naming-test/variant-a-items.md b/internal/vibe-tests/selector-naming-test/variant-a-items.md
new file mode 100644
index 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.md
new file mode 100644
index 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.ts
index 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.tsx
index 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>(
<XDSSelector
label="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.md
index 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)
<XDSSelector
label="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)
<XDSSelector
label="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)
<XDSSelector
label="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 => (
+ <XDSSelectorOption
icon={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"
isRequired
status={{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
<XDSSelector
label="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
+<XDSSelectorOption
icon={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 |
## Keyboard
diff --git a/packages/core/src/Selector/XDSSelector.tsx b/packages/core/src/Selector/XDSSelector.tsx
index 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 positioning
const selectedItemIndex = useMemo(() => {
@@ -489,7 +497,7 @@ export function XDSSelector<T extends XDSSelectorOption>({
// Render an individual item
const 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 (
<XDSField
diff --git a/packages/core/src/Selector/XDSSelectorItem.tsx b/packages/core/src/Selector/XDSSelectorItem.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;