@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/tour/tour.meta.md

@@ -1,121 +0,0 @@
----
-id: tour
-name: Tour
-type: component
-category: deprecated
-since: 0.1.0
-package: '@teamix-evo/ui'
-displayName: 新手引导
----
-
-# Tour 新手引导
-
-新手引导 — antd 独有补足。**等价 antd `Tour`**(v5.0+)。多步骤引导(spotlight + 卡片 + 步进按钮 + 可关闭),帮助新用户首次进入页面时了解关键功能位置。
-
-## When to use
-
-- 首次进入新功能页(关键功能位置说明)
-- 重大改版后的迁移引导(指出新位置)
-- 工具型应用的快速入门(画板 / 编辑器)
-
-## When NOT to use
-
-- 静态帮助文档 → 用 Anchor + 长文档
-- 单一提示 → `Tooltip` / `Popover`
-- 表单字段说明 → `FieldDescription`
-- 错误反馈 → `Alert` / `notification`
-
-## Props
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `steps` | `TourStep[]` | – | ✓ | 步骤列表(antd `steps` 并集)。 |
-| `open` | `boolean` | – | – | 受控 open 状态。 |
-| `defaultOpen` | `boolean` | `false` | – | uncontrolled 初值。 |
-| `onOpenChange` | `(open: boolean) => void` | – | – | open 变化回调。 |
-| `current` | `number` | – | – | 当前步骤索引(受控)。 |
-| `onChange` | `(current: number) => void` | – | – | 步骤变化回调。 |
-| `onFinish` | `() => void` | – | – | 完成时回调(走到最后一步且点击"完成")。 |
-| `onClose` | `() => void` | – | – | 关闭回调(任意时刻点 X / mask)。 |
-| `mask` | `boolean` | `true` | – | 是否显示遮罩(antd `mask` 并集)。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add tour` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add lucide-react@^0.460.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **业务侧自管"是否首次访问"** — 通常配 localStorage `tour:onboarding` 标记;**不要**期望本组件持久化
-- **`target` 必须是已挂载的元素**:用 `useRef` 绑定到 DOM 节点;Tour 用 `getBoundingClientRect()` 定位 spotlight
-- **`target` 不传 = 居中无 spotlight 模式**:用于"欢迎语" / "总结结束语"等无指向步骤
-- **步骤 ≤ 5**:再多用户会跳过 — 太长的引导改用文档 / 视频
-- **`onFinish` 应同时 set localStorage** 标记完成,避免再次弹出
-- **不要在 Tour 内放复杂表单 / 长文本** — 它是定位提示,不是阅读容器
-- **`mask=false`** 仅在用户需要边引导边操作时关闭;默认遮罩聚焦更强
-
-## Examples
-
-```tsx
-import { Tour } from '@/components/ui/tour';
-import * as React from 'react';
-
-function Page() {
-  const newBtnRef = React.useRef<HTMLButtonElement>(null);
-  const settingsRef = React.useRef<HTMLDivElement>(null);
-  const [open, setOpen] = React.useState(false);
-
-  React.useEffect(() => {
-    if (!localStorage.getItem('tour:v1')) setOpen(true);
-  }, []);
-
-  return (
-    <>
-      <button ref={newBtnRef}>新建</button>
-      <div ref={settingsRef}>设置</div>
-
-      <Tour
-        open={open}
-        onOpenChange={setOpen}
-        onFinish={() => localStorage.setItem('tour:v1', '1')}
-        steps={[
-          {
-            target: newBtnRef,
-            title: '从这里新建',
-            description: '点击「新建」按钮即可创建新的项目',
-            placement: 'bottom',
-          },
-          {
-            target: settingsRef,
-            title: '个性化设置',
-            description: '在此处调整主题 / 通知偏好',
-            placement: 'left',
-          },
-          {
-            title: '完成!',
-            description: '开始使用吧 🎉',
-          },
-        ]}
-      />
-    </>
-  );
-}
-```

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

@@ -1,66 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Tour } from './tour';
-import { Button } from '@/components/button/button';
-
-const meta: Meta<typeof Tour> = {
-  title: '废弃 · Deprecated/Tour',
-  component: Tour,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n新手引导 — 多步骤 spotlight + 卡片 + 步进按钮。帮助新用户首次进入页面时了解关键功能位置。等价 antd `Tour`（v5.0+）。业务侧自管“是否首次访问”。',
-      },
-    },
-  },
-};
-
-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

@@ -1,242 +0,0 @@
-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="var(--overlay-scrim)"
-              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 border-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="cursor-pointer text-muted-foreground transition-colors hover:text-foreground"
-          >
-            <X className="size-4" />
-          </button>
-        </div>
-        {cur.description ? (
-          <div className="mt-2 text-xs 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

@@ -1,95 +0,0 @@
----
-id: transfer
-name: Transfer
-displayName: 穿梭框
-type: component
-category: data-entry
-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 模式
-
-## Props
-
-<!-- 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 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
-| `checkbox` | component | 复选框 — Radix Checkbox(原生 indeterminate)+ antd Checkbox.Group(options 数组驱动) |
-| `input` | component | 单行文本输入 — clearable / showCount / size(sm 24 / md 32 / lg 36,与 Button 同档)/ error 四档内建能力。前缀/后缀/addon 等复合形态已拆出独立 InputGroup;多行已拆出独立 Textarea |
-
-### 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

@@ -1,64 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { Transfer, type TransferItem } from './transfer';
-
-const meta: Meta<typeof Transfer> = {
-  title: '数据录入 · Data Entry/Transfer',
-  component: Transfer,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '穿梭框 — 双侧勾选 + 移动的批量分配交互（权限分配、字段映射、收件人选择）。受控 targetKeys 单一真值，内置全选 / 半选 / 可选搜索 / 禁用项跳过。等价 antd `Transfer`。',
-      },
-    },
-  },
-};
-
-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
-    />
-  ),
-};