# Tooltip

文字提示气泡框，鼠标悬浮时显示简短文案说明。

## 适用场景

- 图标按钮的 title 提示（替代浏览器默认 title）
- 字段名称或操作的补充解释说明
- 溢出省略文本的完整内容展示
- 需要程序化控制显示/隐藏的提示气泡

## Props

| 名称 | 类型 | 默认值 | 必填 | 说明 |
|------|------|--------|------|------|
| className | `string` | `""` | 否 | 自定义 class |
| content | `ReactNode` | `-` | 否 | 气泡内容 |
| reverseColor | `boolean` | `false` | 否 | 是否为反色（黑底白字） |
| type | `"hover" \| "click" \| "focus"` | `"hover"` | 否 | 触发方式 |
| visible | `boolean` | `-` | 否 | 是否显示（控制值） |
| target | `(() => HTMLElement \| null \| void) \| HTMLElement \| null` | `-` | 否 | 指定 popper 的目标元素，不接受 ReactNode |
| defaultVisible | `boolean` | `-` | 否 | 是否显示的默认值 |
| onChange | `(visible: boolean, e?: Event \| SyntheticEvent) => void` | `-` | 否 | visible 变化回调 |
| beforeChange | `(visible: boolean) => boolean \| void \| Promise<unknown>` | `-` | 否 | visible 变化前的回调。返回 `false` 阻止变化，返回 Promise 则 resolve 后变化 |
| mouseEnterDelay | `number` | `-` | 否 | mouseEnter 延迟触发（ms） |
| mouseLeaveDelay | `number` | `-` | 否 | mouseLeave 延迟触发（ms） |
| focusDelay | `number` | `-` | 否 | focus 延迟触发（ms） |
| blurDelay | `number` | `-` | 否 | blur 延迟触发（ms） |
| shouldHideParent | `boolean` | `-` | 否 | 是否在隐藏时同时隐藏 parent |
| shouldHideOnMousedownDocument | `boolean \| ((e: Event) => boolean)` | `-` | 否 | 对于 `type="click"`，点击 popper 外部时是否隐藏。设为 `false` 可禁用此行为 |
| placement | `Placement` | `-` | 否 | 浮层相对于 target 的位置 |
| arrowOffset | `number \| "auto"` | `-` | 否 | 箭头偏移量，仅在 placement 为 `*-end` / `*-start` 时有效 |
| withArrow | `boolean` | `-` | 否 | 是否显示箭头 |

## 典型用法

### 基础用法

```tsx
import { Tooltip, Button, Icon } from '@befe/brick'
import { SvgEdit, SvgSignQuestion } from '@befe/brick-icon'

// 图标按钮 title 提示
<Tooltip content="编辑">
    <Button size="xl" icon={SvgEdit} type="plain" />
</Tooltip>

// 字段解释
<div>
    单元出价
    <Tooltip content="单元出价的解释">
        <Icon svg={SvgSignQuestion} style={{ fontSize: 14 }} />
    </Tooltip>
</div>

// 白底（默认）
<Tooltip content="说明文字">
    <Button type="normal">触发位置</Button>
</Tooltip>

// 黑底反色
<Tooltip reverseColor content="说明文字">
    <Button type="normal">触发位置</Button>
</Tooltip>

// 无箭头
<Tooltip content="说明文字" withArrow={false}>
    <Button type="normal">触发位置</Button>
</Tooltip>
```

### 位置

```tsx
<Tooltip placement="top-start" content="提示">...</Tooltip>
<Tooltip placement="top" content="提示">...</Tooltip>
<Tooltip placement="right" content="提示">...</Tooltip>
<Tooltip placement="bottom-end" content="提示">...</Tooltip>
```

### 受控模式

```tsx
import { useRef, useState } from 'react'

const [visible, setVisible] = useState(true)
const refTarget = useRef<HTMLButtonElement>(null)

<Tooltip
    content={
        <div>
            <span>重要信息</span>
            <Button type="plain" color="brand" onClick={() => setVisible(false)}>已阅</Button>
        </div>
    }
    visible={visible}
    type="click"
    target={() => refTarget.current}
    onChange={v => console.log('visible change', v)}
>
    <Button refHTMLElement={refTarget} onClick={() => setVisible(true)}>
        重要信息！
    </Button>
</Tooltip>
```

## 注意事项

- Tooltip 主要用于 hover 时显示纯文本说明；更复杂的浮层内容请使用 Popover
- `target` 不接受 ReactNode，只接受 HTMLElement 或返回 HTMLElement 的函数
- 以下 props 名已变更（旧名已废弃）：`mouseEnterDelayInMS` → `mouseEnterDelay`，`mouseLeaveDelayInMS` → `mouseLeaveDelay`，`focusDelayInMS` → `focusDelay`，`blurDelayInMS` → `blurDelay`
- `beforeChange` 可用于拦截 visible 变化：返回 `false` 阻止，返回 Promise 则异步确认后再变化