@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/tooltip/meta.md

@@ -0,0 +1,186 @@
+# Tooltip
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+提示 Tooltip
+悬停或聚焦时展示简短提示文字，可选两种视觉变体（亮底 / 反色）。
+
+## 使用场景
+
+- 图标按钮需要文字解释
+- 截断文本悬停展示完整内容
+- 为操作提供额外上下文信息
+- 组合结构：TooltipProvider > Tooltip > TooltipTrigger + TooltipContent (> TooltipArrow?)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控显示状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始显示状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 显示 / 关闭状态变化回调。 |
+| `delayDuration` | `number` | – | – | 悬停多久后打开（毫秒）。默认跟随 Provider 设置。 |
+| `disableHoverableContent` | `boolean` | `false` | – | 是否禁用鼠标进入 Tooltip 内保持显示。 |
+| `variant` | `'default' \| 'inverse'` | `'default'` | – | 视觉变体：default = 亮底；inverse = 反色（深底白字）。 |
+| `container` | `HTMLElement \| null` | `document.body` | – | 浮层渲染容器，透传给 Portal。 |
+
+## 示例
+
+### Sides
+
+不同方向的提示。
+
+```tsx
+<TooltipProvider>
+  <div className="flex items-center gap-4">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>上</Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">上方提示</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>下</Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">下方提示</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>左</Button>
+      </TooltipTrigger>
+      <TooltipContent side="left">左侧提示</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>右</Button>
+      </TooltipTrigger>
+      <TooltipContent side="right">右侧提示</TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
+### Variants
+
+两种视觉变体：默认（亮底）与反色（深底）。
+
+```tsx
+<TooltipProvider>
+  <div className="flex items-center gap-4">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>default</Button>
+      </TooltipTrigger>
+      <TooltipContent variant="default">亮底文字提示</TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>inverse</Button>
+      </TooltipTrigger>
+      <TooltipContent variant="inverse">深底反色提示</TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
+### WithArrow
+
+显示尖角箭头。
+
+```tsx
+<TooltipProvider>
+  <div className="flex items-center gap-4">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>带箭头</Button>
+      </TooltipTrigger>
+      <TooltipContent>
+        提示内容
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>反色 + 箭头</Button>
+      </TooltipTrigger>
+      <TooltipContent variant="inverse">
+        深色提示
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
+### ArrowSides
+
+四个方向的箭头 — 箭头随 side 自动朝向 trigger。
+
+```tsx
+<TooltipProvider delayDuration={0}>
+  <div className="grid grid-cols-2 place-items-center gap-16 p-12">
+    <Tooltip open>
+      <TooltipTrigger asChild>
+        <Button>side=top</Button>
+      </TooltipTrigger>
+      <TooltipContent side="top">
+        top
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+    <Tooltip open>
+      <TooltipTrigger asChild>
+        <Button>side=bottom</Button>
+      </TooltipTrigger>
+      <TooltipContent side="bottom">
+        bottom
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+    <Tooltip open>
+      <TooltipTrigger asChild>
+        <Button>side=left</Button>
+      </TooltipTrigger>
+      <TooltipContent side="left">
+        left
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+    <Tooltip open>
+      <TooltipTrigger asChild>
+        <Button>side=right</Button>
+      </TooltipTrigger>
+      <TooltipContent side="right">
+        right
+        <TooltipArrow />
+      </TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```
+
+### Delay
+
+自定义触发延时。
+
+```tsx
+<TooltipProvider delayDuration={500}>
+  <div className="flex items-center gap-4">
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <Button>500ms</Button>
+      </TooltipTrigger>
+      <TooltipContent>跟随 Provider 的延时</TooltipContent>
+    </Tooltip>
+    <Tooltip delayDuration={0}>
+      <TooltipTrigger asChild>
+        <Button>立即</Button>
+      </TooltipTrigger>
+      <TooltipContent>覆盖为 0ms</TooltipContent>
+    </Tooltip>
+  </div>
+</TooltipProvider>
+```

package/src/components/tooltip/stories.tsx

@@ -0,0 +1,212 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from './index';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Tooltip> = {
+  title: '数据展示 · Data Display/Tooltip 文字提示',
+  component: Tooltip,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础文字提示，悬停时显示。 */
+export const Default: Story = {
+  render: () => (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button>悬停查看</Button>
+        </TooltipTrigger>
+        <TooltipContent>
+          <p>这是一条提示信息</p>
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  ),
+};
+
+/** 不同方向的提示。 */
+export const Sides: Story = {
+  render: () => (
+    <TooltipProvider>
+      <div className="flex items-center gap-4">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>上</Button>
+          </TooltipTrigger>
+          <TooltipContent side="top">上方提示</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>下</Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">下方提示</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>左</Button>
+          </TooltipTrigger>
+          <TooltipContent side="left">左侧提示</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>右</Button>
+          </TooltipTrigger>
+          <TooltipContent side="right">右侧提示</TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+/** 两种视觉变体：默认（亮底）与反色（深底）。 */
+export const Variants: Story = {
+  render: () => (
+    <TooltipProvider>
+      <div className="flex items-center gap-4">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>default</Button>
+          </TooltipTrigger>
+          <TooltipContent variant="default">亮底文字提示</TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>inverse</Button>
+          </TooltipTrigger>
+          <TooltipContent variant="inverse">深底反色提示</TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+/** 12 方向矩阵：side × align 组合。 */
+export const AllPositions: Story = {
+  render: () => {
+    const sides = ['top', 'right', 'bottom', 'left'] as const;
+    const aligns = ['start', 'center', 'end'] as const;
+    return (
+      <TooltipProvider>
+        <div className="grid grid-cols-3 gap-4">
+          {sides.flatMap((side) =>
+            aligns.map((align) => (
+              <Tooltip key={`${side}-${align}`}>
+                <TooltipTrigger asChild>
+                  <Button>{`${side}-${align}`}</Button>
+                </TooltipTrigger>
+                <TooltipContent side={side} align={align}>
+                  {`${side} / ${align}`}
+                </TooltipContent>
+              </Tooltip>
+            )),
+          )}
+        </div>
+      </TooltipProvider>
+    );
+  },
+};
+
+/** 显示尖角箭头。 */
+export const WithArrow: Story = {
+  render: () => (
+    <TooltipProvider>
+      <div className="flex items-center gap-4">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>带箭头</Button>
+          </TooltipTrigger>
+          <TooltipContent>
+            提示内容
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>反色 + 箭头</Button>
+          </TooltipTrigger>
+          <TooltipContent variant="inverse">
+            深色提示
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+/** 四个方向的箭头 — 箭头随 side 自动朝向 trigger。 */
+export const ArrowSides: Story = {
+  render: () => (
+    <TooltipProvider delayDuration={0}>
+      <div className="grid grid-cols-2 place-items-center gap-16 p-12">
+        <Tooltip open>
+          <TooltipTrigger asChild>
+            <Button>side=top</Button>
+          </TooltipTrigger>
+          <TooltipContent side="top">
+            top
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+        <Tooltip open>
+          <TooltipTrigger asChild>
+            <Button>side=bottom</Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">
+            bottom
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+        <Tooltip open>
+          <TooltipTrigger asChild>
+            <Button>side=left</Button>
+          </TooltipTrigger>
+          <TooltipContent side="left">
+            left
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+        <Tooltip open>
+          <TooltipTrigger asChild>
+            <Button>side=right</Button>
+          </TooltipTrigger>
+          <TooltipContent side="right">
+            right
+            <TooltipArrow />
+          </TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+  ),
+};
+
+/** 自定义触发延时。 */
+export const Delay: Story = {
+  render: () => (
+    <TooltipProvider delayDuration={500}>
+      <div className="flex items-center gap-4">
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button>500ms</Button>
+          </TooltipTrigger>
+          <TooltipContent>跟随 Provider 的延时</TooltipContent>
+        </Tooltip>
+        <Tooltip delayDuration={0}>
+          <TooltipTrigger asChild>
+            <Button>立即</Button>
+          </TooltipTrigger>
+          <TooltipContent>覆盖为 0ms</TooltipContent>
+        </Tooltip>
+      </div>
+    </TooltipProvider>
+  ),
+};