@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/transfer/meta.md

@@ -0,0 +1,76 @@
+# Transfer
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+穿梭框 Transfer
+双栏勾选 + 移动的批量分配交互，将元素在两侧之间穿梭。
+
+## 使用场景
+
+- 权限分配（角色 → 用户）等需要明确「已选 / 未选」分区的批量操作
+- 字段映射 / 列选择 / 收件人挑选等中量级（10–500 条）多选场景
+- 需要在面板内完成搜索过滤、自定义渲染或自定义列表（树 / 表格）时
+
+## 组合结构
+
+```
+Transfer > TransferPanel × 2 + Operations
+```
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `dataSource` | `TransferItem[]` | – | ✓ | 数据源。 |
+| `targetKeys` | `string[]` | – | – | 受控右侧已选 key（穿梭到右侧的项）。 |
+| `defaultTargetKeys` | `string[]` | – | – | 默认右侧已选 key（非受控）。 |
+| `selectedKeys` | `string[]` | – | – | 受控两侧勾选态 key（包含左右两侧的勾选项）。 |
+| `defaultSelectedKeys` | `string[]` | – | – | 默认两侧勾选态 key（非受控）。 |
+| `onChange` | `( targetKeys: string[], direction: TransferDirection, moveKeys: string[], ) => void` | – | – | 移动回调；direction 为新增项流向的方向。 |
+| `onSelectChange` | `( sourceSelectedKeys: string[], targetSelectedKeys: string[], ) => void` | – | – | 勾选态变化回调。 |
+| `onSearch` | `(direction: TransferDirection, value: string) => void` | – | – | 搜索输入回调。 |
+| `size` | `TransferSize` | `'default'` | – | 尺寸。 |
+| `mode` | `'normal' \| 'simple'` | `'normal'` | – | 移动模式：normal=勾选 + 按钮；simple=单击即移动。 |
+| `oneWay` | `boolean` | `false` | – | 单向模式（隐藏左移按钮，右侧每行末尾出现移除按钮）。 |
+| `showSearch` | `boolean \| [boolean, boolean]` | `false` | – | 是否显示搜索框；boolean 或 [左, 右]。 |
+| `filterOption` | `( input: string, item: TransferItem, direction: TransferDirection, ) => boolean` | – | – | 自定义过滤函数。 |
+| `showSelectAll` | `boolean` | `true` | – | 是否显示头部全选 checkbox。 |
+| `disabled` | `boolean` | `false` | – | 整体禁用。 |
+| `leftDisabled` | `boolean` | `false` | – | 仅禁用左侧面板。 |
+| `rightDisabled` | `boolean` | `false` | – | 仅禁用右侧面板。 |
+| `titles` | `[React.ReactNode, React.ReactNode]` | `['', '']` | – | 左右标题。 |
+| `operations` | `[React.ReactNode, React.ReactNode]` | – | – | 自定义按钮内容；[向右图标, 向左图标]。 |
+| `render` | `(item: TransferItem) => React.ReactNode` | – | – | 单项自定义渲染。 |
+| `listClassName` | `string` | – | – | 列表面板自定义类名（同时作用于左右）。 |
+| `listStyle` | `React.CSSProperties` | – | – | 列表面板自定义内联样式。 |
+| `locale` | `TransferLocale` | – | – | 文案本地化。 |
+| `children` | `(panelProps: TransferListBodyProps) => React.ReactNode` | – | – | 自定义面板 render-prop（antd v5 契约）。传入时由调用方接管列表区。 |
+
+## 示例
+
+### Sizes
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Transfer
+    size="sm"
+    dataSource={dataSource.slice(0, 6)}
+    defaultTargetKeys={['item-1']}
+    titles={['Small', 'Small']}
+  />
+  <Transfer
+    size="default"
+    dataSource={dataSource.slice(0, 6)}
+    defaultTargetKeys={['item-1']}
+    titles={['Default', 'Default']}
+  />
+  <Transfer
+    size="lg"
+    dataSource={dataSource.slice(0, 6)}
+    defaultTargetKeys={['item-1']}
+    titles={['Large', 'Large']}
+  />
+</div>
+```

package/src/components/transfer/stories.tsx

@@ -0,0 +1,221 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { ChevronsLeft, ChevronsRight, Folder } from 'lucide-react';
+
+import { Transfer } from '.';
+import type { TransferItem, TransferListBodyProps } from '.';
+
+const dataSource: TransferItem[] = Array.from({ length: 12 }, (_, i) => ({
+  key: `item-${i}`,
+  title: `内容 ${i + 1}`,
+  disabled: i === 3,
+}));
+
+const dataSourceWithDescription: TransferItem[] = Array.from(
+  { length: 8 },
+  (_, i) => ({
+    key: `member-${i}`,
+    title: `成员 ${i + 1}`,
+    description: `角色 ${i % 3 === 0 ? '管理员' : '只读'}`,
+    disabled: i === 2,
+  }),
+);
+
+const meta: Meta<typeof Transfer> = {
+  title: '数据录入 · Data Entry/Transfer 穿梭框',
+  component: Transfer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '穿梭框 — 双栏勾选 + 移动的批量分配交互，对齐 antd v5 schema（key / title / description）。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Transfer>;
+
+export const Basic: Story = {
+  name: '基础穿梭框',
+  args: { dataSource, defaultTargetKeys: ['item-1', 'item-5'] },
+};
+
+export const WithSearch: Story = {
+  name: '带搜索（双侧）',
+  args: { dataSource, showSearch: true, defaultTargetKeys: ['item-2'] },
+};
+
+export const SearchPerSide: Story = {
+  name: '仅左侧搜索',
+  args: {
+    dataSource,
+    showSearch: [true, false] as [boolean, boolean],
+    defaultTargetKeys: ['item-2'],
+  },
+};
+
+export const Sizes: Story = {
+  name: '尺寸三档',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <Transfer
+        size="sm"
+        dataSource={dataSource.slice(0, 6)}
+        defaultTargetKeys={['item-1']}
+        titles={['Small', 'Small']}
+      />
+      <Transfer
+        size="default"
+        dataSource={dataSource.slice(0, 6)}
+        defaultTargetKeys={['item-1']}
+        titles={['Default', 'Default']}
+      />
+      <Transfer
+        size="lg"
+        dataSource={dataSource.slice(0, 6)}
+        defaultTargetKeys={['item-1']}
+        titles={['Large', 'Large']}
+      />
+    </div>
+  ),
+};
+
+export const SimpleMode: Story = {
+  name: '简单模式',
+  args: {
+    dataSource,
+    mode: 'simple',
+    defaultTargetKeys: ['item-1'],
+    titles: ['可选项', '已选项'],
+  },
+};
+
+export const OneWay: Story = {
+  name: '单向穿梭',
+  args: {
+    dataSource,
+    oneWay: true,
+    defaultTargetKeys: ['item-2', 'item-5'],
+    titles: ['可选项', '已选项'],
+  },
+};
+
+export const WithDescription: Story = {
+  name: '带描述',
+  args: {
+    dataSource: dataSourceWithDescription,
+    defaultTargetKeys: ['member-1'],
+    titles: ['可分配', '已分配'],
+  },
+};
+
+export const CustomRender: Story = {
+  name: '自定义渲染',
+  args: {
+    dataSource,
+    defaultTargetKeys: ['item-1'],
+    render: (item) => (
+      <span className="inline-flex items-center gap-1.5">
+        <Folder className="size-3 text-muted-foreground" />
+        {item.title}
+      </span>
+    ),
+  },
+};
+
+export const CustomOperations: Story = {
+  name: '自定义按钮',
+  args: {
+    dataSource,
+    defaultTargetKeys: ['item-1'],
+    operations: [<ChevronsRight />, <ChevronsLeft />] as [
+      React.ReactNode,
+      React.ReactNode,
+    ],
+  },
+};
+
+export const Disabled: Story = {
+  name: '整体禁用',
+  args: { dataSource, disabled: true, defaultTargetKeys: ['item-1', 'item-4'] },
+};
+
+export const PartialDisabled: Story = {
+  name: '仅禁用一侧',
+  args: {
+    dataSource,
+    leftDisabled: true,
+    defaultTargetKeys: ['item-2', 'item-5'],
+    titles: ['左侧禁用', '右侧可操作'],
+  },
+};
+
+export const WithLocale: Story = {
+  name: '自定义文案',
+  args: {
+    dataSource,
+    showSearch: true,
+    titles: ['可分配成员', '已分配成员'],
+    locale: {
+      itemUnit: '人',
+      itemsUnit: '人',
+      notFoundContent: '没有匹配的成员',
+      searchPlaceholder: '按姓名搜索',
+    },
+  },
+};
+
+export const CustomPanel: Story = {
+  name: '自定义面板',
+  render: () => {
+    const [target, setTarget] = React.useState<string[]>(['item-1']);
+    return (
+      <Transfer
+        dataSource={dataSource}
+        targetKeys={target}
+        onChange={setTarget}
+        showSelectAll={false}
+        titles={['Source', 'Target']}
+      >
+        {({
+          direction,
+          filteredItems,
+          selectedKeys,
+          disabled,
+          onItemSelect,
+        }: TransferListBodyProps) => (
+          <ul className="flex flex-col gap-0.5 p-1 text-xs">
+            {filteredItems.map((item) => {
+              const checked = selectedKeys.includes(item.key);
+              return (
+                <li
+                  key={item.key}
+                  className={`flex cursor-pointer items-center gap-2 rounded-sm px-1.5 py-1 hover:bg-accent/50 ${
+                    checked ? 'bg-accent/40' : ''
+                  } ${
+                    disabled || item.disabled
+                      ? 'pointer-events-none opacity-50'
+                      : ''
+                  }`}
+                  onClick={() => onItemSelect(item.key, !checked)}
+                >
+                  <span
+                    className={`inline-block size-1.5 rounded-full ${
+                      direction === 'left'
+                        ? 'bg-primary'
+                        : 'bg-muted-foreground'
+                    }`}
+                  />
+                  {item.title}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </Transfer>
+    );
+  },
+};