@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/carousel/carousel.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Carousel,
   CarouselContent,
@@ -12,7 +12,15 @@ const meta: Meta<typeof Carousel> = {
   title: '数据展示 · Data Display/Carousel',
   component: Carousel,
   tags: ['autodocs'],
-  parameters: { layout: 'centered' },
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          '走马灯 — 基于 embla-carousel-react，支持单页 / 多页 / 循环 / 拖拽 / 自动播放插件。对应 antd `Carousel` 的核心场景。',
+      },
+    },
+  },
 };
 
 export default meta;
@@ -41,10 +49,7 @@ export const Single: Story = {
 export const ThreePerView: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Carousel
-      opts={{ align: 'start' }}
-      className="w-full max-w-2xl"
-    >
+    <Carousel opts={{ align: 'start' }} className="w-full max-w-2xl">
       <CarouselContent>
         {Array.from({ length: 8 }).map((_, i) => (
           <CarouselItem key={i} className="md:basis-1/3">

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

@@ -1,13 +1,14 @@
 ---
 id: cascader
 name: Cascader
+displayName: 级联选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Cascader
+# Cascader 级联选择
 
 级联选择 — antd 独有补足。**等价 antd `Cascader`**。多级联动选择(地区 / 分类 / 组织架构 / 文件夹路径),选项树由 `options.children` 表达;点击触发器弹出多列面板,**叶子触发 onChange**(可改 `changeOnSelect` 为每级触发)。
 
@@ -23,21 +24,14 @@ package: "@teamix-evo/ui"
 - 树形多选 → `TreeSelect`(可勾选)
 - 离散级别独立选择 → 多个 `Select` 并排(级联弱)
 
+## 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 -->
 ### 同库依赖
 
@@ -46,8 +40,8 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
-| `popover` | component | 可交互浮层 — Radix Popover + antd arrow 并集 |
+| `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 依赖
 
@@ -108,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,16 +1,16 @@
 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: {
     docs: {
       description: {
         component:
-          '级联选择 — 多级联动(地区 / 分类 / 文件夹路径),多列面板,叶子触发 onChange(可改 changeOnSelect 为每级触发)。等价 antd `Cascader`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '级联选择 — 多级联动（地区 / 分类 / 文件夹路径），多列面板，叶子触发 onChange（可改 changeOnSelect 为每级触发）。等价 antd `Cascader`。',
       },
     },
   },
@@ -52,7 +52,13 @@ const regions: CascaderOption[] = [
   {
     value: 'us',
     label: '美国',
-    children: [{ value: 'ca', label: '加州', children: [{ value: 'sf', label: '旧金山' }] }],
+    children: [
+      {
+        value: 'ca',
+        label: '加州',
+        children: [{ value: 'sf', label: '旧金山' }],
+      },
+    ],
   },
 ];
 
@@ -67,12 +73,7 @@ export const ChangeOnSelect: Story = {
     const [v, setV] = React.useState<string[]>([]);
     return (
       <div className="flex flex-col gap-2">
-        <Cascader
-          options={regions}
-          changeOnSelect
-          value={v}
-          onChange={setV}
-        />
+        <Cascader options={regions} changeOnSelect value={v} onChange={setV} />
         <div className="text-xs text-muted-foreground">
           value: {v.length ? v.join(' / ') : '(空)'}
         </div>
@@ -106,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>
+  ),
+};