@redis-ui/components 42.7.0 → 43.0.2

package/skills/redis-ui-components/references/Select.md

@@ -0,0 +1,517 @@
+# Select
+
+A single-select dropdown component built on Radix UI primitives. Supports searchable options, virtualized lists, custom value rendering, validation states, and full composition via sub-components for trigger, content, and option customization.
+
+## Import
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| options | `TOption[]` (extends `SelectOption`) | *required* | Array of selectable options |
+| disabled | `boolean` | `false` | Whether the select is disabled |
+| defaultOpen | `boolean` | - | Uncontrolled initial open state |
+| open | `boolean` | - | Controlled open state |
+| onOpenChange | `(open: boolean) => void` | - | Called when open state changes |
+| defaultValue | `TValue` | - | Uncontrolled initial selected value |
+| value | `TValue` | - | Controlled selected value |
+| onChange | `(value: TValue) => void` | - | Called when selection changes |
+| customCompare | `SelectCompareHandler<TOption>` | - | Custom search comparison handler. Receives `(option, searchValue)` and returns boolean |
+| error | `string \| ReactElement` | - | Error message or element. Enables error state; overrides valid status |
+| valid | `boolean` | - | Enables valid status indicator |
+| placeholder | `ReactNode` | `'Select...'` | Placeholder text when no value is selected |
+| valueRender | `SelectValueRender<TOption>` | - | Custom render function for both trigger and option values. Receives `{ option, isSelected, isOptionValue }` |
+| searchable | `boolean` | - | Enables search input in the dropdown content |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Dropdown placement relative to trigger |
+| maxVisibleItems | `number` | - | Maximum number of visible items before scrolling |
+| virtualized | `boolean` | - | Enables virtualized rendering for long lists |
+| contentWidth | `string` | - | Custom width for the dropdown content |
+| allowReset | `boolean` | - | Shows a reset button to clear the selected value |
+| loading | `boolean` | - | Shows a loading indicator on the trigger |
+| id | `string` | - | Custom id for the select trigger (must start with a letter) |
+
+The component also extends Radix UI `SelectTriggerProps` (excluding `children`, `placeholder`, `asChild`, `onChange`).
+
+### SelectOption Type
+| Field | Type | Description |
+|-------|------|-------------|
+| value | `string` | *required* - Unique option value |
+| label | `string` | Display label |
+| icon | `IconType \| ComponentType` | Optional icon component |
+| disabled | `boolean` | Whether the option is disabled |
+| hidden | `boolean` | Whether the option is hidden |
+
+## Sub-components
+
+- **`Select.Compose`** - Context provider that wraps trigger and content. Accepts state/option props.
+- **`Select.Trigger`** - Default trigger button with combobox styling.
+- **`Select.Trigger.Compose`** - Composable trigger wrapper. Accepts `customContainer` prop for custom trigger UI.
+- **`Select.Trigger.Value`** - Displays the selected value or placeholder text.
+- **`Select.Trigger.Arrow`** - Dropdown arrow indicator. Accepts optional `icon` prop.
+- **`Select.Trigger.ResetButton`** - Button to clear the current selection.
+- **`Select.Trigger.StatusIndicator`** - Shows valid/error status indicator.
+- **`Select.Trigger.LoadingIndicator`** - Shows loading spinner. Accepts `loading` prop.
+- **`Select.Content`** - Default dropdown content with options list and optional search.
+- **`Select.Content.Compose`** - Composable content wrapper for custom content layouts.
+- **`Select.Content.Search`** - Search input for filtering options.
+- **`Select.Content.OptionList`** - Renders the list of options. Accepts `style` for custom sizing.
+- **`Select.Content.Footer`** - Footer area inside the dropdown content.
+- **`Select.Option`** - Default option component.
+- **`Select.Option.Compose`** - Composable option wrapper (must be root element in custom option components).
+- **`Select.Option.Indicator`** - Selection check indicator. Accepts children to customize the icon.
+- **`Select.Option.Content`** - Content area within an option.
+
+### Select.Content Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| searchable | `boolean` | - | Enables the search input |
+| optionValueRender | `SelectValueRender<TOption>` | - | Custom render for option values only |
+| optionComponent | `SelectOptionComponent<TOption>` | - | Custom component to render each option |
+| maxVisibleItems | `number` | - | Maximum visible items before scrolling |
+| virtualized | `boolean` | - | Enables virtualized rendering |
+| placement | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Dropdown placement |
+| contentWidth | `string` | - | Custom dropdown width |
+
+### Select.Trigger Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| placeholder | `ReactNode` | - | Placeholder text |
+| valueRender | `SelectValueRender<TOption>` | - | Custom render for the trigger value |
+| allowReset | `boolean` | - | Shows reset button |
+| loading | `boolean` | - | Shows loading indicator |
+| id | `string` | - | Custom id for the trigger element |
+
+### Select.Trigger.Compose Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| customContainer | `boolean` | - | When true, allows using a custom container element instead of the default combobox button |
+| id | `string` | - | Custom id |
+
+## Examples
+
+### Playground
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select
+  options={options}
+  searchable
+  onChange={(value) => console.log(value)}
+  onOpenChange={(open) => console.log(open)}
+/>
+```
+
+### WithLabel
+> Component doesn't have internal label or any other external decoration elements.
+> For these purposes, there is a wrapper element `FormField`.
+> If custom id specified for select, `FormField` inherits it,
+> otherwise label will be auto connected to the select with generated id.
+> Note: custom id must start with a letter to work correctly.
+```tsx
+import { Select, FormField } from '@redislabsdev/redis-ui-components';
+
+<FormField label="FormField Label with custom id" additionalText="Additional text">
+  <Select
+    options={options}
+    placeholder="Select placeholder"
+    id="custom-id"
+    onChange={(value) => console.log(value)}
+    onOpenChange={(open) => console.log(open)}
+  />
+</FormField>
+```
+
+### Status
+> Adding `valid` prop enables valid status.
+> Adding some text to the `error` prop of `Select` enables error state. Hover error indicator to see specified text in tooltip.
+> Note: error status overrides valid status.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<>
+  Valid status
+  <Select options={options} valid onChange={(value) => console.log(value)} />
+  Error status
+  <Select options={options} error="Error message" onChange={(value) => console.log(value)} />
+</>
+```
+
+### ResetButton
+> Single Select allows user to clean selected value. Set `allowReset` prop to show Reset button.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select
+  options={options}
+  allowReset
+  defaultValue="orange"
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### Loading
+> Adding `loading` prop enables loading indicator. It can be used together with other indicators and states.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<>
+  Loading indicator
+  <Select options={options} loading onChange={(value) => console.log(value)} />
+  With other elements
+  <Select
+    options={options}
+    defaultValue="banana"
+    valid
+    allowReset
+    loading
+    onChange={(value) => console.log(value)}
+  />
+</>
+```
+
+### Disabled
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<>
+  Default
+  <Select options={options} disabled />
+  With selected item
+  <Select options={options} disabled value="orange" />
+  With error message
+  <Select
+    options={options}
+    disabled
+    value="banana"
+    error="Error message"
+    allowReset
+    loading
+  />
+</>
+```
+
+### ValueRender
+> Value rendering can be customized by specifying `valueRender` prop.
+> It can be customized for both option and trigger.
+> Event handler receives current `option`, `isSelected` flag and `isOptionValue` flag if rendering option in dropdown list.
+> Note: if valueRender handler returns `undefined` or `null`, then default rendering will be applied.
+```tsx
+import { Select, SelectValueRender } from '@redislabsdev/redis-ui-components';
+
+const customValueRender: SelectValueRender = ({ option, isSelected, isOptionValue }) => {
+  const color = !isOptionValue ? 'green' : (isSelected && 'blueviolet') || 'orange';
+  const stateLabel = isOptionValue ? `${isSelected ? 'Selected Option' : 'Option'}` : 'Value';
+
+  return (
+    <div>
+      <span style={{ fontSize: '0.7em', color }}>{stateLabel}: </span>
+      {option.label}
+    </div>
+  );
+};
+
+<Select
+  options={options}
+  defaultValue="orange"
+  valueRender={customValueRender}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### CustomSearch
+> If there is additional info for an option, then it is possible to search by that info as well.
+> Set the comparison handler to the `customCompare` prop to enable custom search.
+> The handler receives an option and a search string in lowercase.
+> The handler should return true if the search string is found in the option search fields.
+> Note: if a custom search should include a default search by label, then label needs to be added to the custom search implementation, since custom search completely replaces the default search.
+```tsx
+import { Select, SelectCompareHandler, SelectOption, SelectValueRender } from '@redislabsdev/redis-ui-components';
+
+const customCompare: SelectCompareHandler<SelectOption> = (option, searchValue) => {
+  const fieldsForSearch = [option.label, option.state as string];
+  return fieldsForSearch.some((field) => field?.toLowerCase().includes(searchValue));
+};
+
+const valueRender: SelectValueRender = ({ option }) => {
+  return (
+    <>
+      <span>{option.label}</span>
+      &nbsp;
+      <span style={{ fontSize: '0.8em' }}>{`(${option.state})`}</span>
+    </>
+  );
+};
+
+<Select
+  options={usStates}
+  searchable
+  customCompare={customCompare}
+  valueRender={valueRender}
+  onChange={(value) => console.log(value)}
+/>
+```
+
+### VirtualList
+> List of options can be virtualized by adding `virtualized` prop. It allows to have very long list of items without performance drop.
+```tsx
+import { Select, FormField } from '@redislabsdev/redis-ui-components';
+
+<FormField label="Countries">
+  <Select
+    virtualized
+    searchable
+    options={countryOptions}
+    allowReset
+    defaultValue="ua"
+    maxVisibleItems={6}
+    onChange={(value) => console.log(value)}
+  />
+</FormField>
+```
+
+---
+
+## Content Composition
+
+### Content Playground
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose options={options} onChange={(value) => console.log(value)}>
+  <Select.Trigger />
+  <Select.Content />
+</Select.Compose>
+```
+
+### OptionValueRender
+> Value rendering can be customized separately for option and trigger values.
+> Option value rendering can be customized by specifying `optionValueRender` prop of `Select.Content`.
+> Event handler receives current `option`, `isSelected` flag and truthy `isOptionValue` flag for rendering option value.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger />
+  <Select.Content
+    optionValueRender={({ option, isSelected }) => {
+      return (
+        <div>
+          <span
+            style={{
+              fontSize: '0.7em',
+              color: (isSelected && 'blueviolet') || 'orange'
+            }}
+          >
+            {isSelected ? 'Selected Option' : 'Option'}:
+          </span>{' '}
+          {option.label}
+        </div>
+      );
+    }}
+  />
+</Select.Compose>
+```
+
+### OptionComponent
+> Prop `optionComponent` (unlike `optionValueRender`) allows rendering the entire option, including the selection indicator.
+> If Option Component is not specified, `Select` renders options using default `Select.Option`.
+> Custom `optionComponent` can be used together with custom `optionValueRender`.
+> Option component receives default or custom rendered value as `content` prop.
+> Note: custom option component must use `Select.Option.Compose` as root element to work correctly.
+```tsx
+import { Select, SelectOptionComponent } from '@redislabsdev/redis-ui-components';
+
+const CustomOption: SelectOptionComponent = ({ option, content, ...restProps }) => (
+  <Select.Option.Compose option={option} {...restProps}>
+    <Select.Option.Indicator />
+    <Select.Option.Content>{content}</Select.Option.Content>
+  </Select.Option.Compose>
+);
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger />
+  <Select.Content optionComponent={CustomOption} />
+</Select.Compose>
+```
+
+### CustomCheckIndicator
+> Shows how, using composition, to replace the icon of the check indicator.
+```tsx
+import { Select, SelectOptionComponent } from '@redislabsdev/redis-ui-components';
+import { PocIcon } from '@redislabsdev/redis-ui-icons';
+
+const CustomOption: SelectOptionComponent = ({ option, content, ...restProps }) => (
+  <Select.Option.Compose option={option} {...restProps}>
+    <Select.Option.Content>{content}</Select.Option.Content>
+    <Select.Option.Indicator>
+      <PocIcon color="danger500" size="XL" />
+    </Select.Option.Indicator>
+  </Select.Option.Compose>
+);
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger />
+  <Select.Content optionComponent={CustomOption} />
+</Select.Compose>
+```
+
+### ContentComposition
+> Composition example includes all parts of `Select.Content` and shows usage of static elements.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose
+  options={options}
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger />
+  <Select.Content.Compose>
+    <div style={{ textAlign: 'center' }}>Top static element</div>
+    <Select.Content.Search />
+    <div style={{ textAlign: 'center' }}>Middle static element</div>
+    <Select.Content.OptionList style={{ maxHeight: 100 }} />
+    <div style={{ textAlign: 'center' }}>Bottom static element</div>
+    <Select.Content.Footer>
+      <div style={{ textAlign: 'center' }}>Custom element in Footer</div>
+    </Select.Content.Footer>
+  </Select.Content.Compose>
+</Select.Compose>
+```
+
+### ContentListComposition
+> By adding extra list container, some static elements can be scrolled along with other options.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose
+  options={options}
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger />
+  <Select.Content.Compose>
+    <Select.Content.Search />
+    <div style={{ overflowY: 'auto', maxHeight: 200 }}>
+      <div style={{ textAlign: 'center' }}>Top scrollable element</div>
+      <Select.Content.OptionList />
+      <div style={{ textAlign: 'center' }}>Bottom scrollable element</div>
+    </div>
+  </Select.Content.Compose>
+</Select.Compose>
+```
+
+---
+
+## Trigger Composition
+
+### Trigger Playground
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose options={options} onChange={(value) => console.log(value)}>
+  <Select.Trigger placeholder="Select fruit..." allowReset={false} />
+  <Select.Content />
+</Select.Compose>
+```
+
+### Trigger ValueRender
+> Value rendering can be customized separately for option and trigger values.
+> Trigger value rendering can be customized by specifying `valueRender` prop of `Select.Trigger`.
+> Event handler receives current `option` prop.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+const valueRender = ({ option }) => {
+  return (
+    <div>
+      <span style={{ fontSize: '0.7em', color: 'green' }}> Option: </span> {option.label}
+    </div>
+  );
+};
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger valueRender={valueRender} />
+  <Select.Content />
+</Select.Compose>
+```
+
+### CustomContainer
+> By default, `Select.Trigger` wraps children with combobox-styled button container.
+> It is possible to use custom container by defining the `customContainer` prop.
+> Note: custom container may have its own style and behavior and therefore can have name conflicts with attributes added by `Select.Trigger`. In this case custom container can be wrapped in a `span` or `div`, which will take over all attributes from the trigger.
+```tsx
+import { useState } from 'react';
+import { Select, ToggleButton } from '@redislabsdev/redis-ui-components';
+
+const [open, setOpen] = useState(false);
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  open={open}
+  onOpenChange={setOpen}
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger.Compose customContainer>
+    <span>
+      <ToggleButton pressed={open}>
+        <Select.Trigger.Value />
+        <Select.Trigger.Arrow />
+      </ToggleButton>
+    </span>
+  </Select.Trigger.Compose>
+  <Select.Content />
+</Select.Compose>
+```
+
+### TriggerComposition
+> Default composition example includes all parts of `Trigger`.
+```tsx
+import { Select } from '@redislabsdev/redis-ui-components';
+
+<Select.Compose
+  options={options}
+  defaultValue="orange"
+  error="error message"
+  onChange={(value) => console.log(value)}
+>
+  <Select.Trigger.Compose>
+    <Select.Trigger.Value placeholder="Placeholder" />
+    <Select.Trigger.ResetButton />
+    <Select.Trigger.StatusIndicator />
+    <Select.Trigger.LoadingIndicator loading />
+    <Select.Trigger.Arrow />
+  </Select.Trigger.Compose>
+
+  <Select.Content />
+</Select.Compose>
+```
+
+## Notes
+
+- The `Select` top-level component is a convenience wrapper that internally uses `Select.Compose`, `Select.Trigger`, and `Select.Content`.
+- For full customization, use the compose pattern: `Select.Compose` > `Select.Trigger` / `Select.Content`.
+- Custom id must start with a letter to work correctly with `FormField` label association.
+- Error status overrides valid status when both are set.
+- If `valueRender` returns `undefined` or `null`, default rendering is applied.
+- Custom search via `customCompare` completely replaces the default search -- include label matching in your handler if needed.
+- Custom option components must use `Select.Option.Compose` as the root element.
+- Custom trigger containers may have name conflicts with attributes added by `Select.Trigger`; wrap in a `span` or `div` to avoid this.
+- `useSelectContext` hook is exported and can be used inside custom option components to access select state.