@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/sonner/sonner.stories.tsx

@@ -1,11 +1,19 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Toaster, toast } from './sonner';
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Toaster> = {
-  title: '反馈与浮层 · Feedback/Sonner',
+  title: '反馈 · Feedback/Sonner',
   component: Toaster,
   tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Toast 轻提示 —— 函数式触发的悬浮反馈,基于 [`sonner`](https://sonner.emilkowal.ski/) 包装。能力是 antd `message`(简短行内) + `notification`(标题 + 描述 + 行动)的并集:覆盖 `success` / `error` / `warning` / `info` / `loading` 五种状态,支持 `toast()` / `toast.promise()` / `action`。视觉走 OpenTrek semantic tokens —— **无边框、纯 shadow 分界、面性(filled)状态图标**,所有样式来自 `@teamix-evo/tokens`,无 mock。',
+      },
+    },
+  },
   argTypes: {
     position: {
       control: 'select',
@@ -18,23 +26,27 @@ const meta: Meta<typeof Toaster> = {
         'bottom-right',
       ],
     },
-    richColors: { control: 'boolean' },
     expand: { control: 'boolean' },
     closeButton: { control: 'boolean' },
+    visibleToasts: { control: { type: 'number', min: 1, max: 9 } },
   },
   args: {
     position: 'top-right',
-    richColors: true,
     closeButton: true,
+    expand: false,
+    visibleToasts: 5,
   },
 };
 
 export default meta;
 type Story = StoryObj<typeof Toaster>;
 
+/**
+ * Playground —— 触发不同状态的 toast,观察无边框 + 实心图标的整体节奏。
+ */
 export const Playground: Story = {
   render: (args) => (
-    <div className="flex flex-col gap-2">
+    <div className="flex flex-col items-start gap-2">
       <Toaster {...args} />
       <Button onClick={() => toast('已复制到剪贴板')}>普通</Button>
       <Button
@@ -61,6 +73,20 @@ export const Playground: Story = {
       >
         Warning
       </Button>
+      <Button
+        variant="outline"
+        onClick={() =>
+          toast.info('新功能上线', { description: '试试新版本的智能搜索。' })
+        }
+      >
+        Info
+      </Button>
+      <Button
+        variant="outline"
+        onClick={() => toast.loading('保存中...', { duration: 2000 })}
+      >
+        Loading
+      </Button>
       <Button
         variant="outline"
         onClick={() =>
@@ -89,3 +115,50 @@ export const Playground: Story = {
     </div>
   ),
 };
+
+/**
+ * 五种语义状态 —— 一次性弹出全部状态,直观对比无边框 + 浅底 + 实心图标的视觉节奏。
+ */
+export const AllStates: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => (
+    <div className="flex flex-col items-start gap-2">
+      <Toaster {...args} expand visibleToasts={9} />
+      <Button
+        onClick={() => {
+          toast.success('保存成功', { description: '所有更改已生效。' });
+          toast.error('提交失败', { description: '请检查网络后重试。' });
+          toast.warning('账号即将过期', { description: '请在 7 天内续费。' });
+          toast.info('新版本可用', { description: '建议升级到最新版本。' });
+          toast.loading('正在同步...', { duration: 6000 });
+        }}
+      >
+        弹出全部 5 种状态
+      </Button>
+    </div>
+  ),
+};
+
+/**
+ * 与 Action 行动按钮组合 —— 撤销 / 重试等可执行操作。
+ */
+export const WithAction: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => (
+    <div className="flex flex-col items-start gap-2">
+      <Toaster {...args} />
+      <Button
+        onClick={() =>
+          toast('草稿已删除', {
+            action: {
+              label: '撤销',
+              onClick: () => toast.success('已恢复草稿'),
+            },
+          })
+        }
+      >
+        删除草稿(可撤销)
+      </Button>
+    </div>
+  ),
+};

package/src/components/sonner/sonner.tsx

@@ -1,33 +1,162 @@
 import { Toaster as Sonner, type ToasterProps as SonnerProps } from 'sonner';
+import {
+  CircleCheck,
+  CircleX,
+  Info,
+  Loader2,
+  TriangleAlert,
+} from 'lucide-react';
+
+import { cn } from '@/utils/cn';
 
 /**
  * Toaster 容器 — 应用根挂一次,后续在任意地方调 `toast()` / `toast.success()` / `toast.error()` /
- * `toast.warning()` / `toast.loading()` / `toast.promise()` 等触发 toast。
+ * `toast.warning()` / `toast.info()` / `toast.loading()` / `toast.promise()` 等触发 toast。
  *
- * 默认主题跟随系统;视觉走 design tokens(`--background` / `--border` / `--foreground`)。
+ * 视觉走 design tokens —— **去边框、纯 shadow 分界、面性状态图标**:
+ *   - 卡片:`border-0` + `shadow-lg`,卡片不再有线条切割感
+ *   - 5 状态:`success` / `error` / `warning` / `info` / `loading` 都有对齐 OpenTrek 的配色与图标
+ *   - 图标:`fill-* + text-*-foreground` 实心圆/三角面性风格(基于 lucide-react)
  *
  * 来自 antd `message` + `notification` 的并集 — sonner 的 toast API 已经覆盖了:
  *   - 短文字提示(对应 message)
  *   - 标题 + 描述(对应 notification)
  *   - 操作按钮(action)
- *   - Promise 状态切换(loading → success/error)
+ *   - Promise 状态切换(loading → success / error)
  */
-export interface ToasterProps extends SonnerProps {}
+export interface ToasterProps
+  extends Omit<
+    SonnerProps,
+    | 'position'
+    | 'duration'
+    | 'visibleToasts'
+    | 'expand'
+    | 'richColors'
+    | 'closeButton'
+    | 'theme'
+    | 'dir'
+  > {
+  /**
+   * Toast 弹出位置(对齐 antd `message.config.placement`)。
+   * @default "top-right"
+   */
+  position?: SonnerProps['position'];
+  /**
+   * 自动消失时长(ms)— 0 表示常驻不自动关闭。
+   * @default 4000
+   */
+  duration?: number;
+  /**
+   * 同屏最大可见 toast 数(超出旧的自动收起)。
+   * @default 3
+   */
+  visibleToasts?: number;
+  /**
+   * 鼠标 hover 时是否展开堆叠的 toast(否则保持折叠堆叠状)。
+   * @default false
+   */
+  expand?: boolean;
+  /**
+   * 启用 sonner 自带的"丰富配色"(更高对比度的状态色背景);
+   * 关闭则走我们的视觉(对齐 OpenTrek tokens)。
+   * @default false
+   */
+  richColors?: boolean;
+  /**
+   * 每张 toast 是否显示关闭按钮(右上角 ×)。
+   * @default false
+   */
+  closeButton?: boolean;
+  /**
+   * 主题 — `'light'` / `'dark'` / `'system'`(跟随 OS 偏好)。
+   * 通常无需手传,组件会跟随 `<html>` 上的 `.dark` class 自动切换。
+   */
+  theme?: SonnerProps['theme'];
+  /**
+   * 文字方向 — `'ltr'` / `'rtl'` / `'auto'`。
+   * @default "auto"
+   */
+  dir?: SonnerProps['dir'];
+}
+
+/**
+ * 面性状态图标 —— 通过 `fill-*` 给 SVG 根元素填充语义色,
+ * 再用 `text-*-foreground` 把 currentColor 设为对比色;
+ * lucide SVG 内部 `<circle>` / `<path>` 默认 `stroke="currentColor"`,
+ * 因此环线与勾叉自动呈现高对比 foreground 颜色,得到"色块底 + 白色记号"的实心视觉。
+ */
+const filledIcons = {
+  success: (
+    <CircleCheck
+      aria-hidden
+      className="size-5 fill-success text-success-foreground"
+    />
+  ),
+  error: (
+    <CircleX
+      aria-hidden
+      className="size-5 fill-destructive text-destructive-foreground"
+    />
+  ),
+  warning: (
+    <TriangleAlert
+      aria-hidden
+      className="size-5 fill-warning text-warning-foreground"
+    />
+  ),
+  info: <Info aria-hidden className="size-5 fill-info text-info-foreground" />,
+  loading: (
+    <Loader2
+      aria-hidden
+      className="size-5 animate-spin text-muted-foreground"
+    />
+  ),
+};
 
-const Toaster = ({ ...props }: ToasterProps) => {
+const Toaster = ({ className, toastOptions, ...props }: ToasterProps) => {
   return (
     <Sonner
       theme="system"
-      className="toaster group"
+      className={cn('toaster group', className)}
+      icons={filledIcons}
       toastOptions={{
+        ...toastOptions,
         classNames: {
-          toast:
-            'group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg',
+          // 基础卡片:去边框,纯 shadow 分界,留出图标 / 文本节奏
+          toast: cn(
+            'group toast',
+            'group-[.toaster]:bg-background group-[.toaster]:text-foreground',
+            'group-[.toaster]:border-0 group-[.toaster]:shadow-lg',
+            'group-[.toaster]:rounded-md group-[.toaster]:px-4 group-[.toaster]:py-3',
+            'group-[.toaster]:gap-3',
+          ),
+          // 状态色:每种状态对应"浅底 + 同色文字",图标已在 icons 内填充实心色块
+          success: cn(
+            'group-[.toaster]:bg-success-subtle group-[.toaster]:text-success',
+          ),
+          error: cn(
+            'group-[.toaster]:bg-destructive/10 group-[.toaster]:text-destructive',
+          ),
+          warning: cn(
+            'group-[.toaster]:bg-warning-subtle group-[.toaster]:text-warning',
+          ),
+          info: cn(
+            'group-[.toaster]:bg-info-subtle group-[.toaster]:text-info',
+          ),
+          loading: cn(
+            'group-[.toaster]:bg-muted group-[.toaster]:text-foreground',
+          ),
+          // 默认 / 非状态 toast
+          default: cn(
+            'group-[.toaster]:bg-background group-[.toaster]:text-foreground',
+          ),
           description: 'group-[.toast]:text-muted-foreground',
           actionButton:
             'group-[.toast]:bg-primary group-[.toast]:text-primary-foreground',
           cancelButton:
             'group-[.toast]:bg-muted group-[.toast]:text-muted-foreground',
+          icon: 'group-[.toast]:shrink-0',
+          ...(toastOptions?.classNames ?? {}),
         },
       }}
       {...props}

package/src/components/spinner/spinner.meta.md

@@ -1,20 +1,21 @@
 ---
 id: spinner
 name: Spinner
+displayName: 加载指示器
 type: component
-category: foundation
+category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Spinner
+# Spinner 加载指示器
 
-旋转加载指示器 — shadcn 2025-10 新增,**等价 antd `Spin`**(无遮罩版)。基于 `lucide-react` 的 `Loader2`,4 档尺寸 + 4 档语义配色,自带 `role="status"` 与读屏文本。
+旋转加载指示器 — shadcn 2025-10 新增,**等价 antd `Spin`** 能力并集。核心 `Spinner` 是行内 / 局部旋转指示;配套 `SpinnerOverlay` 实现 antd `<Spin>{children}</Spin>` 的包裹遮罩形态。
 
 ## When to use
 
 - 按钮 / 表单内联 loading(`Button loading` 内部已用同一图标,这里独立 spinner 用于自定义触发器)
-- 容器局部加载(请求中)
+- 容器局部加载(请求中) — 需要遮罩时用 `SpinnerOverlay`
 - 全屏 loading 占位(`size="xl"` + 居中)
 
 ## When NOT to use
@@ -23,14 +24,22 @@ package: "@teamix-evo/ui"
 - 整页"模态阻塞 loading" → `Dialog` + Spinner 自行组合(本组件不内置遮罩)
 - 进度可知场景 → `Progress`(线形)或 `ProgressCircle`(环形)
 
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。 |
-| `tone` | `'default' \| 'muted' \| 'primary' \| 'destructive'` | `"default"` | – | 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。 |
+| `size` | `'sm' \| 'md' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 尺寸 — 与 antd Spin 的 small/middle/large 对齐(加 xl 用于全屏 loading)。 |
+| `color` | `'default' \| 'muted' \| 'primary' \| 'destructive'` | `"default"` | – | 配色 — `muted` 走次级文本色;`primary` / `destructive` 走语义色。对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md)。 |
 | `label` | `string` | – | – | 给读屏器的描述(默认 "Loading...")。 |
 <!-- auto:props:end -->
 
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成，数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -52,25 +61,65 @@ pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
 ## AI 生成纪律
 
 - **不要自己写 `<div className="animate-spin">`** — 用本组件,保留读屏可访问性
-- **`tone="primary"` 配主操作 loading**,`tone="destructive"` 仅用于真正失败回退 — 不要乱用
+- **`color="primary"` 配主操作 loading**,`color="destructive"` 仅用于真正失败回退 — 不要乱用
 - **不要给 spinner 加旋转字幕 / 进度数字** — 那是 Progress 的职责,语义不同
-- **包裹遮罩 loading**:外层加 `relative` 容器 + spinner 居中,**不要**包到本组件内部破坏其单一职责
+- **包裹遮罩场景请用 `SpinnerOverlay`** — 不要手写 `relative` + 遮罩 div,不要把遮罩逻辑塞进 `Spinner` 本体
+- **使用 SpinnerOverlay 时,外层 `className` 应控制边框 / 背景 / 圆角** — 本组件只负责 loading 的遮罩与 spinner 居中
 
 ## Examples
 
 ```tsx
-import { Spinner } from '@/components/ui/spinner';
+import { Spinner, SpinnerOverlay } from '@/components/ui/spinner';
 
 // 行内
-<span>正在保存 <Spinner size="sm" tone="muted" /></span>
+<span>正在保存 <Spinner size="sm" color="muted" /></span>
 
 // 居中
 <div className="flex h-40 items-center justify-center">
-  <Spinner size="lg" tone="primary" label="加载用户信息..." />
+  <Spinner size="lg" color="primary" label="加载用户信息..." />
 </div>
 
 // 全屏
 <div className="fixed inset-0 grid place-items-center bg-background/80 backdrop-blur-sm">
-  <Spinner size="xl" tone="primary" />
+  <Spinner size="xl" color="primary" />
 </div>
+
+// 包裹子元遮罩(antd Spin wrap children 并集)
+<SpinnerOverlay loading={isFetching} tip="加载中..." className="rounded-md border">
+  <Card>...</Card>
+</SpinnerOverlay>
 ```
+
+---
+
+## Loading 形态 — 旧库 API → 新映射
+
+> 旧库 `Loading`(hybridcloud) → 新库 `Spinner`(行内) + `SpinnerOverlay`(包裹遮罩)。
+> 新库用 lucide `Loader2` + Tailwind `animate-spin`,视觉走 OpenTrek tokens。
+
+### 命名 & 结构映射
+
+| 旧库                    | 新库                      | 说明                  |
+| ----------------------- | ------------------------- | --------------------- |
+| `Loading` (无 children) | `Spinner`                 | 行内旋转图标          |
+| `Loading` (有 children) | `SpinnerOverlay`          | 包裹遮罩加载          |
+| `visible`               | `loading`                 | prop 重命名           |
+| `size: 'small'`         | `size: 'sm'`              | 尺寸缩写              |
+| `size: 'medium'`        | `size: 'md' \| 'default'` | md = medium = default |
+| `size: 'large'`         | `size: 'lg'`              | 尺寸缩写              |
+| —                       | `size: 'xl'`              | 新增(全屏加载用)      |
+| `color='blue'`          | `color='primary'`         | 语义化                |
+| `tip`                   | `tip`                     | 保留(SpinnerOverlay)  |
+| `tipAlign='right'`      | 不复刻                    | tip 固定下方          |
+| `indicator` 自定义      | 不复刻                    | 固定 Loader2 图标     |
+| `fullScreen`            | 不复刻                    | 外层 div 自行组合     |
+| `disableScroll`         | 不复刻                    | 自行 overflow-hidden  |
+
+### 迁移 FAQ
+
+| 问题               | 回答                                                                                 |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| visible → loading? | prop 改名,语义相同(boolean)                                                          |
+| 包裹加载怎么写?    | `<SpinnerOverlay loading={flag}>{children}</SpinnerOverlay>`                         |
+| 全屏加载怎么做?    | `<div className="fixed inset-0 grid place-items-center"><Spinner size="xl" /></div>` |
+| blur 效果?         | `<SpinnerOverlay blur loading>...</SpinnerOverlay>` — 遮罩加模糊                     |

package/src/components/spinner/spinner.stories.tsx

@@ -1,26 +1,26 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import { Spinner } from './spinner';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { Spinner, SpinnerOverlay } from './spinner';
 
 const meta: Meta<typeof Spinner> = {
-  title: '基础原语 · Foundation/Spinner',
+  title: '反馈 · Feedback/Spinner',
   component: Spinner,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '旋转加载指示器 — 局部 / 行内 loading(请求中、按钮提交、占位等待)。基于 lucide Loader2,4 档尺寸 + 4 档配色,自带 role="status" 与 sr-only 读屏文案。shadcn 2025-10 新增,对齐 antd `Spin`(无遮罩版本)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '旋转加载指示器 — 局部 / 行内 loading（请求中、按钮提交、占位等待）。基于 lucide Loader2，4 档尺寸 + 4 档配色，自带 role="status" 与 sr-only 读屏文案。配套 `SpinnerOverlay` 可实现 antd `<Spin>{children}</Spin>` 的包裹遮罩形态。',
       },
     },
   },
   argTypes: {
     size: { control: 'inline-radio', options: ['sm', 'default', 'lg', 'xl'] },
-    tone: {
+    color: {
       control: 'inline-radio',
       options: ['default', 'muted', 'primary', 'destructive'],
     },
   },
-  args: { size: 'default', tone: 'default' },
+  args: { size: 'default', color: 'default' },
 };
 
 export default meta;
@@ -40,14 +40,14 @@ export const Sizes: Story = {
   ),
 };
 
-export const Tones: Story = {
+export const Colors: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <div className="flex items-center gap-6">
-      <Spinner tone="default" />
-      <Spinner tone="muted" />
-      <Spinner tone="primary" />
-      <Spinner tone="destructive" />
+      <Spinner color="default" />
+      <Spinner color="muted" />
+      <Spinner color="primary" />
+      <Spinner color="destructive" />
     </div>
   ),
 };
@@ -56,7 +56,7 @@ export const Inline: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <p className="text-sm">
-      正在保存草稿 <Spinner size="sm" tone="muted" />
+      正在保存草稿 <Spinner size="sm" color="muted" />
     </p>
   ),
 };
@@ -64,8 +64,60 @@ export const Inline: Story = {
 export const Centered: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="flex h-40 items-center justify-center rounded-md border">
-      <Spinner size="lg" tone="primary" />
+    <div className="flex h-40 items-center justify-center rounded-md border border-border">
+      <Spinner size="lg" color="primary" />
     </div>
   ),
 };
+
+// ─── SpinnerOverlay (wrap children) ─────────────────────────────────────
+
+export const OverlayBasic: StoryObj<typeof SpinnerOverlay> = {
+  name: 'Overlay · 包裹子元遮罩',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <SpinnerOverlay tip="加载中…" className="w-80 rounded-md border border-border">
+      <div className="flex flex-col gap-2 p-6">
+        <div className="text-base font-semibold">项目名称</div>
+        <p className="text-sm text-muted-foreground">
+          内容被半透明遮罩覆盖，但仍然占据原有空间，加载结束后不会抖动。
+        </p>
+        <div className="text-xs text-muted-foreground">2 小时前·北京</div>
+      </div>
+    </SpinnerOverlay>
+  ),
+};
+
+export const OverlayBlur: StoryObj<typeof SpinnerOverlay> = {
+  name: 'Overlay · 高斯模糊',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <SpinnerOverlay
+      blur
+      tip="提交中…"
+      className="w-80 rounded-md border border-border"
+    >
+      <div className="flex flex-col gap-2 p-6">
+        <div className="text-base font-semibold">提交表单</div>
+        <p className="text-sm text-muted-foreground">
+          开启 blur 后，内容会轻微模糊，强化 “不可交互” 的视觉提示。
+        </p>
+      </div>
+    </SpinnerOverlay>
+  ),
+};
+
+export const OverlayInactive: StoryObj<typeof SpinnerOverlay> = {
+  name: 'Overlay · 未加载状态',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <SpinnerOverlay loading={false} className="w-80 rounded-md border border-border">
+      <div className="flex flex-col gap-2 p-6">
+        <div className="text-base font-semibold">加载完成</div>
+        <p className="text-sm text-muted-foreground">
+          loading=false 时仅渲染 children，零额外开销。
+        </p>
+      </div>
+    </SpinnerOverlay>
+  ),
+};