@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/select/select.meta.md

@@ -2,43 +2,71 @@
 id: select
 name: Select
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 下拉选择
 ---
 
-# Select
+# Select 下拉选择
 
-下拉选择 — Radix Select 标准实现。**仅单选**(Radix Select 设计如此),多选 / 搜索请用 `Combobox`(基于 Command + Popover,在 v0.x)。
-对应 antd `Select` 的最常见单选场景;antd 的 `mode="multiple"` / `showSearch` / `tags` 等高级形态由 Combobox 接力。
+下拉选择 — **单组件覆盖 cd `Select` 全部模式**:单选 / 多选 / 搜索 / 标签创建(creatable)/ 远程异步(onSearch)/ 虚拟滚动(virtual)/ 弹层容器(container)。基于 **Popover + cmdk Command + @tanstack/react-virtual**;触发器 `size` 三档与 Button / Input 同档(24 / 32 / 36)。原独立的 `Combobox` 已合并入此组件(参考 ButtonGroup → Button、Textarea → Input 范式)。
+
+> **W3 重构**(2026-06):原 `Select`(Radix Select 单选基础版) + `Combobox`(独立多选/搜索) 合并为一个数据驱动的 `Select`,完整对齐 cd hybridcloud `Select` 全部能力。原 JSX-style API(`SelectTrigger` / `SelectContent` / `SelectItem`)已下线,业务侧需迁移到数据驱动 API(`options` / `groups` / `value`)。详见 §[迁移指南](#迁移指南--从旧版-jsx-api--新数据驱动-api)。
 
 ## When to use
 
-- 单选枚举(状态 / 类型 / 区域 / 时区等)
-- 选项 ≥ 5 时替代 RadioGroup
-- 选项较长 / 需要分组 / 需要 Label 分隔
+- 单选(`<Select options={...} />`)— 单值场景
+- 多选(`<Select multiple options={...} />`)— Tag 形式回显已选项
+- 可搜索过滤(`searchable`)— 弹层顶部搜索框,本地 filter
+- 远程异步(`onSearch`)— 输入触发拉接口刷新 options(自动关闭本地 filter)
+- 自由创建标签(`creatable` + `multiple`)— 等价 cd `mode="tag"`,经典 Tag 输入器
+- 大数据集(`virtual`)— ≥ 100 项时启用虚拟滚动,首次渲染显著优化
+- 内层容器场景(`container`)— Dialog / Drawer / 自定义 overlay 内,Portal 挂到指定节点
 
 ## When NOT to use
 
-- 多选 / 可搜索 → `Combobox`(v0.x)
-- 选项 ≤ 4 → `RadioGroup`(更直观)
-- 自由输入 → `Input`
-- 需要异步加载选项 → `Combobox` + 自定义数据源
+- 选项 ≤ 4 → `RadioGroup`(更直观,无需展开)
+- 自由文本输入 → `Input`
+- 树形选择 → `TreeSelect` / `Cascader`
+- 多列级联选择 → `Cascader`
+- 命令面板 / 全局搜索 → `Command`(直接用底层 cmdk,不要走 Select)
 
 ## Props
 
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `SelectTrigger` 的 props;`Select`(Root)透传 Radix `value / defaultValue / onValueChange / open / disabled / required / name`。
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `position` | `React.ComponentPropsWithoutRef< typeof SelectPrimitive.Content >['position']` | `"popper"` | – | 浮层定位策略。`popper` 跟随 trigger 并自动避让边界;`item-aligned` 把当前选中项与 trigger 对齐(类似原生 `<select>`)。默认 `popper` 与 antd Select 行为一致。 |
+| `options` | `SelectOption[]` | – | – | 扁平选项列表(与 `groups` 二选一)— 等价 antd `<Select options>` 数据驱动模式。 |
+| `groups` | `SelectOptionGroup[]` | – | – | 分组选项列表 — 等价 antd `<Select.OptGroup>`,数据驱动版本。 |
+| `multiple` | `boolean` | `false` | – | 多选模式(antd `mode="multiple"` 并集)。开启后 `value` / `defaultValue` 为 `string[]`,选中项以 Tag 形式回显。 |
+| `searchable` | `boolean` | `false` | – | 启用搜索(antd `showSearch` 并集) — 弹层顶部出现搜索输入框。 |
+| `creatable` | `boolean` | `false` | – | 允许创建新项(antd `mode="tag"` 并集) — 输入未匹配现有选项时,顶部显示 "Create &lt;query&gt;" 项,Enter 或点击即创建并选中。配合 `multiple` 是经典 Tag 模式。 创建时通过 `onCreate(value)` 通知消费方(由消费方决定是否把新项追加到 `options`)。 |
+| `onCreate` | `(value: string) => void` | – | – | 创建新项时的回调(creatable 模式) — 消费方据此追加 options。 |
+| `onSearch` | `(query: string) => void` | – | – | 异步搜索(antd `onSearch` 并集)— 输入变化时触发,消费方据 `query` 拉接口刷新 `options`。 触发后默认**关闭本地 filter**(因为远端已经过滤过);如需保留本地 filter,设 `filter={true}` 显式启用。 |
+| `filter` | `boolean \| ((query: string, option: SelectOption) => boolean)` | `true` | – | 是否启用本地 filter:`true`(默认) / `false` / 自定义函数。 配合 `onSearch` 时通常设 `false` — 服务端已过滤,本地不再筛。 |
+| `value` | `SelectValue` | – | – | 受控 value — 单选 `string`、多选 `string[]`。 |
+| `defaultValue` | `SelectValue` | – | – | uncontrolled 初值。 |
+| `onChange` | `((value: string) => void) \| ((value: string[]) => void)` | – | – | value 变化回调。 |
+| `maxTagCount` | `number` | – | – | 多选模式下展示的最大 Tag 数,超出折叠为 `+N`(antd `maxTagCount` 并集)。 |
+| `placeholder` | `string` | `"请选择..."` | – | 触发器占位文本。 |
+| `searchPlaceholder` | `string` | `"搜索..."` | – | 搜索框占位文本(searchable / creatable 时生效)。 |
+| `emptyText` | `string` | `"无匹配项"` | – | 无匹配项时的提示文本。 |
+| `hideEmptyOptionGroup` | `boolean` | `true` | – | 搜索后无匹配项的分组是否隐藏(antd `hideEmptyOptionGroup` 并集)。 |
+| `clearable` | `boolean` | `false` | – | 显示清除按钮(antd `allowClear` 并集) — 触发器有值时右侧 ✕,点击清空。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"md"` | – | 触发器尺寸 — 与 Button / Input 同档:`sm`(24) / `md`(32) / `lg`(36)。 |
+| `error` | `boolean` | `false` | – | 错误态(自动设置 `aria-invalid="true"`,渲染 destructive 边框)。 |
+| `disabled` | `boolean` | – | – | 禁用整个组件。 |
+| `className` | `string` | – | – | 触发器额外类名(可覆盖宽度 / 边距等)。 |
+| `contentClassName` | `string` | – | – | 弹层 className。 |
+| `container` | `HTMLElement \| null` | – | – | 弹层挂载容器(antd `popupContainer` 并集) — 透传给 Popover Portal。 默认挂在 `document.body`;在内层滚动容器 / Dialog 内时常需指定。 |
+| `virtual` | `boolean \| { threshold?: number; itemHeight?: number }` | `false (传 `true` 等价 `{ threshold: 100, itemHeight: 36 }`)` | – | 虚拟滚动(antd `virtual`) — 选项数 ≥ `threshold` 时启用 react-virtual, 大数据集下显著优化首次渲染。注意:启用后本地 filter 仍生效但分组渲染受限 (groups + virtual 同时启用时按 flatten 渲染),业务侧大数据集建议直接走 options。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -47,64 +75,181 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `command` | component | 命令面板 / 下拉底座 — cmdk(Linear / Raycast 风格)提供过滤 / 键盘导航 / a11y;同时为 Combobox / Select / AutoComplete 提供同源下拉内核 |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
 
 ### npm 依赖
 
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add @radix-ui/react-select@^2.1.0 lucide-react@^0.460.0
+pnpm add @tanstack/react-virtual@^3.0.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
-> 完整子组件:`Select / SelectGroup / SelectValue / SelectTrigger / SelectContent / SelectLabel / SelectItem / SelectSeparator / SelectScrollUpButton / SelectScrollDownButton`。
-
 ## AI 生成纪律
 
-- **`SelectValue` 配 placeholder**:`<SelectValue placeholder="..." />` 提供未选时的占位文字
-- **每个 SelectItem 必有 value**:不能空字符串(Radix 拒绝);用稳定 ID
-- **大量选项必分组**:超过 8 个用 `SelectGroup` + `SelectLabel`,加 `SelectSeparator` 分段
-- **不要嵌套 Select**:嵌套下拉是反模式
-- **键盘可用性自带**:Radix 自动支持 Type-ahead(首字母搜索),不需要再加 search
+- **数据驱动 API**:`options: SelectOption[]` 或 `groups: SelectOptionGroup[]` 二选一,**不要**回到 JSX 子组件嵌套(原 `<SelectItem>` 已下线)
+- **multiple 模式 value 是 `string[]`** — 单选是 `string`;TypeScript 上联合类型,业务侧传值时形态要与 `multiple` 匹配
+- **creatable 必配 onCreate**:消费方在 `onCreate(value)` 回调中决定是否把新项追加到 `options`(否则只是临时选中,关闭后丢失)
+- **onSearch 异步搜索 + filter=false 配合用**:`onSearch` 默认会关闭本地 filter(避免"客户端 filter + 服务端 filter 双过滤"导致结果空集);如果想保留本地 filter,显式 `filter={true}`
+- **virtual 启用门槛**:`options.length >= threshold`(默认 100)才启用;小数据集走 cmdk 路径(更轻量、自带 keyboard nav)
+- **container 用法**:仅在 Dialog / Drawer / 自定义 overlay 内才需要;默认挂 `document.body` 即可。Dialog 内必须传 container 否则 Popover 会被 Dialog overlay 遮挡
+- **size 三档**:`sm`(24) / `md`(32) / `lg`(36),与 Button / Input 同档;`"default"` 仅向后兼容,新代码用 `"md"`
+- **error 走 aria-invalid**:`error=true` 自动设 `aria-invalid="true"` + destructive 边框;**不要**手写 `border-destructive`
+- **clearable 与 maxTagCount 组合用**:多选 + 大量已选项时,`maxTagCount` 折叠展示,`clearable` 一键清空,UX 更友好
 
 ## Examples
 
 ```tsx
-import {
-  Select, SelectTrigger, SelectValue, SelectContent,
-  SelectGroup, SelectLabel, SelectItem, SelectSeparator,
-} from '@/components/ui/select';
-
-// 基础
-<Select>
-  <SelectTrigger className="w-48">
+import { Select } from '@/components/ui/select';
+
+// 单选
+<Select
+  options={[
+    { value: 'bj', label: '北京' },
+    { value: 'sh', label: '上海' },
+  ]}
+  placeholder="选择城市"
+/>
+
+// 单选 + 受控
+const [v, setV] = React.useState('bj');
+<Select
+  options={cityOptions}
+  value={v}
+  onChange={(next) => setV(next as string)}
+/>
+
+// 分组
+<Select
+  groups={[
+    { label: '亚洲', options: [{ value: 'cn', label: '北京' }] },
+    { label: '欧洲', options: [{ value: 'uk', label: '伦敦' }] },
+  ]}
+/>
+
+// 可搜索
+<Select searchable options={cityOptions} />
+
+// 多选 + 折叠 +N
+<Select multiple maxTagCount={3} options={cityOptions} defaultValue={['bj','sh','hz','sz']} />
+
+// Creatable / Tag 模式(对齐 cd `mode="tag"`)
+const [opts, setOpts] = React.useState([...]);
+<Select
+  multiple
+  creatable
+  searchable
+  options={opts}
+  onCreate={(val) => setOpts(prev => [...prev, { value: val, label: val }])}
+/>
+
+// 远程异步搜索
+const [opts, setOpts] = React.useState([]);
+<Select
+  searchable
+  options={opts}
+  onSearch={async (q) => {
+    const list = await api.search(q);
+    setOpts(list);
+  }}
+/>
+
+// 虚拟滚动(5000 项)
+<Select searchable virtual options={hugeList} />
+
+// Dialog 内场景:挂到 Dialog 容器
+const dialogRef = React.useRef<HTMLDivElement>(null);
+<DialogContent ref={dialogRef}>
+  <Select options={...} container={dialogRef.current} />
+</DialogContent>
+```
+
+## Select 形态 — 旧库 API → 新库映射
+
+> cd hybridcloud `Select` 单组件多模式;新库 W3 重构后也是单组件多模式 — 模式拆为 prop 而非组件。
+
+### 命名映射
+
+| cloud-design / antd 旧库 | `@teamix-evo/ui` Select | 备注 |
+| --- | --- | --- |
+| `<Select mode="single">` | `<Select>` | 默认单选 |
+| `<Select mode="multiple">` | `<Select multiple>` | Tag 回显 |
+| `<Select mode="tag">` | `<Select multiple creatable>` | 拆为两个 prop |
+| `<Select.AutoComplete>` | `<Select searchable creatable>` | 合并到 Select |
+| `dataSource` / `children OptGroup` | `options={...}` / `groups={...}` | 数据驱动 |
+| `showSearch` | `searchable` | ✅ |
+| `showSearch + onSearch` | `searchable` + `onSearch` | ✅ async 远程 |
+| `useVirtual` | `virtual`(默认 false,设 true 启用) | ✅ 阈值 100 项 |
+| `popupContainer` | `container` | ✅ 透传 Popover Portal |
+| `popupClassName` / `popupStyle` | `contentClassName` | API 精简 |
+| `maxTagCount` | `maxTagCount` | ✅ 同名 |
+| `hasClear` | `clearable` | ✅ |
+| `value` / `defaultValue` / `onChange` | 同名;value 类型由 `multiple` 决定 | `string` 或 `string[]` |
+| `visible` / `onVisibleChange` | `open` / `onOpenChange` | (Radix Popover 透传) |
+| `hasArrow` | 不修复 — 走 outline 视觉 | — |
+| `fillProps` / `displayValue` | 不修复 — `SelectOption.label` 直接接 ReactNode | — |
+| `filterTreeNode` | `filter` prop(自定义函数) | 单选 / 多选都可 |
+| `hasBorder={false}` | `className="border-0"` 自定义 | — |
+
+### Breaking Changes(从原 v0.1 Select 迁移时需改写)
+
+> 注意:这是**新旧 @teamix-evo/ui Select** 之间的 breaking,不是 cd → @teamix-evo/ui 的迁移。cd → @teamix-evo/ui 见上方命名映射表。
+
+1. **JSX 子组件 API 已下线** — 原 `<SelectTrigger>` / `<SelectContent>` / `<SelectItem>` / `<SelectValue>` / `<SelectGroup>` / `<SelectLabel>` / `<SelectSeparator>` 全部移除,改用数据驱动 API
+2. **value 类型** — 单选保持 `string`,多选必须是 `string[]`(原 v0.1 仅支持单选)
+3. **onChange 签名** — 原 Radix `onValueChange` 改为 `onChange`,支持 `(string) => void`(单选)或 `(string[]) => void`(多选)
+4. **`searchable` 默认 false** — 原 Combobox 默认 true;现合并到 Select 后默认关闭(对齐 cd `showSearch` 默认 false)
+5. **Combobox 已下线** — 原从 `@/components/ui/combobox` 导入 `Combobox` 的代码,改为从 `@/components/ui/select` 导入 `Select` 即可(props 大致兼容,部分命名优化)
+
+### 迁移指南 — 从旧版 JSX API → 新数据驱动 API
+
+```tsx
+// ❌ Before(旧 v0.1 Select,JSX 子组件)
+<Select onValueChange={setV}>
+  <SelectTrigger>
     <SelectValue placeholder="选择城市" />
   </SelectTrigger>
   <SelectContent>
     <SelectItem value="bj">北京</SelectItem>
     <SelectItem value="sh">上海</SelectItem>
-    <SelectItem value="hz">杭州</SelectItem>
   </SelectContent>
 </Select>
 
-// 分组
-<Select>
-  <SelectTrigger className="w-48"><SelectValue placeholder="选择时区" /></SelectTrigger>
-  <SelectContent>
-    <SelectGroup>
-      <SelectLabel>亚洲</SelectLabel>
-      <SelectItem value="cn">北京时间 (UTC+8)</SelectItem>
-      <SelectItem value="jp">东京时间 (UTC+9)</SelectItem>
-    </SelectGroup>
-    <SelectSeparator />
-    <SelectGroup>
-      <SelectLabel>欧洲</SelectLabel>
-      <SelectItem value="uk">伦敦时间 (UTC+0)</SelectItem>
-    </SelectGroup>
-  </SelectContent>
-</Select>
+// ✅ After(W3+,数据驱动)
+<Select
+  onChange={(next) => setV(next as string)}
+  placeholder="选择城市"
+  options={[
+    { value: 'bj', label: '北京' },
+    { value: 'sh', label: '上海' },
+  ]}
+/>
+```
 
-// 受控
-const [v, setV] = React.useState('bj');
-<Select value={v} onValueChange={setV}>...</Select>
+```tsx
+// ❌ Before(旧 Combobox)
+import { Combobox } from '@/components/ui/combobox';
+<Combobox multiple searchable options={...} />
+
+// ✅ After(W3+,Combobox 合一进 Select)
+import { Select } from '@/components/ui/select';
+<Select multiple searchable options={...} />
 ```
+
+### 不修复 / 后续工序清单
+
+- **`hasArrow` / `hasBorder={false}`**:走 outline trigger 视觉一致;需要无边框时自定义 `className="border-0 shadow-none"`
+- **`fillProps` / `displayValue`**:`SelectOption.label` 已支持 ReactNode,自定义渲染直接传节点
+- **`itemRender` / `valueRender`**:同上,通过 label 节点渲染
+- **`onMouseEnter` / `onMouseLeave` 选项级**:不修复 — 业务低频,需要时用 `label: <span onMouseEnter={...}>` 自管
+- **`isPreview` / `renderPreview`**:不修复 — 走 `disabled` + 自定义渲染替代
+
+### Select 专项 AI 生成纪律
+
+- 数据驱动 — `options` 或 `groups` 二选一;`groups[].options[]` 不可空数组
+- `keywords` 用于扩展搜索匹配 — 当 `label` 是富节点(如带图标)无法直接 includes 匹配时,通过 `keywords: ['搜索关键字','别名']` 让 cmdk 命中
+- creatable 时业务侧 `onCreate` 必须更新 `options`,否则关闭弹层后新创建项丢失(只在已选 value 中,但下次打开时无对应 label)
+- 远程搜索时 `emptyText` 建议条件渲染:加载中 → "加载中...",未输入 → "请输入关键字",无结果 → "无匹配项"
+- virtual 启用后 `groups` 渲染受限(强制 flatten),业务大数据集建议直接走 `options` 扁平列表

package/src/components/select/select.stories.tsx

@@ -1,32 +1,64 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import {
-  Select,
-  SelectTrigger,
-  SelectValue,
-  SelectContent,
-  SelectGroup,
-  SelectLabel,
-  SelectItem,
-  SelectSeparator,
-} from './select';
-
-const meta: Meta<typeof SelectTrigger> = {
-  title: '表单与输入 · Form/Select',
-  component: SelectTrigger,
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Select } from './select';
+
+const cityOptions = [
+  { value: 'bj', label: '北京' },
+  { value: 'sh', label: '上海' },
+  { value: 'hz', label: '杭州' },
+  { value: 'sz', label: '深圳' },
+];
+
+const tzGroups = [
+  {
+    label: '亚洲',
+    options: [
+      { value: 'cn', label: '北京时间 (UTC+8)' },
+      { value: 'jp', label: '东京时间 (UTC+9)' },
+      { value: 'sg', label: '新加坡时间 (UTC+8)' },
+    ],
+  },
+  {
+    label: '欧洲',
+    options: [
+      { value: 'uk', label: '伦敦时间 (UTC+0)' },
+      { value: 'de', label: '柏林时间 (UTC+1)' },
+    ],
+  },
+];
+
+const meta: Meta<typeof Select> = {
+  title: '数据录入 · Data Entry/Select',
+  component: Select,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '下拉选择 — 从预置选项中选中一个值，由按钮触发弹出选项列表。Radix Select 实现 + antd Select 的并集能力：支持 `SelectGroup` / `SelectLabel` / `SelectSeparator` 组合出分组下拉，`size`（sm / default / lg）可调，默认带键盘导航与文本检索。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '下拉选择 — 单组件覆盖 cd `Select` 全部模式:**单选 / 多选 / 搜索 / 标签创建(creatable)/ 远程异步 / 虚拟滚动**。基于 Popover + cmdk Command;触发器 `size` 三档与 Button / Input 同档(24/32/36)。原 `Combobox` 已合并入此组件。',
       },
     },
   },
   argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
+    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
+    multiple: { control: 'boolean' },
+    searchable: { control: 'boolean' },
+    creatable: { control: 'boolean' },
+    clearable: { control: 'boolean' },
     disabled: { control: 'boolean' },
+    error: { control: 'boolean' },
+    placeholder: { control: 'text' },
+  },
+  args: {
+    size: 'md',
+    multiple: false,
+    searchable: false,
+    creatable: false,
+    clearable: false,
+    disabled: false,
+    error: false,
+    placeholder: '请选择...',
   },
-  args: { size: 'default' },
   decorators: [
     (Story) => (
       <div className="w-64">
@@ -37,64 +69,207 @@ const meta: Meta<typeof SelectTrigger> = {
 };
 
 export default meta;
-type Story = StoryObj<typeof SelectTrigger>;
+type Story = StoryObj<typeof Select>;
 
 export const Playground: Story = {
-  render: (args) => (
-    <Select>
-      <SelectTrigger {...args}>
-        <SelectValue placeholder="选择城市" />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value="bj">北京</SelectItem>
-        <SelectItem value="sh">上海</SelectItem>
-        <SelectItem value="hz">杭州</SelectItem>
-        <SelectItem value="sz">深圳</SelectItem>
-      </SelectContent>
-    </Select>
+  render: (args) => <Select {...args} options={cityOptions} />,
+};
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      {(['sm', 'md', 'lg'] as const).map((s) => (
+        <Select
+          key={s}
+          size={s}
+          options={cityOptions}
+          placeholder={`size = ${s} (h-${s === 'sm' ? '6' : s === 'md' ? '8' : '9'})`}
+        />
+      ))}
+    </div>
   ),
 };
 
 export const Grouped: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Select groups={tzGroups} placeholder="选择时区" />,
+};
+
+export const Searchable: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Select>
-      <SelectTrigger>
-        <SelectValue placeholder="选择时区" />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectGroup>
-          <SelectLabel>亚洲</SelectLabel>
-          <SelectItem value="cn">北京时间 (UTC+8)</SelectItem>
-          <SelectItem value="jp">东京时间 (UTC+9)</SelectItem>
-          <SelectItem value="sg">新加坡时间 (UTC+8)</SelectItem>
-        </SelectGroup>
-        <SelectSeparator />
-        <SelectGroup>
-          <SelectLabel>欧洲</SelectLabel>
-          <SelectItem value="uk">伦敦时间 (UTC+0)</SelectItem>
-          <SelectItem value="de">柏林时间 (UTC+1)</SelectItem>
-        </SelectGroup>
-      </SelectContent>
-    </Select>
+    <Select
+      searchable
+      options={cityOptions}
+      placeholder="可搜索的城市"
+      searchPlaceholder="输入城市名..."
+    />
   ),
 };
 
-export const Sizes: Story = {
+export const Multiple: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex flex-col gap-3">
-      {(['sm', 'default', 'lg'] as const).map((s) => (
-        <Select key={s}>
-          <SelectTrigger size={s}>
-            <SelectValue placeholder={`size = ${s}`} />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="a">选项 A</SelectItem>
-            <SelectItem value="b">选项 B</SelectItem>
-          </SelectContent>
-        </Select>
-      ))}
+    <Select
+      multiple
+      options={cityOptions}
+      placeholder="选择多个城市"
+      defaultValue={['bj', 'hz']}
+    />
+  ),
+};
+
+export const MultipleWithMaxTagCount: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Select
+      multiple
+      maxTagCount={2}
+      options={cityOptions}
+      placeholder="最多展示 2 个 Tag,其余折叠 +N"
+      defaultValue={['bj', 'sh', 'hz', 'sz']}
+    />
+  ),
+};
+
+/**
+ * Creatable / Tag 模式 — 等价 cd `Select mode="tag"`。
+ * 输入未匹配 options 的内容时,顶部显示"创建 'xxx'"项,Enter 即创建并选中。
+ * 配合 `multiple` 是经典 Tag 输入器(自由标签创建 + 已选标签 chip 展示)。
+ */
+export const CreatableTags: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [opts, setOpts] = React.useState([
+      { value: 'react', label: 'React' },
+      { value: 'vue', label: 'Vue' },
+      { value: 'angular', label: 'Angular' },
+    ]);
+    return (
+      <Select
+        multiple
+        creatable
+        searchable
+        options={opts}
+        placeholder="选择 / 创建技术栈"
+        searchPlaceholder="输入并按 Enter 创建..."
+        onCreate={(val) => setOpts((prev) => [...prev, { value: val, label: val }])}
+      />
+    );
+  },
+};
+
+/**
+ * 远程异步搜索 — 等价 cd `Select showSearch onSearch`。
+ * `onSearch` 在输入变化时触发(本 demo 模拟接口延迟),消费方据 `query` 拉接口
+ * 刷新 `options`;同时本地 filter 默认关闭(已由服务端过滤)。
+ */
+export const AsyncRemoteSearch: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [opts, setOpts] = React.useState<{ value: string; label: string }[]>(
+      [],
+    );
+    const [loading, setLoading] = React.useState(false);
+
+    const handleSearch = React.useCallback(async (q: string) => {
+      if (!q.trim()) {
+        setOpts([]);
+        return;
+      }
+      setLoading(true);
+      // 模拟接口请求
+      await new Promise((r) => setTimeout(r, 300));
+      setOpts([
+        { value: `${q}-1`, label: `${q} 远程结果 1` },
+        { value: `${q}-2`, label: `${q} 远程结果 2` },
+        { value: `${q}-3`, label: `${q} 远程结果 3` },
+      ]);
+      setLoading(false);
+    }, []);
+
+    return (
+      <Select
+        searchable
+        options={opts}
+        onSearch={handleSearch}
+        placeholder="远程搜索"
+        searchPlaceholder="输入查询关键字..."
+        emptyText={loading ? '加载中...' : '输入关键字开始搜索'}
+      />
+    );
+  },
+};
+
+/**
+ * 虚拟滚动 — 选项数 ≥ `threshold`(默认 100)时启用 `@tanstack/react-virtual`,
+ * 大数据集首次渲染显著提速。本 demo 渲染 5000 项。
+ */
+export const Virtual: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const opts = React.useMemo(
+      () =>
+        Array.from({ length: 5000 }, (_, i) => ({
+          value: `item-${i}`,
+          label: `选项 #${i.toString().padStart(4, '0')}`,
+        })),
+      [],
+    );
+    return (
+      <Select
+        searchable
+        virtual
+        options={opts}
+        placeholder="5000 项 — 虚拟滚动"
+        searchPlaceholder="搜索 5000 个选项..."
+      />
+    );
+  },
+};
+
+export const Clearable: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Select
+      clearable
+      options={cityOptions}
+      defaultValue="bj"
+      placeholder="可清除"
+    />
+  ),
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Select disabled options={cityOptions} placeholder="已禁用" />,
+};
+
+export const Error: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-1">
+      <Select error options={cityOptions} placeholder="请选择(必填)" />
+      <span className="text-xs text-destructive">该字段为必填项</span>
     </div>
   ),
 };
+
+export const Controlled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState<string>('');
+    return (
+      <div className="flex flex-col gap-2">
+        <Select
+          options={cityOptions}
+          value={v}
+          onChange={(next: string | string[]) => setV(next as string)}
+          placeholder="受控单选"
+        />
+        <span className="text-xs text-muted-foreground">当前值: {v || '(未选)'}</span>
+      </div>
+    );
+  },
+};