@cube-dev/ui-kit 0.0.0-canary-c210a8c → 0.0.0-canary-60981ef

package/docs/components/fields/ListBox.md

@@ -0,0 +1,691 @@
+# 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
+
+### Base Properties
+
+Supports [Base properties](../../tasty/tasty.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:
+
+| Modifier | Type | Description |
+|----------|------|-------------|
+| `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:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| 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'` | How the description is positioned (default: `'block'`) |
+| 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.
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| 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](../form/Field.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