@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/sonner/index.tsx

@@ -0,0 +1,149 @@
+/**
+ * 轻提示 Toast (Sonner)
+ *
+ * 等价 cloud-design Notification + Message 弹窗便捷用法的并集：通过 `toast()` 函数式 API
+ * 触发非侵入式悬浮反馈，支持 success / info / warning / error / loading + help（自定义图标）
+ * 五档语义状态、placement 容器级位置、按 id 更新与关闭、action / cancel 操作区、promise 链式更新、
+ * 自定义渲染等业界流行能力。
+ *
+ * @when
+ * - 操作完成后的轻量反馈（成功 / 失败 / 警告 / 提示）
+ * - 长任务进度推送（loading → success / error 链式更新）
+ * - 系统主动通知，附带"撤销 / 详情"等下一步行动点
+ *
+ * @see https://sonner.emilkowal.ski/
+ *
+ * 组合关系：业务侧只需挂一次 `<Toaster />` 容器，全局通过 `toast(...)` 触发。
+ */
+import * as React from 'react';
+import {
+  Toaster as SonnerToaster,
+  toast,
+  type ToasterProps as SonnerToasterProps,
+} from 'sonner';
+import {
+  CircleCheckIcon,
+  CircleHelpIcon,
+  InfoIcon,
+  Loader2Icon,
+  OctagonXIcon,
+  TriangleAlertIcon,
+} from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+/**
+ * 容器级摆放位置 — cloud-design Notification.config({ placement }) 的 6 档形态。
+ * 内部映射为 sonner 原生 `position` 字段；保留独立命名是为了与项目其它组件的 `placement` 命名风格一致。
+ */
+export type ToasterPlacement =
+  | 'top-left'
+  | 'top-right'
+  | 'top-center'
+  | 'bottom-left'
+  | 'bottom-right'
+  | 'bottom-center';
+
+export interface ToasterProps
+  extends Omit<SonnerToasterProps, 'position' | 'visibleToasts'> {
+  /** 弹出位置，默认 `top-right`（对齐 cloud-design Notification 默认 tr） */
+  placement?: ToasterPlacement;
+  /** 同屏最多可见数量，超出进入堆叠队列；默认 `3`（对齐 cloud-design Notification.config.maxCount 常用值） */
+  maxToasts?: number;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── */
+/* 内置状态图标（占位）                                                        */
+/*                                                                            */
+/* TODO(icon): 项目自研 Icon 组件就绪后，统一替换以下 STATE_ICONS 即可，         */
+/*             不影响 Toaster / toast 的 API。                                 */
+/* ────────────────────────────────────────────────────────────────────────── */
+const STATE_ICONS = {
+  success: <CircleCheckIcon className="size-4 shrink-0 text-success" />,
+  info: <InfoIcon className="size-4 shrink-0 text-info" />,
+  warning: <TriangleAlertIcon className="size-4 shrink-0 text-warning" />,
+  error: <OctagonXIcon className="size-4 shrink-0 text-destructive" />,
+  loading: (
+    <Loader2Icon className="size-4 shrink-0 animate-spin text-muted-foreground" />
+  ),
+};
+
+/**
+ * `help` 状态在 sonner 原生类型中不存在，作为业界常见第六档语义保留。
+ * 业务侧通过 `toast(msg, { icon: HelpToastIcon })` 触发，或参考 stories 演示。
+ */
+export const HelpToastIcon = (
+  <CircleHelpIcon className="size-4 shrink-0 text-help" />
+);
+
+function Toaster({
+  theme,
+  placement = 'top-right',
+  maxToasts = 3,
+  duration = 4500,
+  expand = false,
+  closeButton = true,
+  richColors = false,
+  className,
+  style,
+  toastOptions,
+  icons,
+  ...props
+}: ToasterProps) {
+  return (
+    <SonnerToaster
+      data-slot="sonner-toaster"
+      theme={theme as SonnerToasterProps['theme']}
+      position={placement}
+      visibleToasts={maxToasts}
+      duration={duration}
+      expand={expand}
+      closeButton={closeButton}
+      richColors={richColors}
+      icons={{ ...STATE_ICONS, ...icons }}
+      className={cn('toaster group', className)}
+      style={
+        {
+          // 容器与文字基础变量 — 沿用主题语义 token，dark 自动跟随
+          '--normal-bg': 'var(--popover)',
+          '--normal-text': 'var(--popover-foreground)',
+          '--normal-border': 'var(--border)',
+          '--border-radius': 'var(--radius)',
+          // 状态变量桥接 — 开启 richColors 时由 sonner 消费
+          '--success-bg': 'var(--success-bg)',
+          '--success-text': 'var(--success)',
+          '--success-border': 'var(--success-border)',
+          '--info-bg': 'var(--info-bg)',
+          '--info-text': 'var(--info)',
+          '--info-border': 'var(--info-border)',
+          '--warning-bg': 'var(--warning-bg)',
+          '--warning-text': 'var(--warning)',
+          '--warning-border': 'var(--warning-border)',
+          '--error-bg': 'var(--destructive-bg)',
+          '--error-text': 'var(--destructive)',
+          '--error-border': 'var(--destructive-border)',
+          ...style,
+        } as React.CSSProperties
+      }
+      toastOptions={{
+        ...toastOptions,
+        classNames: {
+          toast:
+            'group toast group-[.toaster]:bg-popover group-[.toaster]:text-popover-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg',
+          title: 'text-sm font-medium leading-5 text-foreground',
+          description: 'text-xs leading-5 text-muted-foreground',
+          actionButton:
+            'group-[.toast]:bg-primary group-[.toast]:text-primary-foreground group-[.toast]:rounded-sm group-[.toast]:text-xs group-[.toast]:px-2 group-[.toast]:py-1 group-[.toast]:cursor-pointer hover:group-[.toast]:bg-primary/90',
+          cancelButton:
+            'group-[.toast]:bg-muted group-[.toast]:text-muted-foreground group-[.toast]:rounded-sm group-[.toast]:text-xs group-[.toast]:px-2 group-[.toast]:py-1 group-[.toast]:cursor-pointer hover:group-[.toast]:bg-muted/80',
+          closeButton:
+            'group-[.toast]:bg-transparent group-[.toast]:text-muted-foreground group-[.toast]:border-border hover:group-[.toast]:text-foreground',
+          ...toastOptions?.classNames,
+        },
+      }}
+      {...props}
+    />
+  );
+}
+
+export { Toaster, toast };

package/src/components/sonner/meta.md

@@ -0,0 +1,156 @@
+# Toaster
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+轻提示 Toast (Sonner)
+等价 cloud-design Notification + Message 弹窗便捷用法的并集：通过 `toast()` 函数式 API
+触发非侵入式悬浮反馈，支持 success / info / warning / error / loading + help（自定义图标）
+五档语义状态、placement 容器级位置、按 id 更新与关闭、action / cancel 操作区、promise 链式更新、
+自定义渲染等业界流行能力。
+
+## 使用场景
+
+- 操作完成后的轻量反馈（成功 / 失败 / 警告 / 提示）
+- 长任务进度推送（loading → success / error 链式更新）
+- 系统主动通知，附带"撤销 / 详情"等下一步行动点
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `placement` | `ToasterPlacement` | – | – | 弹出位置，默认 `top-right`（对齐 cloud-design Notification 默认 tr） |
+| `maxToasts` | `number` | – | – | 同屏最多可见数量，超出进入堆叠队列；默认 `3`（对齐 cloud-design Notification.config.maxCount 常用值） |
+
+## 示例
+
+### WithTitleAndDescription
+
+标题 + 描述 — 对应 cloud-design `Notification.open({ title, content })`。
+
+```tsx
+<Button
+  onClick={() =>
+    toast('文件已保存', {
+      description: '你的修改已自动同步到云端，可在历史版本中找回。',
+    })
+  }
+>
+  触发
+</Button>
+```
+
+### WithAction
+
+操作按钮 — 业内主流 `action` props，单击执行下一步行动并关闭。
+
+```tsx
+<Button
+  onClick={() =>
+    toast('已删除项目「示例」', {
+      description: '删除后 7 天内可在回收站恢复。',
+      action: {
+        label: '撤销',
+        onClick: () => toast.success('已撤销删除'),
+      },
+    })
+  }
+>
+  触发
+</Button>
+```
+
+### WithCancel
+
+取消按钮 — 与 action 并存的次级行动点，可阻断默认行为。
+
+```tsx
+<Button
+  onClick={() =>
+    toast('确认离开当前页面？', {
+      description: '未保存的修改将丢失。',
+      action: { label: '继续', onClick: () => toast.info('已继续') },
+      cancel: { label: '取消', onClick: () => toast('已取消') },
+    })
+  }
+>
+  触发
+</Button>
+```
+
+### LoadingThenResolve
+
+按 id 链式更新 — 等价 cloud-design `Message.loading + Message.success({ key })`。
+
+```tsx
+<Button
+  onClick={() => {
+    const id = toast.loading('正在上传...');
+    setTimeout(() => {
+      toast.success('上传完成', {
+        id,
+        description: '文件已发布到生产环境。',
+      });
+    }, 1500);
+  }}
+>
+  触发
+</Button>
+```
+
+### Duration
+
+持续时长 — `duration` 控制关闭延迟，`Infinity` 持久不关。对应 cloud-design `duration: 0`。
+
+```tsx
+<div className="flex flex-wrap gap-2">
+  <Button onClick={() => toast('1.5 秒后关闭', { duration: 1500 })}>
+    短 (1.5s)
+  </Button>
+  <Button onClick={() => toast('8 秒后关闭', { duration: 8000 })}>
+    长 (8s)
+  </Button>
+  <Button
+    onClick={() =>
+      toast('持久通知', {
+        description: '需要手动关闭，等价 cloud-design duration:0。',
+        duration: Infinity,
+      })
+    }
+  >
+    持久 (Infinity)
+  </Button>
+</div>
+```
+
+### Custom
+
+自定义渲染 — `toast.custom` 完全接管节点，用于嵌入富内容卡片。
+
+```tsx
+<Button
+  onClick={() =>
+    toast.custom((id) => (
+      <div className="flex w-80 items-start gap-3 rounded-md border border-border bg-popover p-3 text-popover-foreground shadow-lg">
+        <CircleHelpIcon className="mt-0.5 size-4 shrink-0 text-help" />
+        <div className="flex-1">
+          <div className="text-sm font-medium">自定义卡片</div>
+          <div className="mt-1 text-xs text-muted-foreground">
+            你可以在此渲染任意 JSX：表单、富文本、进度条等。
+          </div>
+        </div>
+        <button
+          type="button"
+          className="cursor-pointer text-xs text-muted-foreground hover:text-foreground"
+          onClick={() => toast.dismiss(id)}
+        >
+          关闭
+        </button>
+      </div>
+    ))
+  }
+>
+  触发
+</Button>
+```

package/src/components/sonner/stories.tsx

@@ -0,0 +1,285 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+import { CircleHelpIcon } from 'lucide-react';
+import { Button } from '@/components/button';
+import { HelpToastIcon, Toaster, toast } from './index';
+
+const meta: Meta<typeof Toaster> = {
+  title: '反馈 · Feedback/Sonner 通知',
+  component: Toaster,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+  },
+  decorators: [
+    (Story) => (
+      <div>
+        <Story />
+        <Toaster />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof Toaster>;
+
+/** 五档语义状态 — 等价 cloud-design `Message.success / .error / .warning / .notice / .help / .loading`。 */
+export const Default: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button onClick={() => toast('默认通知')}>默认</Button>
+      <Button onClick={() => toast.success('保存成功')}>success</Button>
+      <Button onClick={() => toast.info('已收到 3 条新消息')}>info</Button>
+      <Button onClick={() => toast.warning('请检查网络连接')}>warning</Button>
+      <Button onClick={() => toast.error('操作失败，请重试')}>error</Button>
+      <Button
+        onClick={() =>
+          toast('需要帮助？', {
+            description: '点击查看帮助文档了解此操作的更多细节。',
+            icon: HelpToastIcon,
+          })
+        }
+      >
+        help
+      </Button>
+      <Button onClick={() => toast.loading('正在加载...')}>loading</Button>
+    </div>
+  ),
+};
+
+/** 标题 + 描述 — 对应 cloud-design `Notification.open({ title, content })`。 */
+export const WithTitleAndDescription: Story = {
+  render: () => (
+    <Button
+      onClick={() =>
+        toast('文件已保存', {
+          description: '你的修改已自动同步到云端，可在历史版本中找回。',
+        })
+      }
+    >
+      触发
+    </Button>
+  ),
+};
+
+/** 操作按钮 — 业内主流 `action` props，单击执行下一步行动并关闭。 */
+export const WithAction: Story = {
+  render: () => (
+    <Button
+      onClick={() =>
+        toast('已删除项目「示例」', {
+          description: '删除后 7 天内可在回收站恢复。',
+          action: {
+            label: '撤销',
+            onClick: () => toast.success('已撤销删除'),
+          },
+        })
+      }
+    >
+      触发
+    </Button>
+  ),
+};
+
+/** 取消按钮 — 与 action 并存的次级行动点，可阻断默认行为。 */
+export const WithCancel: Story = {
+  render: () => (
+    <Button
+      onClick={() =>
+        toast('确认离开当前页面？', {
+          description: '未保存的修改将丢失。',
+          action: { label: '继续', onClick: () => toast.info('已继续') },
+          cancel: { label: '取消', onClick: () => toast('已取消') },
+        })
+      }
+    >
+      触发
+    </Button>
+  ),
+};
+
+/** 按 id 链式更新 — 等价 cloud-design `Message.loading + Message.success({ key })`。 */
+export const LoadingThenResolve: Story = {
+  render: () => (
+    <Button
+      onClick={() => {
+        const id = toast.loading('正在上传...');
+        setTimeout(() => {
+          toast.success('上传完成', {
+            id,
+            description: '文件已发布到生产环境。',
+          });
+        }, 1500);
+      }}
+    >
+      触发
+    </Button>
+  ),
+};
+
+/** Promise 链式更新 — 一次声明 loading / success / error 三态文案，自动跟随 Promise 状态。 */
+export const PromiseToast: Story = {
+  render: () => {
+    const mockRequest = () =>
+      new Promise<{ name: string }>((resolve, reject) => {
+        setTimeout(() => {
+          if (Math.random() > 0.3) resolve({ name: '订单 No.2026' });
+          else reject(new Error('服务暂不可用'));
+        }, 1500);
+      });
+
+    return (
+      <Button
+        onClick={() =>
+          toast.promise(mockRequest(), {
+            loading: '正在提交订单...',
+            success: (data) => `${data.name} 已提交`,
+            error: (err: Error) => `提交失败：${err.message}`,
+          })
+        }
+      >
+        触发
+      </Button>
+    );
+  },
+};
+
+/** 持续时长 — `duration` 控制关闭延迟，`Infinity` 持久不关。对应 cloud-design `duration: 0`。 */
+export const Duration: Story = {
+  render: () => (
+    <div className="flex flex-wrap gap-2">
+      <Button onClick={() => toast('1.5 秒后关闭', { duration: 1500 })}>
+        短 (1.5s)
+      </Button>
+      <Button onClick={() => toast('8 秒后关闭', { duration: 8000 })}>
+        长 (8s)
+      </Button>
+      <Button
+        onClick={() =>
+          toast('持久通知', {
+            description: '需要手动关闭，等价 cloud-design duration:0。',
+            duration: Infinity,
+          })
+        }
+      >
+        持久 (Infinity)
+      </Button>
+    </div>
+  ),
+};
+
+/** 容器位置 — `placement` 6 档形态，对应 cloud-design `Notification.config({ placement })`。 */
+export const Placement: Story = {
+  decorators: [(Story) => <Story />],
+  render: () => {
+    const [placement, setPlacement] = React.useState<
+      | 'top-left'
+      | 'top-right'
+      | 'top-center'
+      | 'bottom-left'
+      | 'bottom-right'
+      | 'bottom-center'
+    >('top-right');
+    const placements = [
+      'top-left',
+      'top-center',
+      'top-right',
+      'bottom-left',
+      'bottom-center',
+      'bottom-right',
+    ] as const;
+
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex flex-wrap gap-2">
+          {placements.map((p) => (
+            <Button
+              key={p}
+              variant={p === placement ? 'default' : 'outline'}
+              onClick={() => {
+                setPlacement(p);
+                toast.success(`位置：${p}`);
+              }}
+            >
+              {p}
+            </Button>
+          ))}
+        </div>
+        <Toaster placement={placement} />
+      </div>
+    );
+  },
+};
+
+/** 自定义渲染 — `toast.custom` 完全接管节点，用于嵌入富内容卡片。 */
+export const Custom: Story = {
+  render: () => (
+    <Button
+      onClick={() =>
+        toast.custom((id) => (
+          <div className="flex w-80 items-start gap-3 rounded-md border border-border bg-popover p-3 text-popover-foreground shadow-lg">
+            <CircleHelpIcon className="mt-0.5 size-4 shrink-0 text-help" />
+            <div className="flex-1">
+              <div className="text-sm font-medium">自定义卡片</div>
+              <div className="mt-1 text-xs text-muted-foreground">
+                你可以在此渲染任意 JSX：表单、富文本、进度条等。
+              </div>
+            </div>
+            <button
+              type="button"
+              className="cursor-pointer text-xs text-muted-foreground hover:text-foreground"
+              onClick={() => toast.dismiss(id)}
+            >
+              关闭
+            </button>
+          </div>
+        ))
+      }
+    >
+      触发
+    </Button>
+  ),
+};
+
+/** 主动关闭 — `toast.dismiss(id)` 关闭指定通知，`toast.dismiss()` 清空全部。 */
+export const DismissProgrammatic: Story = {
+  render: () => {
+    const idRef = React.useRef<string | number | undefined>(undefined);
+    return (
+      <div className="flex flex-wrap gap-2">
+        <Button
+          onClick={() => {
+            idRef.current = toast('一条可被定向关闭的通知', {
+              description: '保留这条 id，再点"关闭它"按钮。',
+              duration: Infinity,
+            });
+          }}
+        >
+          打开 1 条
+        </Button>
+        <Button
+          variant="outline"
+          onClick={() => {
+            for (let i = 0; i < 3; i += 1) {
+              toast.info(`批量通知 ${i + 1}`);
+            }
+          }}
+        >
+          打开 3 条
+        </Button>
+        <Button
+          variant="destructive"
+          onClick={() => {
+            if (idRef.current !== undefined) toast.dismiss(idRef.current);
+          }}
+        >
+          关闭它（按 id）
+        </Button>
+        <Button variant="destructive" onClick={() => toast.dismiss()}>
+          全部关闭
+        </Button>
+      </div>
+    );
+  },
+};