@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/cascader/cascader.meta.md

@@ -3,7 +3,7 @@ id: cascader
 name: Cascader
 displayName: 级联选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -27,35 +27,21 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称             | 类型                                                           | 默认值      | 必填 | 说明                                                                       |
-| ---------------- | -------------------------------------------------------------- | ----------- | ---- | -------------------------------------------------------------------------- |
-| `options`        | `CascaderOption[]`                                             | –           | ✓    | 级联选项树(antd `options` 并集)。                                          |
-| `value`          | `string[]`                                                     | –           | –    | 受控值(每层 value 数组)。                                                  |
-| `defaultValue`   | `string[]`                                                     | –           | –    | uncontrolled 初值。                                                        |
-| `onChange`       | `(value: string[], selectedOptions: CascaderOption[]) => void` | –           | –    | 值变化回调 — 触发条件:点选叶子节点或显式 changeOnSelect。                  |
-| `changeOnSelect` | `boolean`                                                      | `false`     | –    | 每选中一级即触发 onChange(antd `changeOnSelect` 并集) — 默认仅选叶子触发。 |
-| `placeholder`    | `string`                                                       | `"请选择"`  | –    | 占位文本。                                                                 |
-| `separator`      | `string`                                                       | `" / "`     | –    | 路径展示的分隔符。                                                         |
-| `disabled`       | `boolean`                                                      | –           | –    | 整体禁用。                                                                 |
-| `className`      | `string`                                                       | –           | –    | 触发器 className(给外层 Button)。                                          |
-| `size`           | `'sm' \| 'default' \| 'lg'`                                    | `"default"` | –    | 触发器尺寸。                                                               |
-
+_(组件无 `<Name>Props` interface — props 详见 [`cascader.tsx`](./cascader.tsx))_
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add cascader` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry     | 类型      | 描述                                                                                    |
-| --------- | --------- | --------------------------------------------------------------------------------------- |
-| `cn`      | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                      |
-| `button`  | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
-| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集                                            |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
+| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集,使用 showArrow 控制尖角(与 Tooltip / HoverCard 命名统一) |
 
 ### npm 依赖
 
@@ -64,7 +50,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
@@ -117,3 +102,39 @@ const [v, setV] = React.useState<string[]>(['cn', 'zj', 'hz']);
   onChange={(vals, opts) => setV(vals)}
 />
 ```
+
+---
+
+## Cascader 形态 — 旧库 API → 新映射
+
+> 旧库 `CascaderSelect`(hybridcloud) → 新库 `Cascader`(简化命名)。
+> 新库使用 Radix Popover + 自绘多列面板;点击触发器弹出 flex 列布局,每级一列,叶子节点触发 onChange。
+
+### 命名 & 结构映射
+
+| 旧库                           | 新库                                      | 说明                                |
+| ------------------------------ | ----------------------------------------- | ----------------------------------- |
+| `CascaderSelect`               | `Cascader`                                | 组件名简化                          |
+| `dataSource`                   | `options`                                 | 数据源 prop 更名                    |
+| `size: small/medium/large`     | `size: 'sm' \| 'md' \| 'default' \| 'lg'` | md = medium = default               |
+| `onChange(value, data, extra)` | `onChange(value, selectedOptions)`        | 签名简化,extra 合入 selectedOptions |
+| `canOnlyCheckLeaf={false}`     | `changeOnSelect`                          | 中途选择;默认仅叶子触发             |
+| `hasClear`                     | _(未来 P2: allowClear)_                   | MVP 不含清除按钮                    |
+| `showSearch`                   | _(未来 P1: showSearch + onSearch)_        | MVP 不含搜索                        |
+| `multiple`                     | _(未来 P1: multiple + checkbox)_          | MVP 仅单选                          |
+| `loadData`                     | _(未来 P1: loadData 异步)_                | MVP 需前端准备完整 options 树       |
+| `expandTriggerType="hover"`    | _(未来 P2: expandTrigger)_                | MVP 仅 click 展开                   |
+| `displayRender`                | _(未来 P2)_                               | MVP 用 separator 拼接 label         |
+| `header/footer`                | 不复刻                                    | 低频,Tailwind 自行包装              |
+| `useVirtual`                   | 不复刻                                    | 级联层级有限,无虚拟化需求           |
+| `valueRender/itemRender`       | 不复刻                                    | 精简 API                            |
+
+### 迁移 FAQ
+
+| 问题                                    | 回答                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------- |
+| `dataSource` 和 `options` 结构有差异吗? | 无;旧库同样是 `{ value, label, children }` 递归结构                                   |
+| 怎么实现"只选到省"?                     | 设 `changeOnSelect`,每级点击都触发 onChange                                           |
+| 怎么实现懒加载?                         | MVP 暂不支持 loadData — 建议在 onChange 中拿到路径后异步 fetch 子节点、再更新 options |
+| 大数据量(> 300 节点)怎么办?             | 数据拆分:options 先只传第一层,onChange 时动态追加子层                                 |
+| 新库为什么没有 multiple?                | 多选级联复杂度高(checkbox + tag + search);待独立迭代,不阻塞基础级联能力               |

package/src/components/cascader/cascader.stories.tsx

@@ -1,9 +1,9 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Cascader, type CascaderOption } from './cascader';
 
 const meta: Meta<typeof Cascader> = {
-  title: '表单与输入 · Form/Cascader',
+  title: '数据录入 · Data Entry/Cascader',
   component: Cascader,
   tags: ['autodocs'],
   parameters: {
@@ -107,3 +107,14 @@ export const Disabled: Story = {
     <Cascader disabled options={regions} defaultValue={['cn', 'zj', 'hz']} />
   ),
 };
+
+export const Sizes: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Cascader options={regions} size="sm" placeholder="sm" />
+      <Cascader options={regions} size="md" placeholder="md (default)" />
+      <Cascader options={regions} size="lg" placeholder="lg" />
+    </div>
+  ),
+};