@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/tree/meta.md

@@ -0,0 +1,96 @@
+# Tree
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+树 Tree
+多层级结构数据展示，支持展开收起、选中、勾选（父子联动 / 独立）、回填策略、
+节点占满整行、自定义图标、异步加载、过滤高亮、虚拟滚动等业界主流能力。
+
+## 使用场景
+
+- 文件目录 / 组织架构 / 分类层级浏览
+- 需要勾选 / 单选 / 多选层级数据
+- 大数据量树（开启 `virtual`）
+- 异步分级加载（`loadData`）
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `block` | `"true" \| "false"` | – | – | – |
+| `treeData` | `TreeNode[]` | – | ✓ | 树形数据源。 |
+| `selectable` | `boolean` | – | – | 是否支持节点选中。@default true |
+| `multiple` | `boolean` | – | – | 是否支持多选选中。@default false |
+| `selectedKeys` | `string[]` | – | – | 受控选中节点 key 列表。 |
+| `defaultSelectedKeys` | `string[]` | – | – | 默认选中节点 key 列表。 |
+| `onSelect` | `( selectedKeys: string[], info: { node: TreeNode; selected: boolean; selectedNodes: TreeNode[] }, ) => void` | – | – | 选中变化回调。 |
+| `checkable` | `boolean` | – | – | 是否显示复选框。@default false |
+| `checkedKeys` | `string[]` | – | – | 受控勾选 key 列表。 |
+| `defaultCheckedKeys` | `string[]` | – | – | 默认勾选 key 列表。 |
+| `checkStrictly` | `boolean` | – | – | 父子勾选独立（不联动）。@default false |
+| `checkedStrategy` | `'all' \| 'parent' \| 'child'` | `'all'` | – | 勾选回填策略： - 'all' 全量返回（默认，与 cloud-design 一致） - 'parent' 父级 fully checked 时仅返回父级 - 'child' 仅返回叶子节点 仅在 `checkStrictly=false` 时生效。 |
+| `onCheck` | `( checkedKeys: string[], info: { node: TreeNode; checked: boolean; checkedNodes: TreeNode[]; indeterminateKeys: string[]; }, ) => void` | – | – | 勾选变化回调。 |
+| `expandedKeys` | `string[]` | – | – | 受控展开 key 列表。 |
+| `defaultExpandedKeys` | `string[]` | – | – | 默认展开 key 列表。 |
+| `defaultExpandAll` | `boolean` | – | – | 默认展开全部节点。@default false |
+| `autoExpandParent` | `boolean` | `true` | – | 自动展开父节点；搜索高亮场景下建议设为 false 由外部控制。 |
+| `onExpand` | `( expandedKeys: string[], info: { node: TreeNode; expanded: boolean }, ) => void` | – | – | 展开/收起回调。 |
+| `showLine` | `boolean` | – | – | 是否显示连接线。@default false |
+| `showIcon` | `boolean` | `false（与 antd v5 一致）` | – | 是否显示节点图标（默认 File / Folder，可由 node.icon 覆盖）。 |
+| `blockNode` | `boolean` | – | – | 节点占满整行（替代 cloud-design 的 isLabelBlock / isNodeBlock）。@default false |
+| `size` | `'sm' \| 'default'` | – | – | 节点行高档位。@default 'default' |
+| `loadData` | `(node: TreeNode) => Promise<void> \| void` | – | – | 异步加载子节点：点击展开非 isLeaf 且 children 未提供的节点时调用。 业务侧应在 resolve 前更新 treeData 引用，组件不直接持有 children 状态。 |
+| `filterTreeNode` | `(node: TreeNode) => boolean` | – | – | 节点过滤回调；返回 true 的节点 label 会被高亮（不影响节点显隐， 业务侧可配合 expandedKeys 做搜索体验）。 |
+| `titleRender` | `(node: TreeNode) => React.ReactNode` | – | – | 自定义节点 label 渲染（替代 cloud-design 的 renderChildNodes）。 |
+| `virtual` | `boolean \| { threshold?: number; itemHeight?: number }` | – | – | 虚拟滚动；启用且展平后可见节点 ≥ threshold 时启用 react-virtual。 - `true` 等价 `{ threshold: 200 }` - 启用时容器需固定高度，默认 `max-h-96 overflow-auto`，可通过 className 覆盖。 |
+
+## 示例
+
+### BlockNode
+
+节点占满整行 blockNode：常用于在节点尾部追加操作按钮。配合 titleRender。 对应 cd `node-block`。
+
+```tsx
+<Tree
+  treeData={orgTree}
+  defaultExpandAll
+  showIcon
+  blockNode
+  titleRender={(node) => (
+    <span className="flex w-full items-center justify-between gap-2">
+      <span className="truncate">{node.label}</span>
+      {!node.children && (
+        <Button
+          variant="ghost"
+          size="sm"
+          onClick={(e) => {
+            e.stopPropagation();
+            console.log('行操作', node);
+          }}
+        >
+          操作
+        </Button>
+      )}
+    </span>
+  )}
+/>
+```
+
+### Sizes
+
+尺寸：sm / default 两档行高。
+
+```tsx
+<div className="flex gap-8">
+  <div className="flex flex-col gap-2">
+    <span className="text-xs text-muted-foreground">size=sm</span>
+    <Tree treeData={treeData} defaultExpandAll size="sm" />
+  </div>
+  <div className="flex flex-col gap-2">
+    <span className="text-xs text-muted-foreground">size=default</span>
+    <Tree treeData={treeData} defaultExpandAll />
+  </div>
+</div>
+```

package/src/components/tree/stories.tsx

@@ -0,0 +1,385 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Building2Icon, FolderIcon, UserIcon } from 'lucide-react';
+
+import { Tree } from './index';
+import type { TreeNode } from './index';
+import { Button } from '@/components/button';
+import { Checkbox } from '@/components/checkbox';
+import { Input } from '@/components/input';
+
+// ─── 数据 ────────────────────────────────────────────────────────────────────
+
+const treeData: TreeNode[] = [
+  {
+    key: '1',
+    label: 'Component',
+    children: [
+      {
+        key: '2',
+        label: 'Form',
+        selectable: false,
+        children: [
+          { key: '4', label: 'Input' },
+          { key: '5', label: 'Select', disabled: true },
+        ],
+      },
+      {
+        key: '3',
+        label: 'Display',
+        children: [{ key: '6', label: 'Table' }],
+      },
+    ],
+  },
+  {
+    key: '7',
+    label: 'Layout',
+    children: [
+      { key: '8', label: 'Grid' },
+      { key: '9', label: 'Stack' },
+    ],
+  },
+];
+
+const orgTree: TreeNode[] = [
+  {
+    key: 'eng',
+    label: '工程部',
+    icon: <Building2Icon className="size-3.5" />,
+    children: [
+      {
+        key: 'fe',
+        label: '前端组',
+        icon: <FolderIcon className="size-3.5" />,
+        children: [
+          {
+            key: 'fe-zhang',
+            label: '张三',
+            icon: <UserIcon className="size-3.5" />,
+          },
+          {
+            key: 'fe-li',
+            label: '李四',
+            icon: <UserIcon className="size-3.5" />,
+          },
+        ],
+      },
+      {
+        key: 'be',
+        label: '后端组',
+        icon: <FolderIcon className="size-3.5" />,
+        children: [
+          {
+            key: 'be-wang',
+            label: '王五',
+            icon: <UserIcon className="size-3.5" />,
+          },
+        ],
+      },
+    ],
+  },
+];
+
+// ─── Meta ────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof Tree> = {
+  title: '数据展示 · Data Display/Tree 树',
+  component: Tree,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      source: { type: 'dynamic' },
+      description: {
+        component:
+          '树 — 多层级结构数据展示。支持选中 / 多选、勾选（父子联动 / 独立 / 三档回填策略）、节点占满整行、自定义图标、异步加载、过滤高亮、虚拟滚动。',
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+// ─── Stories ─────────────────────────────────────────────────────────────────
+
+/** 基础：默认展开 + 选中 + 勾选 + 禁用，对应 cd `basic`。 */
+export const Default: Story = {
+  render: () => (
+    <Tree
+      treeData={treeData}
+      defaultExpandedKeys={['1', '2']}
+      checkable
+      defaultCheckedKeys={['4', '6']}
+    />
+  ),
+};
+
+/**
+ * 受控选中 + 节点级 selectable 覆盖 + multiple 多选选中，对应 cd `control-select`。
+ */
+export const Selectable: Story = {
+  render: () => {
+    const [keys, setKeys] = React.useState<string[]>(['4']);
+    const [multi, setMulti] = React.useState(false);
+    return (
+      <div className="flex flex-col gap-2">
+        <label className="flex items-center gap-2 text-xs">
+          <Checkbox
+            checked={multi}
+            onCheckedChange={(next) => {
+              setMulti(next === true);
+              setKeys([]);
+            }}
+          />
+          支持多选 multiple
+        </label>
+        <Tree
+          treeData={treeData}
+          defaultExpandAll
+          multiple={multi}
+          selectedKeys={keys}
+          onSelect={(next) => setKeys(next)}
+        />
+        <span className="text-xs text-muted-foreground">
+          selectedKeys: {JSON.stringify(keys)}
+        </span>
+      </div>
+    );
+  },
+};
+
+/**
+ * 勾选：checkable + checkStrictly 切换 + 三档 checkedStrategy 输出对比，
+ * 对应 cd `control-check`。
+ */
+export const Checkable: Story = {
+  render: () => {
+    const [strictly, setStrictly] = React.useState(false);
+    const [keys, setKeys] = React.useState<string[]>([]);
+    return (
+      <div className="flex flex-col gap-3">
+        <label className="flex items-center gap-2 text-xs">
+          <Checkbox
+            checked={strictly}
+            onCheckedChange={(next) => {
+              setStrictly(next === true);
+              setKeys([]);
+            }}
+          />
+          取消父子关联 checkStrictly
+        </label>
+        <Tree
+          treeData={treeData}
+          defaultExpandAll
+          checkable
+          checkStrictly={strictly}
+          checkedKeys={keys}
+          onCheck={(next) => setKeys(next)}
+        />
+        <span className="text-xs text-muted-foreground">
+          checkedKeys: {JSON.stringify(keys)}
+        </span>
+      </div>
+    );
+  },
+};
+
+/** 三档回填策略对比：parent / child / all。 */
+export const CheckedStrategy: Story = {
+  render: () => {
+    const Demo = ({ strategy }: { strategy: 'parent' | 'child' | 'all' }) => {
+      const [keys, setKeys] = React.useState<string[]>([]);
+      return (
+        <div className="flex items-start gap-3">
+          <span className="mt-1 w-16 shrink-0 text-xs text-muted-foreground">
+            {strategy}
+          </span>
+          <Tree
+            treeData={treeData}
+            defaultExpandAll
+            checkable
+            checkedStrategy={strategy}
+            checkedKeys={keys}
+            onCheck={(next) => setKeys(next)}
+          />
+          <span className="mt-1 text-xs text-muted-foreground">
+            出参：{JSON.stringify(keys)}
+          </span>
+        </div>
+      );
+    };
+    return (
+      <div className="flex flex-col gap-4">
+        <Demo strategy="all" />
+        <Demo strategy="parent" />
+        <Demo strategy="child" />
+      </div>
+    );
+  },
+};
+
+/** 连接线 showLine：在子树左侧加一根 1px 线条，对应 cd `line`。 */
+export const WithLine: Story = {
+  render: () => <Tree treeData={treeData} defaultExpandAll showLine />,
+};
+
+/** 自定义图标 + showIcon，对应 cd `icon`。 */
+export const WithIcon: Story = {
+  render: () => <Tree treeData={orgTree} defaultExpandAll showIcon />,
+};
+
+/**
+ * 异步加载：点击展开非 isLeaf 节点时调用 loadData，期间显示 spinner。
+ * 对应 cd `dynamic`。
+ */
+export const LoadData: Story = {
+  render: () => {
+    const [data, setData] = React.useState<TreeNode[]>([
+      { key: '0', label: '点击展开加载' },
+      { key: '1', label: '点击展开加载' },
+      { key: '2', label: '叶子节点', isLeaf: true },
+    ]);
+    const onLoad = (node: TreeNode) =>
+      new Promise<void>((resolve) => {
+        setTimeout(() => {
+          setData((prev) => addChildren(prev, node.key));
+          resolve();
+        }, 800);
+      });
+    return <Tree treeData={data} loadData={onLoad} />;
+  },
+};
+
+function addChildren(data: TreeNode[], key: string): TreeNode[] {
+  return data.map((n) => {
+    if (n.key === key) {
+      return {
+        ...n,
+        children: [
+          { key: `${key}-0`, label: '子节点 A' },
+          { key: `${key}-1`, label: '子节点 B' },
+        ],
+      };
+    }
+    if (n.children) {
+      return { ...n, children: addChildren(n.children, key) };
+    }
+    return n;
+  });
+}
+
+/**
+ * 搜索高亮：外部 Input 驱动 expandedKeys + filterTreeNode 高亮命中节点。
+ * 搜索时 autoExpandParent=true 自动展开命中节点的祖先链。对应 cd `search-tree`。
+ */
+export const Search: Story = {
+  render: () => {
+    const [keyword, setKeyword] = React.useState('');
+    const [expanded, setExpanded] = React.useState<string[]>(['1']);
+    const matchedKeys = React.useMemo(() => {
+      const kw = keyword.trim();
+      if (!kw) return new Set<string>();
+      const out = new Set<string>();
+      const walk = (nodes: TreeNode[]) => {
+        for (const n of nodes) {
+          if (String(n.label).toLowerCase().includes(kw.toLowerCase())) {
+            out.add(n.key);
+          }
+          if (n.children) walk(n.children);
+        }
+      };
+      walk(treeData);
+      return out;
+    }, [keyword]);
+    React.useEffect(() => {
+      if (matchedKeys.size > 0) setExpanded(Array.from(matchedKeys));
+    }, [matchedKeys]);
+    return (
+      <div className="flex w-72 flex-col gap-2">
+        <Input
+          size="sm"
+          placeholder="搜索节点 label"
+          value={keyword}
+          onChange={(e) => setKeyword(e.target.value)}
+        />
+        <Tree
+          treeData={treeData}
+          expandedKeys={expanded}
+          onExpand={(next) => setExpanded(next)}
+          autoExpandParent={!!keyword}
+          filterTreeNode={(n) => matchedKeys.has(n.key)}
+        />
+      </div>
+    );
+  },
+};
+
+/**
+ * 节点占满整行 blockNode：常用于在节点尾部追加操作按钮。配合 titleRender。
+ * 对应 cd `node-block`。
+ */
+export const BlockNode: Story = {
+  render: () => (
+    <Tree
+      treeData={orgTree}
+      defaultExpandAll
+      showIcon
+      blockNode
+      titleRender={(node) => (
+        <span className="flex w-full items-center justify-between gap-2">
+          <span className="truncate">{node.label}</span>
+          {!node.children && (
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={(e) => {
+                e.stopPropagation();
+                console.log('行操作', node);
+              }}
+            >
+              操作
+            </Button>
+          )}
+        </span>
+      )}
+    />
+  ),
+};
+
+/** 虚拟滚动：1000+ 节点开启 virtual，对应 cd `virtual-tree`。 */
+export const Virtual: Story = {
+  render: () => {
+    const big = React.useMemo<TreeNode[]>(() => {
+      const out: TreeNode[] = [];
+      for (let i = 0; i < 50; i++) {
+        out.push({
+          key: `g-${i}`,
+          label: `分组 ${i}`,
+          children: Array.from({ length: 30 }).map((_, j) => ({
+            key: `g-${i}-${j}`,
+            label: `节点 ${i}-${j}`,
+          })),
+        });
+      }
+      return out;
+    }, []);
+    return <Tree treeData={big} defaultExpandAll virtual />;
+  },
+};
+
+/** 尺寸：sm / default 两档行高。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex gap-8">
+      <div className="flex flex-col gap-2">
+        <span className="text-xs text-muted-foreground">size=sm</span>
+        <Tree treeData={treeData} defaultExpandAll size="sm" />
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-xs text-muted-foreground">size=default</span>
+        <Tree treeData={treeData} defaultExpandAll />
+      </div>
+    </div>
+  ),
+};