@justeattakeaway/pie-tooltip 0.2.0 → 0.3.0

package/src/index.ts

@@ -22,6 +22,7 @@ import {
     defaultProps,
     headingLevels,
     ON_TOOLTIP_CLOSE_EVENT,
+    ON_TOOLTIP_OPEN_EVENT,
     positions,
     sizes,
     types,
@@ -70,9 +71,72 @@ const createsContainingBlock = (styles: CSSStyleDeclaration): boolean => {
     return /\b(transform|perspective|filter|backdrop-filter|contain|translate|rotate|scale)\b/.test(styles.willChange);
 };
 
+const flattenedAncestors = (element: Element): Array<Element> => {
+    const { documentElement } = element.ownerDocument;
+    const ancestors: Array<Element> = [];
+    let current = element;
+
+    while (current !== documentElement) {
+        const parentNode: Node | null = current.assignedSlot ?? current.parentNode;
+        const parent = parentNode instanceof ShadowRoot ? parentNode.host : parentNode;
+
+        if (!(parent instanceof Element)) {
+            break;
+        }
+
+        ancestors.push(parent);
+        current = parent;
+    }
+
+    return ancestors;
+};
+
+// The ancestors that clip the trigger. Overflow on the root element and the body is left out:
+// that is the viewport clip, which every element is subject to and which no panel can escape.
+const collectClippingAncestors = (element: Element): Array<Element> => {
+    const { documentElement, body } = element.ownerDocument;
+
+    return flattenedAncestors(element).filter((ancestor) => {
+        if (ancestor === documentElement || ancestor === body) {
+            return false;
+        }
+
+        const styles = getComputedStyle(ancestor);
+
+        return styles.overflowX !== 'visible' || styles.overflowY !== 'visible';
+    });
+};
+
+// The region an element clips its descendants to: its padding box, minus any scrollbar.
+// `clientLeft`/`clientTop` are the border widths and `clientWidth`/`clientHeight` the padding box,
+// so together they convert the border-box rect the browser reports into the clip region.
+const getClipRect = (element: Element): DOMRect => {
+    const { left, top } = element.getBoundingClientRect();
+    const {
+        clientLeft, clientTop, clientWidth, clientHeight,
+    } = element;
+
+    return new DOMRect(left + clientLeft, top + clientTop, clientWidth, clientHeight);
+};
+
+// Intersects two rects. Returns `null` when they do not overlap.
+const intersectRects = (a: DOMRect, b: DOMRect): DOMRect | null => {
+    const left = Math.max(a.left, b.left);
+    const top = Math.max(a.top, b.top);
+    const right = Math.min(a.right, b.right);
+    const bottom = Math.min(a.bottom, b.bottom);
+
+    if (right <= left || bottom <= top) {
+        return null;
+    }
+
+    return new DOMRect(left, top, right - left, bottom - top);
+};
+
 /**
  * @tagname pie-tooltip
- * @event {Event} pie-tooltip-close - When the close button is clicked. Set `isOpen` to `false` in response.
+ * @event {Event} pie-tooltip-open - When a configured trigger asks for the panel. Set `isOpen` to `true` in response.
+ * @event {Event} pie-tooltip-close - When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.
  * @slot content - The descriptive content of the panel. Must not contain focusable elements.
  * @slot action - An optional slot for interactive content such as a `pie-button`. Filling this slot switches the panel to a non-modal dialog.
  */
@@ -113,6 +177,9 @@ export class PieTooltip extends PieElement implements TooltipProps {
     @property({ type: Object })
     public aria: TooltipProps['aria'];
 
+    @property({ type: Array })
+    public triggers: TooltipProps['triggers'] = [];
+
     @queryAssignedElements({ slot: 'action' }) private _assignedActionElements!: Array<HTMLElement>;
 
     @query('.c-tooltip-origin') private _originElement!: HTMLElement | null;
@@ -121,14 +188,25 @@ export class PieTooltip extends PieElement implements TooltipProps {
 
     @state() private _isPositioned = false;
 
+    @state() private _isAnchorVisible = true;
+
+    private _clippedTriggerElement: Element | null = null;
+
+    private _triggerClippers: Array<Element> = [];
+
     private _triggerTrackingController: AbortController | undefined;
+    private _interactionController: AbortController | undefined;
 
     private _directionObserver: MutationObserver | undefined;
 
+    private _triggerObserver: ResizeObserver | undefined;
+
     private _reanchorFrame = 0;
 
     private _shouldResolveOverlayMode = false;
 
+    private _hoverCloseTimer: ReturnType<typeof setTimeout> | undefined;
+
     static styles = unsafeCSS(styles);
 
     private get _mode (): TooltipMode | undefined {
@@ -142,6 +220,7 @@ export class PieTooltip extends PieElement implements TooltipProps {
     protected firstUpdated (): void {
         this.resolveMode();
         this.projectOverTrigger();
+        this._rebuildInteractionListeners();
     }
 
     protected updated (changedProperties: PropertyValues<this>): void {
@@ -155,14 +234,26 @@ export class PieTooltip extends PieElement implements TooltipProps {
             this.projectOverTrigger();
         }
 
+        // Tracking is bound to a specific trigger element and a specific ancestor chain, so a new
+        // trigger needs it rebuilt rather than left in place. `startTrackingTrigger` early-returns
+        // while a controller exists, so the stop has to come first.
+        if (this.isOpen && changedProperties.has('trigger')) {
+            this.stopTrackingTrigger();
+        }
+
         if (this.isOpen) {
             this.startTrackingTrigger();
         } else {
             this.stopTrackingTrigger();
         }
+
+        if (changedProperties.has('triggers') || changedProperties.has('trigger')) {
+            this._rebuildInteractionListeners();
+        }
     }
 
     public disconnectedCallback (): void {
+        this._teardownInteractionListeners();
         this.stopTrackingTrigger();
         super.disconnectedCallback();
     }
@@ -203,6 +294,40 @@ export class PieTooltip extends PieElement implements TooltipProps {
         window.addEventListener('scroll', handleViewportChange, { capture: true, passive: true, signal });
         window.addEventListener('resize', handleResize, { passive: true, signal });
 
+        // `scroll` is not composed, so its path stops at the shadow root it happened in and a
+        // listener on `window` never sees it. A scroll container inside another component's
+        // shadow root (`pie-modal`'s, for one) therefore needs its own listener, or the panel
+        // detaches from the trigger as soon as that container scrolls.
+        const shadowRoots = new Set<ShadowRoot>();
+
+        flattenedAncestors(this).forEach((ancestor) => {
+            const root = ancestor.getRootNode();
+
+            if (root instanceof ShadowRoot) {
+                shadowRoots.add(root);
+            }
+        });
+
+        shadowRoots.forEach((root) => {
+            root.addEventListener('scroll', handleViewportChange, { capture: true, passive: true, signal });
+        });
+
+        // A trigger inside a container that was `display: none` when the panel opened has no box
+        // to measure. `pie-modal` calls `showModal()` from an async `firstUpdated`, so this is the
+        // normal case for a tooltip inside a modal that is open on load.
+        this._triggerObserver = new ResizeObserver(() => {
+            // Geometry changed, so the ancestor chain may have too. Flagged rather than resolved
+            // here so the walk runs at most once per frame.
+            this._shouldResolveOverlayMode = true;
+            handleViewportChange();
+        });
+
+        const triggerElement = this._getTriggerElement();
+
+        if (triggerElement) {
+            this._triggerObserver.observe(triggerElement);
+        }
+
         this._directionObserver = new MutationObserver(handleViewportChange);
         this._directionObserver.observe(this.ownerDocument.documentElement, {
             attributeFilter: ['dir'],
@@ -219,6 +344,9 @@ export class PieTooltip extends PieElement implements TooltipProps {
         this._directionObserver?.disconnect();
         this._directionObserver = undefined;
 
+        this._triggerObserver?.disconnect();
+        this._triggerObserver = undefined;
+
         this._shouldResolveOverlayMode = false;
 
         if (this._reanchorFrame) {
@@ -234,23 +362,32 @@ export class PieTooltip extends PieElement implements TooltipProps {
     // Picks between `absolute` (browser handles scrolling, but clipped by overflow ancestors) and
     // `fixed` (escapes overflow clips, but must re-offset on every scroll). Switches to `fixed`
     // only when it escapes a clip that `absolute` would not.
+    //
+    // An overflow ancestor clips a positioned box only if it is that box's containing block or an
+    // ancestor of it; a clipper strictly inside the containing block does not clip. So each
+    // clipper is counted against a mode only once that mode's containing block has been reached.
     private resolveOverlayMode (): void {
         let isAtOrAboveAbsoluteContainingBlock = false;
         let isAtOrAboveFixedContainingBlock = false;
-        let isAbsoluteClipped = false;
-        let isFixedClipped = false;
+        let absoluteClippers = 0;
+        let fixedClippers = 0;
 
-        let node: Node | null = this.parentNode;
+        const { documentElement, body } = this.ownerDocument;
 
-        while (node) {
-            // Step over shadow roots to the host; layout follows the light DOM, not slot assignment.
-            const element = node instanceof ShadowRoot ? node.host : node;
+        // Resolved on the same triggers as the overlay mode, because both answers change only
+        // when the ancestor chain does.
+        this._refreshTriggerClippers();
 
-            if (!(element instanceof Element)) {
-                break;
+        flattenedAncestors(this).forEach((element) => {
+            const styles = getComputedStyle(element);
+
+            // `display: contents` generates no box, so it can neither be a containing block nor
+            // clip. `display: none` is deliberately not skipped: its computed values still
+            // describe the box it will generate, so the answer holds once it is shown.
+            if (styles.display === 'contents') {
+                return;
             }
 
-            const styles = getComputedStyle(element);
             const isContainingBlock = createsContainingBlock(styles);
 
             if (isContainingBlock || styles.position !== 'static') {
@@ -261,21 +398,31 @@ export class PieTooltip extends PieElement implements TooltipProps {
                 isAtOrAboveFixedContainingBlock = true;
             }
 
-            // Check after setting the containing-block flags so an ancestor that is both the
-            // containing block and the clipper is counted correctly.
-            if (styles.overflowX !== 'visible' || styles.overflowY !== 'visible') {
-                isAbsoluteClipped = isAbsoluteClipped || isAtOrAboveAbsoluteContainingBlock;
-                isFixedClipped = isFixedClipped || isAtOrAboveFixedContainingBlock;
-            }
+            const clips = styles.overflowX !== 'visible' || styles.overflowY !== 'visible';
 
-            if (element === this.ownerDocument.documentElement) {
-                break;
-            }
+            // Overflow on the root element and on the body propagates to the viewport, which no
+            // positioning scheme escapes. Counting it can only make `fixed` look no better than
+            // `absolute`, which is what happens while a `pie-modal` is open, because its scroll
+            // lock sets `overflow: hidden` on the body.
+            const propagatesOverflowToViewport = element === documentElement || element === body;
 
-            node = element.parentNode;
-        }
+            // Counted after the containing-block flags so an ancestor that is both the containing
+            // block and the clipper is counted correctly.
+            if (clips && !propagatesOverflowToViewport) {
+                if (isAtOrAboveAbsoluteContainingBlock) {
+                    absoluteClippers += 1;
+                }
 
-        this.style.position = isAbsoluteClipped && !isFixedClipped ? 'fixed' : '';
+                if (isAtOrAboveFixedContainingBlock) {
+                    fixedClippers += 1;
+                }
+            }
+        });
+
+        // The fixed containing block is always at or above the absolute one, so the clippers that
+        // apply to a fixed box are a subset of those that apply to an absolute one. A lower count
+        // therefore always means a strictly better escape, never a worse one.
+        this.style.position = fixedClippers < absoluteClippers ? 'fixed' : '';
     }
 
     // Measures the trigger relative to the origin marker (which sits at the containing block's
@@ -284,13 +431,36 @@ export class PieTooltip extends PieElement implements TooltipProps {
     private projectOverTrigger (): void {
         this._isPositioned = false;
 
-        const triggerElement = this.trigger ? this.ownerDocument.getElementById(this.trigger) : null;
+        const triggerElement = this._getTriggerElement();
 
         if (!triggerElement || !this._originElement) {
             ['top', 'left', 'width', 'height'].forEach((suffix) => {
                 this.style.removeProperty(`--tooltip-anchor-${suffix}`);
             });
             this.style.removeProperty('--tooltip-container-inline-size');
+            this._isAnchorVisible = true;
+            this._isPositioned = true;
+
+            return;
+        }
+
+        if (triggerElement !== this._clippedTriggerElement) {
+            this._refreshTriggerClippers();
+        }
+
+        // Anchoring to the trigger's full box would point the panel at a part of the trigger that
+        // has been scrolled out of sight, leaving whatever sits over it — a pinned modal footer,
+        // for one — between the two. Anchoring to the visible part instead keeps the arrow on the
+        // edge the reader can actually see.
+        const visibleRect = this._triggerClippers.reduce<DOMRect | null>(
+            (rect, clipper) => (rect ? intersectRects(rect, getClipRect(clipper)) : null),
+            triggerElement.getBoundingClientRect(),
+        );
+
+        // Nothing of the trigger is left to point at, so there is nothing to describe either.
+        this._isAnchorVisible = visibleRect !== null;
+
+        if (!visibleRect) {
             this._isPositioned = true;
 
             return;
@@ -299,7 +469,7 @@ export class PieTooltip extends PieElement implements TooltipProps {
         const originRect = this._originElement.getBoundingClientRect();
         const {
             top, left, width, height,
-        } = triggerElement.getBoundingClientRect();
+        } = visibleRect;
 
         this.style.setProperty('--tooltip-anchor-top', `${top - originRect.top}px`);
         this.style.setProperty('--tooltip-anchor-left', `${left - originRect.left}px`);
@@ -313,18 +483,143 @@ export class PieTooltip extends PieElement implements TooltipProps {
         this._isPositioned = true;
     }
 
+    // Cached because `projectOverTrigger` runs on every re-anchoring frame, and collecting these
+    // costs a computed style per ancestor. Refreshed when the trigger changes and whenever the
+    // overlay mode is resolved, which is the same cadence as an ancestor chain actually changing.
+    private _refreshTriggerClippers (): void {
+        const triggerElement = this._getTriggerElement();
+
+        this._clippedTriggerElement = triggerElement;
+        this._triggerClippers = triggerElement ? collectClippingAncestors(triggerElement) : [];
+    }
+
     private handleCloseButtonClick (): void {
+        this._requestClose();
+    }
+
+    private _getTriggerElement (): Element | null {
+        return this.trigger ? this.ownerDocument.getElementById(this.trigger) : null;
+    }
+
+    private _requestOpen (): void {
+        if (this.isOpen) return;
+
+        /**
+         * @ignore
+         */
+        this.dispatchEvent(new Event(ON_TOOLTIP_OPEN_EVENT, { bubbles: true, composed: true }));
+    }
+
+    private _requestClose (): void {
+        if (!this.isOpen) return;
+
         /**
-         * The custom elements manifest analyser scans `this.dispatchEvent` calls for event names
-         * but cannot resolve constants, so it would record an event literally named
-         * `ON_TOOLTIP_CLOSE_EVENT` and generate a matching React callback prop. `@ignore` skips
-         * this call site; the event is declared by the class-level `@event` tag instead.
-         *
          * @ignore
          */
         this.dispatchEvent(new Event(ON_TOOLTIP_CLOSE_EVENT, { bubbles: true, composed: true }));
     }
 
+    private _startHoverCloseTimer (): void {
+        if (this._hoverCloseTimer !== undefined) return;
+        this._hoverCloseTimer = setTimeout(() => {
+            this._hoverCloseTimer = undefined;
+            this._requestClose();
+        }, 100);
+    }
+
+    private _cancelHoverCloseTimer (): void {
+        if (this._hoverCloseTimer !== undefined) {
+            clearTimeout(this._hoverCloseTimer);
+            this._hoverCloseTimer = undefined;
+        }
+    }
+
+    private _rebuildInteractionListeners (): void {
+        this._teardownInteractionListeners();
+
+        if (!this.triggers?.length) return;
+
+        const controller = new AbortController();
+        const { signal } = controller;
+        this._interactionController = controller;
+
+        const triggerEl = this._getTriggerElement();
+
+        this.ownerDocument.addEventListener('keydown', (e: KeyboardEvent) => {
+            if (e.key === 'Escape' && this.isOpen) {
+                this._requestClose();
+            }
+        }, { signal });
+
+        if (!triggerEl) return;
+
+        if (this.triggers.includes('hover')) {
+            triggerEl.addEventListener('mouseenter', () => {
+                this._cancelHoverCloseTimer();
+                this._requestOpen();
+            }, { signal });
+
+            triggerEl.addEventListener('mouseleave', () => {
+                this._startHoverCloseTimer();
+            }, { signal });
+
+            // panel mouseenter/leave for the hover bridge (includes the bridge pseudo-element)
+            const panel = this.renderRoot.querySelector('.c-tooltip');
+            if (panel) {
+                panel.addEventListener('mouseenter', () => {
+                    this._cancelHoverCloseTimer();
+                }, { signal });
+
+                panel.addEventListener('mouseleave', () => {
+                    this._startHoverCloseTimer();
+                }, { signal });
+            }
+        }
+
+        if (this.triggers.includes('focus')) {
+            // open on focus, close on blur unless focus moved into panel action content
+            triggerEl.addEventListener('focusin', () => {
+                this._requestOpen();
+            }, { signal });
+
+            triggerEl.addEventListener('focusout', (e: Event) => {
+                const related = (e as FocusEvent).relatedTarget as Node | null;
+                // relatedTarget is retargeted to the shadow host when focus moves into shadow DOM
+                const staysInside = related && (this.contains(related) || related === this);
+                if (!staysInside) {
+                    this._requestClose();
+                }
+            }, { signal });
+        }
+
+        if (this.triggers.includes('click')) {
+            triggerEl.addEventListener('click', (e: Event) => {
+                e.stopPropagation();
+                if (this.isOpen) {
+                    this._requestClose();
+                } else {
+                    this._requestOpen();
+                }
+            }, { signal });
+
+            // Light-dismiss: click anywhere outside the panel and trigger
+            this.ownerDocument.addEventListener('click', (e: Event) => {
+                const target = e.composedPath()[0] as Node;
+                const isInsidePanel = this.contains(target) || this.shadowRoot?.contains(target);
+                const isInsideTrigger = triggerEl.contains(target) || target === triggerEl;
+                if (!isInsidePanel && !isInsideTrigger && this.isOpen) {
+                    this._requestClose();
+                }
+            }, { signal });
+        }
+    }
+
+    private _teardownInteractionListeners (): void {
+        this._interactionController?.abort();
+        this._interactionController = undefined;
+        this._cancelHoverCloseTimer();
+    }
+
     private renderHeading (): TemplateResult {
         const tag = unsafeStatic(this.headingLevel);
 
@@ -368,6 +663,7 @@ export class PieTooltip extends PieElement implements TooltipProps {
             [`${componentClass}-layer--type-${type}`]: true,
             'is-open': !!isOpen,
             'is-positioned': this._isPositioned,
+            'is-anchorVisible': this._isAnchorVisible,
         };
 
         const panelClasses = {

package/src/react.ts

@@ -11,13 +11,15 @@ const PieTooltipReact = createComponent({
     react: React,
     tagName: 'pie-tooltip',
     events: {
-        onPieTooltipClose: 'pie-tooltip-close' as EventName<Event>, // When the close button is clicked. Set `isOpen` to `false` in response.
+        onPieTooltipOpen: 'pie-tooltip-open' as EventName<Event>, // When a configured trigger asks for the panel. Set `isOpen` to `true` in response.
+        onPieTooltipClose: 'pie-tooltip-close' as EventName<Event>, // When the close button is clicked, or a configured trigger asks to dismiss the panel. Set `isOpen` to `false` in response.
     },
 });
 
 type ReactBaseType = React.HTMLAttributes<HTMLElement>
 
 type PieTooltipEvents = {
+    onPieTooltipOpen?: (event: Event) => void;
     onPieTooltipClose?: (event: Event) => void;
 };
 

package/src/tooltip.scss

@@ -65,7 +65,9 @@ $tooltip-alignments: ('', '-start', '-end');
     visibility: hidden;
     transition: visibility 0s linear 150ms;
 
-    &.is-open.is-positioned {
+    // `is-anchorVisible` is false when the trigger has been scrolled entirely out of a clipping
+    // ancestor: there is nothing left to point at, so the panel hides rather than float free.
+    &.is-open.is-positioned.is-anchorVisible {
         visibility: visible;
         transition-delay: 0s;
     }
@@ -168,7 +170,7 @@ $tooltip-alignments: ('', '-start', '-end');
         transform var(--tooltip-motion-duration) var(--tooltip-motion-easing);
 }
 
-.c-tooltip-layer.is-open.is-positioned .c-tooltip {
+.c-tooltip-layer.is-open.is-positioned.is-anchorVisible .c-tooltip {
     --tooltip-motion-duration: 200ms;
 
     opacity: 1;
@@ -367,3 +369,45 @@ $tooltip-alignments: ('', '-start', '-end');
     inset-block-start: var(--dt-spacing-b);
     inset-inline-end: var(--dt-spacing-b);
 }
+
+// Hover bridge: a transparent pseudo-element extending from each panel edge toward its
+// trigger, covering the --tooltip-layer-offset gap. Keeps the hover region intact so
+// the pointer can travel from the trigger into the panel without the close timer firing.
+// Sized from --tooltip-layer-offset so widening --tooltip-offset cannot open a hole.
+@each $alignment in $tooltip-alignments {
+    .c-tooltip--top#{$alignment}::before {
+        content: '';
+        position: absolute;
+        inset-block-start: 100%;
+        block-size: var(--tooltip-layer-offset);
+        inset-inline-start: 0;
+        inline-size: 100%;
+    }
+
+    .c-tooltip--bottom#{$alignment}::before {
+        content: '';
+        position: absolute;
+        inset-block-end: 100%;
+        block-size: var(--tooltip-layer-offset);
+        inset-inline-start: 0;
+        inline-size: 100%;
+    }
+
+    .c-tooltip--left#{$alignment}::before {
+        content: '';
+        position: absolute;
+        inset-inline-start: 100%;
+        inline-size: var(--tooltip-layer-offset);
+        inset-block-start: 0;
+        block-size: 100%;
+    }
+
+    .c-tooltip--right#{$alignment}::before {
+        content: '';
+        position: absolute;
+        inset-inline-end: 100%;
+        inline-size: var(--tooltip-layer-offset);
+        inset-block-start: 0;
+        block-size: 100%;
+    }
+}