@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/tooltip/tooltip.tsx

@@ -1,14 +1,51 @@
 import * as React from 'react';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import { cva, type VariantProps } from 'class-variance-authority';
 
 import { cn } from '@/utils/cn';
 
 const TooltipProvider = TooltipPrimitive.Provider;
 const TooltipRoot = TooltipPrimitive.Root;
-const TooltipTrigger = TooltipPrimitive.Trigger;
+const TooltipTrigger = React.forwardRef<
+  React.ElementRef<typeof TooltipPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <TooltipPrimitive.Trigger
+    ref={ref}
+    className={cn('cursor-pointer', className)}
+    {...props}
+  />
+));
+TooltipTrigger.displayName = TooltipPrimitive.Trigger.displayName;
+
+const tooltipContentVariants = cva(
+  'z-50 overflow-hidden rounded-md px-3 py-1.5 text-xs animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground shadow-md',
+        light:
+          'border border-border bg-popover text-popover-foreground shadow-md',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+/** 箭头填充色与变体一一对应。 */
+const arrowFillByVariant: Record<
+  NonNullable<VariantProps<typeof tooltipContentVariants>['variant']>,
+  string
+> = {
+  default: 'fill-primary',
+  light: 'fill-popover',
+};
 
 export interface TooltipContentProps
-  extends React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content> {
+  extends React.ComponentPropsWithoutRef<typeof TooltipPrimitive.Content>,
+    VariantProps<typeof tooltipContentVariants> {
   /**
    * 是否显示三角形箭头(antd `arrow` 并集)。
    * @default true
@@ -19,24 +56,37 @@ export interface TooltipContentProps
 const TooltipContent = React.forwardRef<
   React.ElementRef<typeof TooltipPrimitive.Content>,
   TooltipContentProps
->(({ className, sideOffset = 4, arrow = true, children, ...props }, ref) => (
-  <TooltipPrimitive.Portal>
-    <TooltipPrimitive.Content
-      ref={ref}
-      sideOffset={sideOffset}
-      className={cn(
-        'z-50 overflow-hidden rounded-md bg-primary px-3 py-1.5 text-xs text-primary-foreground shadow-md animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
-        className,
-      )}
-      {...props}
-    >
-      {children}
-      {arrow ? (
-        <TooltipPrimitive.Arrow className="fill-primary" width={8} height={4} />
-      ) : null}
-    </TooltipPrimitive.Content>
-  </TooltipPrimitive.Portal>
-));
+>(
+  (
+    {
+      className,
+      sideOffset = 4,
+      arrow = true,
+      variant = 'default',
+      children,
+      ...props
+    },
+    ref,
+  ) => (
+    <TooltipPrimitive.Portal>
+      <TooltipPrimitive.Content
+        ref={ref}
+        sideOffset={sideOffset}
+        className={cn(tooltipContentVariants({ variant }), className)}
+        {...props}
+      >
+        {children}
+        {arrow ? (
+          <TooltipPrimitive.Arrow
+            className={arrowFillByVariant[variant ?? 'default']}
+            width={8}
+            height={4}
+          />
+        ) : null}
+      </TooltipPrimitive.Content>
+    </TooltipPrimitive.Portal>
+  ),
+);
 TooltipContent.displayName = TooltipPrimitive.Content.displayName;
 
 // ─── Convenience wrapper(antd-style 一行调用)──────────────────────────────
@@ -52,6 +102,14 @@ export interface TooltipProps
   title: React.ReactNode;
   /** 弹出方向。 @default "top" */
   side?: 'top' | 'right' | 'bottom' | 'left';
+  /**
+   * 视觉变体:
+   * - `default`:深色背景 + 浅色文字(信息密度高、对比强,适合图标按钮 / 列截断提示)
+   * - `light`:浅色背景 + 深色文字 + 边框 + 阴影(视觉更轻,贴近富内容卡片调性,
+   *   对齐 cloud-design Balloon `type="primary"`)
+   * @default "default"
+   */
+  variant?: 'default' | 'light';
   /** 是否显示三角形箭头。 @default true */
   arrow?: boolean;
   /** 显示延迟(ms),默认沿用 Provider 的 delayDuration。 */
@@ -64,6 +122,7 @@ const Tooltip: React.FC<TooltipProps> = ({
   children,
   title,
   side = 'top',
+  variant = 'default',
   arrow = true,
   delayDuration,
   withProvider = false,
@@ -72,7 +131,7 @@ const Tooltip: React.FC<TooltipProps> = ({
   const inner = (
     <TooltipRoot delayDuration={delayDuration} {...rootProps}>
       <TooltipTrigger asChild>{children}</TooltipTrigger>
-      <TooltipContent side={side} arrow={arrow}>
+      <TooltipContent side={side} variant={variant} arrow={arrow}>
         {title}
       </TooltipContent>
     </TooltipRoot>
@@ -90,4 +149,5 @@ export {
   TooltipRoot,
   TooltipTrigger,
   TooltipContent,
+  tooltipContentVariants,
 };

package/src/components/tour/tour.meta.md

@@ -2,12 +2,13 @@
 id: tour
 name: Tour
 type: component
-category: feedback
+category: deprecated
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 新手引导
 ---
 
-# Tour
+# Tour 新手引导
 
 新手引导 — antd 独有补足。**等价 antd `Tour`**(v5.0+)。多步骤引导(spotlight + 卡片 + 步进按钮 + 可关闭),帮助新用户首次进入页面时了解关键功能位置。
 
@@ -24,6 +25,8 @@ package: "@teamix-evo/ui"
 - 表单字段说明 → `FieldDescription`
 - 错误反馈 → `Alert` / `notification`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -38,6 +41,8 @@ package: "@teamix-evo/ui"
 | `mask` | `boolean` | `true` | – | 是否显示遮罩(antd `mask` 并集)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -46,7 +51,7 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
 
 ### npm 依赖
 

package/src/components/tour/tour.stories.tsx

@@ -1,17 +1,17 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Tour } from './tour';
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Tour> = {
-  title: '反馈与浮层 · Feedback/Tour',
+  title: '废弃 · Deprecated/Tour',
   component: Tour,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '新手引导 — 多步骤 spotlight + 卡片 + 步进按钮。帮助新用户首次进入页面时了解关键功能位置。等价 antd `Tour`(v5.0+)。业务侧自管"是否首次访问"。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n新手引导 — 多步骤 spotlight + 卡片 + 步进按钮。帮助新用户首次进入页面时了解关键功能位置。等价 antd `Tour`（v5.0+）。业务侧自管“是否首次访问”。',
       },
     },
   },

package/src/components/tour/tour.tsx

@@ -176,7 +176,7 @@ const Tour: React.FC<TourProps> = ({
             <rect
               width="100%"
               height="100%"
-              fill="rgba(0,0,0,0.5)"
+              fill="var(--overlay-scrim)"
               mask="url(#tour-mask)"
             />
           </svg>
@@ -188,7 +188,7 @@ const Tour: React.FC<TourProps> = ({
       <div
         role="dialog"
         className={cn(
-          'absolute w-80 rounded-md border bg-popover p-4 text-popover-foreground shadow-xl',
+          'absolute w-80 rounded-md border border-border bg-popover p-4 text-popover-foreground shadow-xl',
         )}
         style={cardStyle}
       >
@@ -198,13 +198,13 @@ const Tour: React.FC<TourProps> = ({
             type="button"
             aria-label="关闭"
             onClick={close}
-            className="text-muted-foreground transition-colors hover:text-foreground"
+            className="cursor-pointer text-muted-foreground transition-colors hover:text-foreground"
           >
             <X className="size-4" />
           </button>
         </div>
         {cur.description ? (
-          <div className="mt-2 text-sm text-muted-foreground">
+          <div className="mt-2 text-xs text-muted-foreground">
             {cur.description}
           </div>
         ) : null}

package/src/components/transfer/transfer.meta.md

@@ -1,13 +1,14 @@
 ---
 id: transfer
 name: Transfer
+displayName: 穿梭框
 type: component
-category: data-display
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Transfer
+# Transfer 穿梭框
 
 穿梭框 — antd 独有补足。**双侧勾选 + 移动**的批量分配交互(权限分配、字段映射、收件人选择)。受控 `targetKeys` + `onChange` 单一真值,内置全选 / 半选 / 可选搜索 / 禁用项。
 
@@ -22,6 +23,8 @@ package: "@teamix-evo/ui"
 - 单纯多选 → `Select multiple` / `CheckboxGroup`(轻量)
 - 选项 > 500 — 本组件未做虚拟化,建议改用 `Table` + 行选 + bulk action 模式
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -36,6 +39,8 @@ package: "@teamix-evo/ui"
 | `className` | `string` | – | – | – |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -44,9 +49,9 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
 | `checkbox` | component | 复选框 — Radix Checkbox(原生 indeterminate)+ antd Checkbox.Group(options 数组驱动) |
-| `input` | component | 文本输入 — shadcn 简洁基底 + antd prefix/suffix/clearable/showCount/addonBefore/addonAfter/size |
+| `input` | component | 单行文本输入 — clearable / showCount / size(sm 24 / md 32 / lg 36,与 Button 同档)/ error 四档内建能力。前缀/后缀/addon 等复合形态已拆出独立 InputGroup;多行已拆出独立 Textarea |
 
 ### npm 依赖
 
@@ -86,5 +91,5 @@ const [target, setTarget] = React.useState<string[]>(['2', '4']);
   onChange={setTarget}
   titles={['全部成员', '已授权']}
   showSearch
-/>
+/>;
 ```

package/src/components/transfer/transfer.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 { Transfer, type TransferItem } from './transfer';
 
 const meta: Meta<typeof Transfer> = {
-  title: '数据展示 · Data Display/Transfer',
+  title: '数据录入 · Data Entry/Transfer',
   component: Transfer,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '穿梭框 — 双侧勾选 + 移动的批量分配交互(权限分配、字段映射、收件人选择)。受控 targetKeys 单一真值,内置全选 / 半选 / 可选搜索 / 禁用项跳过。视觉走 OpenTrek tokens,等价 antd `Transfer`,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '穿梭框 — 双侧勾选 + 移动的批量分配交互（权限分配、字段映射、收件人选择）。受控 targetKeys 单一真值，内置全选 / 半选 / 可选搜索 / 禁用项跳过。等价 antd `Transfer`。',
       },
     },
   },
@@ -30,11 +30,7 @@ export const Playground: Story = {
   render: () => {
     const [target, setTarget] = React.useState<string[]>(['2', '4']);
     return (
-      <Transfer
-        dataSource={data}
-        targetKeys={target}
-        onChange={setTarget}
-      />
+      <Transfer dataSource={data} targetKeys={target} onChange={setTarget} />
     );
   },
 };

package/src/components/transfer/transfer.tsx

@@ -120,33 +120,39 @@ const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
       query: string,
       setQuery: (v: string) => void,
     ) => {
-      const selectableKeys = visible.filter((i) => !i.disabled).map((i) => i.key);
+      const selectableKeys = visible
+        .filter((i) => !i.disabled)
+        .map((i) => i.key);
       const allChecked =
-        selectableKeys.length > 0 && selectableKeys.every((k) => checked.includes(k));
+        selectableKeys.length > 0 &&
+        selectableKeys.every((k) => checked.includes(k));
       const someChecked =
         !allChecked && selectableKeys.some((k) => checked.includes(k));
       const toggleAll = (value: boolean) => {
-        if (value) setChecked(Array.from(new Set([...checked, ...selectableKeys])));
+        if (value)
+          setChecked(Array.from(new Set([...checked, ...selectableKeys])));
         else setChecked(checked.filter((k) => !selectableKeys.includes(k)));
       };
 
       return (
-        <div className="flex w-56 flex-col overflow-hidden rounded-md border bg-card text-sm">
-          <div className="flex items-center justify-between gap-2 border-b px-3 py-2">
+        <div className="flex w-56 flex-col overflow-hidden rounded-md border border-border bg-card text-xs">
+          <div className="flex items-center justify-between gap-2 border-b border-b-border bg-muted/40 px-3 py-2">
             <label className="flex items-center gap-2">
               <Checkbox
-                checked={allChecked ? true : someChecked ? 'indeterminate' : false}
+                checked={
+                  allChecked ? true : someChecked ? 'indeterminate' : false
+                }
                 disabled={disabled || selectableKeys.length === 0}
                 onCheckedChange={(c) => toggleAll(c === true)}
               />
-              <span className="text-xs text-muted-foreground">
+              <span className="text-xs text-muted-foreground tabular-nums">
                 {checked.length}/{items.length}
               </span>
             </label>
-            <span className="text-xs font-medium">{title}</span>
+            <span className="text-xs font-medium text-foreground">{title}</span>
           </div>
           {showSearch ? (
-            <div className="border-b p-2">
+            <div className="border-b border-b-border p-2">
               <div className="relative">
                 <Search className="absolute left-2 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
                 <Input
@@ -175,8 +181,9 @@ const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
                   <li key={item.key}>
                     <label
                       className={cn(
-                        'flex items-center gap-2 px-3 py-1.5',
-                        !itemDisabled && 'cursor-pointer hover:bg-accent',
+                        'flex items-center gap-2 px-3 py-1.5 transition-colors',
+                        !itemDisabled && 'cursor-pointer hover:bg-accent/50',
+                        !itemDisabled && isChecked && 'bg-accent/40',
                         itemDisabled && 'cursor-not-allowed opacity-50',
                       )}
                     >
@@ -185,7 +192,8 @@ const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
                         disabled={itemDisabled}
                         onCheckedChange={(c) => {
                           if (c === true) setChecked([...checked, item.key]);
-                          else setChecked(checked.filter((k) => k !== item.key));
+                          else
+                            setChecked(checked.filter((k) => k !== item.key));
                         }}
                       />
                       <span className="min-w-0 flex-1 truncate">
@@ -202,10 +210,7 @@ const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
     };
 
     return (
-      <div
-        ref={ref}
-        className={cn('flex items-center gap-3', className)}
-      >
+      <div ref={ref} className={cn('flex items-center gap-3', className)}>
         {renderPane(
           titles[0],
           leftItems,
@@ -215,22 +220,24 @@ const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
           leftQuery,
           setLeftQuery,
         )}
-        <div className="flex flex-col gap-2">
+        <div className="flex flex-col gap-1.5">
           <Button
-            size="icon"
+            size="sm"
             variant="outline"
             disabled={disabled || leftChecked.length === 0}
             onClick={moveRight}
             aria-label="移动到右侧"
-            icon={<ChevronRight />}
+            className="size-7 p-0"
+            icon={<ChevronRight className="size-3.5" />}
           />
           <Button
-            size="icon"
+            size="sm"
             variant="outline"
             disabled={disabled || rightChecked.length === 0}
             onClick={moveLeft}
             aria-label="移动到左侧"
-            icon={<ChevronLeft />}
+            className="size-7 p-0"
+            icon={<ChevronLeft className="size-3.5" />}
           />
         </div>
         {renderPane(

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

@@ -1,13 +1,14 @@
 ---
 id: tree
 name: Tree
+displayName: 树形控件
 type: component
 category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Tree
+# Tree 树形控件
 
 树形控件 — antd 独有补足。递归层级展示(组织架构、文件系统、分类目录),支持**可展开 / 可单选 / 可勾选(父子级联 + 半选)**,受控与非受控并存。Radix 未提供 tree primitive — 本组件自实现递归 + 受控逻辑。
 
@@ -23,6 +24,8 @@ package: "@teamix-evo/ui"
 - 大数据量(> 1000 节点)— 本组件不做虚拟化,业务侧请自做分页 / 懒加载子节点
 - 拖拽排序场景 → 需配合 `react-dnd` 等库自行扩展,本组件不内置
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -41,6 +44,8 @@ package: "@teamix-evo/ui"
 | `onExpand` | `(next: string[]) => void` | – | – | 展开变化回调。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -66,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
 
@@ -82,7 +90,11 @@ const data: TreeNode[] = [
     title: 'src',
     icon: <Folder className="size-3.5" />,
     children: [
-      { key: 'src/index.ts', title: 'index.ts', icon: <File className="size-3.5" /> },
+      {
+        key: 'src/index.ts',
+        title: 'index.ts',
+        icon: <File className="size-3.5" />,
+      },
       {
         key: 'src/components',
         title: 'components',
@@ -97,7 +109,7 @@ const data: TreeNode[] = [
 ];
 
 // 默认展开 + 选择
-<Tree data={data} defaultExpandAll />
+<Tree data={data} defaultExpandAll />;
 
 // 可勾选(受控)
 const [checked, setChecked] = React.useState<string[]>([]);
@@ -107,5 +119,51 @@ const [checked, setChecked] = React.useState<string[]>([]);
   defaultExpandAll
   checkedKeys={checked}
   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';
 
@@ -11,7 +11,7 @@ const meta: Meta<typeof Tree> = {
     docs: {
       description: {
         component:
-          '树形控件 — 递归层级展示(目录、组织、分类)。支持展开 / 单选 / 父子级联勾选(自动半选),受控与非受控并存。Radix 未提供 tree primitive,本组件自实现递归与级联。视觉走 OpenTrek tokens,等价 antd `Tree`,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '树形控件 — 递归层级展示（目录、组织、分类）。支持展开 / 单选 / 父子级联勾选（自动半选），受控与非受控并存。Radix 未提供 tree primitive，本组件自实现递归与级联。等价 antd `Tree`。',
       },
     },
   },
@@ -26,22 +26,45 @@ const fileTree: TreeNode[] = [
     title: 'src',
     icon: <Folder className="size-3.5" />,
     children: [
-      { key: 'src/index.ts', title: 'index.ts', icon: <File className="size-3.5" /> },
+      {
+        key: 'src/index.ts',
+        title: 'index.ts',
+        icon: <File className="size-3.5" />,
+      },
       {
         key: 'src/components',
         title: 'components',
         icon: <Folder className="size-3.5" />,
         children: [
-          { key: 'src/components/Button.tsx', title: 'Button.tsx', icon: <File className="size-3.5" /> },
-          { key: 'src/components/Input.tsx', title: 'Input.tsx', icon: <File className="size-3.5" /> },
-          { key: 'src/components/Dialog.tsx', title: 'Dialog.tsx', icon: <File className="size-3.5" />, disabled: true },
+          {
+            key: 'src/components/Button.tsx',
+            title: 'Button.tsx',
+            icon: <File className="size-3.5" />,
+          },
+          {
+            key: 'src/components/Input.tsx',
+            title: 'Input.tsx',
+            icon: <File className="size-3.5" />,
+          },
+          {
+            key: 'src/components/Dialog.tsx',
+            title: 'Dialog.tsx',
+            icon: <File className="size-3.5" />,
+            disabled: true,
+          },
         ],
       },
       {
         key: 'src/utils',
         title: 'utils',
         icon: <Folder className="size-3.5" />,
-        children: [{ key: 'src/utils/cn.ts', title: 'cn.ts', icon: <File className="size-3.5" /> }],
+        children: [
+          {
+            key: 'src/utils/cn.ts',
+            title: 'cn.ts',
+            icon: <File className="size-3.5" />,
+          },
+        ],
       },
     ],
   },
@@ -99,11 +122,7 @@ export const ControlledExpand: Story = {
   render: () => {
     const [expanded, setExpanded] = React.useState<string[]>(['src']);
     return (
-      <Tree
-        data={fileTree}
-        expandedKeys={expanded}
-        onExpand={setExpanded}
-      />
+      <Tree data={fileTree} expandedKeys={expanded} onExpand={setExpanded} />
     );
   },
 };