@cube-dev/ui-kit 0.121.0 → 0.121.1

package/docs/components/fields/ListBox.md

@@ -0,0 +1,714 @@
+# ListBox
+
+A versatile list selection component that allows users to select one or more items from a list of options. Built with React Aria's accessibility features and the Cube `tasty` style system, it supports sections, descriptions, keyboard navigation, and virtualization for large datasets.
+
+## When to Use
+
+- Present a list of selectable options in a contained area
+- Enable single or multiple selection from a set of choices
+- Display structured data with sections and descriptions
+- Create custom selection interfaces that need to remain visible
+- Build form controls that require persistent option visibility
+- Handle lists of any size (virtualization is automatic for flat lists)
+- When you need rich option content (icons, descriptions, badges, hotkeys)
+- For multiple selection with clear visual feedback (checkboxes)
+- When options should always be visible (for searchable lists, consider FilterListBox)
+
+## Component
+
+---
+
+### Properties
+
+- **`selectedKey`** `string` — The selected key in controlled mode
+- **`defaultSelectedKey`** `string` — The default selected key in uncontrolled mode
+- **`selectedKeys`** `string[] | 'all'` — The selected keys in controlled multiple mode. Use "all" to select all items or an array of keys.
+- **`defaultSelectedKeys`** `string[] | 'all'` — The default selected keys in uncontrolled multiple mode. Use "all" to select all items or an array of keys.
+- **`selectionMode`** `'single' | 'multiple'` (default: `single`) — Selection mode
+- **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
+- **`disabledKeys`** `Key[]` — Array of keys for disabled items
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ListBox size
+- **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
+- **`filter`** `(nodes: Iterable<Node>) => Iterable<Node>` — Filter function for the list items
+- **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available
+- **`header`** `ReactNode` — Custom header content
+- **`footer`** `ReactNode` — Custom footer content
+- **`focusOnHover`** `boolean` (default: `true`) — Whether moving the pointer over an option will move DOM focus to that option
+- **`shouldUseVirtualFocus`** `boolean` (default: `false`) — Whether to use virtual focus instead of DOM focus
+- **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection mode
+- **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
+- **`description`** `string` — Field description
+- **`message`** `string` — Help or error message
+- **`showSelectAll`** `boolean` (default: `false`) — Whether to show the "Select All" option in multiple selection mode
+- **`selectAllLabel`** `string` (default: `Select All`) — Label for the "Select All" option
+- **`onSelectionChange`** `(keys: Key | Key[] | 'all' | null) => void` — Callback when selection changes
+- **`onEscape`** `() => void` — Callback when Escape key is pressed
+- **`onOptionClick`** `(key: Key) => void` — Callback when an option is clicked (non-checkbox area)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports all [Field properties](../../FieldProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the root wrapper element of the component.
+
+**Sub-elements:**
+- `ValidationState` - Container for validation and loading indicators
+
+#### listStyles
+
+Customizes the list container element.
+
+#### optionStyles
+
+Customizes individual option elements.
+
+**Sub-elements:**
+- `Label` - The main text of each option
+- `Description` - Secondary descriptive text for options
+- `Content` - Container for label and description
+- `Checkbox` - Checkbox element when `isCheckable={true}`
+- `CheckboxWrapper` - Wrapper around the checkbox
+
+#### sectionStyles
+
+Customizes section wrapper elements.
+
+#### headingStyles
+
+Customizes section heading elements.
+
+#### headerStyles
+
+Customizes the header area when header prop is provided.
+
+#### footerStyles
+
+Customizes the footer area when footer prop is provided.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop: `display`, `font`, `preset`, `hide`, `opacity`, `whiteSpace`, `color`, `fill`, `fade`, `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`, `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `reset`, `padding`, `paddingInline`, `paddingBlock`, `shadow`, `border`, `radius`, `overflow`, `scrollbar`, `outline`, `textAlign`, `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`.
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`invalid`** `boolean` — Applied when `validationState="invalid"`
+- **`valid`** `boolean` — Applied when `validationState="valid"`
+- **`disabled`** `boolean` — Applied when `isDisabled={true}`
+- **`focused`** `boolean` — Applied when the ListBox has focus
+- **`header`** `boolean` — Applied when header prop is provided or `showSelectAll={true}`
+- **`footer`** `boolean` — Applied when footer prop is provided
+- **`selectAll`** `boolean` — Applied when `showSelectAll={true}` in multiple selection mode
+
+## Key Properties
+
+### Selection Behavior
+
+**isCheckable** (`boolean`, default: `false`)
+- When `true` in multiple selection mode, displays checkboxes on the left of each option
+- Checkboxes are visible when the item is hovered, focused, or selected
+- Improves clarity of multiple selection interactions
+
+**showSelectAll** (`boolean`, default: `false`)
+- When `true` in multiple selection mode, displays a "Select All" option in the header
+- The checkbox shows three states: unchecked (none selected), indeterminate (some selected), checked (all selected)
+- Only works with `selectionMode="multiple"`
+
+**selectAllLabel** (`ReactNode`, default: `'Select All'`)
+- Custom label for the "Select All" option
+- Only used when `showSelectAll={true}`
+
+**allValueProps** (`Partial<CubeItemProps>`)
+- Props to customize the styling and behavior of the "Select All" option
+- Accepts any Item props like `styles`, `icon`, etc.
+
+**disallowEmptySelection** (`boolean`, default: `false`)
+- When `true`, prevents the user from deselecting the last selected item
+- Ensures at least one item is always selected in single selection mode
+
+**disableSelectionToggle** (`boolean`, default: `false`)
+- When `true`, clicking an already-selected item keeps it selected instead of toggling it off
+- Useful when embedding ListBox inside components like ComboBox
+
+**disabledKeys** (`Key[]`)
+- Array of keys for items that should be disabled
+- Disabled items cannot be selected and are visually distinguished
+
+### Visual Styling
+
+**shape** (`'card' | 'plain' | 'popover'`, default: `'card'`)
+- Controls the visual styling of the ListBox container
+- `card`: Standard card styling with border and margin (default)
+- `plain`: No border, no margin, no radius - suitable for embedded use
+- `popover`: No border, but keeps margin and radius - suitable for overlay use
+- Use `plain` when embedding ListBox directly into another component
+- Use `popover` when using ListBox inside overlays (Dialog, ComboBox, Picker)
+
+### Focus and Interaction
+
+**focusOnHover** (`boolean`, default: `true`)
+- When `true`, moving the pointer over an option will move DOM focus to that option
+- Set to `false` for components that keep DOM focus outside (e.g., searchable FilterListBox)
+
+**shouldUseVirtualFocus** (`boolean`, default: `false`)
+- When `true`, uses virtual focus for keyboard navigation
+- DOM focus stays outside individual option elements (useful for searchable lists)
+
+**shouldFocusWrap** (`boolean`, default: `false`)
+- When `true`, keyboard navigation wraps around when reaching the end of the list
+
+### Event Handlers
+
+**onSelectionChange** (`(key: Key | null | 'all' | Key[]) => void`)
+- Callback fired when selection changes
+- In single mode: receives a single key or `null`
+- In multiple mode: receives an array of keys or `'all'` for select all
+
+**onEscape** (`() => void`)
+- Callback fired when the user presses Escape key
+- When provided, prevents React Aria's default Escape behavior (selection reset)
+- Useful for closing parent overlays
+
+**onOptionClick** (`(key: Key) => void`)
+- Callback fired when an option is clicked (not on the checkbox area in checkable mode)
+- Used by FilterPicker to close the popover on non-checkbox clicks
+
+### Advanced
+
+**stateRef** (`RefObject<any>`)
+- Ref to access the internal ListState instance
+- Allows parent components to access selection state and other list functionality
+
+**listRef** (`RefObject<HTMLUListElement>`)
+- Ref for accessing the list DOM element
+
+## Sub-components
+
+### ListBox.Item
+
+Individual items within the ListBox. Each item is rendered using [Item](../content/Item.md) and supports all Item properties for layout, icons, descriptions, and interactive features.
+
+#### Item API
+
+ListBox.Item is built using [Item](../content/Item.md), which provides rich layout and interaction capabilities. All Item properties are supported:
+
+- **`key`** `string \| number` — Unique identifier for the item (required)
+- **`children`** `ReactNode` — The main content/label for the option
+- **`textValue`** `string` — Text representation for complex JSX content (for screen readers and search)
+- **`icon`** `ReactNode` — Icon displayed before the content
+- **`rightIcon`** `ReactNode` — Icon displayed after the content
+- **`description`** `ReactNode` — Secondary text below the main content
+- **`descriptionPlacement`** `'inline' \| 'block'` (default: `'block'`) — How the description is positioned
+- **`prefix`** `ReactNode` — Content displayed at the start (before icon)
+- **`suffix`** `ReactNode` — Content displayed at the end (after content)
+- **`hotkeys`** `string` — Keyboard shortcut hint (e.g., `'ctrl+a'`) displayed as suffix
+- **`tooltip`** `string \| object` — Tooltip shown on hover. Object: `{ title, description, placement }`
+- **`styles`** `Styles` — Custom styling for the item
+- **`qa`** `string` — QA identifier for testing
+
+#### Example with Rich Items
+
+```jsx
+<ListBox label="Team Members" selectionMode="multiple">
+  <ListBox.Item 
+    key="user1" 
+    icon={<IconUser />}
+    description="Product Manager"
+    suffix="Online"
+  >
+    Alice Johnson
+  </ListBox.Item>
+  <ListBox.Item 
+    key="user2" 
+    icon={<IconUser />}
+    description="Senior Developer"
+    rightIcon={<IconBadge />}
+  >
+    Bob Smith
+  </ListBox.Item>
+</ListBox>
+```
+
+### ListBox.Section
+
+Groups related items together with an optional heading.
+
+- **`title`** `ReactNode` — Optional heading text for the section
+- **`children`** `ListBox.Item[]` — Collection of ListBox.Item components
+
+## Variants
+
+### Selection Modes
+
+- `single` - Allows selecting only one item at a time
+- `multiple` - Allows selecting multiple items
+- `none` - No selection allowed (display only)
+
+### Sizes
+
+- `small` - Compact size for dense interfaces (28px item height)
+- `medium` - Standard size for general use (32px item height, default)
+- `large` - Emphasized size for important sections (40px item height)
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<ListBox label="Select a fruit" selectionMode="single">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+  <ListBox.Item key="cherry">Cherry</ListBox.Item>
+</ListBox>
+```
+
+### With Descriptions
+
+```jsx
+<ListBox label="Choose a framework" selectionMode="single">
+  <ListBox.Item 
+    key="react" 
+    description="A JavaScript library for building user interfaces"
+  >
+    React
+  </ListBox.Item>
+  <ListBox.Item 
+    key="vue" 
+    description="The Progressive JavaScript Framework"
+  >
+    Vue.js
+  </ListBox.Item>
+</ListBox>
+```
+
+### With Sections
+
+```jsx
+<ListBox label="Select food items" selectionMode="single">
+  <ListBox.Section title="Fruits">
+    <ListBox.Item key="apple">Apple</ListBox.Item>
+    <ListBox.Item key="banana">Banana</ListBox.Item>
+  </ListBox.Section>
+  <ListBox.Section title="Vegetables">
+    <ListBox.Item key="carrot">Carrot</ListBox.Item>
+    <ListBox.Item key="broccoli">Broccoli</ListBox.Item>
+  </ListBox.Section>
+</ListBox>
+```
+
+### Multiple Selection
+
+```jsx
+<ListBox
+  label="Select skills (multiple)"
+  selectionMode="multiple"
+>
+  <ListBox.Item key="html">HTML</ListBox.Item>
+  <ListBox.Item key="css">CSS</ListBox.Item>
+  <ListBox.Item key="javascript">JavaScript</ListBox.Item>
+</ListBox>
+```
+
+### Multiple Selection with Checkboxes
+
+```jsx
+<ListBox
+  label="Select permissions"
+  selectionMode="multiple"
+  isCheckable={true}
+>
+  <ListBox.Item key="read" description="View content and data">Read</ListBox.Item>
+  <ListBox.Item key="write" description="Create and edit content">Write</ListBox.Item>
+  <ListBox.Item key="delete" description="Remove content permanently">Delete</ListBox.Item>
+</ListBox>
+```
+
+### Multiple Selection with Select All
+
+```jsx
+<ListBox
+  label="Select permissions"
+  selectionMode="multiple"
+  isCheckable={true}
+  showSelectAll={true}
+  selectAllLabel="All Permissions"
+>
+  <ListBox.Item key="read" description="View content and data">Read</ListBox.Item>
+  <ListBox.Item key="write" description="Create and edit content">Write</ListBox.Item>
+  <ListBox.Item key="execute" description="Execute operations">Execute</ListBox.Item>
+</ListBox>
+```
+
+### With Header and Footer
+
+```jsx
+<ListBox
+  label="Programming Languages"
+  header={
+    <Space gap="1x" flow="row" placeItems="center">
+      <Title level={6}>Languages</Title>
+      <Badge type="note">12</Badge>
+    </Space>
+  }
+  footer={
+    <Text color="#dark.50" preset="t4">
+      Popular languages shown
+    </Text>
+  }
+>
+  <ListBox.Item key="javascript">JavaScript</ListBox.Item>
+  <ListBox.Item key="python">Python</ListBox.Item>
+</ListBox>
+```
+
+### Controlled Selection
+
+```jsx
+const [selectedKey, setSelectedKey] = useState('apple');
+
+<ListBox
+  label="Controlled ListBox"
+  selectedKey={selectedKey}
+  onSelectionChange={setSelectedKey}
+  selectionMode="single"
+>
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Disabled Items
+
+```jsx
+<ListBox
+  label="Select an option"
+  selectionMode="single"
+  disabledKeys={['disabled1', 'disabled2']}
+>
+  <ListBox.Item key="available1">Available Option 1</ListBox.Item>
+  <ListBox.Item key="disabled1">Disabled Option 1</ListBox.Item>
+  <ListBox.Item key="available2">Available Option 2</ListBox.Item>
+</ListBox>
+```
+
+### Disallow Empty Selection
+
+```jsx
+<ListBox
+  label="Must select one option"
+  selectionMode="single"
+  disallowEmptySelection={true}
+  defaultSelectedKey="apple"
+>
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Rich Content Options
+
+```jsx
+<ListBox label="User Roles" selectionMode="single" size="large">
+  <ListBox.Item
+    key="admin"
+    description="Full system administration access"
+    prefix={<Badge type="danger">Admin</Badge>}
+    suffix={<Badge type="note">3</Badge>}
+    rightIcon={<SettingsIcon />}
+    hotkeys="ctrl+a"
+  >
+    System Administrator
+  </ListBox.Item>
+  <ListBox.Item
+    key="editor"
+    description="Content creation and editing permissions"
+    prefix={<Badge type="warning">Editor</Badge>}
+    suffix={<Badge type="note">12</Badge>}
+    rightIcon={<EditIcon />}
+    hotkeys="ctrl+e"
+  >
+    Content Editor
+  </ListBox.Item>
+</ListBox>
+```
+
+### With Tooltips
+
+```jsx
+<ListBox label="Project Actions" selectionMode="single">
+  <ListBox.Item
+    key="create"
+    tooltip="Create a new project with default settings"
+    icon={<PlusIcon />}
+  >
+    Create Project
+  </ListBox.Item>
+  <ListBox.Item
+    key="import"
+    tooltip={{
+      title: 'Import Project',
+      description: 'Import an existing project from file or URL',
+      placement: 'right',
+    }}
+    icon={<DatabaseIcon />}
+  >
+    Import Project
+  </ListBox.Item>
+</ListBox>
+```
+
+### With Complex Content
+
+```jsx
+<ListBox label="Choose your plan" selectionMode="single">
+  <ListBox.Item
+    key="basic"
+    textValue="Basic Plan - Free with limited features"
+  >
+    <Space gap="1x" flow="column">
+      <Text weight="600">Basic Plan</Text>
+      <Badge type="neutral">Free</Badge>
+    </Space>
+  </ListBox.Item>
+  <ListBox.Item
+    key="pro"
+    textValue="Pro Plan - Monthly subscription with all features"
+  >
+    <Space gap="1x" flow="column">
+      <Text weight="600">Pro Plan</Text>
+      <Badge type="purple">$19/month</Badge>
+    </Space>
+  </ListBox.Item>
+</ListBox>
+```
+
+### Different Sizes
+
+```jsx
+<ListBox size="small" label="Small Size">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+
+<ListBox size="medium" label="Medium Size (Default)">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+
+<ListBox size="large" label="Large Size">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Visual Shape Variants
+
+```jsx
+{/* Card shape (default) - with border and margin */}
+<ListBox shape="card" label="Select a fruit" selectionMode="single">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+
+{/* Plain shape - no border, no margin, no radius */}
+<ListBox shape="plain" label="Select a fruit" selectionMode="single">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+
+{/* Popover shape - no border, but keeps margin and radius */}
+<ListBox shape="popover" label="Select a fruit" selectionMode="single">
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### Custom Escape Handling
+
+```jsx
+const [selectedKey, setSelectedKey] = useState('apple');
+
+<ListBox
+  label="Custom Escape Handling"
+  selectedKey={selectedKey}
+  selectionMode="single"
+  onSelectionChange={setSelectedKey}
+  onEscape={() => {
+    // Custom escape behavior - could close a parent modal, etc.
+    console.log('Escape pressed');
+  }}
+>
+  <ListBox.Item key="apple">Apple</ListBox.Item>
+  <ListBox.Item key="banana">Banana</ListBox.Item>
+</ListBox>
+```
+
+### In Forms
+
+```jsx
+<Form onSubmit={handleSubmit}>
+  <ListBox
+    name="technology"
+    label="Preferred Technology"
+    isRequired
+    selectionMode="single"
+  >
+    <ListBox.Section title="Frontend">
+      <ListBox.Item key="react">React</ListBox.Item>
+      <ListBox.Item key="vue">Vue.js</ListBox.Item>
+    </ListBox.Section>
+  </ListBox>
+  <Form.Submit>Submit</Form.Submit>
+</Form>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to/from the ListBox
+- `Arrow Keys` - Navigate between options
+- `Space/Enter` - Select/deselect the focused option
+- `Home/End` - Move to first/last option
+- `Page Up/Page Down` - Move up/down by multiple items
+- `Escape` - Deselect all items (if onEscape not provided)
+
+### Screen Reader Support
+
+- ListBox announces as "listbox" with proper role
+- Selected items are announced as "selected"
+- Section headings are properly associated with their items
+- Selection changes are announced immediately
+- Item descriptions are read along with labels
+
+### ARIA Properties
+
+- `aria-label` - Provides accessible label when no visible label exists
+- `aria-labelledby` - Associates with external label element
+- `aria-describedby` - Associates with description text
+- `aria-multiselectable` - Indicates multiple selection capability
+- `aria-activedescendant` - Tracks focused item for screen readers
+
+## Best Practices
+
+1. **Do**: Provide clear, descriptive labels for options
+   ```jsx
+   <ListBox.Item key="react" description="JavaScript library for UIs">
+     React
+   </ListBox.Item>
+   ```
+
+2. **Don't**: Use ListBox for very large datasets without considering virtualization
+   ```jsx
+   // ✅ Virtualization is automatic for lists without sections
+   <ListBox height="300px">
+     {hugeArray.map(item => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>)}
+   </ListBox>
+   ```
+
+3. **Do**: Use sections to organize related options
+   ```jsx
+   <ListBox.Section title="Frontend Frameworks">
+     <ListBox.Item key="react">React</ListBox.Item>
+   </ListBox.Section>
+   ```
+
+4. **Do**: Use `isCheckable` for clearer multiple selection UI
+   ```jsx
+   <ListBox selectionMode="multiple" isCheckable={true}>
+     {/* Checkboxes make the selection state obvious */}
+   </ListBox>
+   ```
+
+5. **Do**: Use `showSelectAll` for efficient multiple selection from lists
+   ```jsx
+   <ListBox selectionMode="multiple" isCheckable={true} showSelectAll selectAllLabel="Select All">
+     {/* Easy bulk selection with visual feedback */}
+   </ListBox>
+   ```
+
+6. **Do**: Use `textValue` for complex option content
+   ```jsx
+   <ListBox.Item key="item" textValue="Basic Plan - Free">
+     <Space gap="1x" flow="column">
+       <Text weight="600">Basic Plan</Text>
+       <Badge>Free</Badge>
+     </Space>
+   </ListBox.Item>
+   ```
+
+7. **Do**: Leverage Item features for rich content
+   ```jsx
+   <ListBox.Item
+     key="admin"
+     icon={<UserIcon />}
+     description="Full access"
+     suffix={<Badge>3</Badge>}
+     hotkeys="ctrl+a"
+   >
+     Administrator
+   </ListBox.Item>
+   ```
+
+8. **Accessibility**: Always provide meaningful labels and descriptions
+9. **Performance**: Virtualization is automatic when there are no sections
+10. **UX**: Consider FilterListBox for searchable lists with many options
+
+## Integration with Forms
+
+This component supports all [Field properties](../../FieldProperties.md) when used within a Form. The component automatically handles form validation, field states, and integrates with form submission.
+
+```jsx
+<Form onSubmit={handleSubmit}>
+  <ListBox
+    name="preferences"
+    label="User Preferences"
+    isRequired
+    rules={[{ required: true }]}
+    selectionMode="multiple"
+  >
+    <ListBox.Item key="notifications">Email Notifications</ListBox.Item>
+    <ListBox.Item key="newsletter">Newsletter</ListBox.Item>
+  </ListBox>
+</Form>
+```
+
+## Performance
+
+### Virtualization
+
+ListBox automatically enables virtualization when:
+- No sections are present (sections disable virtualization)
+- Provides smooth scrolling even with large datasets
+- Only visible items are rendered in the DOM
+- Uses `@tanstack/react-virtual` for efficient rendering
+- Automatically measures item heights for consistent scrolling
+- Supports items with varying heights (descriptions, complex content)
+
+**Note**: Virtualization is transparent to the user - no configuration needed. It works automatically when you have a flat list without sections.
+
+### Optimization Tips
+
+- Use `textValue` prop for complex option content to improve accessibility and search
+- Avoid sections for very large lists to enable virtualization
+- Use `items` prop pattern with dynamic data for better performance
+- Consider FilterListBox for searchable large lists (100+ items)
+- Virtualization handles items with varying heights automatically
+
+## Related Components
+
+- [FilterListBox](./FilterListBox.md) - ListBox with integrated search functionality
+- [FilterPicker](./FilterPicker.md) - ListBox in a trigger-based popover
+- [Select](./Select.md) - Dropdown selection without persistent visibility
+- [ComboBox](./ComboBox.md) - Dropdown with text input and search
+- [RadioGroup](./RadioGroup.md) - Single selection with radio buttons
+- [CheckboxGroup](./Checkbox.md) - Multiple selection with checkboxes