@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/skeleton/skeleton.meta.md

@@ -1,13 +1,14 @@
 ---
 id: skeleton
 name: Skeleton
+displayName: 骨架屏
 type: component
-category: foundation
+category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Skeleton
+# Skeleton 骨架屏
 
 骨架屏占位 — shadcn 单元素 pulse + antd 子组件家族(`SkeletonAvatar / SkeletonImage / SkeletonButton / SkeletonInput / SkeletonParagraph`)。
 
@@ -56,8 +57,6 @@ pnpm add class-variance-authority@^0.7.0
 ```
 <!-- auto:deps:end -->
 
-> 子组件 `SkeletonAvatar / SkeletonImage / SkeletonButton / SkeletonInput / SkeletonParagraph` 各自的 Props 可在 [`skeleton.tsx`](./skeleton.tsx) 查看。
-
 ## AI 生成纪律
 
 - **形状要与最终内容匹配**:文本用 `shape="line"`,头像用 `<SkeletonAvatar />`,图片用 `<SkeletonImage />`,**不要**全用矩形糊弄

package/src/components/skeleton/skeleton.stories.tsx

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import {
   Skeleton,
   SkeletonAvatar,
@@ -9,14 +9,14 @@ import {
 } from './skeleton';
 
 const meta: Meta<typeof Skeleton> = {
-  title: '基础原语 · Foundation/Skeleton',
+  title: '反馈 · Feedback/Skeleton',
   component: Skeleton,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '骨架屏 — 在内容加载过程中呈现占位图形，减少加载期间的视觉跳动。shadcn `Skeleton` 原子 + antd `Skeleton` 的能力并集：除原子 `Skeleton`（支持 `shape: rect | circle | line`）外，同时提供预设组合 `SkeletonAvatar` / `SkeletonImage` / `SkeletonButton` / `SkeletonInput` / `SkeletonParagraph`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '骨架屏 — 在内容加载过程中呈现占位图形，减少加载期间的视觉跳动。shadcn `Skeleton` 原子 + antd 能力并集：支持 `shape: rect | circle | line`，同时提供预设组合 `SkeletonAvatar` / `SkeletonImage` / `SkeletonButton` / `SkeletonInput` / `SkeletonParagraph`。',
       },
     },
   },
@@ -58,7 +58,7 @@ export const Family: Story = {
 export const Card: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="w-80 rounded-lg border p-4">
+    <div className="w-80 rounded-lg border border-border p-4">
       <SkeletonImage />
       <SkeletonParagraph rows={3} className="mt-3" />
     </div>

package/src/components/skeleton/skeleton.tsx

@@ -43,11 +43,12 @@ Skeleton.displayName = 'Skeleton';
 
 export interface SkeletonAvatarProps extends Omit<SkeletonProps, 'shape'> {
   /** 尺寸:小 32 / 默认 40 / 大 64。 @default "default" */
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 const SkeletonAvatar = React.forwardRef<HTMLDivElement, SkeletonAvatarProps>(
-  ({ size = 'default', className, ...props }, ref) => {
-    const dim = size === 'sm' ? 'size-8' : size === 'lg' ? 'size-16' : 'size-10';
+  ({ size = 'md', className, ...props }, ref) => {
+    const dim =
+      size === 'sm' ? 'size-8' : size === 'lg' ? 'size-16' : 'size-10';
     return (
       <Skeleton
         ref={ref}
@@ -74,10 +75,10 @@ const SkeletonImage = React.forwardRef<HTMLDivElement, SkeletonImageProps>(
 SkeletonImage.displayName = 'SkeletonImage';
 
 export interface SkeletonButtonProps extends Omit<SkeletonProps, 'shape'> {
-  size?: 'sm' | 'default' | 'lg';
+  size?: 'sm' | 'md' | 'default' | 'lg';
 }
 const SkeletonButton = React.forwardRef<HTMLDivElement, SkeletonButtonProps>(
-  ({ size = 'default', className, ...props }, ref) => {
+  ({ size = 'md', className, ...props }, ref) => {
     const h = size === 'sm' ? 'h-8' : size === 'lg' ? 'h-10' : 'h-9';
     return (
       <Skeleton
@@ -104,8 +105,7 @@ const SkeletonInput = React.forwardRef<HTMLDivElement, SkeletonInputProps>(
 );
 SkeletonInput.displayName = 'SkeletonInput';
 
-export interface SkeletonParagraphProps
-  extends Omit<SkeletonProps, 'shape'> {
+export interface SkeletonParagraphProps extends Omit<SkeletonProps, 'shape'> {
   /**
    * 段落行数。最后一行宽度自动收窄至 60%,模拟自然段尾。
    * @default 3

package/src/components/slider/slider.meta.md

@@ -1,13 +1,14 @@
 ---
 id: slider
 name: Slider
+displayName: 滑块
 type: component
-category: form
+category: data-entry
 since: 0.1.0
 package: '@teamix-evo/ui'
 ---
 
-# Slider
+# Slider 滑块
 
 滑块 — Radix Slider + antd 的 `marks` 刻度标签。**单 / 双滑块由 `value`/`defaultValue` 数组长度决定**(传 `[lo, hi]` 自动变范围滑块)。
 
@@ -30,7 +31,21 @@ package: '@teamix-evo/ui'
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `marks` | `Record<number, React.ReactNode>` | – | – | 刻度标记(antd `marks` 并集)。键为 0~max 的数值,值为标签文本。 渲染时小标记点 + 文字标签出现在轨道下方。 |
+| `value` | `number[]` | – | – | 受控 value — **必为数组**,单滑块 `[v]`,范围滑块 `[lo, hi]`(单/双由数组长度决定)。 与 `defaultValue` 二选一。 |
+| `defaultValue` | `number[]` | – | – | 非受控初始值。同样数组形态(单/双由长度决定)。 |
+| `onValueChange` | `(value: number[]) => void` | – | – | 滑块拖动 / 步进时触发(实时,频率高)。 业务表单层用 `onValueCommit` 拿到最终值更省心。 |
+| `onValueCommit` | `(value: number[]) => void` | – | – | 拖动结束(mouse up / key up)时触发一次,适合"提交"语义。 |
+| `min` | `number` | `0` | – | 最小值。 |
+| `max` | `number` | `100` | – | 最大值。 |
+| `step` | `number` | `1` | – | 步进单位(键盘 ←→ / 拖动吸附)。 |
+| `disabled` | `boolean` | `false` | – | 禁用整个 Slider(灰化 + 不响应交互)。 |
+| `orientation` | `'horizontal' \| 'vertical'` | `"horizontal"` | – | 排列方向(键盘导航方向跟随)。 |
+| `inverted` | `boolean` | `false` | – | 反向滚动(从右往左 / 从下往上)。 |
+| `name` | `string` | – | – | 表单字段名(原生 `<input name>`)。 |
+| `marks` | `Record<number, React.ReactNode>` | – | – | 刻度标记(antd `marks` 并集)。键为 0~max 的数值,值为标签文本。 渲染时小标记点 + 文字标签出现在轨道下方(默认)或上方(`marksPosition="above"`)。 |
+| `marksPosition` | `'above' \| 'below'` | `"below"` | – | 刻度文字位置(cloud-design `marksPosition` 并集) — `"below"` 在轨道下方,`"above"` 在轨道上方。 |
+| `tooltipVisible` | `boolean` | `false` | – | 是否常驻显示当前值的 tooltip(cloud-design `tooltipVisible` 并集) — `true` 时所有 thumb 都会持续显示数值气泡;`false` 时仅在 hover / drag 时显示(默认)。 |
+| `tipRender` | `(value: number) => React.ReactNode` | – | – | 自定义 tooltip 渲染函数(cloud-design `tipRender` 并集)。 不传时直接渲染数值。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -66,8 +81,10 @@ pnpm add @radix-ui/react-slider@^1.2.0
 - **`step` 跨度的可访问性**:键盘 Page Up/Down 步进 = step × 10,设计 step 时考虑这一点
 - **marks 的"圆点"和"文字"必须分两层渲染,不要打包成一个 box**:
   - **圆点**:`absolute top-1/2 -translate-x-1/2 -translate-y-1/2` 居中压在 track 中线上,渲染在 `<SliderPrimitive.Root>` 内、`<Track>` 之外(放进 Track 内会被 `overflow-hidden` 裁掉或被 `Range` 高亮覆盖)
-  - **文字**:独立放在父容器 `bottom-0` 处,通过父容器 `pb-6` 留出 ~14px 间距;不要用 `mt-1` 把文字直接挂在圆点下方,会出现"点和文字粘在一起"的视觉 bug(对照 antd 标准:点压 track、文字距 track ~12px)
+  - **文字**:独立放在父容器 `bottom-0`(默认)或 `top-0`(`marksPosition="above"`)处,通过父容器 `pb-6` / `pt-6` 留出 ~14px 间距;不要用 `mt-1` 把文字直接挂在圆点下方,会出现"点和文字粘在一起"的视觉 bug
 - **`<Thumb>` 必须加 `relative z-10`**:让滑块视觉层级高于 marks 圆点,避免拖动时圆点突兀露在 thumb 之上
+- **`tooltipVisible` 为展示能力**:常驻气泡不要氪加在表单表中使用(气泡会遮住上方行);需要 `tipRender` 定制显示内容时请传函数而非 ReactNode
+- **`marksPosition="above"` 与拖拽 tooltip 会重叠**:同时开启 `marksPosition="above"` 和 `tooltipVisible=true` 时,拖拽气泡会与上方 marks 文字压在一起 — 建议二者选一
 
 ## Examples
 
@@ -80,7 +97,7 @@ import { Slider } from '@/components/ui/slider';
 // 范围滑块
 <Slider defaultValue={[20, 80]} max={100} step={1} />
 
-// 带刻度标签
+// 带刻度标签(下方)
 <Slider
   defaultValue={[40]}
   max={100}
@@ -88,7 +105,42 @@ import { Slider } from '@/components/ui/slider';
   marks={{ 0: '0°C', 20: '20', 40: '40', 60: '60', 80: '80', 100: '100°C' }}
 />
 
+// 刻度上方
+<Slider defaultValue={[40]} marksPosition="above" marks={{ 0: '0', 50: '50', 100: '100' }} />
+
+// 常驻数值气泡
+<Slider defaultValue={[42]} tooltipVisible />
+
+// 自定义 tooltip
+<Slider defaultValue={[1500]} max={5000} tooltipVisible tipRender={(v) => `¥${v}`} />
+
 // 受控
 const [v, setV] = React.useState([50]);
 <Slider value={v} onValueChange={setV} max={100} />
 ```
+
+## Range 形态 — 旧库 API → 新库映射
+
+> 旧库(Teamix 1.0 / `@alifd/next.Range`)→ 新库 `Slider`(Radix `@radix-ui/react-slider` 底层 + antd `marks` 并集)。新库**单/双滑块由数据形态决定** — 不再有独立的 `slider="single|double"` prop。
+
+| 旧库 API | 新库 API | 备注 |
+| --- | --- | --- |
+| 组件名 `Range` | `Slider` | 对齐 shadcn / Radix 命名 |
+| `slider="single"` | `defaultValue={[v]}` | 数据决定 — 数组长度 = 1 即单滑块 |
+| `slider="double"` | `defaultValue={[lo, hi]}` | 数组长度 = 2 即范围滑块 |
+| `onChange(number \| [n,n])` | `onValueChange(number[])` | 始终数组,Radix 命名 |
+| `onProcess` 实时触发 | `onValueChange` | 同一回调,实时触发(Radix 内部) |
+| `reverse` | `inverted`(透传 Radix Root) | Radix 命名 |
+| `marks={5}` 数字密度 | 不修复 — 仅支持 `Record<number, ReactNode>` | 业务自构造 marks 对象 |
+| `marks=true` boolean | 不修复 — 同上 | 业务自构造 |
+| `marks=[5, 50, 100]` array | 不修复 — 同上 | 业务自构造 |
+| `tooltipVisible` | `tooltipVisible` | 同名 |
+| `tipRender` | `tipRender` | 同名 |
+| `fixedWidth` 固定宽度拖动 | 不修复 | 极少使用,P3 |
+| `pure` 纯渲染 | 不修复 | `React.memo` 由消费方按需包裹 |
+
+### 不修复 / 后续工序清单
+
+- **`slider` prop**:不修复 — 数组形态本身已是更直观的 API
+- **`marks` 多类型签名**:仅保留 Object 形式,boolean / number / Array 由业务侧自行构造 marks 对象
+- **`fixedWidth`** / **`pure`**:报告 §5 已列入"保留新库优势",**不修复**

package/src/components/slider/slider.stories.tsx

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Slider } from './slider';
 
 const meta: Meta<typeof Slider> = {
-  title: '表单与输入 · Form/Slider',
+  title: '数据录入 · Data Entry/Slider',
   component: Slider,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '滑块 — 在给定范围内选取一个数值或一段区间。Radix Slider 实现 + antd 的 `marks` 刻度能力：`value` / `defaultValue` 为数组，长度为 1 时为单滑块、为 2 时自动切换为区间滑块；可配 `marks` 渲染轨道下方的刻度点与标签。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '滑块 — 在给定范围内选取一个数值或一段区间。Radix Slider 实现 + antd `marks` 刻度 ∪ cloud-design `marksPosition` / `tooltipVisible` / `tipRender` 并集能力:`value` / `defaultValue` 为数组,长度为 1 时为单滑块、为 2 时自动切换为区间滑块;可配 `marks` 渲染轨道下方(默认)或上方(`marksPosition="above"`)的刻度点与标签,`tooltipVisible` 控制数值气泡是否常驻。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -18,11 +18,20 @@ const meta: Meta<typeof Slider> = {
     max: { control: 'number' },
     step: { control: 'number' },
     disabled: { control: 'boolean' },
+    tooltipVisible: { control: 'boolean' },
+    marksPosition: { control: 'inline-radio', options: ['below', 'above'] },
+  },
+  args: {
+    defaultValue: [42],
+    min: 0,
+    max: 100,
+    step: 1,
+    tooltipVisible: false,
+    marksPosition: 'below',
   },
-  args: { defaultValue: [42], min: 0, max: 100, step: 1 },
   decorators: [
     (Story) => (
-      <div className="w-80">
+      <div className="w-80 px-2">
         <Story />
       </div>
     ),
@@ -39,7 +48,7 @@ export const Range: Story = {
   render: () => <Slider defaultValue={[20, 80]} max={100} />,
 };
 
-export const WithMarks: Story = {
+export const WithMarksBelow: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <Slider
@@ -58,6 +67,49 @@ export const WithMarks: Story = {
   ),
 };
 
+export const WithMarksAbove: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Slider
+      defaultValue={[40]}
+      max={100}
+      step={20}
+      marksPosition="above"
+      marks={{
+        0: '0',
+        20: '20',
+        40: '40',
+        60: '60',
+        80: '80',
+        100: '100',
+      }}
+    />
+  ),
+};
+
+export const TooltipAlwaysVisible: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <Slider defaultValue={[42]} tooltipVisible />
+      <Slider defaultValue={[20, 80]} tooltipVisible />
+    </div>
+  ),
+};
+
+export const TooltipWithRender: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Slider
+      defaultValue={[1500]}
+      max={5000}
+      step={100}
+      tooltipVisible
+      tipRender={(v) => `¥${v.toLocaleString()}`}
+    />
+  ),
+};
+
 export const Disabled: Story = {
   parameters: { controls: { disable: true } },
   render: () => (

package/src/components/slider/slider.tsx

@@ -4,12 +4,89 @@ import * as SliderPrimitive from '@radix-ui/react-slider';
 import { cn } from '@/utils/cn';
 
 export interface SliderProps
-  extends React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> {
+  extends Omit<
+    React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root>,
+    | 'value'
+    | 'defaultValue'
+    | 'onValueChange'
+    | 'onValueCommit'
+    | 'min'
+    | 'max'
+    | 'step'
+    | 'disabled'
+    | 'orientation'
+    | 'inverted'
+    | 'name'
+  > {
+  /**
+   * 受控 value — **必为数组**,单滑块 `[v]`,范围滑块 `[lo, hi]`(单/双由数组长度决定)。
+   * 与 `defaultValue` 二选一。
+   */
+  value?: number[];
+  /** 非受控初始值。同样数组形态(单/双由长度决定)。 */
+  defaultValue?: number[];
+  /**
+   * 滑块拖动 / 步进时触发(实时,频率高)。
+   * 业务表单层用 `onValueCommit` 拿到最终值更省心。
+   */
+  onValueChange?: (value: number[]) => void;
+  /**
+   * 拖动结束(mouse up / key up)时触发一次,适合"提交"语义。
+   */
+  onValueCommit?: (value: number[]) => void;
+  /**
+   * 最小值。
+   * @default 0
+   */
+  min?: number;
+  /**
+   * 最大值。
+   * @default 100
+   */
+  max?: number;
+  /**
+   * 步进单位(键盘 ←→ / 拖动吸附)。
+   * @default 1
+   */
+  step?: number;
+  /**
+   * 禁用整个 Slider(灰化 + 不响应交互)。
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * 排列方向(键盘导航方向跟随)。
+   * @default "horizontal"
+   */
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * 反向滚动(从右往左 / 从下往上)。
+   * @default false
+   */
+  inverted?: boolean;
+  /** 表单字段名(原生 `<input name>`)。 */
+  name?: string;
   /**
    * 刻度标记(antd `marks` 并集)。键为 0~max 的数值,值为标签文本。
-   * 渲染时小标记点 + 文字标签出现在轨道下方。
+   * 渲染时小标记点 + 文字标签出现在轨道下方(默认)或上方(`marksPosition="above"`)。
    */
   marks?: Record<number, React.ReactNode>;
+  /**
+   * 刻度文字位置(cloud-design `marksPosition` 并集) — `"below"` 在轨道下方,`"above"` 在轨道上方。
+   * @default "below"
+   */
+  marksPosition?: 'above' | 'below';
+  /**
+   * 是否常驻显示当前值的 tooltip(cloud-design `tooltipVisible` 并集) —
+   * `true` 时所有 thumb 都会持续显示数值气泡;`false` 时仅在 hover / drag 时显示(默认)。
+   * @default false
+   */
+  tooltipVisible?: boolean;
+  /**
+   * 自定义 tooltip 渲染函数(cloud-design `tipRender` 并集)。
+   * 不传时直接渲染数值。
+   */
+  tipRender?: (value: number) => React.ReactNode;
 }
 
 const Slider = React.forwardRef<
@@ -17,19 +94,51 @@ const Slider = React.forwardRef<
   SliderProps
 >(
   (
-    { className, marks, value, defaultValue, min = 0, max = 100, ...props },
+    {
+      className,
+      marks,
+      marksPosition = 'below',
+      tooltipVisible = false,
+      tipRender,
+      value,
+      defaultValue,
+      min = 0,
+      max = 100,
+      onValueChange,
+      ...props
+    },
     ref,
   ) => {
-    // Radix Slider supports range natively when `value` / `defaultValue` is array of length 2.
-    const thumbCount = (value ?? defaultValue ?? [0]).length;
+    // 单 / 双滑块由 value/defaultValue 数组长度决定
+    const initial = (value ?? defaultValue ?? [0]) as number[];
+    const [internal, setInternal] = React.useState<number[]>(initial);
+    const isControlled = value !== undefined;
+    const current = isControlled ? (value as number[]) : internal;
+
+    const handleValueChange = (next: number[]) => {
+      if (!isControlled) setInternal(next);
+      onValueChange?.(next);
+    };
+
+    const thumbCount = current.length;
+    const showAboveMarks = marks && marksPosition === 'above';
+    const showBelowMarks = marks && marksPosition === 'below';
+
     return (
-      <div className={cn('relative w-full', marks ? 'pb-6' : '')}>
+      <div
+        className={cn(
+          'relative w-full',
+          showBelowMarks && 'pb-6',
+          showAboveMarks && 'pt-6',
+        )}
+      >
         <SliderPrimitive.Root
           ref={ref}
           value={value}
           defaultValue={defaultValue}
           min={min}
           max={max}
+          onValueChange={handleValueChange}
           className={cn(
             'relative flex w-full touch-none select-none items-center',
             className,
@@ -53,15 +162,47 @@ const Slider = React.forwardRef<
                 );
               })
             : null}
-          {Array.from({ length: thumbCount }).map((_, i) => (
-            <SliderPrimitive.Thumb
-              key={i}
-              className="relative z-10 block size-4 rounded-full border-2 border-primary bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50"
-            />
-          ))}
+          {Array.from({ length: thumbCount }).map((_, i) => {
+            const v = current[i] ?? 0;
+            const display = tipRender ? tipRender(v) : v;
+            return (
+              <SliderPrimitive.Thumb
+                key={i}
+                className="group relative z-10 block size-4 rounded-full border-2 border-primary bg-background shadow transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50"
+              >
+                {tooltipVisible ? (
+                  <span
+                    className={cn(
+                      // 常驻气泡:thumb 上方 ~8px,带轻微小三角效果(用 box-shadow 做箭头有点冗余,简化为圆角矩形)
+                      'pointer-events-none absolute -top-8 left-1/2 -translate-x-1/2 whitespace-nowrap rounded-md bg-foreground px-2 py-0.5 text-xs font-medium text-background shadow-md',
+                    )}
+                    aria-hidden
+                  >
+                    {display}
+                  </span>
+                ) : (
+                  <span
+                    className={cn(
+                      // 仅 hover / focus / active 时显示
+                      'pointer-events-none absolute -top-8 left-1/2 -translate-x-1/2 whitespace-nowrap rounded-md bg-foreground px-2 py-0.5 text-xs font-medium text-background opacity-0 shadow-md transition-opacity',
+                      'group-hover:opacity-100 group-focus-visible:opacity-100 group-data-[state=active]:opacity-100',
+                    )}
+                    aria-hidden
+                  >
+                    {display}
+                  </span>
+                )}
+              </SliderPrimitive.Thumb>
+            );
+          })}
         </SliderPrimitive.Root>
         {marks ? (
-          <div className="pointer-events-none absolute inset-x-0 bottom-0 h-4">
+          <div
+            className={cn(
+              'pointer-events-none absolute inset-x-0 h-4',
+              marksPosition === 'above' ? 'top-0' : 'bottom-0',
+            )}
+          >
             {Object.entries(marks).map(([k, label]) => {
               const num = Number(k);
               const pct = ((num - min) / (max - min)) * 100;

package/src/components/sonner/sonner.meta.md

@@ -4,14 +4,15 @@ name: Sonner
 type: component
 category: feedback
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 轻提示
 ---
 
-# Sonner
+# Sonner 轻提示
 
 Toast 通知 — 基于 [`sonner`](https://sonner.emilkowal.ski/),已**同时覆盖** antd `message`(行内简短)+ `notification`(标题 + 描述 + 行动)的并集。
 
-**应用根挂 `<Toaster />` 一次**,在任意地方 `import { toast } from '@/components/ui/sonner'` 触发。
+**应用根挂 `<Toaster />` 一次**,在任意地方 `import { toast } from '@/components/ui/sonner'` 触发。视觉走 OpenTrek tokens —— **无边框、纯 shadow 分界、面性(filled)状态图标**;`success` / `error` / `warning` / `info` / `loading` 五种状态各有对应配色与实心图标。
 
 ## When to use
 
@@ -31,7 +32,16 @@ Toast 通知 — 基于 [`sonner`](https://sonner.emilkowal.ski/),已**同时覆
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `<Toaster />` 的 props。`toast()` 函数式 API 见下方 Examples。
 
 <!-- auto:props:begin -->
-_(no props)_
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `position` | `SonnerProps['position']` | `"top-right"` | – | Toast 弹出位置(对齐 antd `message.config.placement`)。 |
+| `duration` | `number` | `4000` | – | 自动消失时长(ms)— 0 表示常驻不自动关闭。 |
+| `visibleToasts` | `number` | `3` | – | 同屏最大可见 toast 数(超出旧的自动收起)。 |
+| `expand` | `boolean` | `false` | – | 鼠标 hover 时是否展开堆叠的 toast(否则保持折叠堆叠状)。 |
+| `richColors` | `boolean` | `false` | – | 启用 sonner 自带的"丰富配色"(更高对比度的状态色背景); 关闭则走我们的视觉(对齐 OpenTrek tokens)。 |
+| `closeButton` | `boolean` | `false` | – | 每张 toast 是否显示关闭按钮(右上角 ×)。 |
+| `theme` | `SonnerProps['theme']` | – | – | 主题 — `'light'` / `'dark'` / `'system'`(跟随 OS 偏好)。 通常无需手传,组件会跟随 `<html>` 上的 `.dark` class 自动切换。 |
+| `dir` | `SonnerProps['dir']` | `"auto"` | – | 文字方向 — `'ltr'` / `'rtl'` / `'auto'`。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -41,14 +51,18 @@ _(no props)_
 <!-- auto:deps:begin -->
 ### 同库依赖
 
-_无 — 本组件不依赖其他 ui entry。_
+> `teamix-evo ui add sonner` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```bash
-pnpm add sonner@^1.5.0
+pnpm add sonner@^1.5.0 lucide-react@^0.460.0
 ```
 <!-- auto:deps:end -->
 
@@ -61,6 +75,8 @@ pnpm add sonner@^1.5.0
 - **错误用 `toast.error()`**:语义化方法比 `toast({ type: 'error' })` 优先
 - **长任务用 `toast.promise()`**:自动显示 loading → success / error,避免手写状态切换
 - **Action 按钮用一个就够**:不要塞多个,过载
+- **不要覆盖 `icons` / `richColors`**:本组件已用面性 lucide 图标 + OpenTrek tokens 处理 5 种状态配色,自行传 `richColors` 会与既有样式冲突;如需自定义图标,通过传入的 `toastOptions.classNames.icon` / `icons` 在外层精细覆盖
+- **禁用边框样式**:卡片默认 `border-0 + shadow-lg`,不要再加 `border` —— 与轻提示克制美学冲突
 
 ## Examples
 
@@ -68,7 +84,7 @@ pnpm add sonner@^1.5.0
 import { Toaster, toast } from '@/components/ui/sonner';
 
 // 应用根
-<Toaster position="top-right" richColors />
+<Toaster position="top-right" richColors />;
 
 // 简单消息(等价 antd message)
 toast('已复制到剪贴板');
@@ -94,3 +110,38 @@ toast('文件已删除', {
   action: { label: '撤销', onClick: () => undo() },
 });
 ```
+
+---
+
+## Message 形态 — 旧库 API → 新映射
+
+> 旧库 `Message`(hybridcloud,含 show/success/error/confirm 等命令式) → 新库 `toast()`(命令式) + `Alert`(内联常驻)。
+> 新库用 [sonner](https://sonner.emilkowal.ski/) 三方库,已自定义视觉(OpenTrek tokens + 面性图标)。
+
+### 命名 & 结构映射
+
+| 旧库                           | 新库                                            | 说明                            |
+| ------------------------------ | ----------------------------------------------- | ------------------------------- |
+| `Message shape='toast'`        | `toast()`                                       | 命令式轻提示                    |
+| `Message shape='inline'`       | `Alert` 组件                                    | 内联常驻提示(独立 entry)        |
+| `Message.success(msg)`         | `toast.success(msg)`                            | 直接映射                        |
+| `Message.error(msg)`           | `toast.error(msg)`                              | 直接映射                        |
+| `Message.warning(msg)`         | `toast.warning(msg)`                            | 直接映射                        |
+| `Message.notice(msg)`          | `toast.info(msg)`                               | notice → info                   |
+| `Message.loading(msg)`         | `toast.loading(msg)`                            | 直接映射                        |
+| `Message.hide()`               | `toast.dismiss()`                               | 全局关闭                        |
+| `Message.config({ duration })` | `<Toaster duration={...} />`                    | 声明式配置                      |
+| `closeable`                    | `closeButton`(Toaster prop)                     | 拼写变更                        |
+| `type='help'`                  | `toast.info()`                                  | 映射到 info                     |
+| Promise 自动切换               | `toast.promise(p, { loading, success, error })` | 新增能力(P0)                    |
+| `title + content`              | `toast.success(title, { description })`         | title 第一参,description 第二参 |
+| `action`                       | `toast(msg, { action: { label, onClick } })`    | 行动按钮                        |
+
+### 迁移 FAQ
+
+| 问题                       | 回答                                               |
+| -------------------------- | -------------------------------------------------- |
+| 内联提示怎么做?            | 用 `Alert` 组件(非 toast),常驻在页面上             |
+| Toaster 放哪?              | 应用根组件放一次即可,如 `layout.tsx`               |
+| 怎么控制位置?              | `<Toaster position="top-right" />`                 |
+| Message.hide(id) 关闭指定? | `const id = toast.loading(...); toast.dismiss(id)` |