@teamix-evo/ui 0.1.1

package/src/components/upload/upload.meta.md

@@ -0,0 +1,111 @@
+---
+id: upload
+name: Upload
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Upload
+
+文件上传 — antd 独有补足。支持**点击 + 拖拽**双模式(`dragger`)、多文件、accept 过滤、`maxCount` / `maxSize` 校验、内置文件列表(显示文件名 / 进度 / 移除按钮)。**只负责前端选择与列表呈现 — 实际上传请求由消费方在 `onChange` 中发起**(组件不内置 XHR)。
+
+## When to use
+
+- 表单中的附件上传(简历、合同、头像、产品图)
+- 拖拽区域批量导入(数据文件、图片)
+- 需要展示上传进度时,通过受控 `fileList` + `status="uploading"` + `percent` 渲染
+
+## When NOT to use
+
+- 仅需读取本地图片用于客户端预览 → 直接用 `<input type="file">`
+- 服务端推送式同步 → 不在本组件职责内
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `fileList` | `UploadFileItem[]` | – | – | 已上传文件列表(受控)— 不传则组件内部维护本地列表(限制少,通常配 onChange)。 |
+| `accept` | `string` | – | – | 文件接受类型(等价 input.accept) — e.g. `image/*`, `.pdf,.docx`。 |
+| `multiple` | `boolean` | `false` | – | 是否支持多文件选择(antd `multiple` 并集)。 |
+| `maxCount` | `number` | – | – | 最大文件数(超出则忽略,触发 `onExceed`)。 |
+| `maxSize` | `number` | – | – | 单文件最大字节数(超出则忽略,触发 `onExceed`)。 |
+| `dragger` | `boolean` | `false` | – | 启用拖拽上传(antd `Dragger` 并集) — 显示大块虚线区,可点击亦可拖拽。 |
+| `disabled` | `boolean` | – | – | 禁用上传(已选文件不可删除)。 |
+| `showFileList` | `boolean` | `true` | – | 是否显示文件列表(antd `showUploadList` 并集)。 |
+| `onChange` | `(next: UploadFileItem[]) => void` | – | – | 文件被添加(用户选择 / 拖入)时的回调 — 返回更新后的列表。 |
+| `onRemove` | `(file: UploadFileItem) => void` | – | – | 文件被移除时的回调。 |
+| `onExceed` | `(rejected: File[], reason: 'count' \| 'size') => void` | – | – | 超出 maxCount / maxSize 时的回调。 |
+| `children` | `React.ReactNode` | – | – | 触发器自定义内容(非 dragger 模式下渲染于 Button 内)。 |
+| `className` | `string` | – | – | – |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add upload` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `progress` | component | 进度条 — Radix 线性 + antd 的 status / showInfo / size 并集 + 配套 ProgressCircle 环形 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **不要在组件内做真上传** — 拿到 `onChange(files)` 后由消费方负责 fetch / axios,组件只管 UI
+- **进度场景**:必须用**受控** `fileList`,在 `onChange` 拿到 file 后启动上传,期间通过 `setState` 更新对应 item 的 `status="uploading"` + `percent`
+- **`maxCount` / `maxSize`**:校验失败会触发 `onExceed(rejected, reason)`,业务侧用 toast 提示;**不要**在组件外手动二次校验
+- **`accept`**:浏览器层过滤,**不能**当作安全校验 — 服务端仍需独立校验文件类型
+- **`dragger` 与 `children`**:dragger=true 时 children 替换默认提示文案;dragger=false 时 children 替换 Button 文本
+- **不要给 input 加 `name`** — Upload 不参与原生 form submit,数据由 `onChange` 取走
+
+## Examples
+
+```tsx
+import { Upload, type UploadFileItem } from '@/components/ui/upload';
+import { toast } from 'sonner';
+import * as React from 'react';
+
+// 点击上传
+<Upload
+  accept="image/*"
+  multiple
+  maxCount={3}
+  maxSize={5 * 1024 * 1024}
+  onExceed={(_, reason) =>
+    toast.error(reason === 'count' ? '最多 3 个文件' : '单文件不能超过 5MB')
+  }
+  onChange={(list) => console.log(list)}
+/>
+
+// 拖拽上传(Dragger)
+<Upload dragger multiple accept=".csv,.xlsx" onChange={(list) => uploadAll(list)} />
+
+// 带进度(受控)
+const [files, setFiles] = React.useState<UploadFileItem[]>([]);
+<Upload
+  fileList={files}
+  multiple
+  onChange={(next) => {
+    setFiles(next);
+    const fresh = next.filter((f) => f.status === 'done' && f.file);
+    fresh.forEach((item) => {
+      uploadXhr(item.file!, (percent) => {
+        setFiles((cur) =>
+          cur.map((f) => (f.uid === item.uid ? { ...f, status: 'uploading', percent } : f)),
+        );
+      });
+    });
+  }}
+/>
+```

package/src/components/upload/upload.stories.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Upload, type UploadFileItem } from './upload';
+
+const meta: Meta<typeof Upload> = {
+  title: '表单与输入 · Form/Upload',
+  component: Upload,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '文件上传 — 支持点击 + 拖拽双模式(Dragger),内置 maxCount / maxSize 校验、文件列表、进度条。组件只负责前端选择与列表呈现,真实上传请求由消费方在 onChange 中发起。视觉走 OpenTrek tokens,等价 antd `Upload` + `Upload.Dragger`,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    multiple: { control: 'boolean' },
+    dragger: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    accept: { control: 'text' },
+  },
+  args: { multiple: false, dragger: false, disabled: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Upload>;
+
+export const Playground: Story = {};
+
+export const Dragger: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Upload dragger multiple accept=".csv,.xlsx,.json" />
+  ),
+};
+
+export const WithLimits: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Upload
+      multiple
+      maxCount={3}
+      maxSize={2 * 1024 * 1024}
+      onExceed={(rej, reason) =>
+        // eslint-disable-next-line no-alert
+        alert(`${reason === 'count' ? '超出最大文件数' : '超出最大文件大小'}: ${rej.map((f) => f.name).join(', ')}`)
+      }
+    />
+  ),
+};
+
+export const ControlledProgress: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [files, setFiles] = React.useState<UploadFileItem[]>([
+      { uid: 'demo-1', name: 'report.pdf', status: 'uploading', percent: 45 },
+      { uid: 'demo-2', name: 'cover.png', status: 'done' },
+      { uid: 'demo-3', name: 'broken.zip', status: 'error' },
+    ]);
+    return (
+      <Upload
+        dragger
+        multiple
+        fileList={files}
+        onChange={setFiles}
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => <Upload dragger disabled />,
+};

package/src/components/upload/upload.tsx

@@ -0,0 +1,265 @@
+import * as React from 'react';
+import { File, Upload as UploadIcon, X } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import { Progress } from '@/components/progress/progress';
+
+export interface UploadFileItem {
+  /** 稳定 ID(由消费方维护)。 */
+  uid: string;
+  /** 显示文件名。 */
+  name: string;
+  /** 文件原对象(可选,服务端已上传完成的回填可不传)。 */
+  file?: File;
+  /**
+   * 上传状态(antd `status` 并集) — uploading 显示进度条;error 红色文案;done 不显示进度。
+   */
+  status?: 'uploading' | 'done' | 'error' | 'removed';
+  /** 上传百分比(0~100),仅 `status="uploading"` 时显示。 */
+  percent?: number;
+  /** 上传完成后的远程 URL(可选)。 */
+  url?: string;
+}
+
+export interface UploadProps {
+  /**
+   * 已上传文件列表(受控)— 不传则组件内部维护本地列表(限制少,通常配 onChange)。
+   */
+  fileList?: UploadFileItem[];
+  /**
+   * 文件接受类型(等价 input.accept) — e.g. `image/*`, `.pdf,.docx`。
+   */
+  accept?: string;
+  /**
+   * 是否支持多文件选择(antd `multiple` 并集)。
+   * @default false
+   */
+  multiple?: boolean;
+  /**
+   * 最大文件数(超出则忽略,触发 `onExceed`)。
+   */
+  maxCount?: number;
+  /**
+   * 单文件最大字节数(超出则忽略,触发 `onExceed`)。
+   */
+  maxSize?: number;
+  /**
+   * 启用拖拽上传(antd `Dragger` 并集) — 显示大块虚线区,可点击亦可拖拽。
+   * @default false
+   */
+  dragger?: boolean;
+  /** 禁用上传(已选文件不可删除)。 */
+  disabled?: boolean;
+  /**
+   * 是否显示文件列表(antd `showUploadList` 并集)。
+   * @default true
+   */
+  showFileList?: boolean;
+  /** 文件被添加(用户选择 / 拖入)时的回调 — 返回更新后的列表。 */
+  onChange?: (next: UploadFileItem[]) => void;
+  /** 文件被移除时的回调。 */
+  onRemove?: (file: UploadFileItem) => void;
+  /** 超出 maxCount / maxSize 时的回调。 */
+  onExceed?: (rejected: File[], reason: 'count' | 'size') => void;
+  /** 触发器自定义内容(非 dragger 模式下渲染于 Button 内)。 */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+function makeUid(): string {
+  return Math.random().toString(36).slice(2, 10) + Date.now().toString(36);
+}
+
+const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
+  (
+    {
+      fileList,
+      accept,
+      multiple = false,
+      maxCount,
+      maxSize,
+      dragger = false,
+      disabled = false,
+      showFileList = true,
+      onChange,
+      onRemove,
+      onExceed,
+      children,
+      className,
+    },
+    ref,
+  ) => {
+    const inputRef = React.useRef<HTMLInputElement>(null);
+    const [internal, setInternal] = React.useState<UploadFileItem[]>([]);
+    const isControlled = fileList !== undefined;
+    const current = isControlled ? fileList! : internal;
+
+    const [dragOver, setDragOver] = React.useState(false);
+
+    const setList = (next: UploadFileItem[]) => {
+      if (!isControlled) setInternal(next);
+      onChange?.(next);
+    };
+
+    const addFiles = (files: File[]) => {
+      if (disabled || files.length === 0) return;
+      let candidate = files;
+
+      if (typeof maxSize === 'number') {
+        const tooBig = candidate.filter((f) => f.size > maxSize);
+        if (tooBig.length) onExceed?.(tooBig, 'size');
+        candidate = candidate.filter((f) => f.size <= maxSize);
+      }
+
+      const remaining =
+        typeof maxCount === 'number'
+          ? Math.max(0, maxCount - current.length)
+          : candidate.length;
+      if (typeof maxCount === 'number' && candidate.length > remaining) {
+        onExceed?.(candidate.slice(remaining), 'count');
+        candidate = candidate.slice(0, remaining);
+      }
+
+      const items: UploadFileItem[] = candidate.map((f) => ({
+        uid: makeUid(),
+        name: f.name,
+        file: f,
+        status: 'done',
+      }));
+      setList([...current, ...items]);
+    };
+
+    const handleSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const list = e.target.files ? Array.from(e.target.files) : [];
+      addFiles(list);
+      e.target.value = '';
+    };
+
+    const remove = (uid: string) => {
+      const target = current.find((f) => f.uid === uid);
+      if (!target) return;
+      setList(current.filter((f) => f.uid !== uid));
+      onRemove?.(target);
+    };
+
+    const openPicker = () => {
+      if (disabled) return;
+      inputRef.current?.click();
+    };
+
+    const onDrop = (e: React.DragEvent) => {
+      e.preventDefault();
+      setDragOver(false);
+      if (disabled) return;
+      const files = Array.from(e.dataTransfer.files);
+      addFiles(files);
+    };
+
+    const trigger = dragger ? (
+      <div
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        aria-disabled={disabled}
+        onClick={openPicker}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            openPicker();
+          }
+        }}
+        onDragOver={(e) => {
+          e.preventDefault();
+          if (!disabled) setDragOver(true);
+        }}
+        onDragLeave={() => setDragOver(false)}
+        onDrop={onDrop}
+        className={cn(
+          'flex cursor-pointer flex-col items-center justify-center gap-2 rounded-md border border-dashed bg-muted/30 px-6 py-10 text-center text-sm text-muted-foreground transition-colors',
+          'hover:border-primary/50 hover:bg-muted/50',
+          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+          dragOver && 'border-primary bg-primary/5',
+          disabled && 'cursor-not-allowed opacity-60',
+        )}
+      >
+        {children ?? (
+          <>
+            <UploadIcon className="size-8 text-primary/70" />
+            <div className="font-medium text-foreground">点击或拖拽文件到此处上传</div>
+            <div className="text-xs">
+              {multiple ? '可选择多个文件' : '仅支持单个文件'}
+              {accept ? ` · 限 ${accept}` : null}
+            </div>
+          </>
+        )}
+      </div>
+    ) : (
+      <Button
+        type="button"
+        variant="outline"
+        onClick={openPicker}
+        disabled={disabled}
+        icon={<UploadIcon />}
+      >
+        {children ?? '选择文件'}
+      </Button>
+    );
+
+    return (
+      <div ref={ref} className={cn('flex flex-col gap-3', className)}>
+        <input
+          ref={inputRef}
+          type="file"
+          accept={accept}
+          multiple={multiple}
+          disabled={disabled}
+          onChange={handleSelect}
+          className="hidden"
+        />
+        {trigger}
+        {showFileList && current.length > 0 ? (
+          <ul className="flex flex-col gap-2">
+            {current.map((f) => (
+              <li
+                key={f.uid}
+                className={cn(
+                  'flex items-center gap-3 rounded-md border bg-card px-3 py-2 text-sm',
+                  f.status === 'error' && 'border-destructive/40',
+                )}
+              >
+                <File className="size-4 shrink-0 text-muted-foreground" />
+                <div className="flex min-w-0 flex-1 flex-col gap-1">
+                  <span
+                    className={cn(
+                      'truncate',
+                      f.status === 'error' && 'text-destructive',
+                    )}
+                    title={f.name}
+                  >
+                    {f.name}
+                  </span>
+                  {f.status === 'uploading' ? (
+                    <Progress value={f.percent ?? 0} size="sm" />
+                  ) : null}
+                </div>
+                {!disabled ? (
+                  <button
+                    type="button"
+                    aria-label={`移除 ${f.name}`}
+                    onClick={() => remove(f.uid)}
+                    className="rounded-sm p-1 text-muted-foreground transition-colors hover:bg-accent hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                  >
+                    <X className="size-4" />
+                  </button>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        ) : null}
+      </div>
+    );
+  },
+);
+Upload.displayName = 'Upload';
+
+export { Upload };

package/src/components/watermark/watermark.meta.md

@@ -0,0 +1,95 @@
+---
+id: watermark
+name: Watermark
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Watermark
+
+水印 — antd 独有补足。**等价 antd `Watermark`**(v5.1+)。在容器内部生成重复平铺的 SVG 水印(文字 / 图片),用于敏感页面 / 内部文档 / 演示场景。
+
+## When to use
+
+- 内部管理后台敏感页面(显示用户名 + 工号,起威慑作用)
+- 文档预览(防止截图被盗用)
+- 设计稿 / 评审页(标注"内部" / "Draft")
+- demo 录屏(标注产品名 / 版本)
+
+## When NOT to use
+
+- 真正的版权保护 → **服务端水印** + 数字签名;前端水印可被开发者删除
+- 通知 / 提示语 → `Alert` / `Tag`(语义不一样)
+- 装饰背景图 → CSS `background-image`
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `content` | `string \| string[]` | – | – | 水印文字(antd `content` 并集) — 单行字符串或多行字符串数组。 |
+| `image` | `string` | – | – | 水印图片(antd `image` 并集) — 优先级高于 `content`。建议透明 PNG / SVG。 |
+| `width` | `number` | `120` | – | 单块水印宽度(px)。 |
+| `height` | `number` | `64` | – | 单块水印高度(px)。 |
+| `rotate` | `number` | `-22` | – | 水印旋转角度(deg)。 |
+| `fontSize` | `number` | `14` | – | 字体大小(px)。 |
+| `fontColor` | `string` | `"rgba(0,0,0,0.15)"` | – | 字体颜色(支持 rgba 设置透明度)。 |
+| `fontWeight` | `'normal' \| 'medium' \| 'bold'` | `"normal"` | – | 字体粗细。 |
+| `gapX` | `number` | `80` | – | 水印块之间的水平间距(px)。 |
+| `gapY` | `number` | `80` | – | 水印块之间的垂直间距(px)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add watermark` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **不可作为安全防护**:Watermark 是**前端视觉效果**,F12 可删 — 真正合规需要**服务端**水印(后端给图片打水印 / 给 PDF 嵌不可见数字签名)
+- **`content` 短文本**(用户名 + 工号 / 公司名):太长会被截断,可改用多行字符串数组
+- **`fontColor` 必须带 alpha**(默认 `rgba(0,0,0,0.15)`):不透明水印会遮挡内容
+- **`image`** 优先级高于 content;**透明 PNG / SVG** 否则会出现矩形背景
+- **`rotate=-22`** 是 antd 默认角度 — 防止水平 / 垂直地平等被截图工具一键去除
+- **不要嵌套 Watermark** — 双重水印视觉混乱
+
+## Examples
+
+```tsx
+import { Watermark } from '@/components/ui/watermark';
+
+// 单行文本
+<Watermark content="Acme Corp · CONFIDENTIAL">
+  <article className="prose">...内部文档内容...</article>
+</Watermark>
+
+// 多行(用户名 + 工号)
+<Watermark content={['Alice Wong', 'EMP-2026-001']}>
+  <DashboardPage />
+</Watermark>
+
+// 图片水印
+<Watermark image="/brand-mark.svg" width={80} height={40}>
+  ...
+</Watermark>
+
+// 调整密度与角度
+<Watermark
+  content="内部资料"
+  gapX={120}
+  gapY={120}
+  rotate={-30}
+  fontColor="rgba(255,0,0,0.2)"
+>
+  ...
+</Watermark>
+```

package/src/components/watermark/watermark.stories.tsx

@@ -0,0 +1,78 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Watermark } from './watermark';
+
+const meta: Meta<typeof Watermark> = {
+  title: '反馈与浮层 · Feedback/Watermark',
+  component: Watermark,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '水印 — 容器内重复平铺的 SVG 文字 / 图片水印(内部敏感页面 / 文档预览 / demo 录屏)。前端视觉效果,不作为安全防护。等价 antd `Watermark`(v5.1+)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    content: { control: 'text' },
+    rotate: { control: { type: 'number', min: -90, max: 90 } },
+    fontSize: { control: { type: 'number', min: 8, max: 48 } },
+    gapX: { control: 'number' },
+    gapY: { control: 'number' },
+  },
+  args: {
+    content: 'Acme Corp · CONFIDENTIAL',
+    rotate: -22,
+    fontSize: 14,
+    gapX: 80,
+    gapY: 80,
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Watermark>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Watermark {...args} className="h-72 w-full rounded-md border bg-card p-6">
+      <h3 className="mb-3 text-lg font-semibold">内部文档</h3>
+      <p className="text-sm text-muted-foreground">
+        这是一段示例文档内容。水印铺在底层,内容可正常交互。
+        本组件适合内部管理后台、敏感页面、设计稿评审等场景。
+      </p>
+    </Watermark>
+  ),
+};
+
+export const MultilineUser: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Watermark
+      content={['Alice Wong', 'EMP-2026-001']}
+      className="h-72 w-full rounded-md border bg-card p-6"
+    >
+      <h3 className="mb-3 text-lg font-semibold">用户信息水印</h3>
+      <p className="text-sm text-muted-foreground">
+        多行水印通常用于"用户名 + 工号",起到威慑截图泄密的作用。
+      </p>
+    </Watermark>
+  ),
+};
+
+export const ColoredAndDense: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Watermark
+      content="内部资料"
+      fontColor="rgba(220,38,38,0.18)"
+      fontWeight="bold"
+      gapX={60}
+      gapY={60}
+      rotate={-30}
+      className="h-72 w-full rounded-md border bg-card p-6"
+    >
+      <h3 className="mb-3 text-lg font-semibold">红色密集水印</h3>
+      <p className="text-sm text-muted-foreground">配合 fontWeight / gap / rotate 调整视觉强度。</p>
+    </Watermark>
+  ),
+};