Tooltip

import type { ReactElement } from 'react'
import { Button, Tooltip, TooltipPopup, TooltipTrigger } from '@gedatou/cadenza-ui'

Base UI 的 Tooltip 穿上 base-nova 皮肤。seam 只改了一件事：shadcn 的 TooltipContent 其实是 Base UI 的 Portal → Positioner → Popup（外加箭头）折成 一个部件，本库公开面按 Base UI 的平铺命名，所以它叫 TooltipPopup —— 跟 Dialog 把 DialogContent 改成 DialogPopup 是同一条 规则。四个定位 prop（side / sideOffset / align / alignOffset）留在 popup 上；要更多定位控制就直接组合 @base-ui/react/tooltip。

改名不改的是 data-slot：popup 仍标 tooltip-content。原因是 Kbd 的样式靠 in-data-[slot=tooltip-content] 在气泡里反色， 而 primitives 逐字节钉死 —— 这个槽名是要守的契约。

使用#

复制import { Tooltip, TooltipPopup, TooltipTrigger } from '@gedatou/cadenza-ui'

复制<Tooltip>
  <TooltipTrigger render={<Button variant="outline" />}>Hover</TooltipTrigger>
  <TooltipPopup>Add to library</TooltipPopup>
</Tooltip>

组成#

复制Tooltip
├── TooltipTrigger
└── TooltipPopup

TooltipProvider 是可选的第四件：包住一组 tooltip 共享一个打开延迟 （vendored 默认 delay={0}，即成组的气泡即刻弹出）。不包时每个触发器自己计时， Base UI 的默认是 600 ms；触发器自己的 delay 两种情况下都优先。

方向#

side 决定气泡贴在触发器的哪一边，箭头跟着走。

import type { ReactElement } from 'react'
import { Button, Tooltip, TooltipPopup, TooltipTrigger } from '@gedatou/cadenza-ui'

side 收六个值：'top' | 'bottom' | 'left' | 'right' | 'inline-start' | 'inline-end'， 后两个按书写方向解析。配套三个微调：sideOffset（离触发器的距离，默认 4）、 align（'start' | 'center' | 'end'，默认 'center'）、alignOffset（默认 0）。 空间不够时 Base UI 自动翻面，最终落点写在 data-side 上（见状态与 className）。

键盘快捷键#

气泡里放一个 Kbd，它自己会反色。

import type { ReactElement } from 'react'
import { Button, Kbd, Tooltip, TooltipPopup, TooltipTrigger } from '@gedatou/cadenza-ui'

反色不靠任何 prop：Kbd 的样式钩在 popup 的 tooltip-content 槽上，这也是 seam 不动 data-slot 的原因。

禁用按钮#

禁用的按钮不发指针事件，要给它挂 tooltip 就用一个 span 当触发器。

import type { ReactElement } from 'react'
import { Button, Tooltip, TooltipPopup, TooltipTrigger } from '@gedatou/cadenza-ui'

render={<span className="inline-flex" />} 把触发器换成 span、按钮放进去当 children；span 收到 hover，按钮照旧禁用。

状态与 className#

className 在 TooltipTrigger 和 TooltipPopup 上都是双形态：字符串，或 (state) => string 的函数。下表左列是挂在 DOM 上的 data-*，Tailwind 直接当变体写 （data-open:animate-in）；右列是同一个状态在函数 className 里的名字。

hover / focus 不写 data 属性，用 CSS 伪类。

需要从外部定位时用 data-slot：

键盘交互#

Props#

顺序规则：必填 → 非受控默认值 → 受控值 → 回调 → 行为开关 → 外观 → className。

Tooltip#

根部件，不渲染元素，管开合状态。

复制<Tooltip onOpenChange={(open, details) => details.reason === 'trigger-focus' && details.cancel()}>

TooltipTrigger#

渲染 <button>；用 render 换成别的元素。

复制<TooltipTrigger render={<Button variant="outline" />} delay={200}>Hover</TooltipTrigger>

TooltipPopup#

气泡本体；内部渲染 Portal、Positioner、Popup 与箭头。

复制<TooltipPopup side="right" className={({ open }) => (open ? 'opacity-100' : 'opacity-0')}>Tip</TooltipPopup>

TooltipProvider#

可选；共享一组 tooltip 的延迟。

复制<TooltipProvider delay={300}>{children}</TooltipProvider>

7 个类型一并导出：TooltipProps / TooltipChangeEventDetails / TooltipTriggerProps / TooltipTriggerState / TooltipPopupProps / TooltipPopupState / TooltipProviderProps。