@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/segmented/segmented.meta.md

@@ -1,106 +0,0 @@
----
-id: segmented
-name: Segmented
-type: component
-category: deprecated
-since: 0.1.0
-package: '@teamix-evo/ui'
-displayName: 分段控制器
----
-
-# Segmented 分段控制器
-
-分段控制器 — antd 独有补足。**等价 antd `Segmented`**(v5.0+)。视觉类似 iOS/macOS 系统 Segmented Control,强调**互斥单选 + 紧凑紧贴**(日 / 周 / 月、列表 / 网格、明 / 暗主题切换)。
-
-> ⚠️ **后续废弃计划**(Task #10 后能力合并):本组件能力已被 `Tabs` 的 `variant="capsule"` + `size` 完全吸收。新项目推荐直接用 [`Tabs`](../tabs/tabs.meta.md) `variant="capsule"`。**本 entry 本轮不删**(防止存量业务 import 断裂),下一个 major 评估迁移进度后从 manifest 下架。
-
-## When to use
-
-- 视图切换(列表 / 网格 / 时间轴)
-- 时间区间切换(日 / 周 / 月 / 年)
-- 主题 / 设置项的 2~4 档枚举(配 icon 视觉更直观)
-
-## When NOT to use
-
-- 工具栏按钮组(多选 / 不互斥)→ `ToggleGroup`
-- 数据流单选过滤 → `RadioGroup`
-- 选项超过 6 个 → 改用 `Select` / `Tabs`
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `options` | `SegmentedOption[]` | – | ✓ | 候选项数组。 |
-| `value` | `string` | – | – | 受控 value。 |
-| `defaultValue` | `string` | – | – | uncontrolled 初值。 |
-| `onChange` | `(value: string) => void` | – | – | value 变化回调。 |
-| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
-| `block` | `boolean` | `false` | – | 是否撑满父容器宽度(antd `block` 并集)。 |
-| `disabled` | `boolean` | – | – | 整组禁用。 |
-<!-- auto:props:end -->
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add segmented` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add class-variance-authority@^0.7.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **选项数控制在 2~5 个**:Segmented 是紧凑控件,超过 5 个会拥挤
-- **同语义同长度文本**:`日 / 周 / 月` 比 `今天的视图 / 本周 / 月` 视觉对称
-- **配 icon 时图标尺寸 ≤ 16px**:Segmented 高度只有 32~40px,icon 大了挤压文字
-- **`block=true`** 用于在容器内撑满(如卡片头切换视图);默认 fit-content 紧凑
-- **不要用 Segmented 触发危险操作**:它是单选切换语义,不是按钮组
-- **disabled 单项**:配 `disabled` 的选项依然显示,但点击 / 键盘均不可达
-
-## Examples
-
-```tsx
-import { Segmented } from '@/components/ui/segmented';
-import { LayoutGrid, List, Calendar } from 'lucide-react';
-import * as React from 'react';
-
-// 基础
-<Segmented
-  options={[
-    { value: 'day', label: '日' },
-    { value: 'week', label: '周' },
-    { value: 'month', label: '月' },
-  ]}
-  defaultValue="week"
-/>
-
-// 配 icon
-const [view, setView] = React.useState('grid');
-<Segmented
-  value={view}
-  onChange={setView}
-  options={[
-    { value: 'grid', label: '网格', icon: <LayoutGrid className="size-4" /> },
-    { value: 'list', label: '列表', icon: <List className="size-4" /> },
-    { value: 'cal', label: '日历', icon: <Calendar className="size-4" /> },
-  ]}
-/>
-
-// block 撑满
-<Segmented
-  block
-  options={[
-    { value: 'light', label: '浅色' },
-    { value: 'dark', label: '深色' },
-    { value: 'system', label: '跟随系统' },
-  ]}
-/>
-```

package/src/components/segmented/segmented.stories.tsx

@@ -1,130 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Calendar, LayoutGrid, List } from 'lucide-react';
-import { Segmented } from './segmented';
-
-const meta: Meta<typeof Segmented> = {
-  title: '废弃 · Deprecated/Segmented',
-  component: Segmented,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n分段控制器 — iOS / macOS 风格的紧凑互斥单选（视图切换、时间区间、主题档）。等价 antd `Segmented`（v5.0+），与 ToggleGroup 互补（后者偏工具栏多选）。',
-      },
-    },
-  },
-  argTypes: {
-    size: { control: 'inline-radio', options: ['sm', 'default', 'lg'] },
-    block: { control: 'boolean' },
-    disabled: { control: 'boolean' },
-  },
-  args: { size: 'default', block: false, disabled: false },
-};
-
-export default meta;
-type Story = StoryObj<typeof Segmented>;
-
-export const Playground: Story = {
-  render: (args) => (
-    <Segmented
-      {...args}
-      defaultValue="week"
-      options={[
-        { value: 'day', label: '日' },
-        { value: 'week', label: '周' },
-        { value: 'month', label: '月' },
-      ]}
-    />
-  ),
-};
-
-export const WithIcons: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [v, setV] = React.useState('grid');
-    return (
-      <Segmented
-        value={v}
-        onChange={setV}
-        options={[
-          {
-            value: 'grid',
-            label: '网格',
-            icon: <LayoutGrid className="size-4" />,
-          },
-          { value: 'list', label: '列表', icon: <List className="size-4" /> },
-          {
-            value: 'cal',
-            label: '日历',
-            icon: <Calendar className="size-4" />,
-          },
-        ]}
-      />
-    );
-  },
-};
-
-export const Block: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="w-80">
-      <Segmented
-        block
-        defaultValue="light"
-        options={[
-          { value: 'light', label: '浅色' },
-          { value: 'dark', label: '深色' },
-          { value: 'system', label: '跟随系统' },
-        ]}
-      />
-    </div>
-  ),
-};
-
-export const Sizes: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <div className="flex flex-col items-start gap-3">
-      <Segmented
-        size="sm"
-        defaultValue="a"
-        options={[
-          { value: 'a', label: 'A' },
-          { value: 'b', label: 'B' },
-        ]}
-      />
-      <Segmented
-        size="default"
-        defaultValue="a"
-        options={[
-          { value: 'a', label: 'A' },
-          { value: 'b', label: 'B' },
-        ]}
-      />
-      <Segmented
-        size="lg"
-        defaultValue="a"
-        options={[
-          { value: 'a', label: 'A' },
-          { value: 'b', label: 'B' },
-        ]}
-      />
-    </div>
-  ),
-};
-
-export const WithDisabledItem: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <Segmented
-      defaultValue="open"
-      options={[
-        { value: 'open', label: '进行中' },
-        { value: 'closed', label: '已关闭' },
-        { value: 'archived', label: '已归档', disabled: true },
-      ]}
-    />
-  ),
-};

package/src/components/segmented/segmented.tsx

@@ -1,146 +0,0 @@
-import * as React from 'react';
-import { cva, type VariantProps } from 'class-variance-authority';
-
-import { cn } from '@/utils/cn';
-
-const segmentedVariants = cva(
-  'inline-flex w-fit items-center rounded-md bg-muted p-1',
-  {
-    variants: {
-      size: {
-        sm: 'h-8 text-xs',
-        md: 'h-9 text-xs',
-        default: 'h-9 text-xs',
-        lg: 'h-10 text-sm',
-      },
-      block: { true: 'w-full', false: 'w-fit' },
-    },
-    defaultVariants: { size: 'md', block: false },
-  },
-);
-
-const itemVariants = cva(
-  'flex items-center justify-center gap-1.5 rounded-sm px-3 transition-all cursor-pointer select-none focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
-  {
-    variants: {
-      active: {
-        true: 'bg-card text-foreground shadow-sm',
-        false: 'text-muted-foreground hover:text-foreground',
-      },
-      disabled: {
-        true: 'cursor-not-allowed opacity-50 hover:text-muted-foreground',
-        false: '',
-      },
-      block: { true: 'flex-1', false: '' },
-    },
-    defaultVariants: { active: false, disabled: false, block: false },
-  },
-);
-
-export interface SegmentedOption {
-  /** 真实 value(受控比对依据)。 */
-  value: string;
-  /** 显示文本。 */
-  label: React.ReactNode;
-  /** 左侧图标(可选)。 */
-  icon?: React.ReactNode;
-  /** 禁用此项。 */
-  disabled?: boolean;
-}
-
-export interface SegmentedProps
-  extends Omit<
-      React.HTMLAttributes<HTMLDivElement>,
-      'onChange' | 'defaultValue'
-    >,
-    VariantProps<typeof segmentedVariants> {
-  /** 候选项数组。 */
-  options: SegmentedOption[];
-  /** 受控 value。 */
-  value?: string;
-  /** uncontrolled 初值。 */
-  defaultValue?: string;
-  /** value 变化回调。 */
-  onChange?: (value: string) => void;
-  /**
-   * 尺寸。
-   * @default "default"
-   */
-  size?: 'sm' | 'md' | 'default' | 'lg';
-  /**
-   * 是否撑满父容器宽度(antd `block` 并集)。
-   * @default false
-   */
-  block?: boolean;
-  /** 整组禁用。 */
-  disabled?: boolean;
-}
-
-/**
- * 分段控制器 — antd 独有补足。**等价 antd `Segmented`**(v5.0+)。
- * 与 `ToggleGroup` 区别:Segmented 视觉**类似 iOS / macOS 系统的 Segmented Control**,
- * 强调"互斥单选 + 紧凑紧贴"(同语义的视图切换:日/周/月、列表/网格);
- * ToggleGroup 偏向工具栏按钮(可选 multiple、视觉更"按钮化")。
- */
-const Segmented = React.forwardRef<HTMLDivElement, SegmentedProps>(
-  (
-    {
-      options,
-      value,
-      defaultValue,
-      onChange,
-      size,
-      block,
-      disabled = false,
-      className,
-      ...props
-    },
-    ref,
-  ) => {
-    const isControlled = value !== undefined;
-    const [internal, setInternal] = React.useState<string>(
-      defaultValue ?? options[0]?.value ?? '',
-    );
-    const current = isControlled ? value! : internal;
-
-    const select = (next: string) => {
-      if (!isControlled) setInternal(next);
-      onChange?.(next);
-    };
-
-    return (
-      <div
-        ref={ref}
-        role="radiogroup"
-        className={cn(segmentedVariants({ size, block }), className)}
-        {...props}
-      >
-        {options.map((opt) => {
-          const itemDisabled = disabled || opt.disabled;
-          const active = opt.value === current;
-          return (
-            <button
-              key={opt.value}
-              type="button"
-              role="radio"
-              aria-checked={active}
-              disabled={itemDisabled}
-              onClick={() => !itemDisabled && select(opt.value)}
-              className={cn(
-                itemVariants({ active, disabled: itemDisabled, block }),
-              )}
-            >
-              {opt.icon ? (
-                <span className="inline-flex">{opt.icon}</span>
-              ) : null}
-              {opt.label}
-            </button>
-          );
-        })}
-      </div>
-    );
-  },
-);
-Segmented.displayName = 'Segmented';
-
-export { Segmented };

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

@@ -1,255 +0,0 @@
----
-id: select
-name: Select
-type: component
-category: data-entry
-since: 0.1.0
-package: '@teamix-evo/ui'
-displayName: 下拉选择
----
-
-# Select 下拉选择
-
-下拉选择 — **单组件覆盖 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
-
-- 单选(`<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
-
-- 选项 ≤ 4 → `RadioGroup`(更直观,无需展开)
-- 自由文本输入 → `Input`
-- 树形选择 → `TreeSelect` / `Cascader`
-- 多列级联选择 → `Cascader`
-- 命令面板 / 全局搜索 → `Command`(直接用底层 cmdk,不要走 Select)
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `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 -->
-
-## 依赖
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add select` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| 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 @tanstack/react-virtual@^3.0.0 lucide-react@^0.460.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **数据驱动 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 } 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>
-  </SelectContent>
-</Select>
-
-// ✅ After(W3+,数据驱动)
-<Select
-  onChange={(next) => setV(next as string)}
-  placeholder="选择城市"
-  options={[
-    { value: 'bj', label: '北京' },
-    { value: 'sh', label: '上海' },
-  ]}
-/>
-```
-
-```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` 扁平列表