feat: add simpler API for controlling overlays

The current implementation uses events to open and close overlays. This would be hard for users to adopt and is not easy to use in our other components that need overlay behaviour.

This change refactors how our overlays are opened and closed to address issue #321.

Author: cuberoot

packages/overlay/src/active-overlay.ts

@@ -14,7 +14,7 @@ import {
     Placement,
     OverlayOpenDetail,
     TriggerInteractions,
-} from './overlay.js';
+} from './overlay-types.js';
 import calculatePosition, { PositionResult } from './calculate-position.js';
 import { Size, Color } from '@spectrum-web-components/theme';
 import {
@@ -114,7 +114,7 @@ export class ActiveOverlay extends LitElement {
     public trigger?: HTMLElement;
 
     private placeholder?: Comment;
-    private root?: HTMLElement;
+    private root?: HTMLElement = document.body;
 
     @property()
     public _state = stateTransition();
@@ -157,9 +157,9 @@ export class ActiveOverlay extends LitElement {
         return [styles];
     }
 
-    private open(openEvent: CustomEvent<OverlayOpenDetail>): void {
-        this.extractEventDetail(openEvent);
-        this.stealOverlayContent(openEvent.detail.content);
+    private open(openDetail: OverlayOpenDetail): void {
+        this.extractDetail(openDetail);
+        this.stealOverlayContent(openDetail.content);
 
         /* istanbul ignore if */
         if (!this.overlayContent) return;
@@ -169,7 +169,7 @@ export class ActiveOverlay extends LitElement {
         this.timeout = window.setTimeout(() => {
             this.state = 'visible';
             delete this.timeout;
-        }, openEvent.detail.delay);
+        }, openDetail.delay);
 
         this.hiddenDeferred = new Deferred<void>();
         this.addEventListener('animationend', this.onAnimationEnd);
@@ -178,14 +178,14 @@ export class ActiveOverlay extends LitElement {
         });
     }
 
-    private extractEventDetail(event: CustomEvent<OverlayOpenDetail>): void {
-        this.overlayContent = event.detail.content;
-        this.trigger = event.detail.trigger;
-        this.placement = event.detail.placement;
-        this.offset = event.detail.offset;
-        this.interaction = event.detail.interaction;
-        this.color = event.detail.theme.color;
-        this.size = event.detail.theme.size;
+    private extractDetail(detail: OverlayOpenDetail): void {
+        this.overlayContent = detail.content;
+        this.trigger = detail.trigger;
+        this.placement = detail.placement;
+        this.offset = detail.offset;
+        this.interaction = detail.interaction;
+        this.color = detail.theme.color;
+        this.size = detail.theme.size;
     }
 
     public dispose(): void {
@@ -327,16 +327,12 @@ export class ActiveOverlay extends LitElement {
         return this.hasTheme ? this.renderTheme(content) : content;
     }
 
-    public static create(
-        openEvent: CustomEvent<OverlayOpenDetail>,
-        root: HTMLElement
-    ): ActiveOverlay {
+    public static create(details: OverlayOpenDetail): ActiveOverlay {
         const overlay = new ActiveOverlay();
 
         /* istanbul ignore else */
-        if (openEvent.detail.content) {
-            overlay.root = root;
-            overlay.open(openEvent);
+        if (details.content) {
+            overlay.open(details);
         }
 
         return overlay;

packages/overlay/src/index.ts

@@ -13,8 +13,8 @@ import { OverlayTrigger } from './overlay-trigger.js';
 import { ActiveOverlay } from './active-overlay.js';
 
 export * from './overlay.js';
-export * from './overlay-root.js';
 export * from './overlay-trigger.js';
+export * from './overlay-types';
 
 /* istanbul ignore else */
 if (!customElements.get('overlay-trigger')) {

packages/overlay/src/overlay-root.ts

@@ -11,7 +11,7 @@ governing permissions and limitations under the License.
 */
 
 import { ActiveOverlay } from './active-overlay.js';
-import { OverlayOpenDetail, OverlayCloseDetail } from './overlay.js';
+import { OverlayOpenDetail } from './overlay-types';
 
 function isLeftClick(event: MouseEvent): boolean {
     return event.button === 0;
@@ -22,19 +22,11 @@ function hasModifier(event: MouseEvent): boolean {
 }
 
 export class OverlayStack {
-    public overlays: ActiveOverlay[] = [];
-
     private preventMouseRootClose = false;
     private root: HTMLElement = document.body;
-    private onChange: (overlays: ActiveOverlay[]) => void;
     private handlingResize = false;
 
-    public constructor(
-        root: HTMLElement,
-        onChange: (overlays: ActiveOverlay[]) => void
-    ) {
-        this.root = root;
-        this.onChange = onChange;
+    public constructor() {
         this.addEventListeners();
     }
 
@@ -43,7 +35,44 @@ export class OverlayStack {
     }
 
     private get topOverlay(): ActiveOverlay | undefined {
-        return this.overlays.slice(-1)[0];
+        for (
+            let index = document.body.children.length - 1;
+            index >= 0;
+            index--
+        ) {
+            const element = document.body.children[index];
+            if (element instanceof ActiveOverlay) {
+                return element;
+            }
+        }
+    }
+
+    private *overlays(): Generator<ActiveOverlay, void, undefined> {
+        for (const item of document.body.children) {
+            if (item instanceof ActiveOverlay) {
+                yield item;
+            }
+        }
+    }
+
+    private findOverlayForContent(
+        overlayContent: HTMLElement
+    ): ActiveOverlay | undefined {
+        for (const item of this.overlays()) {
+            if (overlayContent.isSameNode(item.overlayContent as HTMLElement)) {
+                return item;
+            }
+        }
+    }
+
+    private findOverlayForTrigger(
+        overlayContent: HTMLElement
+    ): ActiveOverlay | undefined {
+        for (const item of this.overlays()) {
+            if (overlayContent.isSameNode(item.trigger as HTMLElement)) {
+                return item;
+            }
+        }
     }
 
     private addEventListeners(): void {
@@ -54,47 +83,37 @@ export class OverlayStack {
     }
 
     private isOverlayActive(overlayContent: HTMLElement): boolean {
-        return !!this.overlays.find((item) =>
-            overlayContent.isSameNode(item.overlayContent as HTMLElement)
-        );
+        return !!this.findOverlayForContent(overlayContent);
     }
 
     private isClickOverlayActiveForTrigger(trigger: HTMLElement): boolean {
-        return this.overlays.some(
-            (item) =>
-                trigger.isSameNode(item.trigger as HTMLElement) &&
-                item.interaction === 'click'
-        );
+        const overlay = this.findOverlayForTrigger(trigger);
+        return overlay != null && overlay.interaction === 'click';
     }
 
-    public openOverlay(event: CustomEvent<OverlayOpenDetail>): void {
-        if (this.isOverlayActive(event.detail.content)) return;
+    public openOverlay(details: OverlayOpenDetail): void {
+        /* istanbul ignore if */
+        if (this.isOverlayActive(details.content)) return;
 
         requestAnimationFrame(() => {
-            const interaction = event.detail.interaction;
-            if (interaction === 'click') {
+            if (details.interaction === 'click') {
                 this.closeAllHoverOverlays();
             } else if (
-                interaction === 'hover' &&
-                this.isClickOverlayActiveForTrigger(event.detail.trigger)
+                details.interaction === 'hover' &&
+                this.isClickOverlayActiveForTrigger(details.trigger)
             ) {
                 // Don't show a hover popover if the click popover is already active
                 return;
             }
 
-            const activeOverlay = ActiveOverlay.create(event, this.root);
-            this.overlays.push(activeOverlay);
-
-            this.onChange(this.overlays);
+            const activeOverlay = ActiveOverlay.create(details);
+            document.body.appendChild(activeOverlay);
         });
     }
 
-    public closeOverlay(event: CustomEvent<OverlayCloseDetail>): void {
+    public closeOverlay(content: HTMLElement): void {
         requestAnimationFrame(() => {
-            const overlayContent = event.detail.content;
-            const overlay = this.overlays.find((item) =>
-                overlayContent.isSameNode(item.overlayContent as HTMLElement)
-            );
+            const overlay = this.findOverlayForContent(content);
             this.hideAndCloseOverlay(overlay);
         });
     }
@@ -123,7 +142,7 @@ export class OverlayStack {
     };
 
     private closeAllHoverOverlays(): void {
-        for (const overlay of this.overlays) {
+        for (const overlay of this.overlays()) {
             if (overlay.interaction === 'hover') {
                 this.hideAndCloseOverlay(overlay);
             }
@@ -133,13 +152,8 @@ export class OverlayStack {
     private async hideAndCloseOverlay(overlay?: ActiveOverlay): Promise<void> {
         if (overlay) {
             await overlay.hide();
-            const index = this.overlays.indexOf(overlay);
-            /* istanbul ignore else */
-            if (index >= 0) {
-                this.overlays[index].dispose();
-                this.overlays.splice(index, 1);
-            }
-            this.onChange(this.overlays);
+            overlay.remove();
+            overlay.dispose();
         }
     }
 
@@ -164,9 +178,9 @@ export class OverlayStack {
 
         this.handlingResize = true;
         requestAnimationFrame(() => {
-            this.overlays.forEach((overlay) => {
+            for (const overlay of this.overlays()) {
                 overlay.updateOverlayPosition();
-            });
+            }
             this.handlingResize = false;
         });
     };