@teamix-evo/ui 0.1.1

package/src/components/transfer/transfer.tsx

@@ -0,0 +1,251 @@
+import * as React from 'react';
+import { ChevronLeft, ChevronRight, Search } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import { Checkbox } from '@/components/checkbox/checkbox';
+import { Input } from '@/components/input/input';
+
+export interface TransferItem {
+  /** 稳定 key — `targetKeys` 比对依据。 */
+  key: string;
+  /** 显示文本。 */
+  title: React.ReactNode;
+  /** 是否禁用(两侧均不可勾选 / 移动)。 */
+  disabled?: boolean;
+}
+
+export interface TransferProps {
+  /** 全部数据源(左+右合集)。 */
+  dataSource: TransferItem[];
+  /** 受控:已"穿梭到右侧"的 key 集合(antd `targetKeys` 并集)。 */
+  targetKeys: string[];
+  /** 右侧集合变化回调。 */
+  onChange?: (next: string[]) => void;
+  /**
+   * 两侧标题(antd `titles` 并集) — `[左, 右]`。
+   * @default ["源", "目标"]
+   */
+  titles?: [React.ReactNode, React.ReactNode];
+  /**
+   * 启用搜索(antd `showSearch` 并集) — 两侧各一个输入框。
+   * @default false
+   */
+  showSearch?: boolean;
+  /**
+   * 自定义渲染单项(antd `render` 并集) — 默认渲染 `item.title`。
+   */
+  render?: (item: TransferItem) => React.ReactNode;
+  /** 整体禁用。 */
+  disabled?: boolean;
+  /** 单侧高度(像素)。 @default 280 */
+  listHeight?: number;
+  className?: string;
+}
+
+const Transfer = React.forwardRef<HTMLDivElement, TransferProps>(
+  (
+    {
+      dataSource,
+      targetKeys,
+      onChange,
+      titles = ['源', '目标'],
+      showSearch = false,
+      render,
+      disabled = false,
+      listHeight = 280,
+      className,
+    },
+    ref,
+  ) => {
+    const [leftChecked, setLeftChecked] = React.useState<string[]>([]);
+    const [rightChecked, setRightChecked] = React.useState<string[]>([]);
+    const [leftQuery, setLeftQuery] = React.useState('');
+    const [rightQuery, setRightQuery] = React.useState('');
+
+    const targetSet = React.useMemo(() => new Set(targetKeys), [targetKeys]);
+
+    const leftItems = React.useMemo(
+      () => dataSource.filter((i) => !targetSet.has(i.key)),
+      [dataSource, targetSet],
+    );
+    const rightItems = React.useMemo(
+      () => dataSource.filter((i) => targetSet.has(i.key)),
+      [dataSource, targetSet],
+    );
+
+    const filterFn = (q: string) => (item: TransferItem) =>
+      q === '' ||
+      (typeof item.title === 'string'
+        ? item.title.toLowerCase().includes(q.toLowerCase())
+        : true);
+
+    const leftVisible = leftItems.filter(filterFn(leftQuery));
+    const rightVisible = rightItems.filter(filterFn(rightQuery));
+
+    // Strip selections that no longer apply when an item moves sides.
+    React.useEffect(() => {
+      setLeftChecked((prev) => prev.filter((k) => !targetSet.has(k)));
+      setRightChecked((prev) => prev.filter((k) => targetSet.has(k)));
+    }, [targetSet]);
+
+    const moveRight = () => {
+      if (disabled) return;
+      const movable = leftChecked.filter((k) => {
+        const it = dataSource.find((i) => i.key === k);
+        return it && !it.disabled;
+      });
+      if (movable.length === 0) return;
+      onChange?.([...targetKeys, ...movable]);
+      setLeftChecked([]);
+    };
+
+    const moveLeft = () => {
+      if (disabled) return;
+      const movable = rightChecked.filter((k) => {
+        const it = dataSource.find((i) => i.key === k);
+        return it && !it.disabled;
+      });
+      if (movable.length === 0) return;
+      onChange?.(targetKeys.filter((k) => !movable.includes(k)));
+      setRightChecked([]);
+    };
+
+    const renderPane = (
+      title: React.ReactNode,
+      items: TransferItem[],
+      visible: TransferItem[],
+      checked: string[],
+      setChecked: React.Dispatch<React.SetStateAction<string[]>>,
+      query: string,
+      setQuery: (v: string) => void,
+    ) => {
+      const selectableKeys = visible.filter((i) => !i.disabled).map((i) => i.key);
+      const allChecked =
+        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])));
+        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">
+            <label className="flex items-center gap-2">
+              <Checkbox
+                checked={allChecked ? true : someChecked ? 'indeterminate' : false}
+                disabled={disabled || selectableKeys.length === 0}
+                onCheckedChange={(c) => toggleAll(c === true)}
+              />
+              <span className="text-xs text-muted-foreground">
+                {checked.length}/{items.length}
+              </span>
+            </label>
+            <span className="text-xs font-medium">{title}</span>
+          </div>
+          {showSearch ? (
+            <div className="border-b p-2">
+              <div className="relative">
+                <Search className="absolute left-2 top-1/2 size-3.5 -translate-y-1/2 text-muted-foreground" />
+                <Input
+                  value={query}
+                  onChange={(e) => setQuery(e.target.value)}
+                  placeholder="搜索..."
+                  className="h-8 pl-7 text-xs"
+                  disabled={disabled}
+                />
+              </div>
+            </div>
+          ) : null}
+          <ul
+            className="flex-1 overflow-auto py-1"
+            style={{ height: listHeight }}
+          >
+            {visible.length === 0 ? (
+              <li className="px-3 py-6 text-center text-xs text-muted-foreground">
+                暂无数据
+              </li>
+            ) : (
+              visible.map((item) => {
+                const isChecked = checked.includes(item.key);
+                const itemDisabled = disabled || item.disabled;
+                return (
+                  <li key={item.key}>
+                    <label
+                      className={cn(
+                        'flex items-center gap-2 px-3 py-1.5',
+                        !itemDisabled && 'cursor-pointer hover:bg-accent',
+                        itemDisabled && 'cursor-not-allowed opacity-50',
+                      )}
+                    >
+                      <Checkbox
+                        checked={isChecked}
+                        disabled={itemDisabled}
+                        onCheckedChange={(c) => {
+                          if (c === true) setChecked([...checked, item.key]);
+                          else setChecked(checked.filter((k) => k !== item.key));
+                        }}
+                      />
+                      <span className="min-w-0 flex-1 truncate">
+                        {render ? render(item) : item.title}
+                      </span>
+                    </label>
+                  </li>
+                );
+              })
+            )}
+          </ul>
+        </div>
+      );
+    };
+
+    return (
+      <div
+        ref={ref}
+        className={cn('flex items-center gap-3', className)}
+      >
+        {renderPane(
+          titles[0],
+          leftItems,
+          leftVisible,
+          leftChecked,
+          setLeftChecked,
+          leftQuery,
+          setLeftQuery,
+        )}
+        <div className="flex flex-col gap-2">
+          <Button
+            size="icon"
+            variant="outline"
+            disabled={disabled || leftChecked.length === 0}
+            onClick={moveRight}
+            aria-label="移动到右侧"
+            icon={<ChevronRight />}
+          />
+          <Button
+            size="icon"
+            variant="outline"
+            disabled={disabled || rightChecked.length === 0}
+            onClick={moveLeft}
+            aria-label="移动到左侧"
+            icon={<ChevronLeft />}
+          />
+        </div>
+        {renderPane(
+          titles[1],
+          rightItems,
+          rightVisible,
+          rightChecked,
+          setRightChecked,
+          rightQuery,
+          setRightQuery,
+        )}
+      </div>
+    );
+  },
+);
+Transfer.displayName = 'Transfer';
+
+export { Transfer };

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

@@ -0,0 +1,111 @@
+---
+id: tree
+name: Tree
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Tree
+
+树形控件 — antd 独有补足。递归层级展示(组织架构、文件系统、分类目录),支持**可展开 / 可单选 / 可勾选(父子级联 + 半选)**,受控与非受控并存。Radix 未提供 tree primitive — 本组件自实现递归 + 受控逻辑。
+
+## When to use
+
+- 层级数据浏览(组织、目录、分类、JSON 结构)
+- 配 `checkable` 让用户多选叶子(权限分配、批量目录选)
+- 配 `selectable` 实现"选中一个节点查看右侧详情"主从布局
+
+## When NOT to use
+
+- 一层无层级 → `List` / `Menu`
+- 大数据量(> 1000 节点)— 本组件不做虚拟化,业务侧请自做分页 / 懒加载子节点
+- 拖拽排序场景 → 需配合 `react-dnd` 等库自行扩展,本组件不内置
+
+<!-- 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` | – | – | 展开变化回调。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add tree` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `checkbox` | component | 复选框 — Radix Checkbox(原生 indeterminate)+ antd Checkbox.Group(options 数组驱动) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`key` 必须 stable**(用数据库 id,不要用 index / 随机串) — `expandedKeys` / `checkedKeys` / `selectedKeys` 比对全靠它
+- **`checkable` 默认级联**:勾选父节点会勾选所有后代,勾选所有后代会自动勾选父节点 — **不要**自己写额外的级联逻辑;`onCheck` 给的是叶子+完全选中的父节点集合(半选不在内)
+- **半选(indeterminate)**自动计算,不需要消费方维护
+- **`selectable` + `checkable` 可共存**,但 UI 上选中高亮与勾选是两套独立状态(对齐 antd)
+- **大数据量警告**:节点数 ≥ 500 时建议拆分为"按需加载子节点"(在 `onExpand` 中拉取),否则首次渲染卡顿
+- **`disabled` 节点**:展开按钮亦禁用,但**仍参与级联计算** — 父被勾选时禁用子也会变为 checked
+
+## Examples
+
+```tsx
+import { Tree, type TreeNode } from '@/components/ui/tree';
+import { Folder, File } from 'lucide-react';
+import * as React from 'react';
+
+const data: TreeNode[] = [
+  {
+    key: 'src',
+    title: 'src',
+    icon: <Folder className="size-3.5" />,
+    children: [
+      { 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' },
+          { key: 'src/components/Input.tsx', title: 'Input.tsx' },
+        ],
+      },
+    ],
+  },
+];
+
+// 默认展开 + 选择
+<Tree data={data} defaultExpandAll />
+
+// 可勾选(受控)
+const [checked, setChecked] = React.useState<string[]>([]);
+<Tree
+  data={data}
+  checkable
+  defaultExpandAll
+  checkedKeys={checked}
+  onCheck={setChecked}
+/>
+```

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

@@ -0,0 +1,109 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { File, Folder } from 'lucide-react';
+import { Tree, type TreeNode } from './tree';
+
+const meta: Meta<typeof Tree> = {
+  title: '数据展示 · Data Display/Tree',
+  component: Tree,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '树形控件 — 递归层级展示(目录、组织、分类)。支持展开 / 单选 / 父子级联勾选(自动半选),受控与非受控并存。Radix 未提供 tree primitive,本组件自实现递归与级联。视觉走 OpenTrek tokens,等价 antd `Tree`,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tree>;
+
+const fileTree: TreeNode[] = [
+  {
+    key: 'src',
+    title: 'src',
+    icon: <Folder className="size-3.5" />,
+    children: [
+      { 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/utils',
+        title: 'utils',
+        icon: <Folder className="size-3.5" />,
+        children: [{ key: 'src/utils/cn.ts', title: 'cn.ts', icon: <File className="size-3.5" /> }],
+      },
+    ],
+  },
+  { key: 'README.md', title: 'README.md', icon: <File className="size-3.5" /> },
+];
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Tree data={fileTree} defaultExpandAll />,
+};
+
+export const Checkable: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [checked, setChecked] = React.useState<string[]>([]);
+    return (
+      <div className="flex flex-col gap-3">
+        <Tree
+          data={fileTree}
+          checkable
+          defaultExpandAll
+          checkedKeys={checked}
+          onCheck={setChecked}
+        />
+        <div className="text-xs text-muted-foreground">
+          已勾选: {checked.length === 0 ? '无' : checked.join(', ')}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Selectable: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [selected, setSelected] = React.useState<string[]>([]);
+    return (
+      <div className="flex flex-col gap-3">
+        <Tree
+          data={fileTree}
+          defaultExpandAll
+          selectedKeys={selected}
+          onSelect={setSelected}
+        />
+        <div className="text-xs text-muted-foreground">
+          已选中: {selected[0] ?? '无'}
+        </div>
+      </div>
+    );
+  },
+};
+
+export const ControlledExpand: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [expanded, setExpanded] = React.useState<string[]>(['src']);
+    return (
+      <Tree
+        data={fileTree}
+        expandedKeys={expanded}
+        onExpand={setExpanded}
+      />
+    );
+  },
+};