@teamix-evo/ui 0.1.1

package/src/components/tour/tour.stories.tsx

@@ -0,0 +1,66 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Tour } from './tour';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Tour> = {
+  title: '反馈与浮层 · Feedback/Tour',
+  component: Tour,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '新手引导 — 多步骤 spotlight + 卡片 + 步进按钮。帮助新用户首次进入页面时了解关键功能位置。等价 antd `Tour`(v5.0+)。业务侧自管"是否首次访问"。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tour>;
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const a = React.useRef<HTMLButtonElement>(null);
+    const b = React.useRef<HTMLButtonElement>(null);
+    const [open, setOpen] = React.useState(false);
+
+    return (
+      <div className="flex flex-col gap-4">
+        <Button onClick={() => setOpen(true)}>启动引导</Button>
+        <div className="flex gap-2">
+          <Button ref={a} variant="outline">
+            新建
+          </Button>
+          <Button ref={b} variant="outline">
+            设置
+          </Button>
+        </div>
+        <Tour
+          open={open}
+          onOpenChange={setOpen}
+          steps={[
+            {
+              target: a,
+              title: '从这里新建',
+              description: '点击「新建」按钮创建一个新项目',
+              placement: 'bottom',
+            },
+            {
+              target: b,
+              title: '个性化设置',
+              description: '在此调整主题、通知等偏好',
+              placement: 'top',
+            },
+            {
+              title: '完成!',
+              description: '开始使用吧 🎉',
+            },
+          ]}
+        />
+      </div>
+    );
+  },
+};

package/src/components/tour/tour.tsx

@@ -0,0 +1,242 @@
+import * as React from 'react';
+import { X } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+
+export interface TourStep {
+  /**
+   * 目标元素引用 — 可以是 React ref `RefObject` 或返回 element 的函数。
+   * 不传则居中显示(无 spotlight)。
+   */
+  target?: React.RefObject<HTMLElement | null> | (() => HTMLElement | null);
+  /** 步骤标题。 */
+  title: React.ReactNode;
+  /** 步骤描述。 */
+  description?: React.ReactNode;
+  /**
+   * 弹层相对目标的位置。
+   * @default "bottom"
+   */
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+}
+
+export interface TourProps {
+  /** 步骤列表(antd `steps` 并集)。 */
+  steps: TourStep[];
+  /** 受控 open 状态。 */
+  open?: boolean;
+  /** uncontrolled 初值。 @default false */
+  defaultOpen?: boolean;
+  /** open 变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /** 当前步骤索引(受控)。 */
+  current?: number;
+  /** 步骤变化回调。 */
+  onChange?: (current: number) => void;
+  /** 完成时回调(走到最后一步且点击"完成")。 */
+  onFinish?: () => void;
+  /** 关闭回调(任意时刻点 X / mask)。 */
+  onClose?: () => void;
+  /** 是否显示遮罩(antd `mask` 并集)。 @default true */
+  mask?: boolean;
+}
+
+const SPOTLIGHT_PADDING = 8;
+
+/**
+ * 新手引导 — antd 独有补足。**等价 antd `Tour`**(v5.0+)。多步骤引导(spotlight + 卡片 + 步进按钮),
+ * 帮助新用户首次进入页面时了解关键功能位置。
+ *
+ * **关键约束**:
+ *   - 目标元素必须**已在 DOM 中**才能定位 spotlight(组件用 `getBoundingClientRect()`)
+ *   - 不内置首次访问检测 — 由业务侧自行管理"是否第一次"(常配 localStorage)
+ */
+const Tour: React.FC<TourProps> = ({
+  steps,
+  open,
+  defaultOpen = false,
+  onOpenChange,
+  current,
+  onChange,
+  onFinish,
+  onClose,
+  mask = true,
+}) => {
+  const isControlledOpen = open !== undefined;
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+  const isOpen = isControlledOpen ? open! : internalOpen;
+
+  const isControlledStep = current !== undefined;
+  const [internalStep, setInternalStep] = React.useState(0);
+  const step = isControlledStep ? current! : internalStep;
+
+  const setOpen = (next: boolean) => {
+    if (!isControlledOpen) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
+  const setStep = (next: number) => {
+    if (!isControlledStep) setInternalStep(next);
+    onChange?.(next);
+  };
+
+  const [, force] = React.useReducer((x: number) => x + 1, 0);
+  React.useEffect(() => {
+    if (!isOpen) return;
+    const onResize = () => force();
+    window.addEventListener('resize', onResize);
+    window.addEventListener('scroll', onResize, { passive: true });
+    return () => {
+      window.removeEventListener('resize', onResize);
+      window.removeEventListener('scroll', onResize);
+    };
+  }, [isOpen]);
+
+  if (!isOpen) return null;
+  const cur = steps[step];
+  if (!cur) return null;
+
+  const target =
+    typeof cur.target === 'function'
+      ? cur.target()
+      : cur.target?.current ?? null;
+
+  const rect = target?.getBoundingClientRect();
+
+  const close = () => {
+    setOpen(false);
+    onClose?.();
+  };
+
+  const finish = () => {
+    setOpen(false);
+    onFinish?.();
+  };
+
+  const placement = cur.placement ?? 'bottom';
+  const cardStyle: React.CSSProperties = rect
+    ? (() => {
+        const offset = 12;
+        switch (placement) {
+          case 'top':
+            return {
+              top: rect.top - offset,
+              left: rect.left + rect.width / 2,
+              transform: 'translate(-50%, -100%)',
+            };
+          case 'left':
+            return {
+              top: rect.top + rect.height / 2,
+              left: rect.left - offset,
+              transform: 'translate(-100%, -50%)',
+            };
+          case 'right':
+            return {
+              top: rect.top + rect.height / 2,
+              left: rect.right + offset,
+              transform: 'translate(0, -50%)',
+            };
+          case 'bottom':
+          default:
+            return {
+              top: rect.bottom + offset,
+              left: rect.left + rect.width / 2,
+              transform: 'translate(-50%, 0)',
+            };
+        }
+      })()
+    : {
+        top: '50%',
+        left: '50%',
+        transform: 'translate(-50%, -50%)',
+      };
+
+  return (
+    <div className="fixed inset-0 z-50">
+      {mask ? (
+        rect ? (
+          <svg
+            className="pointer-events-none absolute inset-0 size-full"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <defs>
+              <mask id="tour-mask">
+                <rect width="100%" height="100%" fill="white" />
+                <rect
+                  x={rect.left - SPOTLIGHT_PADDING}
+                  y={rect.top - SPOTLIGHT_PADDING}
+                  width={rect.width + SPOTLIGHT_PADDING * 2}
+                  height={rect.height + SPOTLIGHT_PADDING * 2}
+                  rx="6"
+                  fill="black"
+                />
+              </mask>
+            </defs>
+            <rect
+              width="100%"
+              height="100%"
+              fill="rgba(0,0,0,0.5)"
+              mask="url(#tour-mask)"
+            />
+          </svg>
+        ) : (
+          <div className="absolute inset-0 bg-black/50" onClick={close} />
+        )
+      ) : null}
+
+      <div
+        role="dialog"
+        className={cn(
+          'absolute w-80 rounded-md border bg-popover p-4 text-popover-foreground shadow-xl',
+        )}
+        style={cardStyle}
+      >
+        <div className="flex items-start justify-between gap-2">
+          <div className="font-semibold">{cur.title}</div>
+          <button
+            type="button"
+            aria-label="关闭"
+            onClick={close}
+            className="text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <X className="size-4" />
+          </button>
+        </div>
+        {cur.description ? (
+          <div className="mt-2 text-sm text-muted-foreground">
+            {cur.description}
+          </div>
+        ) : null}
+        <div className="mt-4 flex items-center justify-between">
+          <span className="text-xs tabular-nums text-muted-foreground">
+            {step + 1} / {steps.length}
+          </span>
+          <div className="flex gap-2">
+            {step > 0 ? (
+              <Button
+                variant="outline"
+                size="sm"
+                onClick={() => setStep(step - 1)}
+              >
+                上一步
+              </Button>
+            ) : null}
+            {step < steps.length - 1 ? (
+              <Button size="sm" onClick={() => setStep(step + 1)}>
+                下一步
+              </Button>
+            ) : (
+              <Button size="sm" onClick={finish}>
+                完成
+              </Button>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+};
+Tour.displayName = 'Tour';
+
+export { Tour };

package/src/components/transfer/transfer.meta.md

@@ -0,0 +1,90 @@
+---
+id: transfer
+name: Transfer
+type: component
+category: data-display
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Transfer
+
+穿梭框 — antd 独有补足。**双侧勾选 + 移动**的批量分配交互(权限分配、字段映射、收件人选择)。受控 `targetKeys` + `onChange` 单一真值,内置全选 / 半选 / 可选搜索 / 禁用项。
+
+## When to use
+
+- 从大集合中挑选若干成员进入小集合(成员授权、邮件收件人)
+- 字段映射:左侧未映射字段 → 右侧已映射字段
+- 类目选择,可选 + 可移除并存
+
+## When NOT to use
+
+- 单纯多选 → `Select multiple` / `CheckboxGroup`(轻量)
+- 选项 > 500 — 本组件未做虚拟化,建议改用 `Table` + 行选 + bulk action 模式
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `dataSource` | `TransferItem[]` | – | ✓ | 全部数据源(左+右合集)。 |
+| `targetKeys` | `string[]` | – | ✓ | 受控:已"穿梭到右侧"的 key 集合(antd `targetKeys` 并集)。 |
+| `onChange` | `(next: string[]) => void` | – | – | 右侧集合变化回调。 |
+| `titles` | `[React.ReactNode, React.ReactNode]` | `["源", "目标"]` | – | 两侧标题(antd `titles` 并集) — `[左, 右]`。 |
+| `showSearch` | `boolean` | `false` | – | 启用搜索(antd `showSearch` 并集) — 两侧各一个输入框。 |
+| `render` | `(item: TransferItem) => React.ReactNode` | – | – | 自定义渲染单项(antd `render` 并集) — 默认渲染 `item.title`。 |
+| `disabled` | `boolean` | – | – | 整体禁用。 |
+| `listHeight` | `number` | `280` | – | 单侧高度(像素)。 |
+| `className` | `string` | – | – | – |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add transfer` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `checkbox` | component | 复选框 — Radix Checkbox(原生 indeterminate)+ antd Checkbox.Group(options 数组驱动) |
+| `input` | component | 文本输入 — shadcn 简洁基底 + antd prefix/suffix/clearable/showCount/addonBefore/addonAfter/size |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`targetKeys` 是单一真值**:左侧 = `dataSource \ targetKeys`,右侧 = `targetKeys`;**不要**自己维护两个数组
+- **禁用项不可被移动**:即使被勾选也会被 batch move 跳过(对齐 antd)
+- **搜索仅做客户端字符串匹配**:`title` 为 string 时按子串匹配;ReactNode 时不过滤(消费方请保证 title 是 string 或在 `dataSource` 上做 server-side filter)
+- **不要在 `onChange` 里改 `dataSource`**:dataSource 应稳定,只改 targetKeys
+- **`titles` 必为长度 2 的数组**:`['可选', '已选']` / `['全部成员', '已授权']` 之类语义
+- **大数据量(> 200 项)**:建议改用 `Table` + 行选择 + 批量操作,Transfer 更适合 < 200 项的小集合穿梭
+
+## Examples
+
+```tsx
+import { Transfer, type TransferItem } from '@/components/ui/transfer';
+import * as React from 'react';
+
+const data: TransferItem[] = Array.from({ length: 12 }, (_, i) => ({
+  key: String(i),
+  title: `成员 ${i + 1}`,
+  disabled: i === 0,
+}));
+
+const [target, setTarget] = React.useState<string[]>(['2', '4']);
+
+<Transfer
+  dataSource={data}
+  targetKeys={target}
+  onChange={setTarget}
+  titles={['全部成员', '已授权']}
+  showSearch
+/>
+```

package/src/components/transfer/transfer.stories.tsx

@@ -0,0 +1,68 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Transfer, type TransferItem } from './transfer';
+
+const meta: Meta<typeof Transfer> = {
+  title: '数据展示 · Data Display/Transfer',
+  component: Transfer,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '穿梭框 — 双侧勾选 + 移动的批量分配交互(权限分配、字段映射、收件人选择)。受控 targetKeys 单一真值,内置全选 / 半选 / 可选搜索 / 禁用项跳过。视觉走 OpenTrek tokens,等价 antd `Transfer`,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Transfer>;
+
+const data: TransferItem[] = Array.from({ length: 12 }, (_, i) => ({
+  key: String(i),
+  title: `成员 ${i + 1}`,
+  disabled: i === 0,
+}));
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [target, setTarget] = React.useState<string[]>(['2', '4']);
+    return (
+      <Transfer
+        dataSource={data}
+        targetKeys={target}
+        onChange={setTarget}
+      />
+    );
+  },
+};
+
+export const WithSearch: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [target, setTarget] = React.useState<string[]>([]);
+    return (
+      <Transfer
+        dataSource={data}
+        targetKeys={target}
+        onChange={setTarget}
+        titles={['全部成员', '已授权']}
+        showSearch
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Transfer
+      dataSource={data}
+      targetKeys={['1', '3']}
+      titles={['只读·左', '只读·右']}
+      disabled
+    />
+  ),
+};