@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,13 +1,14 @@
 ---
 id: upload
 name: Upload
+displayName: 上传
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Upload
+# Upload 上传
 
 文件上传 — antd 独有补足。支持**点击 + 拖拽**双模式(`dragger`)、多文件、accept 过滤、`maxCount` / `maxSize` 校验、内置文件列表(显示文件名 / 进度 / 移除按钮)。**只负责前端选择与列表呈现 — 实际上传请求由消费方在 `onChange` 中发起**(组件不内置 XHR)。
 
@@ -22,6 +23,8 @@ package: "@teamix-evo/ui"
 - 仅需读取本地图片用于客户端预览 → 直接用 `<input type="file">`
 - 服务端推送式同步 → 不在本组件职责内
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -30,9 +33,11 @@ package: "@teamix-evo/ui"
 | `multiple` | `boolean` | `false` | – | 是否支持多文件选择(antd `multiple` 并集)。 |
 | `maxCount` | `number` | – | – | 最大文件数(超出则忽略,触发 `onExceed`)。 |
 | `maxSize` | `number` | – | – | 单文件最大字节数(超出则忽略,触发 `onExceed`)。 |
+| `beforeUpload` | `( file: File, fileList: File[], ) => boolean \| File \| void \| Promise<boolean \| File \| void>` | – | – | 文件添加前的校验钩子(antd `beforeUpload` 并集)。 - 返回 `false` 拒绝当前文件 - 返回 `true` / `undefined` 允许 - 返回 新 `File` 对象可替换原文件(重命名 / 压缩等) - 支持异步 `Promise` 注意: 此钩子在 `maxCount` / `maxSize` 校验**之后**调用。 |
 | `dragger` | `boolean` | `false` | – | 启用拖拽上传(antd `Dragger` 并集) — 显示大块虚线区,可点击亦可拖拽。 |
 | `disabled` | `boolean` | – | – | 禁用上传(已选文件不可删除)。 |
 | `showFileList` | `boolean` | `true` | – | 是否显示文件列表(antd `showUploadList` 并集)。 |
+| `listType` | `'text' \| 'image' \| 'card'` | `"text"` | – | 文件列表的展示形态(antd `listType` 并集) — - `text`(默认):文件名 + 进度条,适用文档上传 - `image`:小缩略图 + 文件名,适用头像 / 附件预览 - `card`:网格大缩略图卡,适用多图上传 / 产品图库 |
 | `onChange` | `(next: UploadFileItem[]) => void` | – | – | 文件被添加(用户选择 / 拖入)时的回调 — 返回更新后的列表。 |
 | `onRemove` | `(file: UploadFileItem) => void` | – | – | 文件被移除时的回调。 |
 | `onExceed` | `(rejected: File[], reason: 'count' \| 'size') => void` | – | – | 超出 maxCount / maxSize 时的回调。 |
@@ -40,6 +45,8 @@ package: "@teamix-evo/ui"
 | `className` | `string` | – | – | – |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -48,7 +55,7 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
 | `progress` | component | 进度条 — Radix 线性 + antd 的 status / showInfo / size 并集 + 配套 ProgressCircle 环形 |
 
 ### npm 依赖
@@ -109,3 +116,41 @@ const [files, setFiles] = React.useState<UploadFileItem[]>([]);
   }}
 />
 ```
+
+---
+
+## Upload 形态 — 旧库 API → 新映射
+
+> 旧库 `Upload`(hybridcloud,含 Upload.Card / Upload.Dragger 子组件) → 新库 `Upload`(单组件 prop 切换)。
+> 新库**不内置网络层**(XHR/fetch)，由消费方在 `onChange` 中自行上传。
+
+### 命名 & 结构映射
+
+| 旧库                               | 新库                             | 说明                             |
+| ---------------------------------- | -------------------------------- | -------------------------------- |
+| `Upload`                           | `Upload`                         | 组件名相同                       |
+| `Upload.Card`                      | `<Upload listType="card" />`     | 子组件变 prop                    |
+| `Upload.Dragger`                   | `<Upload dragger />`             | 子组件变 prop                    |
+| `value / defaultValue`             | `fileList`                       | 文件列表(受控)                   |
+| `limit`                            | `maxCount`                       | 最大文件数                       |
+| `dragable`                         | `dragger`                        | 拖拽上传 prop                    |
+| `action / headers / method`        | 无(消费方自行请求)               | 架构差异:无内置 XHR              |
+| `onSuccess / onError / onProgress` | 无(通过 fileList.status/percent) | 状态驱动而非回调                 |
+| `beforeUpload`                     | _(未来 P1)_                      | MVP 用 accept + maxSize 前置过滤 |
+| `autoUpload`                       | _(未来 P1)_                      | MVP 仅选件,上传由消费方控制      |
+| `itemRender`                       | _(未来 P2)_                      | MVP 使用内置渲染                 |
+| `shape='card'`                     | `listType='card'` + dragger      | 组合代替                         |
+| `useDataURL`                       | 不复刻                           | 消费方 FileReader                |
+| `progressProps`                    | 不复刻                           | 内置简化 Progress                |
+| `isPreview / renderPreview`        | 不复刻                           | 无预览态                         |
+| `fileKeyName`                      | 不复刻                           | 固定用 uid                       |
+
+### 迁移 FAQ
+
+| 问题                | 回答                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------ |
+| 无 action 怎么上传? | 在 `onChange` 中拿到 `file` 对象，自行 fetch/XHR;通过 `setFiles` 更新 status/percent |
+| 怎么实现拖拽?       | `<Upload dragger />` 即可;虚线区域点击/拖放均可触发                                  |
+| 怎么限制文件类型?   | `accept="image/*"` 或 `accept=".pdf,.docx"`                                          |
+| 怎么显示上传进度?   | fileList item 设 `status:'uploading'` + `percent:50`                                 |
+| Card 模式怎么用?    | `<Upload listType="card" dragger />` — 网格缩略图 + 拖拽区                           |

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

@@ -1,16 +1,16 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Upload, type UploadFileItem } from './upload';
 
 const meta: Meta<typeof Upload> = {
-  title: '表单与输入 · Form/Upload',
+  title: '数据录入 · Data Entry/Upload',
   component: Upload,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '文件上传 — 支持点击 + 拖拽双模式(Dragger),内置 maxCount / maxSize 校验、文件列表、进度条。组件只负责前端选择与列表呈现,真实上传请求由消费方在 onChange 中发起。视觉走 OpenTrek tokens,等价 antd `Upload` + `Upload.Dragger`,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '文件上传 — 支持点击 + 拖拽双模式（Dragger），内置 maxCount / maxSize 校验、文件列表、进度条。组件只负责前端选择与列表呈现，真实上传请求由消费方在 onChange 中发起。等价 antd `Upload` + `Upload.Dragger`。',
       },
     },
   },
@@ -19,8 +19,12 @@ const meta: Meta<typeof Upload> = {
     dragger: { control: 'boolean' },
     disabled: { control: 'boolean' },
     accept: { control: 'text' },
+    listType: {
+      control: 'inline-radio',
+      options: ['text', 'image', 'card'],
+    },
   },
-  args: { multiple: false, dragger: false, disabled: false },
+  args: { multiple: false, dragger: false, disabled: false, listType: 'text' },
 };
 
 export default meta;
@@ -30,9 +34,7 @@ export const Playground: Story = {};
 
 export const Dragger: Story = {
   parameters: { controls: { disable: true } },
-  render: () => (
-    <Upload dragger multiple accept=".csv,.xlsx,.json" />
-  ),
+  render: () => <Upload dragger multiple accept=".csv,.xlsx,.json" />,
 };
 
 export const WithLimits: Story = {
@@ -43,8 +45,11 @@ export const WithLimits: Story = {
       maxCount={3}
       maxSize={2 * 1024 * 1024}
       onExceed={(rej, reason) =>
-        // eslint-disable-next-line no-alert
-        alert(`${reason === 'count' ? '超出最大文件数' : '超出最大文件大小'}: ${rej.map((f) => f.name).join(', ')}`)
+        alert(
+          `${reason === 'count' ? '超出最大文件数' : '超出最大文件大小'}: ${rej
+            .map((f) => f.name)
+            .join(', ')}`,
+        )
       }
     />
   ),
@@ -58,9 +63,42 @@ export const ControlledProgress: Story = {
       { 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 />,
+};
+
+// ─── listType · 三种列表形态 ────────────────────────────────────
+
+const imageDemoFiles: UploadFileItem[] = [
+  {
+    uid: 'img-1',
+    name: 'avatar.png',
+    status: 'done',
+    thumbUrl: 'https://github.com/shadcn.png',
+  },
+  {
+    uid: 'img-2',
+    name: 'cover.jpg',
+    status: 'done',
+    thumbUrl: 'https://placehold.co/200x200/e5e7eb/6b7280?text=Cover',
+  },
+  { uid: 'img-3', name: 'broken.png', status: 'error' },
+];
+
+export const ListTypeImage: Story = {
+  name: 'listType="image" · 缩略图列表',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [files, setFiles] = React.useState<UploadFileItem[]>(imageDemoFiles);
     return (
       <Upload
-        dragger
+        listType="image"
+        accept="image/*"
         multiple
         fileList={files}
         onChange={setFiles}
@@ -69,7 +107,29 @@ export const ControlledProgress: Story = {
   },
 };
 
-export const Disabled: Story = {
+export const ListTypeCard: Story = {
+  name: 'listType="card" · 网格卡',
   parameters: { controls: { disable: true } },
-  render: () => <Upload dragger disabled />,
+  render: () => {
+    const [files, setFiles] = React.useState<UploadFileItem[]>([
+      ...imageDemoFiles,
+      {
+        uid: 'img-4',
+        name: 'uploading.png',
+        status: 'uploading',
+        percent: 65,
+        thumbUrl: 'https://placehold.co/200x200/dbeafe/1d4ed8?text=65%25',
+      },
+    ]);
+    return (
+      <Upload
+        dragger
+        listType="card"
+        accept="image/*"
+        multiple
+        fileList={files}
+        onChange={setFiles}
+      />
+    );
+  },
 };

package/src/components/upload/upload.tsx

@@ -1,5 +1,10 @@
 import * as React from 'react';
-import { File, Upload as UploadIcon, X } from 'lucide-react';
+import {
+  File,
+  Image as ImageIcon,
+  Upload as UploadIcon,
+  X,
+} from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 import { Button } from '@/components/button/button';
@@ -20,6 +25,11 @@ export interface UploadFileItem {
   percent?: number;
   /** 上传完成后的远程 URL(可选)。 */
   url?: string;
+  /**
+   * 缩略图 URL(可选) — `listType="image"|"card"` 时以此为展示源;
+   * 未传时回退为 `url` 或默认文件图标。
+   */
+  thumbUrl?: string;
 }
 
 export interface UploadProps {
@@ -44,6 +54,19 @@ export interface UploadProps {
    * 单文件最大字节数(超出则忽略,触发 `onExceed`)。
    */
   maxSize?: number;
+  /**
+   * 文件添加前的校验钩子(antd `beforeUpload` 并集)。
+   * - 返回 `false` 拒绝当前文件
+   * - 返回 `true` / `undefined` 允许
+   * - 返回 新 `File` 对象可替换原文件(重命名 / 压缩等)
+   * - 支持异步 `Promise`
+   *
+   * 注意: 此钩子在 `maxCount` / `maxSize` 校验**之后**调用。
+   */
+  beforeUpload?: (
+    file: File,
+    fileList: File[],
+  ) => boolean | File | void | Promise<boolean | File | void>;
   /**
    * 启用拖拽上传(antd `Dragger` 并集) — 显示大块虚线区,可点击亦可拖拽。
    * @default false
@@ -56,6 +79,14 @@ export interface UploadProps {
    * @default true
    */
   showFileList?: boolean;
+  /**
+   * 文件列表的展示形态(antd `listType` 并集) —
+   *   - `text`(默认):文件名 + 进度条,适用文档上传
+   *   - `image`:小缩略图 + 文件名,适用头像 / 附件预览
+   *   - `card`:网格大缩略图卡,适用多图上传 / 产品图库
+   * @default "text"
+   */
+  listType?: 'text' | 'image' | 'card';
   /** 文件被添加(用户选择 / 拖入)时的回调 — 返回更新后的列表。 */
   onChange?: (next: UploadFileItem[]) => void;
   /** 文件被移除时的回调。 */
@@ -82,9 +113,11 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
       dragger = false,
       disabled = false,
       showFileList = true,
+      listType = 'text',
       onChange,
       onRemove,
       onExceed,
+      beforeUpload,
       children,
       className,
     },
@@ -102,7 +135,7 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
       onChange?.(next);
     };
 
-    const addFiles = (files: File[]) => {
+    const addFiles = async (files: File[]) => {
       if (disabled || files.length === 0) return;
       let candidate = files;
 
@@ -121,6 +154,28 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
         candidate = candidate.slice(0, remaining);
       }
 
+      // beforeUpload 钩子 — 逐文件校验
+      if (beforeUpload) {
+        const accepted: File[] = [];
+        for (const f of candidate) {
+          try {
+            const result = await beforeUpload(f, candidate);
+            if (result === false) continue; // 拒绝
+            if (result instanceof globalThis.File) {
+              accepted.push(result); // 替换文件
+            } else {
+              accepted.push(f); // 允许原文件
+            }
+          } catch {
+            // Promise reject = 拒绝
+            continue;
+          }
+        }
+        candidate = accepted;
+      }
+
+      if (candidate.length === 0) return;
+
       const items: UploadFileItem[] = candidate.map((f) => ({
         uid: makeUid(),
         name: f.name,
@@ -175,7 +230,7 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
         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',
+          'flex cursor-pointer flex-col items-center justify-center gap-2 rounded-md border border-border border-dashed bg-muted/30 px-6 py-10 text-center text-xs 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',
@@ -185,7 +240,9 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
         {children ?? (
           <>
             <UploadIcon className="size-8 text-primary/70" />
-            <div className="font-medium text-foreground">点击或拖拽文件到此处上传</div>
+            <div className="font-medium text-foreground">
+              点击或拖拽文件到此处上传
+            </div>
             <div className="text-xs">
               {multiple ? '可选择多个文件' : '仅支持单个文件'}
               {accept ? ` · 限 ${accept}` : null}
@@ -218,43 +275,119 @@ const Upload = React.forwardRef<HTMLDivElement, UploadProps>(
         />
         {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
+          listType === 'card' ? (
+            <ul
+              className="grid grid-cols-[repeat(auto-fill,minmax(7rem,1fr))] gap-3"
+              role="list"
+            >
+              {current.map((f) => {
+                const thumb = f.thumbUrl ?? f.url;
+                return (
+                  <li
+                    key={f.uid}
                     className={cn(
-                      'truncate',
-                      f.status === 'error' && 'text-destructive',
+                      'group/uc relative flex aspect-square flex-col items-center justify-center overflow-hidden rounded-md border border-border bg-card text-center text-xs',
+                      f.status === 'error' && 'border-destructive/40',
                     )}
-                    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"
+                    {thumb ? (
+                      <img
+                        src={thumb}
+                        alt={f.name}
+                        className="size-full object-cover"
+                      />
+                    ) : (
+                      <div className="flex flex-col items-center gap-1 px-2 text-muted-foreground">
+                        <ImageIcon className="size-6" />
+                        <span
+                          className={cn(
+                            'line-clamp-2 break-all',
+                            f.status === 'error' && 'text-destructive',
+                          )}
+                          title={f.name}
+                        >
+                          {f.name}
+                        </span>
+                      </div>
+                    )}
+                    {f.status === 'uploading' ? (
+                      <div className="absolute inset-x-0 bottom-0 bg-background/85 px-2 py-1">
+                        <Progress value={f.percent ?? 0} size="sm" />
+                      </div>
+                    ) : null}
+                    {!disabled ? (
+                      <button
+                        type="button"
+                        aria-label={`移除 ${f.name}`}
+                        onClick={() => remove(f.uid)}
+                        className="absolute right-1 top-1 cursor-pointer rounded-sm bg-background/80 p-1 text-muted-foreground opacity-0 transition-opacity hover:text-foreground focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring group-hover/uc:opacity-100"
+                      >
+                        <X className="size-3.5" />
+                      </button>
+                    ) : null}
+                  </li>
+                );
+              })}
+            </ul>
+          ) : (
+            <ul className="flex flex-col gap-2">
+              {current.map((f) => {
+                const isImage = listType === 'image';
+                const thumb = f.thumbUrl ?? f.url;
+                return (
+                  <li
+                    key={f.uid}
+                    className={cn(
+                      'flex items-center gap-3 rounded-md border border-border bg-card px-3 py-2 text-xs',
+                      f.status === 'error' && 'border-destructive/40',
+                    )}
                   >
-                    <X className="size-4" />
-                  </button>
-                ) : null}
-              </li>
-            ))}
-          </ul>
+                    {isImage ? (
+                      <div className="size-10 shrink-0 overflow-hidden rounded-sm border border-border bg-muted">
+                        {thumb ? (
+                          <img
+                            src={thumb}
+                            alt={f.name}
+                            className="size-full object-cover"
+                          />
+                        ) : (
+                          <div className="flex size-full items-center justify-center text-muted-foreground">
+                            <ImageIcon className="size-4" />
+                          </div>
+                        )}
+                      </div>
+                    ) : (
+                      <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="cursor-pointer 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>
     );

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

@@ -4,10 +4,11 @@ name: Watermark
 type: component
 category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 水印
 ---
 
-# Watermark
+# Watermark 水印
 
 水印 — antd 独有补足。**等价 antd `Watermark`**(v5.1+)。在容器内部生成重复平铺的 SVG 水印(文字 / 图片),用于敏感页面 / 内部文档 / 演示场景。
 
@@ -24,6 +25,8 @@ package: "@teamix-evo/ui"
 - 通知 / 提示语 → `Alert` / `Tag`(语义不一样)
 - 装饰背景图 → CSS `background-image`
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -39,6 +42,8 @@ package: "@teamix-evo/ui"
 | `gapY` | `number` | `80` | – | 水印块之间的垂直间距(px)。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖