@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/transfer/transfer.tsx

@@ -1,258 +0,0 @@
-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 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
-                }
-                disabled={disabled || selectableKeys.length === 0}
-                onCheckedChange={(c) => toggleAll(c === true)}
-              />
-              <span className="text-xs text-muted-foreground tabular-nums">
-                {checked.length}/{items.length}
-              </span>
-            </label>
-            <span className="text-xs font-medium text-foreground">{title}</span>
-          </div>
-          {showSearch ? (
-            <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
-                  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 transition-colors',
-                        !itemDisabled && 'cursor-pointer hover:bg-accent/50',
-                        !itemDisabled && isChecked && 'bg-accent/40',
-                        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-1.5">
-          <Button
-            size="sm"
-            variant="outline"
-            disabled={disabled || leftChecked.length === 0}
-            onClick={moveRight}
-            aria-label="移动到右侧"
-            className="size-7 p-0"
-            icon={<ChevronRight className="size-3.5" />}
-          />
-          <Button
-            size="sm"
-            variant="outline"
-            disabled={disabled || rightChecked.length === 0}
-            onClick={moveLeft}
-            aria-label="移动到左侧"
-            className="size-7 p-0"
-            icon={<ChevronLeft className="size-3.5" />}
-          />
-        </div>
-        {renderPane(
-          titles[1],
-          rightItems,
-          rightVisible,
-          rightChecked,
-          setRightChecked,
-          rightQuery,
-          setRightQuery,
-        )}
-      </div>
-    );
-  },
-);
-Transfer.displayName = 'Transfer';
-
-export { Transfer };

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

@@ -1,169 +0,0 @@
----
-id: tree
-name: Tree
-displayName: 树形控件
-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` 等库自行扩展,本组件不内置
-
-## 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` | – | – | 展开变化回调。 |
-<!-- 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)
-- **选中 ≠ 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
-
-## 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}
-/>;
-```
-
-## 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,128 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-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，本组件自实现递归与级联。等价 antd `Tree`。',
-      },
-    },
-  },
-};
-
-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} />
-    );
-  },
-};