@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/transfer/index.tsx

@@ -0,0 +1,639 @@
+/**
+ * 穿梭框 Transfer
+ *
+ * 双栏勾选 + 移动的批量分配交互，将元素在两侧之间穿梭。
+ *
+ * @when
+ * - 权限分配（角色 → 用户）等需要明确「已选 / 未选」分区的批量操作
+ * - 字段映射 / 列选择 / 收件人挑选等中量级（10–500 条）多选场景
+ * - 需要在面板内完成搜索过滤、自定义渲染或自定义列表（树 / 表格）时
+ *
+ * @composition
+ * Transfer > TransferPanel × 2 + Operations
+ */
+import * as React from 'react';
+import { ChevronLeft, ChevronRight, X } from 'lucide-react';
+import { cva } from 'class-variance-authority';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+import { Checkbox } from '@/components/checkbox';
+import { Input } from '@/components/input';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface TransferItem {
+  /** 唯一标识。 */
+  key: string;
+  /** 主标题（列表项主显示文本）。 */
+  title: React.ReactNode;
+  /** 描述文本（次行小字，可选）。 */
+  description?: React.ReactNode;
+  /** 单项禁用。 */
+  disabled?: boolean;
+}
+
+type TransferDirection = 'left' | 'right';
+type TransferSize = 'sm' | 'default' | 'lg';
+
+type TransferListBodyProps = {
+  /** 当前面板方位。 */
+  direction: TransferDirection;
+  /** 经搜索过滤后的可见项列表。 */
+  filteredItems: TransferItem[];
+  /** 当前面板已勾选的 key 列表。 */
+  selectedKeys: string[];
+  /** 当前面板是否禁用。 */
+  disabled: boolean;
+  /** 单项勾选切换。 */
+  onItemSelect: (key: string, selected: boolean) => void;
+  /** 批量勾选切换（用于全选 / 反选）。 */
+  onItemSelectAll: (keys: string[], selected: boolean) => void;
+};
+
+type TransferLocale = {
+  /** 单数计数单位。 @default '项' */
+  itemUnit?: string;
+  /** 复数计数单位。 @default '项' */
+  itemsUnit?: string;
+  /** 列表为空时的占位内容。 @default '暂无数据' */
+  notFoundContent?: React.ReactNode;
+  /** 搜索框 placeholder。 @default '搜索' */
+  searchPlaceholder?: string;
+};
+
+interface TransferProps
+  extends Omit<React.ComponentProps<'div'>, 'onChange' | 'children'> {
+  /** 数据源。 */
+  dataSource: TransferItem[];
+  /** 受控右侧已选 key（穿梭到右侧的项）。 */
+  targetKeys?: string[];
+  /** 默认右侧已选 key（非受控）。 */
+  defaultTargetKeys?: string[];
+  /** 受控两侧勾选态 key（包含左右两侧的勾选项）。 */
+  selectedKeys?: string[];
+  /** 默认两侧勾选态 key（非受控）。 */
+  defaultSelectedKeys?: string[];
+
+  /** 移动回调；direction 为新增项流向的方向。 */
+  onChange?: (
+    targetKeys: string[],
+    direction: TransferDirection,
+    moveKeys: string[],
+  ) => void;
+  /** 勾选态变化回调。 */
+  onSelectChange?: (
+    sourceSelectedKeys: string[],
+    targetSelectedKeys: string[],
+  ) => void;
+  /** 搜索输入回调。 */
+  onSearch?: (direction: TransferDirection, value: string) => void;
+
+  /** 尺寸。 @default 'default' */
+  size?: TransferSize;
+  /** 移动模式：normal=勾选 + 按钮；simple=单击即移动。 @default 'normal' */
+  mode?: 'normal' | 'simple';
+  /** 单向模式（隐藏左移按钮，右侧每行末尾出现移除按钮）。 @default false */
+  oneWay?: boolean;
+
+  /** 是否显示搜索框；boolean 或 [左, 右]。 @default false */
+  showSearch?: boolean | [boolean, boolean];
+  /** 自定义过滤函数。 */
+  filterOption?: (
+    input: string,
+    item: TransferItem,
+    direction: TransferDirection,
+  ) => boolean;
+  /** 是否显示头部全选 checkbox。 @default true */
+  showSelectAll?: boolean;
+
+  /** 整体禁用。 @default false */
+  disabled?: boolean;
+  /** 仅禁用左侧面板。 @default false */
+  leftDisabled?: boolean;
+  /** 仅禁用右侧面板。 @default false */
+  rightDisabled?: boolean;
+
+  /** 左右标题。 @default ['', ''] */
+  titles?: [React.ReactNode, React.ReactNode];
+  /** 自定义按钮内容；[向右图标, 向左图标]。 */
+  operations?: [React.ReactNode, React.ReactNode];
+  /** 单项自定义渲染。 */
+  render?: (item: TransferItem) => React.ReactNode;
+
+  /** 列表面板自定义类名（同时作用于左右）。 */
+  listClassName?: string;
+  /** 列表面板自定义内联样式。 */
+  listStyle?: React.CSSProperties;
+
+  /** 文案本地化。 */
+  locale?: TransferLocale;
+
+  /** 自定义面板 render-prop（antd v5 契约）。传入时由调用方接管列表区。 */
+  children?: (panelProps: TransferListBodyProps) => React.ReactNode;
+}
+
+// ─── Size cva ───────────────────────────────────────────────────────────────
+
+const panelVariants = cva(
+  'flex flex-col rounded-md border border-border bg-card',
+  {
+    variants: {
+      size: {
+        sm: 'w-40',
+        default: 'w-48',
+        lg: 'w-56',
+      },
+    },
+    defaultVariants: { size: 'default' },
+  },
+);
+
+const listVariants = cva('flex-1 overflow-y-auto p-1', {
+  variants: {
+    size: {
+      sm: 'max-h-40',
+      default: 'max-h-50',
+      lg: 'max-h-60',
+    },
+  },
+  defaultVariants: { size: 'default' },
+});
+
+// 与 Button 的 icon-sm/icon/icon-lg 对齐
+const operationButtonSize = {
+  sm: 'icon-sm',
+  default: 'icon-sm',
+  lg: 'icon',
+} as const;
+
+const itemTextSize: Record<TransferSize, string> = {
+  sm: 'text-xs',
+  default: 'text-xs',
+  lg: 'text-sm',
+};
+
+// ─── Default filter ─────────────────────────────────────────────────────────
+
+function defaultFilter(input: string, item: TransferItem): boolean {
+  if (!input) return true;
+  if (typeof item.title !== 'string') return true;
+  return item.title.toLowerCase().includes(input.toLowerCase());
+}
+
+// ─── TransferPanel ──────────────────────────────────────────────────────────
+
+interface PanelInternalProps {
+  direction: TransferDirection;
+  size: TransferSize;
+  mode: 'normal' | 'simple';
+  items: TransferItem[];
+  selectedKeys: string[];
+  onSelectChange: (keys: string[]) => void;
+  onSimpleMove?: (key: string) => void;
+  onItemRemove?: (key: string) => void;
+  oneWay: boolean;
+  showSearch: boolean;
+  showSelectAll: boolean;
+  disabled: boolean;
+  title: React.ReactNode;
+  filterOption?: TransferProps['filterOption'];
+  render?: TransferProps['render'];
+  locale: Required<TransferLocale>;
+  listClassName?: string;
+  listStyle?: React.CSSProperties;
+  onSearch?: (direction: TransferDirection, value: string) => void;
+  children?: TransferProps['children'];
+}
+
+function TransferPanel({
+  direction,
+  size,
+  mode,
+  items,
+  selectedKeys,
+  onSelectChange,
+  onSimpleMove,
+  onItemRemove,
+  oneWay,
+  showSearch,
+  showSelectAll,
+  disabled,
+  title,
+  filterOption,
+  render,
+  locale,
+  listClassName,
+  listStyle,
+  onSearch,
+  children,
+}: PanelInternalProps) {
+  const [search, setSearch] = React.useState('');
+
+  const filtered = React.useMemo(() => {
+    if (!search) return items;
+    const filterFn = filterOption
+      ? (item: TransferItem) => filterOption(search, item, direction)
+      : (item: TransferItem) => defaultFilter(search, item);
+    return items.filter(filterFn);
+  }, [search, items, filterOption, direction]);
+
+  const selectableKeys = filtered
+    .filter((item) => !item.disabled)
+    .map((item) => item.key);
+  const selectedSet = React.useMemo(
+    () => new Set(selectedKeys),
+    [selectedKeys],
+  );
+  const checkedCount = selectableKeys.filter((k) => selectedSet.has(k)).length;
+  const allChecked =
+    selectableKeys.length > 0 && checkedCount === selectableKeys.length;
+  const indeterminate = checkedCount > 0 && !allChecked;
+
+  const handleSelectAll = (next: boolean | 'indeterminate') => {
+    if (next === true) {
+      const merged = Array.from(new Set([...selectedKeys, ...selectableKeys]));
+      onSelectChange(merged);
+    } else {
+      const removeSet = new Set(selectableKeys);
+      onSelectChange(selectedKeys.filter((k) => !removeSet.has(k)));
+    }
+  };
+
+  const onItemSelect = (key: string, next: boolean) => {
+    if (next) {
+      if (selectedSet.has(key)) return;
+      onSelectChange([...selectedKeys, key]);
+    } else {
+      onSelectChange(selectedKeys.filter((k) => k !== key));
+    }
+  };
+
+  const onItemSelectAll = (keys: string[], next: boolean) => {
+    if (next) {
+      onSelectChange(Array.from(new Set([...selectedKeys, ...keys])));
+    } else {
+      const removeSet = new Set(keys);
+      onSelectChange(selectedKeys.filter((k) => !removeSet.has(k)));
+    }
+  };
+
+  const renderItemContent = (item: TransferItem) => {
+    if (render) return render(item);
+    if (item.description) {
+      return (
+        <div className="flex min-w-0 flex-col">
+          <span className="truncate">{item.title}</span>
+          <span className="truncate text-xs text-muted-foreground">
+            {item.description}
+          </span>
+        </div>
+      );
+    }
+    return <span className="truncate">{item.title}</span>;
+  };
+
+  const showHeaderCheckbox = mode === 'normal' && showSelectAll;
+  const totalCount = items.length;
+
+  return (
+    <div
+      data-slot="transfer-panel"
+      data-direction={direction}
+      data-size={size}
+      className={cn(panelVariants({ size }))}
+    >
+      {/* Header */}
+      <div className="flex items-center gap-2 border-b border-border px-2 py-2">
+        {showHeaderCheckbox ? (
+          <Checkbox
+            checked={
+              indeterminate ? 'indeterminate' : allChecked && totalCount > 0
+            }
+            disabled={disabled || selectableKeys.length === 0}
+            onCheckedChange={handleSelectAll}
+          />
+        ) : null}
+        <span className="flex-1 truncate text-xs font-medium">{title}</span>
+        <span className="text-xs text-muted-foreground">
+          {checkedCount > 0
+            ? `${checkedCount}/${totalCount} ${
+                totalCount > 1 ? locale.itemsUnit : locale.itemUnit
+              }`
+            : `${totalCount} ${
+                totalCount > 1 ? locale.itemsUnit : locale.itemUnit
+              }`}
+        </span>
+      </div>
+
+      {/* Search */}
+      {showSearch ? (
+        <div
+          data-slot="transfer-search"
+          className="px-2 pt-1.5 pb-2"
+        >
+          <Input
+            value={search}
+            disabled={disabled}
+            placeholder={locale.searchPlaceholder}
+            onChange={(e) => {
+              setSearch(e.target.value);
+              onSearch?.(direction, e.target.value);
+            }}
+          />
+        </div>
+      ) : null}
+
+      {/* List */}
+      <div
+        data-slot="transfer-list"
+        className={cn(listVariants({ size }), listClassName)}
+        style={listStyle}
+      >
+        {typeof children === 'function' ? (
+          children({
+            direction,
+            filteredItems: filtered,
+            selectedKeys,
+            disabled,
+            onItemSelect,
+            onItemSelectAll,
+          })
+        ) : filtered.length === 0 ? (
+          <div className="py-6 text-center text-xs text-muted-foreground">
+            {locale.notFoundContent}
+          </div>
+        ) : (
+          filtered.map((item) => {
+            const itemDisabled = disabled || !!item.disabled;
+            const checked = selectedSet.has(item.key);
+            const showRemove = direction === 'right' && oneWay && !itemDisabled;
+
+            return (
+              <div
+                key={item.key}
+                data-slot="transfer-list-item"
+                data-disabled={itemDisabled || undefined}
+                data-checked={checked || undefined}
+                className={cn(
+                  'group/transfer-item flex items-center gap-2 rounded-sm px-1.5 py-2 transition-colors',
+                  itemTextSize[size],
+                  itemDisabled
+                    ? 'pointer-events-none opacity-50'
+                    : 'cursor-pointer hover:bg-accent/50',
+                  checked && mode === 'normal' && 'bg-accent/30',
+                )}
+                onClick={() => {
+                  if (itemDisabled) return;
+                  if (mode === 'simple') {
+                    onSimpleMove?.(item.key);
+                    return;
+                  }
+                  onItemSelect(item.key, !checked);
+                }}
+              >
+                {mode === 'normal' ? (
+                  <Checkbox
+                    checked={checked}
+                    disabled={itemDisabled}
+                    onCheckedChange={(next) =>
+                      onItemSelect(item.key, next === true)
+                    }
+                    onClick={(e) => e.stopPropagation()}
+                  />
+                ) : null}
+                <div className="min-w-0 flex-1">{renderItemContent(item)}</div>
+                {showRemove ? (
+                  <Button
+                    size="icon-sm"
+                    variant="ghost"
+                    className="opacity-0 group-hover/transfer-item:opacity-100"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      onItemRemove?.(item.key);
+                    }}
+                  >
+                    <X />
+                  </Button>
+                ) : null}
+              </div>
+            );
+          })
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ─── Transfer ───────────────────────────────────────────────────────────────
+
+const DEFAULT_LOCALE: Required<TransferLocale> = {
+  itemUnit: '项',
+  itemsUnit: '项',
+  notFoundContent: '暂无数据',
+  searchPlaceholder: '搜索',
+};
+
+function Transfer({
+  dataSource,
+  targetKeys: controlledTargetKeys,
+  defaultTargetKeys,
+  selectedKeys: controlledSelectedKeys,
+  defaultSelectedKeys,
+  onChange,
+  onSelectChange,
+  onSearch,
+  size = 'default',
+  mode = 'normal',
+  oneWay = false,
+  showSearch = false,
+  filterOption,
+  showSelectAll = true,
+  disabled = false,
+  leftDisabled = false,
+  rightDisabled = false,
+  titles,
+  operations,
+  render,
+  listClassName,
+  listStyle,
+  locale: localeProp,
+  children,
+  className,
+  ...props
+}: TransferProps) {
+  // 受控合并
+  const [internalTargetKeys, setInternalTargetKeys] = React.useState<string[]>(
+    defaultTargetKeys ?? [],
+  );
+  const targetKeys = controlledTargetKeys ?? internalTargetKeys;
+
+  const [internalSelectedKeys, setInternalSelectedKeys] = React.useState<
+    string[]
+  >(defaultSelectedKeys ?? []);
+  const selectedKeys = controlledSelectedKeys ?? internalSelectedKeys;
+
+  const locale = { ...DEFAULT_LOCALE, ...localeProp };
+
+  const targetSet = React.useMemo(() => new Set(targetKeys), [targetKeys]);
+  const leftItems = React.useMemo(
+    () => dataSource.filter((item) => !targetSet.has(item.key)),
+    [dataSource, targetSet],
+  );
+  const rightItems = React.useMemo(
+    () => dataSource.filter((item) => targetSet.has(item.key)),
+    [dataSource, targetSet],
+  );
+
+  const leftSelectedKeys = React.useMemo(() => {
+    const leftKeySet = new Set(leftItems.map((i) => i.key));
+    return selectedKeys.filter((k) => leftKeySet.has(k));
+  }, [leftItems, selectedKeys]);
+
+  const rightSelectedKeys = React.useMemo(() => {
+    const rightKeySet = new Set(rightItems.map((i) => i.key));
+    return selectedKeys.filter((k) => rightKeySet.has(k));
+  }, [rightItems, selectedKeys]);
+
+  const updateSelectedKeys = (next: string[]) => {
+    if (controlledSelectedKeys === undefined) setInternalSelectedKeys(next);
+    const leftKeySet = new Set(leftItems.map((i) => i.key));
+    const rightKeySet = new Set(rightItems.map((i) => i.key));
+    onSelectChange?.(
+      next.filter((k) => leftKeySet.has(k)),
+      next.filter((k) => rightKeySet.has(k)),
+    );
+  };
+
+  const handlePanelSelectChange = (
+    direction: TransferDirection,
+    nextKeys: string[],
+  ) => {
+    const otherKeys =
+      direction === 'left' ? rightSelectedKeys : leftSelectedKeys;
+    updateSelectedKeys([...otherKeys, ...nextKeys]);
+  };
+
+  const moveItems = (moveKeys: string[], direction: TransferDirection) => {
+    if (moveKeys.length === 0) return;
+    const moveSet = new Set(moveKeys);
+    const newTargetKeys =
+      direction === 'right'
+        ? [...targetKeys, ...moveKeys]
+        : targetKeys.filter((k) => !moveSet.has(k));
+    if (controlledTargetKeys === undefined)
+      setInternalTargetKeys(newTargetKeys);
+    onChange?.(newTargetKeys, direction, moveKeys);
+    // 清掉已经移出去的勾选
+    updateSelectedKeys(selectedKeys.filter((k) => !moveSet.has(k)));
+  };
+
+  const moveToRight = () => moveItems(leftSelectedKeys, 'right');
+  const moveToLeft = () => moveItems(rightSelectedKeys, 'left');
+
+  const handleSimpleMove = (direction: TransferDirection) => (key: string) => {
+    moveItems([key], direction === 'left' ? 'right' : 'left');
+  };
+
+  const showSearchTuple: [boolean, boolean] = Array.isArray(showSearch)
+    ? showSearch
+    : [showSearch, showSearch];
+
+  const leftPanelDisabled = disabled || leftDisabled;
+  const rightPanelDisabled = disabled || rightDisabled;
+
+  const [rightOp, leftOp] = operations ?? [<ChevronRight />, <ChevronLeft />];
+
+  const moveToRightDisabled = disabled || leftSelectedKeys.length === 0;
+  const moveToLeftDisabled = disabled || rightSelectedKeys.length === 0;
+
+  return (
+    <div
+      data-slot="transfer"
+      data-size={size}
+      data-mode={mode}
+      className={cn('inline-flex items-start gap-2', className)}
+      {...props}
+    >
+      <TransferPanel
+        direction="left"
+        size={size}
+        mode={mode}
+        items={leftItems}
+        selectedKeys={leftSelectedKeys}
+        onSelectChange={(keys) => handlePanelSelectChange('left', keys)}
+        onSimpleMove={handleSimpleMove('left')}
+        oneWay={oneWay}
+        showSearch={showSearchTuple[0]}
+        showSelectAll={showSelectAll}
+        disabled={leftPanelDisabled}
+        title={titles?.[0]}
+        filterOption={filterOption}
+        render={render}
+        locale={locale}
+        listClassName={listClassName}
+        listStyle={listStyle}
+        onSearch={onSearch}
+        children={children}
+      />
+
+      {mode === 'normal' ? (
+        <div
+          data-slot="transfer-operations"
+          className="flex flex-col gap-1 self-center"
+        >
+          <Button
+            variant={moveToRightDisabled ? 'outline' : 'default'}
+            size={operationButtonSize[size]}
+            disabled={moveToRightDisabled}
+            onClick={moveToRight}
+          >
+            {rightOp}
+          </Button>
+          {!oneWay ? (
+            <Button
+              variant={moveToLeftDisabled ? 'outline' : 'default'}
+              size={operationButtonSize[size]}
+              disabled={moveToLeftDisabled}
+              onClick={moveToLeft}
+            >
+              {leftOp}
+            </Button>
+          ) : null}
+        </div>
+      ) : null}
+
+      <TransferPanel
+        direction="right"
+        size={size}
+        mode={mode}
+        items={rightItems}
+        selectedKeys={rightSelectedKeys}
+        onSelectChange={(keys) => handlePanelSelectChange('right', keys)}
+        onSimpleMove={handleSimpleMove('right')}
+        onItemRemove={(key) => moveItems([key], 'left')}
+        oneWay={oneWay}
+        showSearch={showSearchTuple[1]}
+        showSelectAll={showSelectAll}
+        disabled={rightPanelDisabled}
+        title={titles?.[1]}
+        filterOption={filterOption}
+        render={render}
+        locale={locale}
+        listClassName={listClassName}
+        listStyle={listStyle}
+        onSearch={onSearch}
+        children={children}
+      />
+    </div>
+  );
+}
+
+export { Transfer };
+export type {
+  TransferProps,
+  TransferItem,
+  TransferDirection,
+  TransferListBodyProps,
+  TransferLocale,
+};