@teamix-evo/ui 0.2.0 → 0.3.0

package/src/components/tree/tree.meta.md

@@ -27,36 +27,33 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称                  | 类型                       | 默认值  | 必填 | 说明                                                                       |
-| --------------------- | -------------------------- | ------- | ---- | -------------------------------------------------------------------------- |
-| `data`                | `TreeNode[]`               | –       | ✓    | 树数据(antd `treeData` 并集)。                                             |
-| `checkable`           | `boolean`                  | `false` | –    | 是否启用勾选 checkbox(antd `checkable` 并集) — 父子级联,半选状态自动计算。 |
-| `selectable`          | `boolean`                  | `true`  | –    | 是否启用单击高亮选择(antd `selectable` 并集)。                             |
-| `checkedKeys`         | `string[]`                 | –       | –    | 受控已勾选 key 集合(checkable 时生效)。                                    |
-| `defaultCheckedKeys`  | `string[]`                 | –       | –    | uncontrolled 初值。                                                        |
-| `onCheck`             | `(next: string[]) => void` | –       | –    | 勾选变化回调。                                                             |
-| `selectedKeys`        | `string[]`                 | –       | –    | 受控已选中 key 集合(selectable 时生效;通常单选,数组形式与 antd 对齐)。     |
-| `defaultSelectedKeys` | `string[]`                 | –       | –    | uncontrolled 初值。                                                        |
-| `onSelect`            | `(next: string[]) => void` | –       | –    | 选中变化回调。                                                             |
-| `expandedKeys`        | `string[]`                 | –       | –    | 受控已展开 key 集合。                                                      |
-| `defaultExpandedKeys` | `string[]`                 | –       | –    | uncontrolled 初值。                                                        |
-| `defaultExpandAll`    | `boolean`                  | `false` | –    | 默认展开全部(antd `defaultExpandAll` 并集) — 仅 uncontrolled 模式生效。    |
-| `onExpand`            | `(next: string[]) => void` | –       | –    | 展开变化回调。                                                             |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `data` | `TreeNode[]` | – | ✓ | 树数据(antd `treeData` 并集)。 |
+| `checkable` | `boolean` | `false` | – | 是否启用勾选 checkbox(antd `checkable` 并集) — 父子级联,半选状态自动计算。 |
+| `selectable` | `boolean` | `true` | – | 是否启用单击高亮选择(antd `selectable` 并集)。 |
+| `checkedKeys` | `string[]` | – | – | 受控已勾选 key 集合(checkable 时生效)。 |
+| `defaultCheckedKeys` | `string[]` | – | – | uncontrolled 初值。 |
+| `onCheck` | `(next: string[]) => void` | – | – | 勾选变化回调。 |
+| `selectedKeys` | `string[]` | – | – | 受控已选中 key 集合(selectable 时生效;通常单选,数组形式与 antd 对齐)。 |
+| `defaultSelectedKeys` | `string[]` | – | – | uncontrolled 初值。 |
+| `onSelect` | `(next: string[]) => void` | – | – | 选中变化回调。 |
+| `expandedKeys` | `string[]` | – | – | 受控已展开 key 集合。 |
+| `defaultExpandedKeys` | `string[]` | – | – | uncontrolled 初值。 |
+| `defaultExpandAll` | `boolean` | `false` | – | 默认展开全部(antd `defaultExpandAll` 并集) — 仅 uncontrolled 模式生效。 |
+| `onExpand` | `(next: string[]) => void` | – | – | 展开变化回调。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add tree` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry      | 类型      | 描述                                                                               |
-| ---------- | --------- | ---------------------------------------------------------------------------------- |
-| `cn`       | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                 |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 | `checkbox` | component | 复选框 — Radix Checkbox(原生 indeterminate)+ antd Checkbox.Group(options 数组驱动) |
 
 ### npm 依赖
@@ -66,7 +63,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
@@ -75,6 +71,9 @@ pnpm add lucide-react@^0.460.0
 - **`checkable` 默认级联**:勾选父节点会勾选所有后代,勾选所有后代会自动勾选父节点 — **不要**自己写额外的级联逻辑;`onCheck` 给的是叶子+完全选中的父节点集合(半选不在内)
 - **半选(indeterminate)**自动计算,不需要消费方维护
 - **`selectable` + `checkable` 可共存**,但 UI 上选中高亮与勾选是两套独立状态(对齐 antd)
+- **选中 ≠ hover**:hover 是 `accent/50`(半透明),选中是 `accent` 实色 + `font-medium`,视觉上明显区分;**不要**手动改为其他调色板
+- **节点缩进**:每层 20px刷类 shadcn/cloud-design teamix 规范,**不要**手动调 padding
+- **展开图标**:`size-3` 的 `ChevronRight` 旋转 90°,默认为 `text-muted-foreground` hover 变 `text-foreground` — 不要换 chevron 尺寸
 - **大数据量警告**:节点数 ≥ 500 时建议拆分为"按需加载子节点"(在 `onExpand` 中拉取),否则首次渲染卡顿
 - **`disabled` 节点**:展开按钮亦禁用,但**仍参与级联计算** — 父被勾选时禁用子也会变为 checked
 
@@ -122,3 +121,49 @@ const [checked, setChecked] = React.useState<string[]>([]);
   onCheck={setChecked}
 />;
 ```
+
+## Tree 形态 — 旧库 API → 新库映射
+
+> 旧库 `Tree / Tree.Node`(hybridcloud,JSX 子组件式) → 新库 `Tree`(纯数据驱动)。
+> 新库放弃 JSX `<Tree.Node>` 子组件嵌套,改用 `data: TreeNode[]` 数组(对齐 antd 5+ 的 `treeData` 风格)— tree-shake 友好 / 序列化方便 / 异步加载更直观。
+
+### 命名映射
+
+| 旧库 API | 新库 API | 备注 |
+| --- | --- | --- |
+| `<Tree>` + `<Tree.Node>` 子组件嵌套 | `<Tree data={[{ key, title, children }]} />` | **Breaking** — 改为数据驱动 |
+| `dataSource` | `data` | 字段命名简化 |
+| `Tree.Node` 的 `key/label/children` | `TreeNode.key/title/children` | `label` → `title`(对齐 antd) |
+| `checkedKeys` / `selectedKeys` / `expandedKeys` | 同名保留 | 受控集合 |
+| `defaultCheckedKeys` / `defaultSelectedKeys` / `defaultExpandedKeys` | 同名保留 | uncontrolled 初值 |
+| `defaultExpandAll` | 同名保留 | 仅 uncontrolled 模式 |
+| `onCheck(keys, extra)` | `onCheck(keys)` | 单参数化(extra 信息可在 data 里查) |
+| `onSelect(keys, extra)` | `onSelect(keys)` | 同上 |
+| `isLeaf`(Node prop) | `TreeNode.isLeaf`(data field) | 数据字段化 |
+| `disabled`(Node prop) | `TreeNode.disabled`(data field) | 同上 |
+| `icon`(Node prop) | `TreeNode.icon`(data field) | 同上 |
+
+### Breaking Changes(从旧库迁移时需改写)
+
+1. **JSX `<Tree.Node>` 全部改写为 `data` 数组** — 这是最大改动,业务工程需要重构数据结构
+2. `dataSource` → `data`
+3. `label` → `title`(节点字段)
+4. `onCheck(keys, extra)` → `onCheck(keys)`(extra 信息消失,业务侧自查 data)
+
+### 不修复 / 后续工序清单(报告 §3 P1/P2)
+
+> 以下功能在新库未实现,**业务真有需求时**优先做。多数依赖外部库或较复杂的 source 改造。
+
+- **`draggable` 拖拽排序**(P1):需集成 `@dnd-kit/core` + `@dnd-kit/sortable`,本组件不内置;业务侧自接 dnd-kit
+- **`loadData` 异步加载子节点**(P1):点击展开时触发 fetch,目前业务侧用受控 `expandedKeys` + `onExpand` 自管异步;后续工序加 prop
+- **`checkStrictly` 父子不关联**(P1):checkable 模式下严格独立勾选,目前固定级联;后续 prop
+- **`useVirtual` 虚拟滚动**(P1):大数据量(> 1000 节点)首次渲染卡顿,后续可集成 `react-window` 或 `@tanstack/react-virtual`
+- **`editable` 节点编辑**(P2):双击节点变 Input;业务侧用 `title: <Input />` 自定义渲染替代
+- **`filterTreeNode` 过滤高亮**(P2):配合 TreeSelect 的 showSearch 使用,需在 Tree 层先支持
+
+### 不修复(报告 §5 已明确)
+
+- **JSX `<Tree.Node>`**:数据驱动是显式优势,不回退
+- **`labelRender` vs `label(ReactNode)`**:`title` 直接接 ReactNode,无需另设 render prop
+- **展开动画**:CSS transition 已内置(对齐 antd 默认)
+- **`focusedKey` / `autoFocus`**:Radix-style 内管,不暴露

package/src/components/tree/tree.stories.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { File, Folder } from 'lucide-react';
 import { Tree, type TreeNode } from './tree';
 

package/src/components/tree/tree.tsx

@@ -177,12 +177,12 @@ const TreeRow: React.FC<NodeProps> = ({
     <li role="treeitem" aria-expanded={hasChildren ? isOpen : undefined}>
       <div
         className={cn(
-          'flex items-center gap-2 rounded-md py-1 pr-2 text-sm transition-colors',
-          selectable && !node.disabled && 'hover:bg-accent',
-          isSelected && 'bg-accent text-accent-foreground',
+          'group/tree-row flex items-center gap-1.5 rounded-md py-1 pr-2 text-xs transition-colors',
+          selectable && !node.disabled && 'hover:bg-accent/50',
+          isSelected && 'bg-accent font-medium text-accent-foreground',
           node.disabled && 'cursor-not-allowed opacity-50',
         )}
-        style={{ paddingLeft: `${depth * 16 + 4}px` }}
+        style={{ paddingLeft: `${depth * 20 + 4}px` }}
       >
         {hasChildren ? (
           <button
@@ -190,11 +190,11 @@ const TreeRow: React.FC<NodeProps> = ({
             aria-label={isOpen ? '收起' : '展开'}
             onClick={() => onToggleExpand(node.key)}
             disabled={node.disabled}
-            className="flex size-5 shrink-0 items-center justify-center rounded-sm transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            className="flex size-5 shrink-0 items-center justify-center rounded-sm text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
           >
             <ChevronRight
               className={cn(
-                'size-3.5 transition-transform',
+                'size-3 transition-transform duration-150',
                 isOpen && 'rotate-90',
               )}
             />
@@ -282,7 +282,8 @@ const Tree = React.forwardRef<HTMLDivElement, TreeProps>(
       return [];
     }, [defaultExpandAll, defaultExpandedKeys, data]);
 
-    const [internalExpanded, setInternalExpanded] = React.useState<string[]>(initialExpanded);
+    const [internalExpanded, setInternalExpanded] =
+      React.useState<string[]>(initialExpanded);
     const [internalSelected, setInternalSelected] = React.useState<string[]>(
       defaultSelectedKeys ?? [],
     );
@@ -339,7 +340,7 @@ const Tree = React.forwardRef<HTMLDivElement, TreeProps>(
     };
 
     return (
-      <div ref={ref} className={cn('text-sm', className)} {...props}>
+      <div ref={ref} className={cn('text-xs', className)} {...props}>
         <ul role="tree" className="flex flex-col gap-0.5">
           {data.map((n) => (
             <TreeRow

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

@@ -3,7 +3,7 @@ id: tree-select
 name: TreeSelect
 displayName: 树选择
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
@@ -27,36 +27,34 @@ package: '@teamix-evo/ui'
 ## Props
 
 <!-- auto:props:begin -->
-
-| 名称               | 类型                                  | 默认值      | 必填 | 说明                                                                                            |
-| ------------------ | ------------------------------------- | ----------- | ---- | ----------------------------------------------------------------------------------------------- |
-| `data`             | `TreeNode[]`                          | –           | ✓    | 树形数据(antd `treeData` 并集)。                                                                |
-| `multiple`         | `boolean`                             | `false`     | –    | 多选模式 — 启用后下拉内的 Tree 变为 checkable;value 是 key 数组。                               |
-| `value`            | `string \| string[]`                  | –           | –    | 受控 value: - `multiple=false`:`string`(单 key)/ `undefined`(未选) - `multiple=true`:`string[]` |
-| `defaultValue`     | `string \| string[]`                  | –           | –    | uncontrolled 初值。                                                                             |
-| `onChange`         | `(value: string \| string[]) => void` | –           | –    | value 变化回调。                                                                                |
-| `defaultExpandAll` | `boolean`                             | `false`     | –    | 默认展开全部节点(antd `treeDefaultExpandAll` 并集)。                                            |
-| `placeholder`      | `string`                              | `"请选择"`  | –    | 占位文本。                                                                                      |
-| `disabled`         | `boolean`                             | –           | –    | 整体禁用。                                                                                      |
-| `className`        | `string`                              | –           | –    | 触发器 className。                                                                              |
-| `size`             | `'sm' \| 'default' \| 'lg'`           | `"default"` | –    | 触发器尺寸。                                                                                    |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `data` | `TreeNode[]` | – | ✓ | 树形数据(antd `treeData` 并集)。 |
+| `multiple` | `boolean` | `false` | – | 多选模式 — 启用后下拉内的 Tree 变为 checkable;value 是 key 数组。 |
+| `value` | `string \| string[]` | – | – | 受控 value: - `multiple=false`:`string`(单 key)/ `undefined`(未选) - `multiple=true`:`string[]` |
+| `defaultValue` | `string \| string[]` | – | – | uncontrolled 初值。 |
+| `onChange` | `(value: string \| string[]) => void` | – | – | value 变化回调。 |
+| `defaultExpandAll` | `boolean` | `false` | – | 默认展开全部节点(antd `treeDefaultExpandAll` 并集)。 |
+| `placeholder` | `string` | `"请选择"` | – | 占位文本。 |
+| `disabled` | `boolean` | – | – | 整体禁用。 |
+| `className` | `string` | – | – | 触发器 className。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg'` | `"default"` | – | 触发器尺寸。 |
+| `allowClear` | `boolean` | `false` | – | 显示清除按钮(antd `allowClear` 并集) — 触发器有值时右侧出现 ✕,点击清空。 |
 <!-- auto:props:end -->
 
 ## 依赖
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add tree-select` 时,以下 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 并集                                                                      |
-| `tree`    | component | 树形控件 — antd 独有补足。递归层级展示(目录、组织、分类),可展开 / 可选 / 可勾选(父子级联 + 半选),受控与非受控并存 |
+| 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 命名统一) |
+| `tree` | component | 树形控件 — antd 独有补足。递归层级展示(目录、组织、分类),可展开 / 可选 / 可勾选(父子级联 + 半选),受控与非受控并存 |
 
 ### npm 依赖
 
@@ -65,7 +63,6 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
@@ -112,4 +109,43 @@ const [v, setV] = React.useState<string[]>(['fe', 'be']);
   value={v}
   onChange={(next) => setV(next as string[])}
 />;
+
+// 可清除(hover 时右侧出现 ✕)
+<TreeSelect data={data} allowClear defaultValue="fe" />;
 ```
+
+## TreeSelect 形态 — 旧库 API → 新库映射
+
+> 旧库 `TreeSelect`(hybridcloud) → 新库 `TreeSelect`(命名一致)。
+> 新库基于 Radix Popover + 内嵌 `Tree` 组件,触发器复用 `Button outline variant`。
+
+### 命名映射
+
+| 旧库 API | 新库 API | 备注 |
+| --- | --- | --- |
+| `dataSource` | `data` | 字段命名简化(对齐 React 习惯) |
+| `treeDefaultExpandAll` | `defaultExpandAll` | 去 `tree` 前缀 |
+| `treeCheckable` | `multiple` | 与 Select 多选 prop 命名统一 |
+| `value` / `onChange(value, data)` | `value` / `onChange(value)` | 单参数化 |
+| `size="small\|medium\|large"` | `size="sm\|md\|lg"` | 三档对齐 Button(24/32/36) |
+| `hasClear` | `allowClear` | ✅ 本波次落地 — hover 触发器右侧显示 ✕ |
+| `placeholder` | `placeholder` | 同名 |
+| `disabled` | `disabled` | 同名 |
+
+### 不修复 / 后续工序清单(报告 §3 P1)
+
+> 以下 P1 缺失项**未在 TreeSelect 层补**,因为它们都依赖底层 `Tree` 组件先具备相应能力。**业务真有需求时**优先在 Tree 层做,然后 TreeSelect 透传 prop 即可。
+
+- **showSearch + onSearch 搜索过滤**(P1):Tree 层先实现节点筛选高亮,TreeSelect 在 Popover 顶部加搜索框
+- **loadData 异步加载**(P1):Tree 层先实现节点点击触发异步加载子节点,TreeSelect 透传
+- **treeCheckStrictly 父子不关联**(P1):Tree 层 checkable 模式增 `checkStrictly` prop 关掉父子级联
+- **treeCheckedStrategy 回填策略**(P1):Tree 层暴露 `checkedStrategy: 'all' \| 'parent' \| 'child'`,影响 onCheck 返回的 value 集合
+- **useVirtual 虚拟滚动**(P2):Tree 层加 react-virtual 支持(> 500 节点时显著优化)
+
+### 不修复(报告 §5 已明确)
+
+- **`hasArrow` / `hasBorder`**:统一走 Button outline variant 视觉
+- **`label` 内联标签**:外层用 `<Label>` 配合,组件内不内置
+- **`popupStyle` / `popupClassName` / `popupProps`**:Popover 自身已有 `className`,无需中转
+- **`isPreview` / `renderPreview`**:无预览态(antd 也已废弃)
+- **`preserveNonExistentValue`**:简化处理,不识别的 key 直接舍去

package/src/components/tree-select/tree-select.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 { TreeSelect } from './tree-select';
 
 const meta: Meta<typeof TreeSelect> = {
-  title: '表单与输入 · Form/TreeSelect',
+  title: '数据录入 · Data Entry/TreeSelect',
   component: TreeSelect,
   tags: ['autodocs'],
   parameters: {

package/src/components/tree-select/tree-select.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { ChevronDown } from 'lucide-react';
+import { ChevronDown, X } from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 import { Button } from '@/components/button/button';
@@ -43,7 +43,12 @@ export interface TreeSelectProps {
    * 触发器尺寸。
    * @default "default"
    */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
+  /**
+   * 显示清除按钮(antd `allowClear` 并集) — 触发器有值时右侧出现 ✕,点击清空。
+   * @default false
+   */
+  allowClear?: boolean;
 }
 
 function flattenLabelMap(nodes: TreeNode[]): Map<string, React.ReactNode> {
@@ -72,7 +77,8 @@ const TreeSelect = React.forwardRef<HTMLButtonElement, TreeSelectProps>(
       placeholder = '请选择',
       disabled = false,
       className,
-      size = 'default',
+      size = 'md',
+      allowClear = false,
     },
     ref,
   ) => {
@@ -105,7 +111,7 @@ const TreeSelect = React.forwardRef<HTMLButtonElement, TreeSelectProps>(
             {display.map((d, i) => (
               <span
                 key={i}
-                className="inline-flex rounded-sm bg-muted px-1.5 py-0.5 text-xs"
+                className="inline-flex items-center rounded-md bg-muted px-1.5 py-0.5 text-xs text-muted-foreground"
               >
                 {d}
               </span>
@@ -116,6 +122,18 @@ const TreeSelect = React.forwardRef<HTMLButtonElement, TreeSelectProps>(
       return <span className="truncate">{display}</span>;
     };
 
+    const hasValue = multiple
+      ? Array.isArray(current) && current.length > 0
+      : !!current;
+
+    const handleClear = (e: React.MouseEvent) => {
+      e.preventDefault();
+      e.stopPropagation();
+      const next = multiple ? [] : '';
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    };
+
     return (
       <Popover open={open} onOpenChange={setOpen}>
         <PopoverTrigger asChild>
@@ -126,16 +144,33 @@ const TreeSelect = React.forwardRef<HTMLButtonElement, TreeSelectProps>(
             size={size}
             disabled={disabled}
             className={cn(
-              'min-w-panel-sm justify-between font-normal',
+              'group/treeselect min-w-panel-sm justify-between font-normal',
               !display && 'text-muted-foreground',
               className,
             )}
           >
             <span className="min-w-0 flex-1 text-left">{renderDisplay()}</span>
-            <ChevronDown className="ml-2 size-4 shrink-0 opacity-50" />
+            {allowClear && hasValue && !disabled ? (
+              <span
+                role="button"
+                tabIndex={-1}
+                aria-label="清除"
+                onClick={handleClear}
+                onMouseDown={(e) => e.stopPropagation()}
+                className="ml-2 hidden shrink-0 rounded-sm text-muted-foreground transition-colors hover:text-foreground group-hover/treeselect:inline-flex"
+              >
+                <X className="size-3.5" />
+              </span>
+            ) : null}
+            <ChevronDown
+              className={cn(
+                'ml-2 size-4 shrink-0 opacity-50',
+                allowClear && hasValue && 'group-hover/treeselect:hidden',
+              )}
+            />
           </Button>
         </PopoverTrigger>
-        <PopoverContent className="w-72 p-2" align="start">
+        <PopoverContent className="w-72 p-1" align="start">
           {multiple ? (
             <Tree
               data={data}

package/src/components/typography/typography.meta.md

@@ -3,24 +3,24 @@ id: typography
 name: Typography
 displayName: 排版
 type: component
-category: data-display
+category: general
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
 
 # Typography 排版
 
-排版组件 — `Prose`(富文本容器)+ shadcn 风格 `Title / Paragraph / Text / Link` + antd `Text` 的 `type / strong / delete / disabled / code / ellipsis / copyable` 并集。
+排版组件 — `Prose`(富文本容器)+ shadcn 风格 `Title / Paragraph / Text / Link` + antd `Text` 的 `strong / delete / disabled / code / ellipsis / copyable` 并集。语义色采用 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md) 统一 `color` API。
 
 > Prose 不依赖 `@tailwindcss/typography` 插件,样式手写并对齐 OpenTrek tokens。
 
 ## When to use
 
 - **Prose**:Markdown / CMS 富文本渲染容器(自动套排版样式)
-- **Title**:页面 / 区块标题(`level={1..5}` 自动映射 `<h1>~<h5>`)
+- **Title**:页面 / 区块标题(`level={1..6}` 自动映射 `<h1>~<h6>`,对齐 antd `Typography.Title.level`)
 - **Paragraph**:正文段落(行高 / 字号 / 颜色统一)
-- **Text**:行内文本带语义色 / 强调 / 复制
-- **Link**:语义化链接(类型 + 默认下划线 hover)
+- **Text**:行内文本带语义色(`color`) / 强调 / 复制
+- **Link**:语义化链接(`color` + 默认下划线 hover)
 
 ## When NOT to use
 
@@ -33,31 +33,15 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`typography.tsx`](./typography.tsx) 的 `TextProps` interface JSDoc。
 
 <!-- auto:props:begin -->
-
-#### Text
-
-| 名称       | 类型                                                       | 默认值      | 必填 | 说明                                                                                                                              |
-| ---------- | ---------------------------------------------------------- | ----------- | ---- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `type`     | `TextType`                                                 | `"default"` | –    | 语义色(antd `type` 并集)。                                                                                                        |
-| `delete`   | `boolean`                                                  | `false`     | –    | 删除线。                                                                                                                          |
-| `disabled` | `boolean`                                                  | `false`     | –    | 不可用(灰色 + 不可选)。                                                                                                           |
-| `strong`   | `boolean`                                                  | `false`     | –    | 加粗。                                                                                                                            |
-| `code`     | `boolean`                                                  | `false`     | –    | 行内代码样式(`code`)。                                                                                                            |
-| `ellipsis` | `boolean`                                                  | `false`     | –    | 单行省略(antd `ellipsis` 简化版 — 只支持 boolean,行数 / suffix 留 v0.x)。                                                         |
-| `copyable` | `boolean \| { text: string; tooltips?: [string, string] }` | `false`     | –    | 可复制(antd `copyable` 并集)— 末尾追加复制图标按钮。 传对象时可指定要复制的文本(默认是 children 的纯文本);传 `true` 用 children。 |
-
-#### Title
-
-| 名称    | 类型                    | 默认值 | 必填 | 说明                                                    |
-| ------- | ----------------------- | ------ | ---- | ------------------------------------------------------- |
-| `level` | `1 \| 2 \| 3 \| 4 \| 5` | `1`    | –    | 层级(1~5),决定字号 / 粗细;同时映射为 `<h1>~<h5>` 标签。 |
-
-#### Link
-
-| 名称   | 类型       | 默认值      | 必填 | 说明                      |
-| ------ | ---------- | ----------- | ---- | ------------------------- |
-| `type` | `TextType` | `"default"` | –    | 语义色(同 Text 的 type)。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `color` | `TextColor` | `"default"` | – | 语义色 — 6 档枚举,字面与 OpenTrek tokens 对齐(见 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md))。 antd `type` 迁移:`secondary`→`muted`、`danger`→`destructive`。 |
+| `delete` | `boolean` | `false` | – | 删除线。 |
+| `disabled` | `boolean` | `false` | – | 不可用(灰色 + 不可选)。 |
+| `strong` | `boolean` | `false` | – | 加粗。 |
+| `code` | `boolean` | `false` | – | 行内代码样式(`code`)。 |
+| `ellipsis` | `boolean` | `false` | – | 单行省略(antd `ellipsis` 简化版 — 只支持 boolean,行数 / suffix 留 v0.x)。 |
+| `copyable` | `boolean \| { text: string; tooltips?: [string, string] }` | `false` | – | 可复制(antd `copyable` 并集)— 末尾追加复制图标按钮。 传对象时可指定要复制的文本(默认是 children 的纯文本);传 `true` 用 children。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -65,14 +49,13 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
-
 ### 同库依赖
 
 > `teamix-evo ui add typography` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述                                               |
-| ----- | ---- | -------------------------------------------------- |
-| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -81,17 +64,56 @@ package: '@teamix-evo/ui'
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
-
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
 - **`Title level` 决定标签**:不要用 `<h2>` 配 `level={1}`,语义会冲突
-- **`Text type` 优先于 className 颜色**:语义色让暗色模式自动适配
+- **`Text color` 优先于 className 颜色**:语义色让暗色模式自动适配
 - **`copyable` 仅当 children 是 string**:富节点请显式传 `copyable={{ text: '...' }}`
 - **`ellipsis` 单行**:多行省略请直接 `className="line-clamp-2"`
 - **Prose 内部不要嵌套 Prose**:嵌套排版会双倍间距
 
+## Typography 形态 — 旧库 API → 新库映射
+
+旧库(Teamix 1.0 / `@alifd/next.Typography` + `Typography.Text` / `Typography.Paragraph` / `Typography.H1`~`H6`)与新库(`Typography` / `Title` / `Paragraph` / `Text` / `Link` / `Prose`)逐项对应。
+
+### 组件拆合
+
+| 旧库 | 新库 | 备注 |
+| --- | --- | --- |
+| `Typography` | `Prose` | 富文本容器,渲染 Markdown / CMS 输出 |
+| `Typography.H1` ~ `Typography.H6` | `<Title level={1..6}>` | level 决定字号 + 标签;新增 level=6 对齐 antd |
+| `Typography.Paragraph` | `Paragraph` | 同义 |
+| `Typography.Text` | `Text` | 行内文本 |
+| — | `Link` | 新增 — 语义化 `<a>` 元素 |
+
+### Props / 值映射
+
+| 旧库 | 新库 | 备注 |
+| --- | --- | --- |
+| `<Text type="secondary">` | `<Text color="muted">` | ADR 0021 语义色重命名 |
+| `<Text type="danger">` | `<Text color="destructive">` | ADR 0021 — 不收 antd `error` / `danger` 别名 |
+| `<Text strong>` | `<Text strong>` | 行为一致 |
+| `<Text delete>` | `<Text delete>` | 行为一致 |
+| `<Text code>` | `<Text code>` | 行为一致 |
+| `<Text disabled>` | `<Text disabled>` | 行为一致 |
+| `<Text ellipsis>` | `<Text ellipsis>` | P0 已实现 — 单行 truncate;多行用 `className="line-clamp-N"` |
+| `<Text copyable>` | `<Text copyable>` | P0 已实现 — 默认复制 children;传对象指定 `text` |
+| `<Text copyable={{ text }}>` | `<Text copyable={{ text }}>` | 对象签名一致 |
+| `size="body1/body2/caption/overline"` | className `text-sm/text-xs/...` | shadcn 字号通过 Tailwind 直控,不抽 prop |
+| `mark` 黄色高亮 | 直接用 `<mark>` 标签 | HTML 原生 |
+| `underline` | `className="underline"` | Tailwind utility |
+| `editable` 行内编辑 | 不修复 — 用 Tiptap / Lexical / Input + state | 复杂度高,业务低频 |
+
+### 不修复清单
+
+| 旧库能力 | 理由 |
+| --- | --- |
+| `mark` / `underline` / `delete` / `code` 全 prop | 直接用 HTML 原生 / Tailwind utility 更简洁,只保留 `delete` / `code` 的便捷 prop |
+| `editable` 行内编辑 | 业务低频 + 复杂度高,推荐用 Tiptap 等编辑器 |
+| `component` 自定义根标签 | shadcn 走 `asChild` (Slot) 替代 — 需要时用 `<Title asChild><span>...</span></Title>` |
+
 ## Examples
 
 ```tsx
@@ -105,8 +127,8 @@ import { Prose, Title, Paragraph, Text, Link } from '@/components/ui/typography'
 <Paragraph>正文段落,统一字号 / 行高 / 颜色。</Paragraph>
 
 // 行内文本
-<Text type="success" strong>成功</Text>
-<Text type="danger" delete>已废弃</Text>
+<Text color="success" strong>成功</Text>
+<Text color="destructive" delete>已废弃</Text>
 <Text disabled>不可用</Text>
 <Text code>const x = 1</Text>
 <Text ellipsis>这是一段非常长的文字...被截断</Text>
@@ -115,7 +137,7 @@ import { Prose, Title, Paragraph, Text, Link } from '@/components/ui/typography'
 
 // 链接
 <Link href="/docs">文档</Link>
-<Link href="/danger" type="danger">危险链接</Link>
+<Link href="/danger" color="destructive">危险链接</Link>
 
 // Prose 容器(渲染 Markdown 等富文本)
 <Prose>

package/src/components/typography/typography.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Prose, Title, Paragraph, Text, Link } from './typography';
 
 const meta: Meta<typeof Text> = {
-  title: '数据展示 · Data Display/Typography',
+  title: '通用 · General/Typography',
   component: Text,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '排版组件 — Prose 富文本容器 + Title / Paragraph / Text / Link，合并 antd 的 `type` / `strong` / `delete` / `disabled` / `code` / `ellipsis` / `copyable` 能力。',
+          '排版组件 — Prose 富文本容器 + Title / Paragraph / Text / Link，合并 antd 的 `type` / `strong` / `delete` / `disabled` / `code` / `ellipsis` / `copyable` 能力。语义色采用 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md) 统一 `color` API(antd `type` 的 secondary/success/warning/danger 合并为 `color` 的 muted/success/warning/destructive)。',
       },
     },
   },
@@ -31,15 +31,16 @@ export const Titles: Story = {
   ),
 };
 
-export const TextTypes: Story = {
+export const TextColors: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex flex-col gap-2 text-sm">
       <Text>默认</Text>
-      <Text type="secondary">次要</Text>
-      <Text type="success">成功</Text>
-      <Text type="warning">警告</Text>
-      <Text type="danger">危险</Text>
+      <Text color="muted">次要</Text>
+      <Text color="primary">信息 / 主颜色</Text>
+      <Text color="success">成功</Text>
+      <Text color="warning">警告</Text>
+      <Text color="destructive">危险</Text>
       <Text strong>加粗</Text>
       <Text delete>已废弃</Text>
       <Text disabled>不可用</Text>
@@ -76,7 +77,11 @@ export const Links: Story = {
       <Link href="#docs" onClick={(e) => e.preventDefault()}>
         文档
       </Link>
-      <Link href="#delete" type="danger" onClick={(e) => e.preventDefault()}>
+      <Link
+        href="#delete"
+        color="destructive"
+        onClick={(e) => e.preventDefault()}
+      >
         危险操作链接
       </Link>
     </div>