components/tooltip/tooltip.ts

Functions

Imports

It imports components/popover/popover.ts. Imported by components/admin-shell/admin-shell.react.tsx, components/admin-shell/admin-shell.ts, components/admin-shell/examples.tsx, components/site-header/site-header-parts.react.tsx, components/site-header/site-header.ts, components/theme-switch/theme-switch.react.tsx, components/theme-switch/theme-switch.ts, components/tooltip/tooltip.react.tsx.

Source

1// A tooltip: extra detail about a control, never the only place its label appears. It is the
2// shared popover's tooltip variant (components/popover): the Popover API (popover="manual",
3// role="tooltip"), shown on hover after 300 ms (at once when another tip is open or has just
4// closed) and on keyboard focus, hidden on Esc, on blur and when the pointer leaves, and the
5// pointer can move onto it without it closing (WCAG 1.4.13: dismissible, hoverable,
6// persistent). This module keeps the 0.1 contract on top of it: a trigger names its tip with
7// data-cap-tip="<id>", and attach(trigger, tip) wires one pair.
8import { attach as attachPopover, close, open } from "../popover/popover.ts";
9
10export { HIDE_GRACE_MS, SHOW_DELAY_MS, place, supportsAnchor } from "../popover/popover.ts";
11
12const tips = new WeakMap<HTMLElement, HTMLElement>();
13
14// Wires one trigger to its tip: the tip gets the popover surface (cap-popover, the tooltip
15// variant), popover="manual" and role="tooltip", and the trigger aria-describedby. Returns a
16// function that unwires it.
17export function attach(trigger: HTMLElement, tip: HTMLElement): () => void {
18  tip.classList.add("cap-popover");
19  tip.dataset.variant ??= "tooltip";
20  if (!tip.hasAttribute("popover")) tip.setAttribute("popover", "manual");
21  if (!tip.getAttribute("role")) tip.setAttribute("role", "tooltip");
22  tips.set(trigger, tip);
23  const detach = attachPopover(trigger, tip);
24  return () => {
25    detach();
26    tips.delete(trigger);
27  };
28}
29
30// Shows or hides the tip of a trigger that is attached.
31export function showTip(trigger: HTMLElement): void {
32  const tip = tips.get(trigger);
33  if (tip) open(tip);
34}
35export function hideTip(trigger: HTMLElement): void {
36  const tip = tips.get(trigger);
37  if (tip) close(tip);
38}
39
40// Attaches to every [data-cap-tip] trigger under root not yet attached; the attribute's
41// value is the id of its tip. Returns a function that detaches.
42export function enhance(root: ParentNode = document): () => void {
43  const undo: Array<() => void> = [];
44  for (const trigger of root.querySelectorAll<HTMLElement>("[data-cap-tip]:not([data-cap-ready])")) {
45    const tip = document.getElementById(trigger.dataset.capTip ?? "");
46    if (!tip) continue;
47    trigger.dataset.capReady = "";
48    const detach = attach(trigger, tip);
49    undo.push(() => {
50      detach();
51      delete trigger.dataset.capReady;
52    });
53  }
54  return () => undo.forEach((f) => f());
55}