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

<Meta title="Form/Select/Primitive" of={SelectStories} />

<Title>Select</Title>
<Subtitle>
  Composable select primitives built on Radix UI. Assemble trigger, content, and
  items to build fully custom select experiences.
</Subtitle>
<LifecycleTag variant="Stable" />
**Component type:** Primitive

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

## When to use

Use the `Select` primitives when you need a custom trigger (a `Button`, a heading, an icon-only element) or custom item content not covered by `SimpleSelect`. For a standard option list, use `SimpleSelect` instead.

## Import

```tsx
import {
  Select,
  SelectTrigger,
  SelectContent,
  SelectItem,
  SelectValue,
} from '@chainlink/blocks'
```

## Anatomy

```tsx
<Select>
  <SelectTrigger>
    <SelectValue placeholder="Select an option" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">Option 1</SelectItem>
    <SelectItem value="option2">Option 2</SelectItem>
  </SelectContent>
</Select>
```

## Subcomponents

- `Select`: Root. Manages open/value state. Accepts `size`, `clearable`, `defaultValue`, `value`, `onValueChange`.
- `SelectTrigger`: The button that opens the dropdown. Pass `asChild` to replace it with a custom element.
- `SelectValue`: Renders the selected value or placeholder inside the trigger.
- `SelectIcon`: The dropdown caret. Used inside custom `asChild` triggers to retain the arrow.
- `SelectContent`: The dropdown panel containing items.
- `SelectItem`: An individual option. Accepts `value`, `Icon`, and `disabled`.

## Examples

### Small size

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

### Extra small size

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

### Button custom trigger

<Canvas
  of={SelectStories.ButtonCustomTrigger}
  layout="padded"
  sourceState="shown"
/>

### Text custom trigger

<Canvas
  of={SelectStories.TextCustomTrigger}
  layout="padded"
  sourceState="shown"
/>

### Items with icons

<Canvas of={SelectStories.ItemsWithIcons} layout="padded" sourceState="shown" />

### Clearable

<Canvas of={SelectStories.Clearable} layout="padded" sourceState="shown" />

### Not clearable

<Canvas of={SelectStories.NotClearable} layout="padded" sourceState="shown" />

### Empty states

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

### Content wider than trigger

<Canvas
  of={SelectStories.ContentWiderThanTrigger}
  layout="padded"
  sourceState="shown"
/>

## Related components

- `SimpleSelect` for standard option lists without custom markup