@teamix-evo/ui 0.1.1

package/src/components/tree/tree.tsx

@@ -0,0 +1,367 @@
+import * as React from 'react';
+import { ChevronRight } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Checkbox } from '@/components/checkbox/checkbox';
+
+export interface TreeNode {
+  /** 稳定 key — 受控集合的比对依据。 */
+  key: string;
+  /** 节点显示内容。 */
+  title: React.ReactNode;
+  /** 子节点(无 children 视为叶子)。 */
+  children?: TreeNode[];
+  /** 禁用整行交互(选择 / 勾选 / 展开)。 */
+  disabled?: boolean;
+  /** 节点左侧图标(可选,叶子节点配 file 图标常用)。 */
+  icon?: React.ReactNode;
+}
+
+export interface TreeProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** 树数据(antd `treeData` 并集)。 */
+  data: TreeNode[];
+  /**
+   * 是否启用勾选 checkbox(antd `checkable` 并集) — 父子级联,半选状态自动计算。
+   * @default false
+   */
+  checkable?: boolean;
+  /**
+   * 是否启用单击高亮选择(antd `selectable` 并集)。
+   * @default true
+   */
+  selectable?: boolean;
+  /** 受控已勾选 key 集合(checkable 时生效)。 */
+  checkedKeys?: string[];
+  /** uncontrolled 初值。 */
+  defaultCheckedKeys?: string[];
+  /** 勾选变化回调。 */
+  onCheck?: (next: string[]) => void;
+  /** 受控已选中 key 集合(selectable 时生效;通常单选,数组形式与 antd 对齐)。 */
+  selectedKeys?: string[];
+  /** uncontrolled 初值。 */
+  defaultSelectedKeys?: string[];
+  /** 选中变化回调。 */
+  onSelect?: (next: string[]) => void;
+  /** 受控已展开 key 集合。 */
+  expandedKeys?: string[];
+  /** uncontrolled 初值。 */
+  defaultExpandedKeys?: string[];
+  /**
+   * 默认展开全部(antd `defaultExpandAll` 并集) — 仅 uncontrolled 模式生效。
+   * @default false
+   */
+  defaultExpandAll?: boolean;
+  /** 展开变化回调。 */
+  onExpand?: (next: string[]) => void;
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────
+
+function collectAllKeys(nodes: TreeNode[]): string[] {
+  const out: string[] = [];
+  const walk = (n: TreeNode) => {
+    out.push(n.key);
+    n.children?.forEach(walk);
+  };
+  nodes.forEach(walk);
+  return out;
+}
+
+function collectDescendants(node: TreeNode): string[] {
+  const out: string[] = [];
+  const walk = (n: TreeNode) => {
+    out.push(n.key);
+    n.children?.forEach(walk);
+  };
+  node.children?.forEach(walk);
+  return out;
+}
+
+function buildParentMap(nodes: TreeNode[]): Map<string, string | null> {
+  const map = new Map<string, string | null>();
+  const walk = (n: TreeNode, parent: string | null) => {
+    map.set(n.key, parent);
+    n.children?.forEach((c) => walk(c, n.key));
+  };
+  nodes.forEach((n) => walk(n, null));
+  return map;
+}
+
+function buildNodeMap(nodes: TreeNode[]): Map<string, TreeNode> {
+  const map = new Map<string, TreeNode>();
+  const walk = (n: TreeNode) => {
+    map.set(n.key, n);
+    n.children?.forEach(walk);
+  };
+  nodes.forEach(walk);
+  return map;
+}
+
+/**
+ * Given the explicitly-checked leaf-and-internal set, derive the (checked, halfChecked)
+ * tuple by propagating up: a parent is checked iff *all* its descendants are checked,
+ * halfChecked iff *some* (not all) descendants are checked.
+ */
+function propagate(
+  nodes: TreeNode[],
+  rawChecked: Set<string>,
+): { checked: Set<string>; half: Set<string> } {
+  const checked = new Set<string>();
+  const half = new Set<string>();
+
+  const visit = (n: TreeNode): { full: boolean; partial: boolean } => {
+    if (!n.children || n.children.length === 0) {
+      const isChecked = rawChecked.has(n.key);
+      if (isChecked) checked.add(n.key);
+      return { full: isChecked, partial: false };
+    }
+    let allFull = true;
+    let anyTouched = false;
+    for (const c of n.children) {
+      const r = visit(c);
+      if (!r.full) allFull = false;
+      if (r.full || r.partial) anyTouched = true;
+    }
+    if (allFull) {
+      checked.add(n.key);
+      return { full: true, partial: false };
+    }
+    if (anyTouched) {
+      half.add(n.key);
+      return { full: false, partial: true };
+    }
+    return { full: false, partial: false };
+  };
+
+  nodes.forEach(visit);
+  return { checked, half };
+}
+
+// ─── Node row ─────────────────────────────────────────────────────────────
+
+interface NodeProps {
+  node: TreeNode;
+  depth: number;
+  expanded: Set<string>;
+  selected: Set<string>;
+  checked: Set<string>;
+  half: Set<string>;
+  checkable: boolean;
+  selectable: boolean;
+  onToggleExpand: (key: string) => void;
+  onToggleSelect: (key: string) => void;
+  onToggleCheck: (node: TreeNode, next: boolean) => void;
+}
+
+const TreeRow: React.FC<NodeProps> = ({
+  node,
+  depth,
+  expanded,
+  selected,
+  checked,
+  half,
+  checkable,
+  selectable,
+  onToggleExpand,
+  onToggleSelect,
+  onToggleCheck,
+}) => {
+  const hasChildren = !!node.children && node.children.length > 0;
+  const isOpen = expanded.has(node.key);
+  const isSelected = selected.has(node.key);
+  const isChecked = checked.has(node.key);
+  const isHalf = half.has(node.key);
+
+  return (
+    <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',
+          node.disabled && 'cursor-not-allowed opacity-50',
+        )}
+        style={{ paddingLeft: `${depth * 16 + 4}px` }}
+      >
+        {hasChildren ? (
+          <button
+            type="button"
+            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"
+          >
+            <ChevronRight
+              className={cn(
+                'size-3.5 transition-transform',
+                isOpen && 'rotate-90',
+              )}
+            />
+          </button>
+        ) : (
+          <span aria-hidden="true" className="size-5 shrink-0" />
+        )}
+        {checkable ? (
+          <Checkbox
+            checked={isHalf ? 'indeterminate' : isChecked}
+            disabled={node.disabled}
+            onCheckedChange={(c) => onToggleCheck(node, c === true)}
+          />
+        ) : null}
+        {node.icon ? (
+          <span className="flex size-4 shrink-0 items-center justify-center text-muted-foreground">
+            {node.icon}
+          </span>
+        ) : null}
+        <span
+          className={cn(
+            'min-w-0 flex-1 truncate',
+            selectable && !node.disabled && 'cursor-pointer',
+          )}
+          onClick={() => {
+            if (selectable && !node.disabled) onToggleSelect(node.key);
+          }}
+        >
+          {node.title}
+        </span>
+      </div>
+      {hasChildren && isOpen ? (
+        <ul role="group">
+          {node.children!.map((child) => (
+            <TreeRow
+              key={child.key}
+              node={child}
+              depth={depth + 1}
+              expanded={expanded}
+              selected={selected}
+              checked={checked}
+              half={half}
+              checkable={checkable}
+              selectable={selectable}
+              onToggleExpand={onToggleExpand}
+              onToggleSelect={onToggleSelect}
+              onToggleCheck={onToggleCheck}
+            />
+          ))}
+        </ul>
+      ) : null}
+    </li>
+  );
+};
+
+// ─── Tree ─────────────────────────────────────────────────────────────────
+
+const Tree = React.forwardRef<HTMLDivElement, TreeProps>(
+  (
+    {
+      data,
+      checkable = false,
+      selectable = true,
+      checkedKeys,
+      defaultCheckedKeys,
+      onCheck,
+      selectedKeys,
+      defaultSelectedKeys,
+      onSelect,
+      expandedKeys,
+      defaultExpandedKeys,
+      defaultExpandAll = false,
+      onExpand,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const parentMap = React.useMemo(() => buildParentMap(data), [data]);
+    const nodeMap = React.useMemo(() => buildNodeMap(data), [data]);
+
+    const initialExpanded = React.useMemo(() => {
+      if (defaultExpandedKeys) return defaultExpandedKeys;
+      if (defaultExpandAll) return collectAllKeys(data);
+      return [];
+    }, [defaultExpandAll, defaultExpandedKeys, data]);
+
+    const [internalExpanded, setInternalExpanded] = React.useState<string[]>(initialExpanded);
+    const [internalSelected, setInternalSelected] = React.useState<string[]>(
+      defaultSelectedKeys ?? [],
+    );
+    const [internalChecked, setInternalChecked] = React.useState<string[]>(
+      defaultCheckedKeys ?? [],
+    );
+
+    const expanded = expandedKeys ?? internalExpanded;
+    const selected = selectedKeys ?? internalSelected;
+    const rawChecked = checkedKeys ?? internalChecked;
+
+    const expandedSet = React.useMemo(() => new Set(expanded), [expanded]);
+    const selectedSet = React.useMemo(() => new Set(selected), [selected]);
+
+    const { checked, half } = React.useMemo(
+      () => propagate(data, new Set(rawChecked)),
+      [data, rawChecked],
+    );
+
+    const toggleExpand = (key: string) => {
+      const next = expandedSet.has(key)
+        ? expanded.filter((k) => k !== key)
+        : [...expanded, key];
+      if (expandedKeys === undefined) setInternalExpanded(next);
+      onExpand?.(next);
+    };
+
+    const toggleSelect = (key: string) => {
+      const next = selectedSet.has(key) ? [] : [key];
+      if (selectedKeys === undefined) setInternalSelected(next);
+      onSelect?.(next);
+    };
+
+    const toggleCheck = (node: TreeNode, value: boolean) => {
+      const next = new Set(rawChecked);
+      const subtree = [node.key, ...collectDescendants(node)];
+      if (value) subtree.forEach((k) => next.add(k));
+      else subtree.forEach((k) => next.delete(k));
+
+      // Recompute checked-by-leaves to keep parent states consistent.
+      let cursor: string | null = parentMap.get(node.key) ?? null;
+      while (cursor) {
+        const parent = nodeMap.get(cursor);
+        if (!parent || !parent.children) break;
+        const allKidsChecked = parent.children.every((c) => next.has(c.key));
+        if (allKidsChecked) next.add(parent.key);
+        else next.delete(parent.key);
+        cursor = parentMap.get(cursor) ?? null;
+      }
+
+      const arr = Array.from(next);
+      if (checkedKeys === undefined) setInternalChecked(arr);
+      onCheck?.(arr);
+    };
+
+    return (
+      <div ref={ref} className={cn('text-sm', className)} {...props}>
+        <ul role="tree" className="flex flex-col gap-0.5">
+          {data.map((n) => (
+            <TreeRow
+              key={n.key}
+              node={n}
+              depth={0}
+              expanded={expandedSet}
+              selected={selectedSet}
+              checked={checked}
+              half={half}
+              checkable={checkable}
+              selectable={selectable}
+              onToggleExpand={toggleExpand}
+              onToggleSelect={toggleSelect}
+              onToggleCheck={toggleCheck}
+            />
+          ))}
+        </ul>
+      </div>
+    );
+  },
+);
+Tree.displayName = 'Tree';
+
+export { Tree };

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

@@ -0,0 +1,100 @@
+---
+id: tree-select
+name: TreeSelect
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# TreeSelect
+
+树形下拉选择 — antd 独有补足。**等价 antd `TreeSelect`**。把 `Tree` 嵌入 Popover,提供**单选**(selectable)或**多选**(checkable)两种模式 — 组织架构 / 分类树形选择 / 文件夹路径选择常用。
+
+## When to use
+
+- 组织架构选人(部门 - 子部门 - 个人)
+- 分类目录选择(电商类目、知识库目录)
+- 权限模块树选择(多选,父子级联勾选)
+
+## When NOT to use
+
+- 平层多选 → `Select multiple` / `Combobox`
+- 严格级联(每层必选一个,不可跨层) → `Cascader`
+- 树形浏览(不需要"选中"语义) → `Tree`
+
+<!-- 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"` | – | 触发器尺寸。 |
+<!-- 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 独有补足。递归层级展示(目录、组织、分类),可展开 / 可选 / 可勾选(父子级联 + 半选),受控与非受控并存 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **value 类型由 `multiple` 决定**:single 模式是 `string`,multi 模式是 `string[]` — **不要**让两种模式共用同一 state 类型
+- **multiple 模式下 onCheck 返回的是完全勾选的 key 集合**(包括完全勾选的父级,不包括半选)— 与 antd 行为一致
+- **单选场景** Tree 设置 `selectable=true selectableKeys=[value]`;选中即关闭 Popover(避免用户误操作)
+- **大数据量(> 500 节点)**:Tree 不做虚拟化,深树会卡顿 — 改用 `Cascader` 或按需懒加载子节点
+- **触发器展示**:多选 ≤ 3 项展示 chip 列表,> 3 项展示 `已选 N 项` — 不要在外层再做截断
+- **`disabled` 节点级联仍计算**:父级被勾选时,disabled 子级也会自动 checked(对齐 antd / Tree)
+
+## Examples
+
+```tsx
+import { TreeSelect } from '@/components/ui/tree-select';
+import * as React from 'react';
+
+const data = [
+  {
+    key: 'eng',
+    title: '工程团队',
+    children: [
+      { key: 'fe', title: '前端' },
+      { key: 'be', title: '后端' },
+      {
+        key: 'qa',
+        title: '测试',
+        children: [{ key: 'sdet', title: 'SDET' }],
+      },
+    ],
+  },
+  { key: 'design', title: '设计团队' },
+];
+
+// 单选
+<TreeSelect data={data} defaultExpandAll />
+
+// 多选 + 受控
+const [v, setV] = React.useState<string[]>(['fe', 'be']);
+<TreeSelect data={data} multiple defaultExpandAll value={v} onChange={(next) => setV(next as string[])} />
+```

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

@@ -0,0 +1,80 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { TreeSelect } from './tree-select';
+
+const meta: Meta<typeof TreeSelect> = {
+  title: '表单与输入 · Form/TreeSelect',
+  component: TreeSelect,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '树形下拉 — Tree 嵌入 Popover,单选(selectable)或多选(checkable)两种模式。组织架构 / 分类树形选择 / 文件夹路径选择常用。等价 antd `TreeSelect`。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof TreeSelect>;
+
+const data = [
+  {
+    key: 'eng',
+    title: '工程团队',
+    children: [
+      { key: 'fe', title: '前端' },
+      { key: 'be', title: '后端' },
+      {
+        key: 'qa',
+        title: '测试',
+        children: [
+          { key: 'sdet', title: 'SDET' },
+          { key: 'qa-manual', title: '手工测试' },
+        ],
+      },
+    ],
+  },
+  {
+    key: 'design',
+    title: '设计团队',
+    children: [
+      { key: 'product-design', title: '产品设计' },
+      { key: 'brand', title: '品牌设计' },
+    ],
+  },
+];
+
+export const Single: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <TreeSelect data={data} defaultExpandAll />,
+};
+
+export const Multiple: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [v, setV] = React.useState<string[]>(['fe']);
+    return (
+      <div className="flex flex-col gap-2">
+        <TreeSelect
+          data={data}
+          multiple
+          defaultExpandAll
+          value={v}
+          onChange={(next) => setV(next as string[])}
+        />
+        <div className="text-xs text-muted-foreground">
+          checked: {v.length ? v.join(', ') : '(空)'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <TreeSelect data={data} disabled defaultValue="fe" defaultExpandAll />
+  ),
+};