@spectrum-web-components/overlay 1.0.2 → 1.0.3

package/src/Overlay.dev.js

@@ -41,14 +41,14 @@ import {
   SlottableRequestEvent
 } from "./slottable-request-event.dev.js";
 import styles from "./overlay.css.js";
-const supportsPopover = "showPopover" in document.createElement("div");
-let OverlayFeatures = OverlayDialog(AbstractOverlay);
-if (supportsPopover) {
-  OverlayFeatures = OverlayPopover(OverlayFeatures);
+const browserSupportsPopover = "showPopover" in document.createElement("div");
+let ComputedOverlayBase = OverlayDialog(AbstractOverlay);
+if (browserSupportsPopover) {
+  ComputedOverlayBase = OverlayPopover(ComputedOverlayBase);
 } else {
-  OverlayFeatures = OverlayNoPopover(OverlayFeatures);
+  ComputedOverlayBase = OverlayNoPopover(ComputedOverlayBase);
 }
-const _Overlay = class _Overlay extends OverlayFeatures {
+const _Overlay = class _Overlay extends ComputedOverlayBase {
   constructor() {
     super(...arguments);
     this._delayed = false;
@@ -57,14 +57,34 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     this._open = false;
     /**
      * The state in which the last `request-slottable` event was dispatched.
-     * Do not allow overlays from dispatching the same state twice in a row.
+     *
+     * This property ensures that overlays do not dispatch the same state twice in a row.
+     *
+     * @type {boolean}
+     * @default false
      */
     this.lastRequestSlottableState = false;
     this.receivesFocus = "auto";
     this._state = "closed";
     this.triggerElement = null;
     this.type = "auto";
+    /**
+     * Tracks whether the overlay was previously open.
+     * This is used to restore the open state when re-enabling the overlay.
+     *
+     * @type {boolean}
+     * @default false
+     */
     this.wasOpen = false;
+    /**
+     * Handles the focus out event to close the overlay if the focus moves outside of it.
+     *
+     * This method ensures that the overlay is closed when the focus moves to an element
+     * outside of the overlay, unless the focus is moved to a related element.
+     *
+     * @private
+     * @param {FocusEvent} event - The focus out event.
+     */
     this.closeOnFocusOut = (event) => {
       if (!event.relatedTarget) {
         return;
@@ -107,9 +127,24 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       this.wasOpen = false;
     }
   }
+  /**
+   * Determines if the overlay has a non-virtual trigger element.
+   *
+   * @returns {boolean} `true` if the trigger element is not a virtual trigger, otherwise `false`.
+   */
   get hasNonVirtualTrigger() {
     return !!this.triggerElement && !(this.triggerElement instanceof VirtualTrigger);
   }
+  /**
+   * Provides an instance of the `PlacementController` for managing the positioning
+   * of the overlay relative to its trigger element.
+   *
+   * If the `PlacementController` instance does not already exist, it is created and
+   * assigned to the `_placementController` property.
+   *
+   * @protected
+   * @returns {PlacementController} The `PlacementController` instance.
+   */
   get placementController() {
     if (!this._placementController) {
       this._placementController = new PlacementController(this);
@@ -146,15 +181,36 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     }
     this.requestUpdate("state", oldState);
   }
+  /**
+   * Provides an instance of the `ElementResolutionController` for managing the element
+   * that the overlay should be associated with. If the instance does not already exist,
+   * it is created and assigned to the `_elementResolver` property.
+   *
+   * @protected
+   * @returns {ElementResolutionController} The `ElementResolutionController` instance.
+   */
   get elementResolver() {
     if (!this._elementResolver) {
       this._elementResolver = new ElementResolutionController(this);
     }
     return this._elementResolver;
   }
+  /**
+   * Determines if the overlay uses a dialog.
+   * Returns `true` if the overlay type is "modal" or "page".
+   *
+   * @private
+   * @returns {boolean} `true` if the overlay uses a dialog, otherwise `false`.
+   */
   get usesDialog() {
     return this.type === "modal" || this.type === "page";
   }
+  /**
+   * Determines the value for the popover attribute based on the overlay type.
+   *
+   * @private
+   * @returns {'auto' | 'manual' | undefined} The popover value or undefined if not applicable.
+   */
   get popoverValue() {
     const hasPopoverAttribute = "popover" in this;
     if (!hasPopoverAttribute) {
@@ -170,14 +226,30 @@ const _Overlay = class _Overlay extends OverlayFeatures {
         return this.type;
     }
   }
-  get requiresPosition() {
+  /**
+   * Determines if the overlay requires positioning based on its type and state.
+   *
+   * @protected
+   * @returns {boolean} True if the overlay requires positioning, otherwise false.
+   */
+  get requiresPositioning() {
     if (this.type === "page" || !this.open) return false;
     if (!this.triggerElement || !this.placement && this.type !== "hint")
       return false;
     return true;
   }
+  /**
+   * Manages the positioning of the overlay relative to its trigger element.
+   *
+   * This method calculates the necessary parameters for positioning the overlay,
+   * such as offset, placement, and tip padding, and then delegates the actual
+   * positioning to the `PlacementController`.
+   *
+   * @protected
+   * @override
+   */
   managePosition() {
-    if (!this.requiresPosition || !this.open) return;
+    if (!this.requiresPositioning || !this.open) return;
     const offset = this.offset || 0;
     const trigger = this.triggerElement;
     const placement = this.placement || "right";
@@ -190,6 +262,16 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       type: this.type
     });
   }
+  /**
+   * Manages the process of opening the popover.
+   *
+   * This method handles the necessary steps to open the popover, including managing delays,
+   * ensuring the popover is in the DOM, making transitions, and applying focus.
+   *
+   * @protected
+   * @override
+   * @returns {Promise<void>} A promise that resolves when the popover has been fully opened.
+   */
   async managePopoverOpen() {
     super.managePopoverOpen();
     const targetOpenState = this.open;
@@ -210,6 +292,18 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     }
     await this.applyFocus(targetOpenState, focusEl);
   }
+  /**
+   * Applies focus to the appropriate element after the popover has been opened.
+   *
+   * This method handles the focus management for the overlay, ensuring that the correct
+   * element receives focus based on the overlay's type and state.
+   *
+   * @protected
+   * @override
+   * @param {boolean} targetOpenState - The target open state of the overlay.
+   * @param {HTMLElement | null} focusEl - The element to focus after opening the popover.
+   * @returns {Promise<void>} A promise that resolves when the focus has been applied.
+   */
   async applyFocus(targetOpenState, focusEl) {
     if (this.receivesFocus === "false" || this.type === "hint") {
       return;
@@ -224,6 +318,15 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     }
     focusEl == null ? void 0 : focusEl.focus();
   }
+  /**
+   * Returns focus to the trigger element if the overlay is closed.
+   *
+   * This method ensures that focus is returned to the trigger element when the overlay is closed,
+   * unless the overlay is of type "hint" or the focus is already outside the overlay.
+   *
+   * @protected
+   * @override
+   */
   returnFocus() {
     var _a;
     if (this.open || this.type === "hint") return;
@@ -248,6 +351,16 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       this.triggerElement.focus();
     }
   }
+  /**
+   * Manages the process of opening or closing the overlay.
+   *
+   * This method handles the necessary steps to open or close the overlay, including updating the state,
+   * managing the overlay stack, and handling focus events.
+   *
+   * @protected
+   * @param {boolean} oldOpen - The previous open state of the overlay.
+   * @returns {Promise<void>} A promise that resolves when the overlay has been fully managed.
+   */
   async manageOpen(oldOpen) {
     if (!this.isConnected && this.open) return;
     if (!this.hasUpdated) {
@@ -305,6 +418,14 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       }
     }
   }
+  /**
+   * Binds event handling strategies to the overlay based on the specified trigger interaction.
+   *
+   * This method sets up the appropriate event handling strategy for the overlay, ensuring that
+   * it responds correctly to user interactions such as clicks, hovers, or long presses.
+   *
+   * @protected
+   */
   bindEvents() {
     var _a;
     (_a = this.strategy) == null ? void 0 : _a.abort();
@@ -318,11 +439,29 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       }
     );
   }
+  /**
+   * Handles the `beforetoggle` event to manage the overlay's state.
+   *
+   * This method checks the new state of the event and calls `handleBrowserClose`
+   * if the new state is not 'open'.
+   *
+   * @protected
+   * @param {Event & { newState: string }} event - The `beforetoggle` event with the new state.
+   */
   handleBeforetoggle(event) {
     if (event.newState !== "open") {
       this.handleBrowserClose(event);
     }
   }
+  /**
+   * Handles the browser's close event to manage the overlay's state.
+   *
+   * This method stops the propagation of the event and closes the overlay if it is not
+   * actively opening. If the overlay is actively opening, it calls `manuallyKeepOpen`.
+   *
+   * @protected
+   * @param {Event} event - The browser's close event.
+   */
   handleBrowserClose(event) {
     var _a;
     event.stopPropagation();
@@ -332,11 +471,28 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     }
     this.manuallyKeepOpen();
   }
+  /**
+   * Manually keeps the overlay open.
+   *
+   * This method sets the overlay to open, allows placement updates, and manages the open state.
+   *
+   * @public
+   * @override
+   */
   manuallyKeepOpen() {
     this.open = true;
     this.placementController.allowPlacementUpdate = true;
     this.manageOpen(false);
   }
+  /**
+   * Handles the `slotchange` event to manage the overlay's state.
+   *
+   * This method checks if there are any elements in the slot. If there are no elements,
+   * it releases the description from the strategy. If there are elements and the trigger
+   * is non-virtual, it prepares the description for the trigger element.
+   *
+   * @protected
+   */
   handleSlotchange() {
     var _a, _b;
     if (!this.elements.length) {
@@ -347,11 +503,30 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       );
     }
   }
+  /**
+   * Determines whether the overlay should prevent closing.
+   *
+   * This method checks the `willPreventClose` flag and resets it to `false`.
+   * It returns the value of the `willPreventClose` flag.
+   *
+   * @public
+   * @returns {boolean} `true` if the overlay should prevent closing, otherwise `false`.
+   */
   shouldPreventClose() {
     const shouldPreventClose = this.willPreventClose;
     this.willPreventClose = false;
     return shouldPreventClose;
   }
+  /**
+   * Requests slottable content for the overlay.
+   *
+   * This method dispatches a `SlottableRequestEvent` to request or remove slottable content
+   * based on the current open state of the overlay. It ensures that the same state is not
+   * dispatched twice in a row.
+   *
+   * @protected
+   * @override
+   */
   requestSlottable() {
     if (this.lastRequestSlottableState === this.open) {
       return;
@@ -367,6 +542,15 @@ const _Overlay = class _Overlay extends OverlayFeatures {
     );
     this.lastRequestSlottableState = this.open;
   }
+  /**
+   * Lifecycle method called before the component updates.
+   *
+   * This method handles various tasks before the component updates, such as setting an ID,
+   * managing the open state, resolving the trigger element, and binding events.
+   *
+   * @override
+   * @param {PropertyValues} changes - The properties that have changed.
+   */
   willUpdate(changes) {
     var _a;
     if (!this.hasAttribute("id")) {
@@ -395,6 +579,15 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       this.bindEvents();
     }
   }
+  /**
+   * Lifecycle method called after the component updates.
+   *
+   * This method handles various tasks after the component updates, such as updating the placement
+   * attribute, resetting the overlay position, and clearing the overlay position based on the state.
+   *
+   * @override
+   * @param {PropertyValues} changes - The properties that have changed.
+   */
   updated(changes) {
     super.updated(changes);
     if (changes.has("placement")) {
@@ -411,23 +604,50 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       this.placementController.clearOverlayPosition();
     }
   }
+  /**
+   * Renders the content of the overlay.
+   *
+   * This method returns a template result containing a slot element. The slot element
+   * listens for the `slotchange` event to manage the overlay's state.
+   *
+   * @protected
+   * @returns {TemplateResult} The template result containing the slot element.
+   */
   renderContent() {
     return html`
             <slot @slotchange=${this.handleSlotchange}></slot>
         `;
   }
+  /**
+   * Generates a style map for the dialog element.
+   *
+   * This method returns an object containing CSS custom properties for the dialog element.
+   * The `--swc-overlay-open-count` custom property is set to the current open count of overlays.
+   *
+   * @private
+   * @returns {StyleInfo} The style map for the dialog element.
+   */
   get dialogStyleMap() {
     return {
       "--swc-overlay-open-count": _Overlay.openCount.toString()
     };
   }
+  /**
+   * Renders the dialog element for the overlay.
+   *
+   * This method returns a template result containing a dialog element. The dialog element
+   * includes various attributes and event listeners to manage the overlay's state and behavior.
+   *
+   * @protected
+   * @returns {TemplateResult} The template result containing the dialog element.
+   */
   renderDialog() {
     return html`
             <dialog
                 class="dialog"
                 part="dialog"
                 placement=${ifDefined(
-      this.requiresPosition ? this.placement || "right" : void 0
+      this.requiresPositioning ? this.placement || "right" : void 0
     )}
                 style=${styleMap(this.dialogStyleMap)}
                 @close=${this.handleBrowserClose}
@@ -439,13 +659,22 @@ const _Overlay = class _Overlay extends OverlayFeatures {
             </dialog>
         `;
   }
+  /**
+   * Renders the popover element for the overlay.
+   *
+   * This method returns a template result containing a div element styled as a popover.
+   * The popover element includes various attributes and event listeners to manage the overlay's state and behavior.
+   *
+   * @protected
+   * @returns {TemplateResult} The template result containing the popover element.
+   */
   renderPopover() {
     return html`
             <div
                 class="dialog"
                 part="dialog"
                 placement=${ifDefined(
-      this.requiresPosition ? this.placement || "right" : void 0
+      this.requiresPositioning ? this.placement || "right" : void 0
     )}
                 popover=${ifDefined(this.popoverValue)}
                 style=${styleMap(this.dialogStyleMap)}
@@ -457,6 +686,15 @@ const _Overlay = class _Overlay extends OverlayFeatures {
             </div>
         `;
   }
+  /**
+   * Renders the overlay component.
+   *
+   * This method returns a template result containing either a dialog or popover element
+   * based on the overlay type. It also includes a slot for longpress descriptors.
+   *
+   * @override
+   * @returns {TemplateResult} The template result containing the overlay content.
+   */
   render() {
     const isDialog = this.type === "modal" || this.type === "page";
     return html`
@@ -464,6 +702,13 @@ const _Overlay = class _Overlay extends OverlayFeatures {
             <slot name="longpress-describedby-descriptor"></slot>
         `;
   }
+  /**
+   * Lifecycle method called when the component is added to the DOM.
+   *
+   * This method sets up event listeners and binds events if the component has already updated.
+   *
+   * @override
+   */
   connectedCallback() {
     super.connectedCallback();
     this.addEventListener("close", () => {
@@ -473,6 +718,13 @@ const _Overlay = class _Overlay extends OverlayFeatures {
       this.bindEvents();
     }
   }
+  /**
+   * Lifecycle method called when the component is removed from the DOM.
+   *
+   * This method releases the description from the strategy and updates the 'open' property.
+   *
+   * @override
+   */
   disconnectedCallback() {
     var _a;
     (_a = this.strategy) == null ? void 0 : _a.releaseDescription();
@@ -481,6 +733,14 @@ const _Overlay = class _Overlay extends OverlayFeatures {
   }
 };
 _Overlay.styles = [styles];
+/**
+ * Tracks the number of overlays that have been opened.
+ *
+ * This static property is used to manage the stacking context of multiple overlays.
+ *
+ * @type {number}
+ * @default 1
+ */
 _Overlay.openCount = 1;
 __decorateClass([
   property({ type: Boolean })
@@ -495,7 +755,6 @@ __decorateClass([
   queryAssignedElements({
     flatten: true,
     selector: ':not([slot="longpress-describedby-descriptor"], slot)'
-    // gather only elements slotted into the default slot
   })
 ], _Overlay.prototype, "elements", 2);
 __decorateClass([