components/popover/popover.ts

Functions

Imports

It imports no other module of this repo. Imported by components/breadcrumb/breadcrumb.ts, components/markdown-editor/markdown-editor.ts, components/popover/popover.react.tsx, components/select/select.ts, components/site-header/site-header.ts, components/tooltip/tooltip.ts.

Source

1// The popover and the tooltip, on the Popover API. One module, two behaviours picked by the
2// popup's role:
3//   - a click popover (role="dialog", popover="auto"): the trigger toggles it, light dismiss
4//     and Esc close it, focus moves in on open and returns to the trigger on close;
5//   - a tooltip (role="tooltip", popover="manual"): shown on hover after a delay (at once when
6//     another tip is open or just closed) and on keyboard focus, hidden on Esc, blur and
7//     leave, and hoverable (WCAG 1.4.13: dismissible, hoverable, persistent).
8// Placement is CSS anchor positioning where the browser has it (popover.css), checked against
9// the viewport after opening; where it is missing, or the popup would leave the window, `place`
10// computes it from getBoundingClientRect with a flip and a shift. Every dynamic value goes
11// through the CSSOM (apps keep style-src 'self').
12
13export type Side = "top" | "bottom" | "left" | "right" | "inline-start" | "inline-end";
14export type Align = "start" | "center" | "end";
15
16export interface PlaceOptions {
17  side?: Side;
18  align?: Align;
19  // Gap between trigger and popup in px (the arrow's own space is added). Default 4.
20  offset?: number;
21}
22
23export interface Placement {
24  // The side the popup really ended up on, after any flip.
25  side: "top" | "bottom" | "left" | "right";
26  align: Align;
27  x: number;
28  y: number;
29}
30
31export const SHOW_DELAY_MS = 300;
32export const HIDE_GRACE_MS = 150;
33// A tooltip opens at once when another is open or closed less than this long ago.
34export const GROUP_MS = 400;
35const EDGE = 8;
36const ARROW = 4;
37const ARROW_INSET = 12;
38
39export function supportsAnchor(): boolean {
40  return typeof CSS !== "undefined" && CSS.supports("position-area: bottom") && CSS.supports("anchor-name: --x");
41}
42
43const OPPOSITE = { top: "bottom", bottom: "top", left: "right", right: "left" } as const;
44
45function physical(side: Side, rtl: boolean): "top" | "bottom" | "left" | "right" {
46  if (side === "inline-start") return rtl ? "right" : "left";
47  if (side === "inline-end") return rtl ? "left" : "right";
48  return side;
49}
50
51function clamp(n: number, lo: number, hi: number): number {
52  return Math.max(lo, Math.min(n, Math.max(lo, hi)));
53}
54
55function sideOf(popup: HTMLElement): Side {
56  const s = popup.dataset.side as Side | undefined;
57  if (s) return s;
58  return popup.dataset.variant === "tooltip" ? "top" : "bottom";
59}
60
61function alignOf(popup: HTMLElement): Align {
62  const a = popup.dataset.align;
63  return a === "start" || a === "end" ? a : "center";
64}
65
66function offsetOf(popup: HTMLElement): number {
67  const n = Number(popup.dataset.offset);
68  return popup.dataset.offset !== undefined && Number.isFinite(n) ? n : 4;
69}
70
71function setArrow(popup: HTMLElement, side: Placement["side"], along: number): void {
72  const prop = side === "top" || side === "bottom" ? "--cap-arrow-x" : "--cap-arrow-y";
73  const size = side === "top" || side === "bottom" ? popup.offsetWidth : popup.offsetHeight;
74  popup.style.setProperty(prop, `${Math.round(clamp(along, ARROW_INSET, size - ARROW_INSET))}px`);
75}
76
77// The fallback placement. The popup must already be showing (it is measured). Writes
78// --cap-popover-x / --cap-popover-y (and the arrow's --cap-arrow-x / --cap-arrow-y) on the
79// popup, sets data-placed to the side it landed on, and returns where it went.
80export function place(anchor: Element, popup: HTMLElement, options: PlaceOptions = {}): Placement {
81  const rtl = getComputedStyle(popup).direction === "rtl";
82  const want = physical(options.side ?? sideOf(popup), rtl);
83  const align = options.align ?? alignOf(popup);
84  const arrow = popup.querySelector(":scope > .cap-popover-arrow") ? ARROW : 0;
85  const gap = (options.offset ?? offsetOf(popup)) + arrow;
86  const vw = document.documentElement.clientWidth;
87  const vh = window.innerHeight;
88  const r = anchor.getBoundingClientRect();
89  const w = popup.offsetWidth;
90  const h = popup.offsetHeight;
91
92  const room = { top: r.top - EDGE, bottom: vh - r.bottom - EDGE, left: r.left - EDGE, right: vw - r.right - EDGE };
93  const need = want === "top" || want === "bottom" ? h + gap : w + gap;
94  const opp = OPPOSITE[want];
95  const side = room[want] < need && room[opp] > room[want] ? opp : want;
96
97  let x: number;
98  let y: number;
99  if (side === "top" || side === "bottom") {
100    y = side === "bottom" ? r.bottom + gap : r.top - gap - h;
101    // "start" is the leading edge of the trigger in the reading direction.
102    const lead = align === "start" ? !rtl : align === "end" ? rtl : null;
103    x = lead === null ? r.left + (r.width - w) / 2 : lead ? r.left : r.right - w;
104    x = clamp(x, EDGE, vw - w - EDGE);
105    y = clamp(y, EDGE, vh - h - EDGE);
106    setArrow(popup, side, r.left + r.width / 2 - x);
107  } else {
108    x = side === "right" ? r.right + gap : r.left - gap - w;
109    y = align === "start" ? r.top : align === "end" ? r.bottom - h : r.top + (r.height - h) / 2;
110    y = clamp(y, EDGE, vh - h - EDGE);
111    x = clamp(x, EDGE, vw - w - EDGE);
112    setArrow(popup, side, r.top + r.height / 2 - y);
113  }
114  x = Math.round(x);
115  y = Math.round(y);
116  popup.dataset.placedBy = "js";
117  popup.dataset.placed = side;
118  popup.style.setProperty("--cap-popover-x", `${x}px`);
119  popup.style.setProperty("--cap-popover-y", `${y}px`);
120  return { side, align, x, y };
121}
122
123// After CSS anchor positioning has placed the popup: read which side it is on (the CSS may
124// have flipped it), point the arrow at the trigger, and say whether it is inside the window.
125function settle(anchor: Element, popup: HTMLElement): boolean {
126  const a = anchor.getBoundingClientRect();
127  const p = popup.getBoundingClientRect();
128  const rtl = getComputedStyle(popup).direction === "rtl";
129  const want = physical(sideOf(popup), rtl);
130  const side =
131    want === "top" || want === "bottom"
132      ? p.top + p.height / 2 < a.top + a.height / 2
133        ? "top"
134        : "bottom"
135      : p.left + p.width / 2 < a.left + a.width / 2
136        ? "left"
137        : "right";
138  popup.dataset.placed = side;
139  if (side === "top" || side === "bottom") setArrow(popup, side, a.left + a.width / 2 - p.left);
140  else setArrow(popup, side, a.top + a.height / 2 - p.top);
141  const vw = document.documentElement.clientWidth;
142  const vh = window.innerHeight;
143  return p.left >= -1 && p.top >= -1 && p.right <= vw + 1 && p.bottom <= vh + 1;
144}
145
146let anchors = 0;
147
148function isOpen(popup: HTMLElement): boolean {
149  try {
150    return popup.matches(":popover-open");
151  } catch {
152    return false;
153  }
154}
155
156interface Instance {
157  trigger: HTMLElement;
158  popup: HTMLElement;
159  show: () => void;
160  hide: () => void;
161  // Esc: close, and (for a tooltip) stay closed until the pointer leaves or focus moves on.
162  dismiss: () => void;
163}
164
165const instances = new WeakMap<HTMLElement, Instance>();
166let openTip: Instance | null = null;
167let closedAt = -Infinity;
168const openManual = new Set<Instance>();
169
170function onGlobalKey(e: KeyboardEvent): void {
171  if (e.key !== "Escape") return;
172  // Esc closes the topmost thing this module opened, and only that: a dialog around it
173  // stays open. A tooltip goes first (it is the most recent, smallest layer).
174  const target = openTip ?? [...openManual].pop();
175  if (!target) return;
176  e.preventDefault();
177  e.stopPropagation();
178  target.dismiss();
179}
180
181let keyBound = false;
182function bindKey(): void {
183  if (keyBound) return;
184  keyBound = true;
185  document.addEventListener("keydown", onGlobalKey, true);
186}
187
188function focusables(root: HTMLElement): HTMLElement[] {
189  const sel = 'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"]), [contenteditable=""], [contenteditable="true"]';
190  return [...root.querySelectorAll<HTMLElement>(sel)].filter((el) => !el.matches(":disabled, [inert] *, [hidden]") && el.getClientRects().length > 0);
191}
192
193// Moves focus into a click popover: [autofocus], else the first focusable, else the popup.
194function focusInto(popup: HTMLElement): void {
195  const target = popup.querySelector<HTMLElement>("[autofocus]") ?? focusables(popup)[0];
196  if (target) target.focus({ preventScroll: true });
197  else {
198    if (!popup.hasAttribute("tabindex")) popup.setAttribute("tabindex", "-1");
199    popup.focus({ preventScroll: true });
200  }
201}
202
203// Wires a trigger to its popup. The popup's role picks the behaviour. Returns a function that
204// unwires it.
205export function attach(trigger: HTMLElement, popup: HTMLElement): () => void {
206  if (instances.has(popup)) return () => undefined;
207  const tooltip = popup.getAttribute("role") === "tooltip" || (popup.dataset.variant === "tooltip" && !trigger.hasAttribute("popovertarget"));
208  if (!popup.hasAttribute("popover")) popup.setAttribute("popover", tooltip ? "manual" : "auto");
209  if (!popup.id) popup.id = `cap-popover-${++anchors}`;
210  const undo: Array<() => void> = [];
211  const on = <E extends Event>(target: EventTarget, type: string, fn: (e: E) => void, opts?: boolean | AddEventListenerOptions) => {
212    target.addEventListener(type, fn as EventListener, opts);
213    undo.push(() => target.removeEventListener(type, fn as EventListener, opts));
214  };
215
216  // Anchor positioning needs names; the engine can be forced to the JS fallback with
217  // data-engine="js" (used by the tests and by apps that must match old browsers exactly).
218  const css = supportsAnchor() && popup.dataset.engine !== "js";
219  if (css) {
220    const name = `--cap-anchor-${++anchors}`;
221    trigger.style.setProperty("anchor-name", name);
222    popup.style.setProperty("position-anchor", name);
223    popup.style.setProperty("--cap-offset", `${offsetOf(popup)}px`);
224    undo.push(() => {
225      trigger.style.removeProperty("anchor-name");
226      popup.style.removeProperty("position-anchor");
227      popup.style.removeProperty("--cap-offset");
228    });
229  }
230
231  let frame = 0;
232  const reposition = () => {
233    if (frame) return;
234    frame = requestAnimationFrame(() => {
235      frame = 0;
236      if (!isOpen(popup)) return;
237      if (popup.dataset.placedBy === "js") place(trigger, popup);
238      else settle(trigger, popup);
239    });
240  };
241  const watch = (on_: boolean) => {
242    const f = on_ ? window.addEventListener : window.removeEventListener;
243    f.call(window, "scroll", reposition, true);
244    f.call(window, "resize", reposition);
245  };
246  // Runs once the popup is showing: choose the engine, place, and follow scrolling.
247  const placeNow = () => {
248    if (css) {
249      delete popup.dataset.placedBy;
250      if (!settle(trigger, popup)) place(trigger, popup);
251    } else place(trigger, popup);
252    watch(true);
253  };
254
255  let me: Instance;
256  if (tooltip) {
257    if (!popup.getAttribute("role")) popup.setAttribute("role", "tooltip");
258    const described = (trigger.getAttribute("aria-describedby") ?? "").split(/\s+/).filter(Boolean);
259    if (!described.includes(popup.id)) trigger.setAttribute("aria-describedby", [...described, popup.id].join(" "));
260    popup.dataset.variant ??= "tooltip";
261    const delay = Number(popup.dataset.delay ?? trigger.dataset.delay ?? SHOW_DELAY_MS);
262
263    let showTimer: number | undefined;
264    let hideTimer: number | undefined;
265    // After Esc or a press the tip stays hidden until the pointer leaves or focus moves on.
266    let held = false;
267    const hide = () => {
268      window.clearTimeout(showTimer);
269      window.clearTimeout(hideTimer);
270      if (isOpen(popup)) popup.hidePopover();
271    };
272    const show = () => {
273      window.clearTimeout(showTimer);
274      window.clearTimeout(hideTimer);
275      if (held || !popup.isConnected) return;
276      if (openTip && openTip !== me) openTip.hide();
277      if (!isOpen(popup)) {
278        popup.showPopover();
279        placeNow();
280      }
281      openTip = me;
282      bindKey();
283    };
284    me = {
285      trigger,
286      popup,
287      show,
288      hide,
289      dismiss: () => {
290        held = true;
291        hide();
292      },
293    };
294    on(popup, "toggle", (e: Event) => {
295      if ((e as ToggleEvent).newState !== "closed") return;
296      watch(false);
297      if (openTip === me) {
298        openTip = null;
299        closedAt = performance.now();
300      }
301    });
302
303    const hovered = () => trigger.matches(":hover") || popup.matches(":hover");
304    const focused = () => trigger === document.activeElement && trigger.matches(":focus-visible");
305    const later = () => {
306      window.clearTimeout(hideTimer);
307      hideTimer = window.setTimeout(() => {
308        if (!hovered() && !focused()) hide();
309      }, HIDE_GRACE_MS);
310    };
311    on(trigger, "pointerenter", (e: PointerEvent) => {
312      // Touch has no hover: a tip is never needed there, and a press must not open one.
313      if (e.pointerType === "touch") return;
314      window.clearTimeout(hideTimer);
315      if (isOpen(popup)) return;
316      window.clearTimeout(showTimer);
317      if (openTip || performance.now() - closedAt < GROUP_MS) show();
318      else showTimer = window.setTimeout(show, delay);
319    });
320    on(trigger, "pointerleave", () => {
321      window.clearTimeout(showTimer);
322      held = false;
323      later();
324    });
325    on(popup, "pointerenter", () => window.clearTimeout(hideTimer));
326    on(popup, "pointerleave", () => {
327      held = false;
328      later();
329    });
330    // A press on the trigger is an action, not a hover: hide the tip.
331    on(trigger, "pointerdown", () => {
332      held = true;
333      hide();
334    });
335    on(trigger, "focus", () => {
336      if (trigger.matches(":focus-visible")) show();
337    });
338    on(trigger, "blur", () => {
339      held = false;
340      if (!hovered()) hide();
341    });
342  } else {
343    popup.setAttribute("role", popup.getAttribute("role") ?? "dialog");
344    if (popup.getAttribute("role") === "dialog" && !popup.hasAttribute("aria-label") && !popup.hasAttribute("aria-labelledby")) {
345      const title = popup.querySelector<HTMLElement>(".cap-popover-title");
346      if (title) {
347        if (!title.id) title.id = `${popup.id}-title`;
348        popup.setAttribute("aria-labelledby", title.id);
349      } else if (trigger.textContent?.trim()) popup.setAttribute("aria-label", trigger.textContent.trim());
350    }
351    trigger.setAttribute("aria-haspopup", popup.getAttribute("role") === "dialog" ? "dialog" : "true");
352    trigger.setAttribute("aria-expanded", String(isOpen(popup)));
353    const native = trigger instanceof HTMLButtonElement || trigger instanceof HTMLInputElement;
354    if (native) {
355      if (!trigger.hasAttribute("popovertarget")) trigger.setAttribute("popovertarget", popup.id);
356    } else {
357      on(trigger, "click", () => (isOpen(popup) ? hide() : show()));
358    }
359    const manual = popup.getAttribute("popover") === "manual";
360    const hide = () => {
361      if (isOpen(popup)) popup.hidePopover();
362    };
363    const show = () => {
364      if (!isOpen(popup)) popup.showPopover();
365    };
366    me = { trigger, popup, show, hide, dismiss: hide };
367
368    on(popup, "beforetoggle", (e: Event) => {
369      if ((e as ToggleEvent).newState === "open" && css === false) popup.dataset.placedBy = "pending";
370    });
371    on(popup, "toggle", (e: Event) => {
372      const opened = (e as ToggleEvent).newState === "open";
373      trigger.setAttribute("aria-expanded", String(opened));
374      if (opened) {
375        placeNow();
376        if (manual) openManual.add(me);
377        bindKey();
378        focusInto(popup);
379      } else {
380        watch(false);
381        openManual.delete(me);
382        // Focus goes back to the trigger when it was inside the popup (or lost to the page),
383        // never taken from a control the person moved on to.
384        const active = document.activeElement;
385        if (!active || active === document.body || popup.contains(active)) trigger.focus({ preventScroll: true });
386      }
387    });
388    // Moving focus out of the popup (Tab past its last control) closes it, without stealing focus.
389    on(popup, "focusout", (e: FocusEvent) => {
390      const to = e.relatedTarget as Node | null;
391      if (to && !popup.contains(to) && to !== trigger && !(to as Element).closest?.("[popover]:popover-open")) hide();
392    });
393    on(popup, "click", (e: MouseEvent) => {
394      if ((e.target as Element).closest("[data-popover-close]")) hide();
395    });
396    if (manual) {
397      // Outside press for a manual popover; popover="auto" has it natively.
398      on(document, "pointerdown", (e: PointerEvent) => {
399        const t = e.target as Node;
400        if (isOpen(popup) && !popup.contains(t) && !trigger.contains(t)) hide();
401      });
402    }
403  }
404  instances.set(popup, me);
405  return () => {
406    me.hide();
407    undo.forEach((f) => f());
408    instances.delete(popup);
409  };
410}
411
412// Opens a popup (placing it) whether or not it was attached.
413export function open(popup: HTMLElement): void {
414  const inst = instances.get(popup);
415  if (inst) inst.show();
416  else if (!isOpen(popup)) popup.showPopover();
417}
418
419export function close(popup: HTMLElement): void {
420  const inst = instances.get(popup);
421  if (inst) inst.hide();
422  else if (isOpen(popup)) popup.hidePopover();
423}
424
425export function toggle(popup: HTMLElement): void {
426  if (isOpen(popup)) close(popup);
427  else open(popup);
428}
429
430// The trigger of a [data-cap="popover"] root: [data-popover-trigger], else the first
431// child that is not the popup.
432function triggerOf(root: HTMLElement, popup: HTMLElement): HTMLElement | null {
433  return root.querySelector<HTMLElement>("[data-popover-trigger]") ?? [...root.children].find((c): c is HTMLElement => c instanceof HTMLElement && c !== popup) ?? null;
434}
435
436// Attaches every [data-cap="popover"] under root not yet attached. Returns a function that
437// detaches them.
438export function enhance(root: ParentNode = document): () => void {
439  const undo: Array<() => void> = [];
440  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='popover']:not([data-cap-ready])")) {
441    const popup = el.querySelector<HTMLElement>(":scope > .cap-popover");
442    const trigger = popup && triggerOf(el, popup);
443    if (!popup || !trigger) continue;
444    el.dataset.capReady = "";
445    const detach = attach(trigger, popup);
446    undo.push(() => {
447      detach();
448      delete el.dataset.capReady;
449    });
450  }
451  return () => undo.forEach((f) => f());
452}