@antadesign/anta 0.3.33 → 0.3.35

package/docs/components/tooltip.md

@@ -1,169 +1,260 @@
 # Tooltip
 
-A small floating bubble that describes the element it's placed inside. Render
-`<Tooltip>` as a child of the element it annotates — it doesn't affect that
-element's layout, and its content can be anything.
-
-It shows on hover (after a short `delay`) and on keyboard focus, and dismisses
-on mouse leave, blur, Esc, or when the anchor scrolls away. On touch
-devices — where there's no hover and a tap shouldn't surface it — it opens on
-**press-and-hold** and lingers briefly after you lift, so it stays readable. By
-default the bubble is **pinned** under the anchor; pass `follow` to make it
-**track the cursor** (fading out as the cursor moves away), or `interactive` to
-make it hoverable and clickable (for content like links).
-
-When the anchor implements **`getAnchorRect(): DOMRect`**, the bubble positions
-against that rect instead of the anchor's full box. Anta's `Input` reports its
-field box, so a tooltip on an `<Input>` points at the field, not the surrounding
-label or hint.
+Use Tooltip for supplementary explanations and the full text of clipped labels.
+Place it inside the element it describes. It takes no space in that element's
+layout. Keep essential instructions and actions available without a tooltip.
 
 ## Examples
 
+Hover Status for a text explanation, focus the underlined button with Tab,
+follow the cursor, or enter the interactive bubble to use its link.
+
 ```tsx
-// Place <Tooltip> inside the element it describes; hover or focus the anchor.
-// Pinned under the anchor by default — prefer the top side here (auto-flips
-// down when there's no room).
-<span style={{ cursor: 'help' }}>
-  Status
-  <Tooltip placement="top">Last checked 2 minutes ago</Tooltip>
-</span>
-
-// A near-instant tooltip on a keyboard-focusable button. Never use delay={0} — use ~50.
-<Button priority="tertiary" underline="dashed" label="Focus me with the keyboard">
-  <Tooltip delay={50}>Shows on focus, dismiss with Esc</Tooltip>
-</Button>
+<div style={{ display: 'flex', gap: '16px', alignItems: 'center', flexWrap: 'wrap' }}>
+  <span style={{ cursor: 'help', display: 'inline-flex', alignItems: 'center', gap: '4px' }}>
+    <span>Status</span>
+    <Icon shape="info" size={16} style={{ color: 'var(--text-5)' }} />
+    <Tooltip placement="top">Last checked 2 minutes ago</Tooltip>
+  </span>
+  <Button priority="tertiary" underline="dashed" label="Focus me with the keyboard">
+    <Tooltip delay={50}>Shows on focus, dismiss with Esc</Tooltip>
+  </Button>
+  <Button label="Follow the cursor">
+    <Tooltip follow>Tracks the pointer, fades as you leave</Tooltip>
+  </Button>
+  <Button label="Interact">
+    <Tooltip interactive placement="top">
+      See the <a href="/install/">full guide</a> for details
+    </Tooltip>
+  </Button>
+</div>
+```
 
-// `follow` tracks the cursor and fades by distance as you move away.
-<Button label="Follow the cursor">
-  <Tooltip follow>Tracks the pointer, fades as you leave</Tooltip>
-</Button>
+## Hover and keyboard focus
 
-// Rich content — render anything.
-<Button icon="info">
-  <Tooltip placement="top">
-    <strong>Heads up</strong> — this action can't be undone
-  </Tooltip>
+Hover the button or reach it with Tab to show its explanation after a delay.
+Escape dismisses it. Leaving the anchor, moving focus away, or scrolling also
+closes it. On touch screens, hold the anchor for 500ms; a quick tap does not open
+it. After release, a touch tooltip remains for 1.5 seconds.
+
+Give the trigger an accessible name independently. Put explanations that should
+be available before opening on the trigger with authored ARIA. Here,
+`aria-description` supplies the short description in both open and closed states.
+
+```tsx
+<Button label="Publish" aria-description="Makes the draft public">
+  <Tooltip id="publish-tooltip" delay={50}>Makes the draft public</Tooltip>
 </Button>
+```
+
+## Placement
 
-// Interactive: the bubble becomes hoverable + clickable, so its content
-// (links, buttons) works. Always pinned — a bubble that follows the cursor
-// can't be entered, so `interactive` ignores `follow`. Move from the anchor
-// into the bubble to click; press Esc to dismiss.
-<Button label="Interact">
-  <Tooltip interactive placement="top">
-    See the <a href="/guide">full guide</a> for details
+Choose `top` or `left` to prefer another side. Tooltip flips when that side has
+insufficient room and keeps the bubble within the viewport.
+
+```tsx
+<Button label="Below"><Tooltip>Below the anchor</Tooltip></Button>
+<Button label="Above"><Tooltip placement="top">Above the anchor</Tooltip></Button>
+<Button label="Beside"><Tooltip placement="left">Beside the anchor</Tooltip></Button>
+```
+
+## Follow the cursor
+
+Use `follow` for explanations attached to a larger pointer target. The bubble
+tracks the cursor and fades with distance as the pointer leaves. Moving between
+two `follow` anchors skips the next delay while the previous tooltip is open or
+within its 300ms grace period. Pinned tooltips keep their configured delay.
+Keyboard and touch openings stay anchored to the target.
+
+```tsx
+<Button label="First"><Tooltip follow>First explanation</Tooltip></Button>
+<Button label="Second"><Tooltip follow>Second explanation</Tooltip></Button>
+```
+
+## Interactive content
+
+Pass `interactive` to enter the bubble with the pointer or keyboard and use its
+content. It stays pinned even when `follow` is present. Move from the trigger to
+the link, or focus the trigger and press Tab. Escape dismisses the bubble.
+
+This option preserves Tooltip's existing tooltip semantics. The ARIA tooltip
+pattern describes nonfocusable content; use Menu or Dialog for essential actions
+that need an explicit trigger and popup semantics.
+
+```tsx
+<Button label="Help" aria-description="Read the installation guide for setup details">
+  <Tooltip id="help-tooltip" interactive placement="top">
+    Read the <a href="/install/">installation guide</a>.
   </Tooltip>
 </Button>
 ```
 
-The underlying `<a-tooltip>` works in plain HTML too, as a child of any element:
+## Show only when truncated
 
-```html
-<button>
-  Publish
-  <a-tooltip>Makes the draft public</a-tooltip>
-</button>
+Use `truncatedOnly` when the explanation repeats a label. A label that fits does
+not open a bubble. Hover both labels to compare a clipped target with one that
+fits.
+
+```tsx
+<div style={{ display: 'flex', gap: '28px', alignItems: 'flex-start', flexWrap: 'wrap' }}>
+  <span style={{ display: 'inline-block', maxWidth: '130px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', cursor: 'help' }}>
+    A long label that gets truncated
+    <Tooltip truncatedOnly>A long label that gets truncated</Tooltip>
+  </span>
+  <span style={{ display: 'inline-block', cursor: 'help' }}>
+    Short label
+    <Tooltip truncatedOnly>Short label</Tooltip>
+  </span>
+</div>
 ```
 
-### Adjacent and nested tooltips
+Text with `truncate` already creates an automatic tooltip for clipped,
+non-expandable content.
+
+```tsx
+<Text truncate style={{ maxWidth: '160px' }}>
+  A long release title that does not fit in this space
+</Text>
+<Text truncate>Short title</Text>
+```
 
-Only one tooltip shows at a time. Moving between **adjacent** anchors with
-`follow` tooltips hands off cleanly — the outgoing bubble cross-fades out as the
-next fades in (no blink). If either tooltip does not have `follow`, the next
-tooltip waits for its configured delay. With `follow` tooltips (used below to
-show it), the outgoing bubble also keeps
-trailing the cursor and fades by distance from its anchor (transparent by ~100px
-away), so a near hop reads as a smooth cross-fade and a far one is already gone.
-With **nested** anchors, the inner (descendant) tooltip wins while you're over
-it, and the outer takes back over when you leave. Hover the examples to feel it.
+Nest your own Tooltip inside Text to replace its automatic explanation. An empty
+explicit Tooltip suppresses the automatic one.
 
 ```tsx
-// Adjacent — moving from one to the next cross-fades, no blink. `follow` adds
-// the cursor-trailing + distance fade so the hand-off is most visible.
-<Button label="First"><Tooltip follow>First tooltip</Tooltip></Button>
-<Button label="Second"><Tooltip follow>Second tooltip</Tooltip></Button>
-
-// Nested — wrap stray text in a <span> so the tooltip stays a direct child of
-// the box (its anchor). The inner tooltip wins while you're over the inner button.
-<div tabIndex={0}>
-  <span>Outer box</span>
-  <Tooltip follow>Outer tooltip</Tooltip>
-  <Button label="Inner button"><Tooltip follow>Inner tooltip</Tooltip></Button>
-</div>
+<Text truncate style={{ maxWidth: '160px' }}>
+  A long release title with a custom explanation
+  <Tooltip>This release includes keyboard navigation improvements.</Tooltip>
+</Text>
 ```
 
-### Show only when truncated
+## Adjacent and nested tooltips
 
-Pass **`truncatedOnly`** and the tooltip appears only when its target's text is
-actually ellipsized — a label that fits gets no tooltip. The check is a UI-thread
-layout read, re-measured on each hover (so resizing the container flips it live). By
-default it measures the nearest Anta ellipsizing label (`a-tab-label` /
-`a-button-label`) inside the anchor, then the anchor itself; point it elsewhere with
-**`truncatedSelector`**. Hover both — only the clipped one reveals its full text:
+One tooltip is open per document. A tooltip on a nested anchor takes precedence
+while that anchor is active. Returning to the outer anchor makes its explanation
+available again.
 
 ```tsx
-{/* Only the clipped span shows a tooltip. The anchor IS the clipping box here,
-    so no selector is needed; inside a tab or <Button> the default finds the label. */}
-<span style={{ maxWidth: 130, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
-  A long label that gets truncated
-  <Tooltip truncatedOnly>A long label that gets truncated</Tooltip>
-</span>
+<div style={{ display: 'flex', gap: '40px', alignItems: 'flex-start', flexWrap: 'wrap' }}>
+  <div style={{ display: 'flex', gap: '12px' }}>
+    <Button label="First"><Tooltip follow>First tooltip</Tooltip></Button>
+    <Button label="Second"><Tooltip follow>Second tooltip</Tooltip></Button>
+  </div>
+  <div tabIndex={0} aria-label="Outer box" style={{ padding: '20px', border: '1px dashed var(--border-4)', borderRadius: '6px', cursor: 'help' }}>
+    <span>Outer box</span>
+    <Tooltip follow>Outer tooltip</Tooltip>
+    <div style={{ marginTop: '12px' }}>
+      <Button label="Inner button"><Tooltip follow>Inner tooltip</Tooltip></Button>
+    </div>
+  </div>
+</div>
 ```
 
-### Empty tooltips
+## Content and shape
 
-A tooltip with nothing to show — no element children and no non-whitespace text —
-doesn't open, so `<Tooltip>{maybeEmpty}</Tooltip>` never flashes a blank bubble. This
-is automatic (no prop) and re-checked on each hover, so a tooltip whose content
-arrives later works normally; a bubble whose content is cleared while it's open
-closes itself. Content that's a single icon or image (an element, no text) still
-shows.
+Content can include text, icons, and markup. An empty or whitespace-only tooltip
+does not open. Clearing an open tooltip's content closes it; subsequent content
+is available on the next interaction. Use `round` for a softer shape.
+
+```tsx
+<Button label="Release status">
+  <Tooltip round><strong>Healthy</strong> · Checked two minutes ago</Tooltip>
+</Button>
+<Button icon="info" aria-label="Action details">
+  <Tooltip placement="top"><strong>Heads up</strong> · This action cannot be undone</Tooltip>
+</Button>
+<Button label="No explanation"><Tooltip>{''}</Tooltip></Button>
+```
 
 ## Component props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children?` | ReactNode | — | Tooltip content. Renders anything — text, markup, an icon + text. Lives in the light DOM, so it's styleable with your own plain CSS. |
-| `delay?` | number | 300 | Show delay in milliseconds after hover / focus. Never use `0` — use ~`50` for a near-instant tooltip (0 has caused issues in practice). |
+| `children?` | ReactNode | — | Supplementary text or markup. Content stays in light DOM for application CSS. |
+| `delay?` | number | 300 | Wait in milliseconds after hover or keyboard focus. Use `50` for a short delay. |
 | `follow?` | boolean | — | Follow the cursor instead of pinning under the anchor. The bubble is pinned (anchored beneath the target) by default; pass `follow` for the cursor-tracking behavior, which fades by distance as the cursor leaves. |
-| `interactive?` | boolean | — | Make the bubble hoverable and clickable — enables pointer events and keeps it open while the cursor is over it, so its content (links, buttons) can be interacted with. Always pinned (an interactive bubble can't follow the cursor, even with `follow`). |
+| `interactive?` | boolean | — | Keep content available while the pointer or keyboard focus is inside it. Enables pointer events and pins the bubble even with `follow`. Essential actions belong in a Menu or Dialog with an explicit trigger. |
 | `placement?` | 'top' \| 'bottom' \| 'left' | bottom | Which side of the anchor the bubble prefers. Auto-flips to the other side when there isn't room. |
 | `round?` | boolean \| number \| string | — | Round the bubble to a 20px radius (matching a round menu). Pass a `number` (px) or a CSS length string for a custom radius. |
 | `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is ellipsized); a label that fits gets no tooltip. The check is a UI-thread layout read, re-measured on each show. By default it measures every Anta ellipsizing label part inside the anchor, then the anchor itself — override with `truncatedSelector`. |
 | `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements whose overflow decides whether a `truncatedOnly` tooltip shows. |
 
-## Web Component
+`truncatedOnly` measures the anchor's reported truncation or its `a-tab-label`,
+`a-button-label`, and `a-step-hint` regions. `truncatedSelector` selects a different
+measurement target. Measurements are refreshed when opening.
+
+A custom numeric or length `round` prop emits an inline CSS variable. If your CSP
+blocks style attributes, use external `::part(bubble)` CSS for a custom radius.
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
+## Web Component
 
-Place `<a-tooltip>` inside the element it describes.
+Place `a-tooltip` directly inside its anchor. The author owns markup, styles,
+accessible names, and descriptions. Tooltip does not add attributes
+to its anchor or rewrite the supplied content.
 
 ```html
-<a-button role="button" tabindex="0" priority="secondary">
+<a-button role="button" tabindex="0" aria-label="Publish" aria-description="Makes the draft public">
   <a-button-label>Publish</a-button-label>
-  <a-tooltip>Make the draft public</a-tooltip>
+  <a-tooltip id="raw-publish-tooltip">Makes the draft public</a-tooltip>
 </a-button>
 ```
 
+Referencing the Tooltip host with `aria-describedby` does not provide a reliable
+description while its internal popover is hidden. Use an authored
+`aria-description`, or reference separate application-owned descriptive content
+that remains available to assistive technology.
+
+Raw attributes include `delay`, `placement`, `round`, `follow`, `interactive`,
+`truncated-only`, and `truncated-selector`. Boolean attributes use presence.
+An anchor can implement `getAnchorRect(): DOMRect` to advertise a smaller
+positioning region; Input reports its field instead of its label and hint.
+
+Default styles load from the external component stylesheet. Under CSP, allow
+that same-origin stylesheet and the browser entry. Runtime positioning updates
+only Tooltip's owned shadow elements. Input and Menu also load their defaults
+from external CSS. Custom values serialized into HTML style attributes remain
+subject to the [CSP guidance](../install-config.md#content-security-policy).
+
+Reduced motion disables both fades. Older supported browsers can omit parts of
+the native popover transition while retaining the content and interaction.
+
 ## Styling
 
-The bubble lives in shadow DOM and is exposed as a single **part** — style the box
-(background, frost, shadow, radius, padding, a border) with `::part(bubble)`. Its
-*content* is slotted light DOM with a **normalized text baseline** (Anta body
-typography), so it ignores the anchor's styling; to restyle the text, put a class on
-the content you pass to `<Tooltip>` and target that (a rule on the content wins over
-the baseline). Both together — hover the button to see it; the classes are just for
-the demo:
+Style the visible surface with `::part(bubble)`. Supplied content remains in light
+DOM, so application selectors can style its text. `::part(container)` reaches
+the outer popover and its opening/closing transition. Keep its positioning and
+pointer behavior intact when changing appearance.
+
+The classes below identify this demonstration; use your own selectors.
 
 ```css
-/* the bubble box — a shadow part */
-a-tooltip.fancy::part(bubble) {
+a-tooltip.custom-tooltip::part(bubble) {
   background: #1a161d;
   border-radius: 10px;
   padding: 8px 12px;
-  box-shadow: 0 4px 18px rgba(0, 0, 0, 0.35);
-  backdrop-filter: none;            /* opt out of the frost */
+  box-shadow: 0 4px 18px color-mix(in oklch, black 35%, transparent);
+  backdrop-filter: none;
+}
+.custom-tooltip-text {
+  color: #fff;
+  font-size: 15px;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+}
+```
+
+## Example
+
+```tsx
+import { Tooltip, Button } from '@antadesign/anta'
+
+function Demo() {
+  return (
+    <div className="container">
+      <Button label="Hover me">
+        <Tooltip delay={300}>Edit my props or code</Tooltip>
+      </Button>
+    </div>
+  )
 }
-/* the slotted content — a class on what you pass to <Tooltip> */
-.tip-rich { color: #fff; font-size: 15px; font-weight: 600; letter-spacing: 0.01em; }
 ```