@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/upload/meta.md

@@ -0,0 +1,122 @@
+# Upload
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+上传 Upload
+文件选择与上传组件。支持点击 / 拖拽两种触发形态，内置文件列表（text / image）
+与状态管理，并通过回调式 `customRequest` 与业务真实上传链路对接（含进度、abort、错误重试）。
+
+## 使用场景
+
+- 表单中需要上传附件 / 头像 / 图片
+- 批量文件导入（多选 + 数量 / 体积限制）
+- 拖拽上传区
+- 组合结构：Upload（按钮触发）/ UploadDragger（拖拽触发） — 两者共享上传状态机，可独立使用。
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `fileList` | `UploadFile[]` | – | – | 受控文件列表。 |
+| `defaultFileList` | `UploadFile[]` | – | – | 默认文件列表（非受控）。@default [] |
+| `accept` | `string` | – | – | 接受的文件类型（同 input accept）。 |
+| `multiple` | `boolean` | – | – | 是否多选。@default false |
+| `maxCount` | `number` | – | – | 最大文件数；超出触发 onLimitExceed。 |
+| `maxSize` | `number` | – | – | 单文件最大体积（字节）；超出触发 onSizeExceed 并阻止上传。 |
+| `disabled` | `boolean` | – | – | 是否禁用。@default false |
+| `listType` | `'text' \| 'image'` | – | – | 列表展示样式：text 文字行 / image 图文行（带缩略图）。@default 'text' |
+| `showFileList` | `boolean` | – | – | 是否展示文件列表。@default true |
+| `showRemoveIcon` | `boolean` | – | – | 是否显示删除按钮。@default true |
+| `beforeUpload` | `( file: File, fileList: File[], ) => boolean \| Promise<boolean \| void>` | – | – | 上传前钩子；返回 false / Promise.reject 阻止上传。 |
+| `customRequest` | `( options: UploadRequestOptions, ) => void \| { abort: () => void }` | – | – | 自定义上传实现；不传则文件入列表后停留在 pending 等待业务自行驱动。 |
+| `onChange` | `(fileList: UploadFile[], info?: UploadChangeInfo) => void` | – | – | 列表变化（含状态流转）的统一回调。 |
+| `onRemove` | `(file: UploadFile) => boolean \| Promise<boolean \| void> \| void` | – | – | 移除前钩子；返回 false / Promise<false> 阻止移除。 |
+| `onPreview` | `(file: UploadFile) => void` | – | – | 点击预览（image 列表用）。 |
+| `onLimitExceed` | `(file: File, fileList: File[]) => void` | – | – | 超出 maxCount 时调用。 |
+| `onSizeExceed` | `(file: File) => void` | – | – | 超出 maxSize 时调用。 |
+| `itemRender` | `( file: UploadFile, helpers: { remove: () => void; preview: () => void; retry: () => void }, ) => React.ReactNode` | – | – | 自定义文件项整行渲染。 |
+| `iconRender` | `(file: UploadFile) => React.ReactNode` | – | – | 自定义文件图标渲染（仅默认 itemRender 生效）。 |
+| `children` | `React.ReactNode` | – | – | 触发器内容（按钮模式）。Dragger 模式下作为提示文案的替换。 |
+| `hint` | `React.ReactNode` | – | – | 提示标题。@default '点击或拖拽文件到此区域上传' |
+| `description` | `React.ReactNode` | – | – | 副提示。 |
+
+## 示例
+
+### Drag
+
+```tsx
+<UploadDragger
+  multiple
+  customRequest={mockRequest}
+  description="支持单个或批量文件，最大 10MB"
+/>
+```
+
+### BeforeUpload
+
+```tsx
+<div className="flex flex-col gap-3">
+  <Upload beforeUpload={() => false} customRequest={mockRequest}>
+    <Button variant="outline">同步拒绝（前置阻断）</Button>
+  </Upload>
+  <Upload
+    beforeUpload={async (file) => {
+      await new Promise((r) => setTimeout(r, 600));
+      return file.size <= 5 * 1024 * 1024;
+    }}
+    customRequest={mockRequest}
+  >
+    <Button variant="outline">异步校验（≤5MB）</Button>
+  </Upload>
+</div>
+```
+
+### ItemRender
+
+```tsx
+<Upload
+  customRequest={mockRequest}
+  defaultFileList={[sampleImage, sampleDoc]}
+  itemRender={(file, { remove, preview }) => (
+    <div
+      data-slot="upload-item"
+      data-status={file.status}
+      className="flex items-center gap-2 rounded-sm border border-border bg-card px-2 py-1.5 text-xs"
+    >
+      <Paperclip className="size-3.5 text-muted-foreground" aria-hidden />
+      <span className="flex-1 truncate" title={file.name}>
+        {file.name}
+      </span>
+      <button
+        type="button"
+        aria-label="预览"
+        onClick={preview}
+        className="cursor-pointer rounded-sm p-0.5 text-muted-foreground transition-colors hover:text-foreground"
+      >
+        <Eye className="size-3" aria-hidden />
+      </button>
+      <a
+        href={file.url}
+        download={file.name}
+        target="_blank"
+        rel="noreferrer"
+        aria-label="下载"
+        className="cursor-pointer rounded-sm p-0.5 text-muted-foreground transition-colors hover:text-foreground"
+      >
+        <Download className="size-3" aria-hidden />
+      </a>
+      <button
+        type="button"
+        aria-label="移除"
+        onClick={remove}
+        className="cursor-pointer rounded-sm px-1 text-muted-foreground transition-colors hover:text-foreground"
+      >
+        移除
+      </button>
+    </div>
+  )}
+  onPreview={(file) => window.open(file.url, '_blank')}
+/>
+```

package/src/components/upload/stories.tsx

@@ -0,0 +1,261 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Download, Eye, Paperclip } from 'lucide-react';
+
+import { Upload, UploadDragger, type UploadFile } from '.';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Upload> = {
+  title: '数据录入 · Data Entry/Upload 上传',
+  component: Upload,
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof Upload>;
+
+// ─── 模拟一个有进度、可 abort 的上传请求 ─────────────────────────────────────
+const mockRequest: NonNullable<
+  React.ComponentProps<typeof Upload>['customRequest']
+> = ({ file, onProgress, onSuccess, onError }) => {
+  let percent = 0;
+  const timer = setInterval(() => {
+    percent += 10 + Math.floor(Math.random() * 15);
+    if (percent >= 100) {
+      clearInterval(timer);
+      onProgress(100);
+      // 5% 概率随机失败，便于演示错误态
+      if (Math.random() < 0.05) {
+        onError(new Error('Mock 网络错误'));
+      } else {
+        onSuccess({ ok: true }, URL.createObjectURL(file));
+      }
+    } else {
+      onProgress(percent);
+    }
+  }, 200);
+
+  return {
+    abort: () => clearInterval(timer),
+  };
+};
+
+const sampleImage: UploadFile = {
+  uid: 'sample-1',
+  name: 'IMG.png',
+  status: 'done',
+  size: 1024,
+  url: 'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg',
+  thumbUrl:
+    'https://img.alicdn.com/tps/TB19O79MVXXXXcZXVXXXXXXXXXX-1024-1024.jpg',
+};
+
+const sampleDoc: UploadFile = {
+  uid: 'sample-2',
+  name: 'design-spec.pdf',
+  status: 'done',
+  size: 1024 * 580,
+  url: 'https://example.com/design-spec.pdf',
+};
+
+// ─── Stories ────────────────────────────────────────────────────────────────
+
+export const Basic: Story = {
+  name: '基础',
+  args: {
+    customRequest: mockRequest,
+    defaultFileList: [sampleDoc],
+  },
+};
+
+export const Drag: Story = {
+  name: '拖拽上传',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <UploadDragger
+      multiple
+      customRequest={mockRequest}
+      description="支持单个或批量文件，最大 10MB"
+    />
+  ),
+};
+
+export const ImageList: Story = {
+  name: '图文列表',
+  args: {
+    listType: 'image',
+    multiple: true,
+    accept: 'image/*',
+    customRequest: mockRequest,
+    defaultFileList: [
+      sampleImage,
+      {
+        uid: 'sample-3',
+        name: 'cover.jpg',
+        status: 'uploading',
+        percent: 40,
+        thumbUrl:
+          'https://img.alicdn.com/tfs/TB1x4QlgxYaK1RjSZFnXXa80pXa-1400-742.png',
+      },
+      {
+        uid: 'sample-4',
+        name: 'broken.png',
+        status: 'error',
+        error: new Error('上传失败'),
+      },
+    ],
+  },
+};
+
+export const Multiple: Story = {
+  name: '多选 + 限定类型',
+  args: {
+    multiple: true,
+    accept: 'image/*',
+    customRequest: mockRequest,
+  },
+};
+
+export const MaxCountAndSize: Story = {
+  name: '限制数量与体积',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [hint, setHint] = React.useState<string>('');
+    return (
+      <div className="flex flex-col gap-2">
+        <Upload
+          multiple
+          maxCount={3}
+          maxSize={2 * 1024 * 1024}
+          customRequest={mockRequest}
+          onLimitExceed={(file) =>
+            setHint(`已超出最大数量 (3)，已忽略 ${file.name}`)
+          }
+          onSizeExceed={(file) => setHint(`${file.name} 超过 2MB 体积限制`)}
+        />
+        {hint ? (
+          <span className="text-xs text-destructive">{hint}</span>
+        ) : (
+          <span className="text-xs text-muted-foreground">
+            最多 3 个文件，单文件 ≤ 2MB
+          </span>
+        )}
+      </div>
+    );
+  },
+};
+
+export const BeforeUpload: Story = {
+  name: '上传前校验',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-3">
+      <Upload beforeUpload={() => false} customRequest={mockRequest}>
+        <Button variant="outline">同步拒绝（前置阻断）</Button>
+      </Upload>
+      <Upload
+        beforeUpload={async (file) => {
+          await new Promise((r) => setTimeout(r, 600));
+          return file.size <= 5 * 1024 * 1024;
+        }}
+        customRequest={mockRequest}
+      >
+        <Button variant="outline">异步校验（≤5MB）</Button>
+      </Upload>
+    </div>
+  ),
+};
+
+export const CustomRequest: Story = {
+  name: '自定义上传（进度与中断）',
+  args: {
+    multiple: true,
+    customRequest: mockRequest,
+  },
+};
+
+export const Controlled: Story = {
+  name: '受控',
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [fileList, setFileList] = React.useState<UploadFile[]>([sampleDoc]);
+    return (
+      <div className="flex flex-col gap-2">
+        <Upload
+          fileList={fileList}
+          onChange={(next) => setFileList(next)}
+          customRequest={mockRequest}
+        />
+        <div className="flex items-center gap-2">
+          <Button variant="outline" onClick={() => setFileList([sampleDoc])}>
+            重置
+          </Button>
+          <Button variant="outline" onClick={() => setFileList([])}>
+            清空
+          </Button>
+          <span className="text-xs text-muted-foreground">
+            当前 {fileList.length} 个文件
+          </span>
+        </div>
+      </div>
+    );
+  },
+};
+
+export const Disabled: Story = {
+  name: '禁用',
+  args: {
+    disabled: true,
+    defaultFileList: [sampleDoc],
+  },
+};
+
+export const ItemRender: Story = {
+  name: '自定义文件项',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Upload
+      customRequest={mockRequest}
+      defaultFileList={[sampleImage, sampleDoc]}
+      itemRender={(file, { remove, preview }) => (
+        <div
+          data-slot="upload-item"
+          data-status={file.status}
+          className="flex items-center gap-2 rounded-sm border border-border bg-card px-2 py-1.5 text-xs"
+        >
+          <Paperclip className="size-3.5 text-muted-foreground" aria-hidden />
+          <span className="flex-1 truncate" title={file.name}>
+            {file.name}
+          </span>
+          <button
+            type="button"
+            aria-label="预览"
+            onClick={preview}
+            className="cursor-pointer rounded-sm p-0.5 text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <Eye className="size-3" aria-hidden />
+          </button>
+          <a
+            href={file.url}
+            download={file.name}
+            target="_blank"
+            rel="noreferrer"
+            aria-label="下载"
+            className="cursor-pointer rounded-sm p-0.5 text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <Download className="size-3" aria-hidden />
+          </a>
+          <button
+            type="button"
+            aria-label="移除"
+            onClick={remove}
+            className="cursor-pointer rounded-sm px-1 text-muted-foreground transition-colors hover:text-foreground"
+          >
+            移除
+          </button>
+        </div>
+      )}
+      onPreview={(file) => window.open(file.url, '_blank')}
+    />
+  ),
+};

package/src/components/watermark/index.tsx

@@ -0,0 +1,152 @@
+/* eslint-disable teamix-evo/no-color-literal -- Watermark renders to SVG data URL; CSS var() not supported. Default matches --overlay-watermark token. */
+/**
+ * 水印 Watermark
+ *
+ * 在容器内生成重复平铺的 SVG 水印（文字 / 图片），用于敏感页面防截图标识。
+ *
+ * @when
+ * - 内部文档 / 管理后台需要溯源标识
+ * - 演示环境需要标注"仅供内部使用"
+ * - 合规要求页面带用户身份水印
+ */
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+interface WatermarkProps extends Omit<React.ComponentProps<'div'>, 'content'> {
+  /** 水印文字 — 单行字符串或多行数组。 */
+  content?: string | string[];
+  /** 水印图片 — 优先级高于 `content`，建议透明 PNG / SVG。 */
+  image?: string;
+  /** 单块水印宽度（px）。@default 120 */
+  width?: number;
+  /** 单块水印高度（px）。@default 64 */
+  height?: number;
+  /** 旋转角度（deg）。@default -22 */
+  rotate?: number;
+  /** 字体大小（px）。@default 14 */
+  fontSize?: number;
+  /** 字体颜色（支持 rgba 透明度）。@default "rgba(0,0,0,0.15)" */
+  fontColor?: string;
+  /** 字体粗细。@default "normal" */
+  fontWeight?: 'normal' | 'medium' | 'bold';
+  /** 水平间距（px）。@default 80 */
+  gapX?: number;
+  /** 垂直间距（px）。@default 80 */
+  gapY?: number;
+}
+
+function buildSvg(opts: {
+  content?: string | string[];
+  image?: string;
+  width: number;
+  height: number;
+  rotate: number;
+  fontSize: number;
+  fontColor: string;
+  fontWeight: 'normal' | 'medium' | 'bold';
+  gapX: number;
+  gapY: number;
+}): string {
+  const w = opts.width + opts.gapX;
+  const h = opts.height + opts.gapY;
+  const cx = w / 2;
+  const cy = h / 2;
+  const fontWeightValue =
+    opts.fontWeight === 'bold' ? 700 : opts.fontWeight === 'medium' ? 500 : 400;
+
+  let body = '';
+  if (opts.image) {
+    body = `<image href="${opts.image}" x="${cx - opts.width / 2}" y="${
+      cy - opts.height / 2
+    }" width="${opts.width}" height="${opts.height}" transform="rotate(${
+      opts.rotate
+    } ${cx} ${cy})" />`;
+  } else if (opts.content) {
+    const lines = Array.isArray(opts.content) ? opts.content : [opts.content];
+    const lineHeight = opts.fontSize * 1.4;
+    const totalH = lineHeight * (lines.length - 1);
+    body = `<g transform="rotate(${opts.rotate} ${cx} ${cy})" fill="${
+      opts.fontColor
+    }" font-size="${
+      opts.fontSize
+    }" font-weight="${fontWeightValue}" font-family="system-ui, sans-serif" text-anchor="middle">${lines
+      .map(
+        (line, i) =>
+          `<text x="${cx}" y="${cy - totalH / 2 + i * lineHeight}">${line
+            .replace(/&/g, '&amp;')
+            .replace(/</g, '&lt;')
+            .replace(/>/g, '&gt;')}</text>`,
+      )
+      .join('')}</g>`;
+  }
+
+  return `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}">${body}</svg>`,
+  )}`;
+}
+
+function Watermark({
+  content,
+  image,
+  width = 120,
+  height = 64,
+  rotate = -22,
+  fontSize = 14,
+  fontColor = 'rgba(0,0,0,0.15)',
+  fontWeight = 'normal',
+  gapX = 80,
+  gapY = 80,
+  className,
+  children,
+  ...props
+}: WatermarkProps) {
+  const dataUrl = React.useMemo(
+    () =>
+      buildSvg({
+        content,
+        image,
+        width,
+        height,
+        rotate,
+        fontSize,
+        fontColor,
+        fontWeight,
+        gapX,
+        gapY,
+      }),
+    [
+      content,
+      image,
+      width,
+      height,
+      rotate,
+      fontSize,
+      fontColor,
+      fontWeight,
+      gapX,
+      gapY,
+    ],
+  );
+
+  return (
+    <div
+      data-slot="watermark"
+      className={cn('relative isolate', className)}
+      {...props}
+    >
+      {children}
+      <div
+        aria-hidden="true"
+        className="pointer-events-none absolute inset-0 select-none"
+        style={{
+          backgroundImage: `url("${dataUrl}")`,
+          backgroundRepeat: 'repeat',
+        }}
+      />
+    </div>
+  );
+}
+
+export { Watermark };
+export type { WatermarkProps };

package/src/components/watermark/meta.md

@@ -0,0 +1,67 @@
+# Watermark
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+水印 Watermark
+在容器内生成重复平铺的 SVG 水印（文字 / 图片），用于敏感页面防截图标识。
+
+## 使用场景
+
+- 内部文档 / 管理后台需要溯源标识
+- 演示环境需要标注"仅供内部使用"
+- 合规要求页面带用户身份水印
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `content` | `string \| string[]` | – | – | 水印文字 — 单行字符串或多行数组。 |
+| `image` | `string` | – | – | 水印图片 — 优先级高于 `content`，建议透明 PNG / SVG。 |
+| `width` | `number` | – | – | 单块水印宽度（px）。@default 120 |
+| `height` | `number` | – | – | 单块水印高度（px）。@default 64 |
+| `rotate` | `number` | – | – | 旋转角度（deg）。@default -22 |
+| `fontSize` | `number` | – | – | 字体大小（px）。@default 14 |
+| `fontColor` | `string` | – | – | 字体颜色（支持 rgba 透明度）。@default "rgba(0,0,0,0.15)" |
+| `fontWeight` | `'normal' \| 'medium' \| 'bold'` | – | – | 字体粗细。@default "normal" |
+| `gapX` | `number` | – | – | 水平间距（px）。@default 80 |
+| `gapY` | `number` | – | – | 垂直间距（px）。@default 80 |
+
+## 示例
+
+### Basic
+
+```tsx
+<Watermark content="Teamix Evo">
+  <div className="h-48 rounded-md border border-border p-4">
+    <p className="text-xs text-muted-foreground">
+      这里是被水印覆盖的内容区域
+    </p>
+  </div>
+</Watermark>
+```
+
+### MultiLine
+
+```tsx
+<Watermark content={['Teamix Evo', '2026-06-08']}>
+  <div className="h-48 rounded-md border border-border p-4">
+    <p className="text-xs text-muted-foreground">
+      支持传入字符串数组实现多行水印
+    </p>
+  </div>
+</Watermark>
+```
+
+### CustomStyle
+
+```tsx
+<Watermark content="机密" fontSize={20} rotate={-30} gapX={120} gapY={120}>
+  <div className="h-48 rounded-md border border-border p-4">
+    <p className="text-xs text-muted-foreground">
+      自定义字号、旋转角度和间距
+    </p>
+  </div>
+</Watermark>
+```

package/src/components/watermark/stories.tsx

@@ -0,0 +1,59 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Watermark } from '.';
+
+const meta: Meta<typeof Watermark> = {
+  title: '布局 · Layout/Watermark 水印',
+  component: Watermark,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '水印 — 在页面区域覆盖不可选的文本水印，用于版权声明或信息安全溯源。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Watermark>;
+
+export const Basic: Story = {
+  name: '基础水印',
+  render: () => (
+    <Watermark content="Teamix Evo">
+      <div className="h-48 rounded-md border border-border p-4">
+        <p className="text-xs text-muted-foreground">
+          这里是被水印覆盖的内容区域
+        </p>
+      </div>
+    </Watermark>
+  ),
+};
+
+export const MultiLine: Story = {
+  name: '多行水印',
+  render: () => (
+    <Watermark content={['Teamix Evo', '2026-06-08']}>
+      <div className="h-48 rounded-md border border-border p-4">
+        <p className="text-xs text-muted-foreground">
+          支持传入字符串数组实现多行水印
+        </p>
+      </div>
+    </Watermark>
+  ),
+};
+
+export const CustomStyle: Story = {
+  name: '自定义样式',
+  render: () => (
+    <Watermark content="机密" fontSize={20} rotate={-30} gapX={120} gapY={120}>
+      <div className="h-48 rounded-md border border-border p-4">
+        <p className="text-xs text-muted-foreground">
+          自定义字号、旋转角度和间距
+        </p>
+      </div>
+    </Watermark>
+  ),
+};

package/src/hooks/use-mobile.ts

@@ -2,22 +2,20 @@ import * as React from 'react';
 
 const MOBILE_BREAKPOINT = 768;
 
-/**
- * 检测视口是否处于移动尺寸(< 768px) — Sidebar 复合组件在 mobile 模式下
- * 切换为 Sheet 抽屉的判定依据。
- *
- * 服务端渲染场景下首次返回 `false`,客户端 hydrate 后基于 matchMedia 实时同步。
- */
-export function useIsMobile(): boolean {
-  const [isMobile, setIsMobile] = React.useState<boolean>(false);
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(
+    undefined,
+  );
 
   React.useEffect(() => {
     const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
-    const onChange = () => setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    };
     mql.addEventListener('change', onChange);
-    onChange();
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
     return () => mql.removeEventListener('change', onChange);
   }, []);
 
-  return isMobile;
+  return !!isMobile;
 }