import {
  Meta,
  Title,
  Subtitle,
  Canvas,
  Controls,
} from '@storybook/addon-docs/blocks'
import * as ComboboxStories from './Combobox.stories'
import { LifecycleTag } from '../../docs/components/LifecycleTag'

<Meta title="Form/Combobox" of={ComboboxStories} />

<Title>Combobox</Title>
<Subtitle>
  Composable combobox primitives built on Base UI. Assemble trigger, input,
  list, and items to build fully custom searchable single-select or multi-select
  experiences.
</Subtitle>
<LifecycleTag variant="Stable" />
**Component type:** Primitive

<Canvas of={ComboboxStories.Default} layout="padded" sourceState="shown" />
<Controls of={ComboboxStories.Default} />

## When to use

Use `Combobox` when you need a searchable combobox with custom item rendering (icons, images), multi-select with badge chips, or grouped items. For a standard non-searchable single-select, use `SimpleSelect` instead.

## Import

```tsx
import {
  Combobox,
  ComboboxTrigger,
  ComboboxValue,
  ComboboxContent,
  ComboboxInput,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<Combobox items={options} itemToStringValue={(opt) => opt.label}>
  <ComboboxTrigger>
    <ComboboxValue placeholder="Select an option" />
  </ComboboxTrigger>
  <ComboboxContent>
    <ComboboxInput placeholder="Search..." />
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(option) => (
        <ComboboxItem key={option.value} value={option}>
          {option.label}
        </ComboboxItem>
      )}
    </ComboboxList>
  </ComboboxContent>
</Combobox>
```

## Subcomponents

- `Combobox`: Root. Manages open state and selected value. Accepts `size`, `multiple`, `disabled`, `items`, `value`, `onValueChange`, `defaultValue`.
- `ComboboxTrigger`: The button that opens the dropdown. Includes the clear button and caret icon automatically. Pass `hideIcon` to suppress the caret.
- `ComboboxValue`: Renders the selected value or placeholder inside the trigger. Pass a render function as `children` to display custom content such as an icon + label pair.
- `ComboboxTagsValue`: Multi-select value display. Shows selected items as removable badge chips. Collapses items beyond `maxCount` into a "+N more" chip that clears the overflow on click.
- `ComboboxClear`: The ×-button that clears the selection. Rendered automatically inside `ComboboxTrigger`.
- `ComboboxContent`: The dropdown panel. Renders in a portal and positions relative to the trigger.
- `ComboboxInput`: The search text field inside the dropdown. Base UI filters items automatically as the user types.
- `ComboboxList`: The scrollable list of items. When `multiple`, prepends a Select All row automatically (suppress with `hideSelectAll`). Accepts a render function for item rendering.
- `ComboboxItem`: An individual option. Shows a checkmark (single-select) or checkbox (multi-select) for the selected state. Accepts an `Icon` prop.
- `ComboboxGroup`: Groups related items inside `ComboboxContent`. Pair with `ComboboxLabel` to add a visible heading.
- `ComboboxLabel`: Non-interactive heading for a `ComboboxGroup`.
- `ComboboxEmpty`: Empty-state message shown when the filtered list has no matching items.
- `ComboboxSelectAll`: A "Select All" item rendered automatically by `ComboboxList` in `multiple` mode. Use directly to customise the label text.
- `ComboboxSeparator`: Horizontal rule for visually separating item groups.
- `ComboboxBadge`: A removable badge chip for multi-select values. Used inside `ComboboxTagsValue` automatically; can be composed standalone.

## Examples

### Small size

<Canvas of={ComboboxStories.SmallSize} layout="padded" sourceState="shown" />

### Extra small size

<Canvas of={ComboboxStories.XsSize} layout="padded" sourceState="shown" />

### Items with icons

<Canvas of={ComboboxStories.WithIcons} layout="padded" sourceState="shown" />

### Items with images

<Canvas of={ComboboxStories.WithImages} layout="padded" sourceState="shown" />

### Clear button

<Canvas of={ComboboxStories.ClearButton} layout="padded" sourceState="shown" />

### Empty states

<Canvas of={ComboboxStories.EmptyStates} layout="padded" sourceState="shown" />

### Empty states (multi-select)

<Canvas
  of={ComboboxStories.EmptyStatesMulti}
  layout="padded"
  sourceState="shown"
/>

### Disabled

<Canvas of={ComboboxStories.Disabled} layout="padded" sourceState="shown" />

### Multi-select

<Canvas of={ComboboxStories.MultiSelect} layout="padded" sourceState="shown" />

## Related components

- `SimpleSelect` for a non-searchable select from an options array
- `Select` for a non-searchable select with custom trigger or item content