Tooltip (am-tooltip)

am-tooltip 補充簡短說明。必要資訊應直接顯示在畫面上，不要只藏在 tooltip 裡；需要放入連結或操作時，改用 Dialog。

使用與預覽

先依安裝指南引入 tokens 與元件樣式，再使用下方完整範例。把滑鼠移到按鈕或文字上，也可以使用 Tab 聚焦。

以滑鼠或鍵盤顯示提示，按 Escape 關閉。

查看程式碼可複製完整範例

---
import Button from "@astromer/core/components/Button.astro";
import Tooltip from "@astromer/core/components/Tooltip.astro";
---
<div style="display: flex; flex-wrap: wrap; align-items: center; gap: 0.75rem;">
  <Tooltip content="會保留目前頁面的設定。" placement="top" delay={200}>
    <Button variant="outline">儲存設定</Button>
  </Tooltip>
  <Tooltip content="以 CSS 處理版面與外觀，必要時才加入互動腳本。" placement="bottom" delay={200}>
    <span>CSS-first 是什麼？</span>
  </Tooltip>
</div>

Props

Prop	型別／可用值	預設	用途
`content`	`string`	必填	純文字提示，不接受互動內容
`placement`	`top`、`bottom`、`left`、`right`	`top`	提示相對於觸發器的位置
`delay`	`number`	`700`	顯示前等待時間，單位毫秒
`closeDelay`	`number`	`0`	關閉延遲，實際至少保留 100ms 移動緩衝
`class`	`string`	未設定	附加到 trigger wrapper 的 class

預設 slot 放一個有清楚名稱的觸發器，例如 Button 或文字。不要把多個互不相關的操作包在同一個 Tooltip 中。

互動與狀態

Hover 或 focus 後顯示；滑鼠停留於觸發器或提示內容、或觸發器仍有焦點時保持顯示。
Escape 會立即關閉；移開滑鼠／焦點後再次進入可重新顯示。
可聚焦子元素會合併 aria-describedby，保留既有描述；純文字 slot 的 wrapper 會加入 Tab 順序。
原生 disabled 按鈕無法聚焦，停用原因應使用旁邊的可見文字說明。

定位與限制

目前使用 popover="manual" 與小型腳本控制開關，透過 getBoundingClientRect() 做四向定位。不支援 -start／-end 對齊、自動翻轉或邊界修正；靠近畫面邊緣時，請選擇能容納內容的方向。Tooltip 不是點擊開關的觸控選單。

CSS Anchor Positioning 是後續可考慮的增強，不是目前正式定位路徑。

查看 Tooltip Playground。