# useTooltip

## 使用方法

悬停 / 聚焦触发的文字提示。它在 `useLayer` 之上加了悬停意图、键盘焦点处理和 `aria-describedby` 关联。触发器形态特殊、不想套外壳组件时用它。

```ts
import { useTooltip } from '@astryx-vue/core/Tooltip'
```

把 `triggerRef` 绑到要用提示的元素上：hook 会挂指针和焦点事件，并把自己的 ID 追加到 `aria-describedby`（元素原有的 ID 保留）。气泡自己渲染，把 `contentProps` 摊上去：

```vue
<script setup lang="ts">
import { useTooltip } from '@astryx-vue/core/Tooltip'

const tooltip = useTooltip({ delay: 120 })
</script>

<template>
  <button :ref="tooltip.triggerRef" type="button">
    Hover me
  </button>
  <Teleport to="body">
    <div
      v-show="tooltip.isOpen"
      :ref="tooltip.contentRef"
      v-bind="tooltip.contentProps"
      :style="tooltip.contentStyle"
    >
      Helpful text
    </div>
  </Teleport>
</template>
```

`contentProps` 里有 `role="tooltip"`、ID，以及指针移入气泡时保持显示的处理函数。气泡的 `position: fixed` 由你自己写，`contentStyle` 只给量出来的坐标。

## 建议

| 指引 | 做法 |
| --- | --- |
| Do | 图标按钮、被截断的文字、缩写、紧凑控件这类很短的文字说明用它。 |
| Do | 标准的包裹式用法优先用 `Tooltip` 组件；触发器不是简单子元素时再用 hook。 |
| Don't | 不要往提示里放交互内容：那种场景用 `Popover` 或 `HoverCard`。 |

## 示例

用 `useTooltip` 搭提示，开关完全由代码控制。

### Tooltip — Hook Usage

用 useTooltip 搭提示，开关完全由代码控制。

```vue
<script setup lang="ts">
import { useTooltip } from '@astryx-vue/core/Tooltip'

const tooltip = useTooltip({ placement: 'above', delay: 120 })
const { isOpen, contentStyle, contentProps } = tooltip
</script>

<template>
  <div class="hook-tooltip">
    <button :ref="tooltip.triggerRef" type="button" class="hook-tooltip__trigger">
      Hover or focus me
    </button>

    <Teleport to="body">
      <div
        v-show="isOpen"
        :ref="tooltip.contentRef"
        v-bind="contentProps"
        class="hook-tooltip__bubble"
        :style="contentStyle"
      >
        Tooltip content from useTooltip
      </div>
    </Teleport>
  </div>
</template>

<style scoped>
.hook-tooltip {
  display: flex;
  justify-content: center;
}

.hook-tooltip__trigger {
  padding: 8px 16px;
  border: 1px dashed var(--astryx-color-border, #d4d4d4);
  border-radius: var(--astryx-radius-control, 8px);
  background: var(--astryx-color-background-surface, #fff);
  color: var(--astryx-color-text-primary, #171717);
  font: inherit;
  font-size: 0.875rem;
  cursor: pointer;
}

.hook-tooltip__bubble {
  position: fixed;
  z-index: 1000;
  max-width: 16rem;
  padding: 6px 10px;
  border-radius: var(--astryx-radius-control, 8px);
  background: var(--astryx-color-text-primary, #171717);
  color: var(--astryx-color-text-inverse, #fff);
  font-size: 0.75rem;
  line-height: 1.4;
  pointer-events: auto;
}
</style>
```

## 参数

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `placement` | `'above' \| 'below' \| 'start' \| 'end' \| MaybeRefOrGetter` | `'above'` | 相对触发器的方位。逻辑方向：`start` / `end` 在 RTL 下自动镜像。空间不够时翻到对面。 |
| `alignment` | `'start' \| 'center' \| 'end' \| MaybeRefOrGetter` | `'center'` | 沿方位轴的对齐方式。 |
| `delay` | `number \| MaybeRefOrGetter` | `200` | 悬停多久才显示，单位毫秒。 |
| `hideDelay` | `number \| MaybeRefOrGetter` | `0` | 指针或焦点离开后多久隐藏，单位毫秒。`0` 表示走内部 100 毫秒的桥接时间。 |
| `focusTrigger` | `'auto' \| 'always' \| 'never' \| MaybeRefOrGetter` | `'auto'` | 焦点何时打开提示。`auto` 只给本来就能聚焦的元素挂焦点监听。 |
| `touchTrigger` | `'auto' \| 'tap' \| 'none' \| MaybeRefOrGetter` | `'auto'` | 没有 hover 的触摸设备上轻点做什么。`auto` 在触发器自己有动作时不打开；`tap` 总是打开；`none` 从不打开。 |
| `isEnabled` | `boolean \| MaybeRefOrGetter` | `true` | 是否启用悬停与焦点触发。 |
| `isOpen` | `boolean \| undefined \| MaybeRefOrGetter` | — | 受控的打开状态。`true` 强制显示，`false` 强制隐藏，`undefined` 交给悬停/焦点管理。 |
| `isDefaultOpen` | `boolean` | `false` | 挂载时是否显示。 |
| `onShow` | `() => void` | — | 提示显示后调用。 |
| `onHide` | `() => void` | — | 提示隐藏后调用。 |

## 返回值

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `isOpen` | `ComputedRef<boolean>` | 提示当前是否显示。受控的 `isOpen` 优先于悬停状态。 |
| `triggerRef` | `Ref` | 触发器元素。用 `:ref` 绑上去，hook 会挂事件和 ARIA 关联。 |
| `contentRef` | `Ref` | 气泡容器。 |
| `id` | `string` | 气泡的唯一 ID。 |
| `anchorId` | `string` | 锚点的 CSS 标识，用于高级定位场景。 |
| `describedBy` | `string` | 要拼进 `aria-describedby` 的 ID。hook 已经写到 `triggerRef` 上了，手写 ARIA 时才需要它。 |
| `contentStyle` | `ComputedRef` | 气泡的内联坐标。 |
| `resolvedPlacement` | `ComputedRef<'above' \| 'below' \| 'start' \| 'end'>` | 考虑空间翻转之后实际生效的方位。 |
| `contentProps` | `ComputedRef<Record<string, unknown>>` | 气泡的属性：`id`、`role="tooltip"`，以及保持显示的指针事件。 |