@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Watermark } from './watermark';
 
 const meta: Meta<typeof Watermark> = {
-  title: '反馈与浮层 · Feedback/Watermark',
+  title: '反馈 · Feedback/Watermark',
   component: Watermark,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '水印 — 容器内重复平铺的 SVG 文字 / 图片水印(内部敏感页面 / 文档预览 / demo 录屏)。前端视觉效果,不作为安全防护。等价 antd `Watermark`(v5.1+)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '水印 —— 在容器内重复平铺 SVG 文字 / 图片水印,用于内部敏感页面、文档预览、设计稿评审、demo 录屏等"威慑泄露"场景。antd 独有补足,等价 antd `Watermark`(v5.1+):`content`(单行 / 多行字符串)、`image`(优先级高于 content)、`width` / `height` 单块尺寸、`gapX` / `gapY` 平铺间距、`rotate` 旋转角度(默认 -22°)、`fontSize` / `fontColor` / `fontWeight` 文字样式。**前端视觉效果 ≠ 安全防护**,真正合规需要服务端水印 + 数字签名。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -17,6 +17,7 @@ const meta: Meta<typeof Watermark> = {
     content: { control: 'text' },
     rotate: { control: { type: 'number', min: -90, max: 90 } },
     fontSize: { control: { type: 'number', min: 8, max: 48 } },
+    fontWeight: { control: 'inline-radio', options: ['normal', 'medium', 'bold'] },
     gapX: { control: 'number' },
     gapY: { control: 'number' },
   },
@@ -24,6 +25,7 @@ const meta: Meta<typeof Watermark> = {
     content: 'Acme Corp · CONFIDENTIAL',
     rotate: -22,
     fontSize: 14,
+    fontWeight: 'normal',
     gapX: 80,
     gapY: 80,
   },
@@ -33,8 +35,16 @@ export default meta;
 type Story = StoryObj<typeof Watermark>;
 
 export const Playground: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '基础文字水印 —— 单行 `content` + 默认 `-22°` 旋转,常用于"公司名 · 机密"等场景。',
+      },
+    },
+  },
   render: (args) => (
-    <Watermark {...args} className="h-72 w-full rounded-md border bg-card p-6">
+    <Watermark {...args} className="h-72 w-full rounded-md border border-border bg-card p-6">
       <h3 className="mb-3 text-lg font-semibold">内部文档</h3>
       <p className="text-sm text-muted-foreground">
         这是一段示例文档内容。水印铺在底层,内容可正常交互。
@@ -45,11 +55,19 @@ export const Playground: Story = {
 };
 
 export const MultilineUser: Story = {
-  parameters: { controls: { disable: true } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '多行水印 —— `content` 传字符串数组渲染成两行(用户名 + 工号),起到"截图即追溯"的威慑作用。',
+      },
+    },
+  },
   render: () => (
     <Watermark
       content={['Alice Wong', 'EMP-2026-001']}
-      className="h-72 w-full rounded-md border bg-card p-6"
+      className="h-72 w-full rounded-md border border-border bg-card p-6"
     >
       <h3 className="mb-3 text-lg font-semibold">用户信息水印</h3>
       <p className="text-sm text-muted-foreground">
@@ -59,8 +77,53 @@ export const MultilineUser: Story = {
   ),
 };
 
+export const ImageWatermark: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '图片水印 —— `image` 传 data URL 或 URL,优先级高于 `content`。建议透明 PNG / SVG,否则会出现矩形背景。',
+      },
+    },
+  },
+  render: () => {
+    // 一个简单的内联 SVG 标识,用作水印图片。
+    const svg = encodeURIComponent(
+      '<svg xmlns="http://www.w3.org/2000/svg" width="80" height="40" viewBox="0 0 80 40">' +
+        '<rect x="2" y="2" width="76" height="36" rx="6" fill="none" stroke="rgba(0,0,0,0.25)" stroke-width="1.5"/>' +
+        '<text x="40" y="26" text-anchor="middle" font-family="system-ui" font-size="14" font-weight="600" fill="rgba(0,0,0,0.25)">EVO</text>' +
+        '</svg>',
+    );
+    const dataUrl = `data:image/svg+xml;utf8,${svg}`;
+    return (
+      <Watermark
+        image={dataUrl}
+        width={80}
+        height={40}
+        gapX={60}
+        gapY={60}
+        className="h-72 w-full rounded-md border border-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 } },
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '自定义样式 —— 通过 `fontColor`(带 alpha)、`fontWeight`、`gapX/Y`、`rotate` 调整视觉强度,适配不同重要级别的页面。',
+      },
+    },
+  },
   render: () => (
     <Watermark
       content="内部资料"
@@ -69,10 +132,39 @@ export const ColoredAndDense: Story = {
       gapX={60}
       gapY={60}
       rotate={-30}
-      className="h-72 w-full rounded-md border bg-card p-6"
+      className="h-72 w-full rounded-md border border-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>
+      <p className="text-sm text-muted-foreground">
+        配合 fontWeight / gap / rotate 调整视觉强度。
+      </p>
+    </Watermark>
+  ),
+};
+
+export const SparseLayout: Story = {
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          '稀疏布局 —— 增大 `gapX` / `gapY` 让水印块之间留更多空白,适合阅读类页面。',
+      },
+    },
+  },
+  render: () => (
+    <Watermark
+      content="DRAFT"
+      gapX={160}
+      gapY={140}
+      fontSize={18}
+      className="h-72 w-full rounded-md border border-border bg-card p-6"
+    >
+      <h3 className="mb-3 text-lg font-semibold">长文档预览</h3>
+      <p className="text-sm leading-7 text-muted-foreground">
+        这是一份还未定稿的文档。稀疏的 DRAFT 水印不会过度干扰阅读,
+        但能在截图中清晰地传达"非正式版本"的状态。
+      </p>
     </Watermark>
   ),
 };

package/src/components/watermark/watermark.tsx

@@ -112,6 +112,7 @@ const Watermark = React.forwardRef<HTMLDivElement, WatermarkProps>(
       height = 64,
       rotate = -22,
       fontSize = 14,
+      // eslint-disable-next-line teamix-evo/no-color-literal -- Watermark renders to canvas; CSS var() not supported in canvas API. Default value matches --overlay-watermark token.
       fontColor = 'rgba(0,0,0,0.15)',
       fontWeight = 'normal',
       gapX = 80,

package/src/hooks/use-breakpoint.ts

@@ -0,0 +1,117 @@
+import * as React from 'react';
+
+/**
+ * 响应式断点 5 档 — 对齐《Teamix UI 表单设计规范》§4.1。
+ * CSS 真值见 `@teamix-evo/tokens` 的 `--bp-*` 变量(theme.css)。
+ */
+export type Breakpoint = 'xs' | 's' | 'm' | 'l' | 'xl';
+
+export const BREAKPOINTS: Record<Breakpoint, number> = {
+  xs: 432,
+  s: 672,
+  m: 944,
+  l: 1200,
+  xl: 1600,
+};
+
+const ORDER: Breakpoint[] = ['xl', 'l', 'm', 's', 'xs'];
+
+function resolveCurrent(width: number): Breakpoint | null {
+  for (const bp of ORDER) {
+    if (width >= BREAKPOINTS[bp]) return bp;
+  }
+  return null;
+}
+
+/**
+ * 检测当前视口落在哪一档断点上。
+ *
+ * 返回 ≤ viewport 的最大档位(`viewport ≥ 1600` → `xl`;`viewport < 432` → `null`)。
+ *
+ * 服务端渲染场景下首次返回 `null`,客户端 hydrate 后基于 `matchMedia` 实时同步。
+ *
+ * @example
+ * ```tsx
+ * const bp = useBreakpoint();
+ * const orientation = bp === null ? 'vertical' : 'horizontal';
+ * ```
+ */
+export function useBreakpoint(): Breakpoint | null {
+  const [current, setCurrent] = React.useState<Breakpoint | null>(null);
+
+  React.useEffect(() => {
+    const update = () => setCurrent(resolveCurrent(window.innerWidth));
+    update();
+
+    const queries = ORDER.map((bp) => {
+      const mql = window.matchMedia(`(min-width: ${BREAKPOINTS[bp]}px)`);
+      mql.addEventListener('change', update);
+      return mql;
+    });
+
+    return () => {
+      for (const mql of queries) mql.removeEventListener('change', update);
+    };
+  }, []);
+
+  return current;
+}
+
+/**
+ * 响应式值 — 标量或断点映射对象。`base` 槽是兜底(没有任何断点匹配时使用)。
+ *
+ * @example
+ * ```ts
+ * const orientation: ResponsiveValue<'vertical' | 'horizontal'> = {
+ *   base: 'vertical',  // < 432
+ *   xs: 'horizontal',  // ≥ 432
+ * };
+ * ```
+ */
+export type ResponsiveValue<T> =
+  | T
+  | (Partial<Record<Breakpoint, T>> & { base?: T });
+
+function isResponsiveObject<T>(
+  value: ResponsiveValue<T>,
+): value is Partial<Record<Breakpoint, T>> & { base?: T } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !React.isValidElement(value as React.ReactNode)
+  );
+}
+
+/**
+ * 从响应式值中挑选适合当前断点的真值。
+ *
+ * 解析规则(级联回退):
+ *   `current` → 下移到 ≤ current 的最大档位 → ... → `base` → `undefined`
+ *
+ * 例:`current='m'`,值为 `{ base: 1, xs: 2, m: 3 }`,返回 `3`;
+ *     `current='s'`,值同上,返回 `2`(xs 是 s 之下的最大档位);
+ *     `current=null`,值同上,返回 `1`(base 兜底)。
+ *
+ * 传入标量时原样返回,不做断点匹配。
+ */
+export function pickByBreakpoint<T>(
+  value: ResponsiveValue<T> | undefined,
+  current: Breakpoint | null,
+): T | undefined {
+  if (value === undefined) return undefined;
+  if (!isResponsiveObject(value)) return value as T;
+
+  const map = value as Partial<Record<Breakpoint, T>> & { base?: T };
+
+  if (current === null) return map.base;
+
+  // 从 current 档位往下回退,找到第一个定义过的值
+  const startIdx = ORDER.indexOf(current);
+  for (let i = startIdx; i < ORDER.length; i++) {
+    const bp = ORDER[i]!;
+    const v = map[bp];
+    if (v !== undefined) return v;
+  }
+  return map.base;
+}

package/src/hooks/use-debounce-callback.ts

@@ -0,0 +1,52 @@
+import * as React from 'react';
+
+/**
+ * 防抖回调 hook — 返回一个防抖包装后的函数,在指定 `delay` 毫秒内
+ * 连续调用只会执行最后一次。适用于搜索输入、筛选变更等高频场景。
+ *
+ * @param callback - 需要防抖的回调函数
+ * @param delay - 防抖延迟(ms)
+ * @default delay 300
+ *
+ * @example
+ * ```tsx
+ * const debouncedSearch = useDebounceCallback((value: string) => {
+ *   fetchResults(value);
+ * }, 300);
+ * ```
+ */
+export function useDebounceCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  delay: number = 300,
+): (...args: Parameters<T>) => void {
+  const callbackRef = React.useRef(callback);
+  const timerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // 始终持有最新 callback 引用,避免闭包陈旧
+  React.useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  // 组件卸载时清除 timer
+  React.useEffect(() => {
+    return () => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+    };
+  }, []);
+
+  const debouncedFn = React.useCallback(
+    (...args: Parameters<T>) => {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+      }
+      timerRef.current = setTimeout(() => {
+        callbackRef.current(...args);
+      }, delay);
+    },
+    [delay],
+  );
+
+  return debouncedFn;
+}

package/src/hooks/use-mobile.ts

@@ -0,0 +1,23 @@
+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);
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+    const onChange = () => setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+    mql.addEventListener('change', onChange);
+    onChange();
+    return () => mql.removeEventListener('change', onChange);
+  }, []);
+
+  return isMobile;
+}