@lion/ui 0.0.1

package/components/overlays/src/OverlayMixin.js

@@ -0,0 +1,373 @@
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { OverlayController } from './OverlayController.js';
+import { isEqualConfig } from './utils/is-equal-config.js';
+
+/**
+ * @typedef {import('../types/OverlayConfig.js').OverlayConfig} OverlayConfig
+ * @typedef {import('../types/OverlayMixinTypes.js').DefineOverlayConfig} DefineOverlayConfig
+ * @typedef {import('../types/OverlayMixinTypes.js').OverlayMixin} OverlayMixin
+ */
+
+/**
+ * @type {OverlayMixin}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<import('lit').LitElement>} superclass
+ */
+export const OverlayMixinImplementation = superclass =>
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  class OverlayMixin extends superclass {
+    static get properties() {
+      return {
+        opened: {
+          type: Boolean,
+          reflect: true,
+        },
+      };
+    }
+
+    constructor() {
+      super();
+      this.opened = false;
+      /** @private */
+      this.__needsSetup = true;
+      /** @type {OverlayConfig} */
+      this.config = {};
+
+      /** @type {EventListener} */
+      this.toggle = this.toggle.bind(this);
+      /** @type {EventListener} */
+      this.open = this.open.bind(this);
+      /** @type {EventListener} */
+      this.close = this.close.bind(this);
+    }
+
+    get config() {
+      return /** @type {OverlayConfig} */ (this.__config);
+    }
+
+    /** @param {OverlayConfig} value */
+    set config(value) {
+      const shouldUpdate = !isEqualConfig(this.config, value);
+
+      if (this._overlayCtrl && shouldUpdate) {
+        this._overlayCtrl.updateConfig(value);
+      }
+      this.__config = value;
+      if (this._overlayCtrl && shouldUpdate) {
+        this.__syncToOverlayController();
+      }
+    }
+
+    /**
+     * @override
+     * @param {string} name
+     * @param {any} oldValue
+     */
+    requestUpdate(name, oldValue) {
+      super.requestUpdate(name, oldValue);
+      if (name === 'opened' && this.opened !== oldValue) {
+        this.dispatchEvent(new Event('opened-changed'));
+      }
+    }
+
+    /**
+     * @overridable method `_defineOverlay`
+     * @desc returns an instance of a (dynamic) overlay controller
+     * In case overriding _defineOverlayConfig is not enough
+     * @param {DefineOverlayConfig} config
+     * @returns {OverlayController}
+     * @protected
+     */
+    // eslint-disable-next-line
+    _defineOverlay({ contentNode, invokerNode, referenceNode, backdropNode, contentWrapperNode }) {
+      const overlayConfig = this._defineOverlayConfig() || {};
+      return new OverlayController({
+        contentNode,
+        invokerNode,
+        referenceNode,
+        backdropNode,
+        contentWrapperNode,
+        ...overlayConfig, // wc provided in the class as defaults
+        ...this.config, // user provided (e.g. in template)
+        popperConfig: {
+          ...(overlayConfig.popperConfig || {}),
+          ...(this.config.popperConfig || {}),
+          modifiers: [
+            ...(overlayConfig.popperConfig?.modifiers || []),
+            ...(this.config.popperConfig?.modifiers || []),
+          ],
+        },
+      });
+    }
+
+    /**
+     * @overridable method `_defineOverlayConfig`
+     * @desc returns an object with default configuration options for your overlay component.
+     * This is generally speaking easier to override than _defineOverlay method entirely.
+     * @returns {OverlayConfig}
+     * @protected
+     */
+    // eslint-disable-next-line
+    _defineOverlayConfig() {
+      return {
+        placementMode: 'local',
+      };
+    }
+
+    /**
+     * @param {import('lit').PropertyValues } changedProperties
+     */
+    updated(changedProperties) {
+      super.updated(changedProperties);
+
+      if (changedProperties.has('opened') && this._overlayCtrl && !this.__blockSyncToOverlayCtrl) {
+        this.__syncToOverlayController();
+      }
+    }
+
+    /**
+     * @overridable
+     * @desc use this method to setup your open and close event listeners
+     * For example, set a click event listener on _overlayInvokerNode to set opened to true
+     * @protected
+     */
+    // eslint-disable-next-line class-methods-use-this
+    _setupOpenCloseListeners() {
+      /**
+       * @param {{ stopPropagation: () => void; }} ev
+       */
+      this.__closeEventInContentNodeHandler = ev => {
+        ev.stopPropagation();
+        /** @type {OverlayController} */ (this._overlayCtrl).hide();
+      };
+      if (this._overlayContentNode) {
+        this._overlayContentNode.addEventListener(
+          'close-overlay',
+          this.__closeEventInContentNodeHandler,
+        );
+      }
+    }
+
+    /**
+     * @overridable
+     * @desc use this method to tear down your event listeners
+     * @protected
+     */
+    // eslint-disable-next-line class-methods-use-this
+    _teardownOpenCloseListeners() {
+      if (this._overlayContentNode) {
+        this._overlayContentNode.removeEventListener(
+          'close-overlay',
+          /** @type {EventListener} */ (this.__closeEventInContentNodeHandler),
+        );
+      }
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      // we do a setup after every connectedCallback as firstUpdated will only be called once
+      this.__needsSetup = true;
+      this.updateComplete.then(() => {
+        if (this.__needsSetup) {
+          this._setupOverlayCtrl();
+        }
+        this.__needsSetup = false;
+      });
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      if (this._overlayCtrl) {
+        this._teardownOverlayCtrl();
+      }
+    }
+
+    get _overlayInvokerNode() {
+      return /** @type {HTMLElement | undefined} */ (
+        Array.from(this.children).find(child => child.slot === 'invoker')
+      );
+    }
+
+    /**
+     * @overridable
+     */
+    // eslint-disable-next-line class-methods-use-this
+    get _overlayReferenceNode() {
+      return undefined;
+    }
+
+    get _overlayBackdropNode() {
+      return /** @type {HTMLElement | undefined} */ (
+        Array.from(this.children).find(child => child.slot === 'backdrop')
+      );
+    }
+
+    get _overlayContentNode() {
+      if (!this._cachedOverlayContentNode) {
+        this._cachedOverlayContentNode =
+          Array.from(this.children).find(child => child.slot === 'content') ||
+          this.config.contentNode;
+      }
+      return /** @type {HTMLElement} */ (this._cachedOverlayContentNode);
+    }
+
+    get _overlayContentWrapperNode() {
+      return /** @type {HTMLElement | undefined} */ (
+        this.shadowRoot?.querySelector('#overlay-content-node-wrapper')
+      );
+    }
+
+    /** @protected */
+    _setupOverlayCtrl() {
+      /** @type {OverlayController} */
+      this._overlayCtrl = this._defineOverlay({
+        contentNode: this._overlayContentNode,
+        contentWrapperNode: this._overlayContentWrapperNode,
+        invokerNode: this._overlayInvokerNode,
+        referenceNode: this._overlayReferenceNode,
+        backdropNode: this._overlayBackdropNode,
+      });
+      this.__syncToOverlayController();
+      this.__setupSyncFromOverlayController();
+      this._setupOpenCloseListeners();
+    }
+
+    /** @protected */
+    _teardownOverlayCtrl() {
+      this._teardownOpenCloseListeners();
+      this.__teardownSyncFromOverlayController();
+      /** @type {OverlayController} */
+      (this._overlayCtrl).teardown();
+    }
+
+    /**
+     * When the opened state is changed by an Application Developer,cthe OverlayController is
+     * requested to show/hide. It might happen that this request is not honoured
+     * (intercepted in before-hide for instance), so that we need to sync the controller state
+     * to this webcomponent again, preventing eternal loops.
+     * @param {boolean} newOpened
+     * @protected
+     */
+    async _setOpenedWithoutPropertyEffects(newOpened) {
+      this.__blockSyncToOverlayCtrl = true;
+      this.opened = newOpened;
+      await this.updateComplete;
+      this.__blockSyncToOverlayCtrl = false;
+    }
+
+    /** @private */
+    __setupSyncFromOverlayController() {
+      this.__onOverlayCtrlShow = () => {
+        this.opened = true;
+      };
+
+      this.__onOverlayCtrlHide = () => {
+        this.opened = false;
+      };
+
+      /**
+       * @param {{ preventDefault: () => void; }} beforeShowEvent
+       */
+      this.__onBeforeShow = beforeShowEvent => {
+        const event = new CustomEvent('before-opened', { cancelable: true });
+        this.dispatchEvent(event);
+        if (event.defaultPrevented) {
+          // Check whether our current `.opened` state is not out of sync with overlayCtrl
+          this._setOpenedWithoutPropertyEffects(
+            /** @type {OverlayController} */ (this._overlayCtrl).isShown,
+          );
+          beforeShowEvent.preventDefault();
+        }
+      };
+
+      /**
+       * @param {{ preventDefault: () => void; }} beforeHideEvent
+       */
+      this.__onBeforeHide = beforeHideEvent => {
+        const event = new CustomEvent('before-closed', { cancelable: true });
+        this.dispatchEvent(event);
+        if (event.defaultPrevented) {
+          // Check whether our current `.opened` state is not out of sync with overlayCtrl
+          this._setOpenedWithoutPropertyEffects(
+            /** @type {OverlayController} */
+            (this._overlayCtrl).isShown,
+          );
+          beforeHideEvent.preventDefault();
+        }
+      };
+
+      /** @type {OverlayController} */
+      (this._overlayCtrl).addEventListener('show', this.__onOverlayCtrlShow);
+      /** @type {OverlayController} */
+      (this._overlayCtrl).addEventListener('hide', this.__onOverlayCtrlHide);
+      /** @type {OverlayController} */
+      (this._overlayCtrl).addEventListener('before-show', this.__onBeforeShow);
+      /** @type {OverlayController} */
+      (this._overlayCtrl).addEventListener('before-hide', this.__onBeforeHide);
+    }
+
+    /** @private */
+    __teardownSyncFromOverlayController() {
+      /** @type {OverlayController} */
+      (this._overlayCtrl).removeEventListener(
+        'show',
+        /** @type {EventListener} */ (this.__onOverlayCtrlShow),
+      );
+      /** @type {OverlayController} */ (this._overlayCtrl).removeEventListener(
+        'hide',
+        /** @type {EventListener} */ (this.__onOverlayCtrlHide),
+      );
+      /** @type {OverlayController} */ (this._overlayCtrl).removeEventListener(
+        'before-show',
+        /** @type {EventListener} */ (this.__onBeforeShow),
+      );
+      /** @type {OverlayController} */ (this._overlayCtrl).removeEventListener(
+        'before-hide',
+        /** @type {EventListener} */ (this.__onBeforeHide),
+      );
+    }
+
+    /** @private */
+    __syncToOverlayController() {
+      if (this.opened) {
+        /** @type {OverlayController} */
+        (this._overlayCtrl).show();
+      } else {
+        /** @type {OverlayController} */
+        (this._overlayCtrl).hide();
+      }
+    }
+
+    /**
+     * Toggles the overlay
+     */
+    async toggle() {
+      await /** @type {OverlayController} */ (this._overlayCtrl).toggle();
+    }
+
+    /**
+     * Shows the overlay
+     */
+    async open() {
+      await /** @type {OverlayController} */ (this._overlayCtrl).show();
+    }
+
+    /**
+     * Hides the overlay
+     */
+    async close() {
+      await /** @type {OverlayController} */ (this._overlayCtrl).hide();
+    }
+
+    /**
+     * Sometimes it's needed to recompute Popper position of an overlay, for instance when we have
+     * an opened combobox and the surrounding context changes (the space consumed by the textbox
+     * increases vertically)
+     */
+    repositionOverlay() {
+      const ctrl = /** @type {OverlayController} */ (this._overlayCtrl);
+      if (ctrl.placementMode === 'local' && ctrl._popper) {
+        ctrl._popper.update();
+      }
+    }
+  };
+export const OverlayMixin = dedupeMixin(OverlayMixinImplementation);

package/components/overlays/src/OverlaysManager.js

@@ -0,0 +1,248 @@
+/**
+ * @typedef {import('lit').CSSResult} CSSResult
+ * @typedef {import('./OverlayController.js').OverlayController} OverlayController
+ */
+
+import { globalOverlaysStyle } from './globalOverlaysStyle.js';
+import { setSiblingsInert, unsetSiblingsInert } from './utils/inert-siblings.js';
+
+const isIOS = navigator.userAgent.match(/iPhone|iPad|iPod/i);
+
+/**
+ * `OverlaysManager` which manages overlays which are rendered into the body
+ */
+export class OverlaysManager {
+  static __createGlobalRootNode() {
+    const rootNode = document.createElement('div');
+    rootNode.classList.add('global-overlays');
+    document.body.appendChild(rootNode);
+    return rootNode;
+  }
+
+  static __createGlobalStyleNode() {
+    const styleTag = document.createElement('style');
+    styleTag.setAttribute('data-global-overlays', '');
+    styleTag.textContent = /** @type {CSSResult} */ (globalOverlaysStyle).cssText;
+    document.head.appendChild(styleTag);
+    return styleTag;
+  }
+
+  /**
+   * no setter as .list is intended to be read-only
+   * You can use .add or .remove to modify it
+   */
+  // eslint-disable-next-line class-methods-use-this
+  get globalRootNode() {
+    if (!OverlaysManager.__globalRootNode) {
+      OverlaysManager.__globalRootNode = OverlaysManager.__createGlobalRootNode();
+      OverlaysManager.__globalStyleNode = OverlaysManager.__createGlobalStyleNode();
+    }
+    return OverlaysManager.__globalRootNode;
+  }
+
+  /**
+   * no setter as .list is intended to be read-only
+   * You can use .add or .remove to modify it
+   */
+  get list() {
+    return this.__list;
+  }
+
+  /**
+   * no setter as .shownList is intended to be read-only
+   * You can use .show or .hide on individual controllers to modify
+   */
+  get shownList() {
+    return this.__shownList;
+  }
+
+  constructor() {
+    /**
+     * @type {OverlayController[]}
+     * @private
+     */
+    this.__list = [];
+    /**
+     * @type {OverlayController[]}
+     * @private
+     */
+    this.__shownList = [];
+    /** @private */
+    this.__siblingsInert = false;
+    /**
+     * @type {WeakMap<OverlayController, OverlayController[]>}
+     * @private
+     */
+    this.__blockingMap = new WeakMap();
+  }
+
+  /**
+   * Registers an overlay controller.
+   * @param {OverlayController} ctrlToAdd controller of the newly added overlay
+   * @returns {OverlayController} same controller after adding to the manager
+   */
+  add(ctrlToAdd) {
+    if (this.list.find(ctrl => ctrlToAdd === ctrl)) {
+      throw new Error('controller instance is already added');
+    }
+    this.list.push(ctrlToAdd);
+    return ctrlToAdd;
+  }
+
+  /**
+   * @param {OverlayController} ctrlToRemove
+   */
+  remove(ctrlToRemove) {
+    if (!this.list.find(ctrl => ctrlToRemove === ctrl)) {
+      throw new Error('could not find controller to remove');
+    }
+    this.__list = this.list.filter(ctrl => ctrl !== ctrlToRemove);
+  }
+
+  /**
+   * @param {OverlayController} ctrlToShow
+   */
+  show(ctrlToShow) {
+    if (this.list.find(ctrl => ctrlToShow === ctrl)) {
+      this.hide(ctrlToShow);
+    }
+    this.__shownList.unshift(ctrlToShow);
+
+    // make sure latest shown ctrl is visible
+    Array.from(this.__shownList)
+      .reverse()
+      .forEach((ctrl, i) => {
+        // eslint-disable-next-line no-param-reassign
+        ctrl.elevation = i + 1;
+      });
+  }
+
+  /**
+   * @param {any} ctrlToHide
+   */
+  hide(ctrlToHide) {
+    if (!this.list.find(ctrl => ctrlToHide === ctrl)) {
+      throw new Error('could not find controller to hide');
+    }
+    this.__shownList = this.shownList.filter(ctrl => ctrl !== ctrlToHide);
+  }
+
+  teardown() {
+    this.list.forEach(ctrl => {
+      ctrl.teardown();
+    });
+
+    this.__list = [];
+    this.__shownList = [];
+    this.__siblingsInert = false;
+
+    const rootNode = OverlaysManager.__globalRootNode;
+    if (rootNode) {
+      if (rootNode.parentElement) {
+        rootNode.parentElement.removeChild(rootNode);
+      }
+      OverlaysManager.__globalRootNode = undefined;
+
+      document.head.removeChild(
+        /** @type {HTMLStyleElement} */ (OverlaysManager.__globalStyleNode),
+      );
+      OverlaysManager.__globalStyleNode = undefined;
+    }
+  }
+
+  /** Features right now only for Global Overlay Manager */
+
+  get siblingsInert() {
+    return this.__siblingsInert;
+  }
+
+  disableTrapsKeyboardFocusForAll() {
+    this.shownList.forEach(ctrl => {
+      if (ctrl.trapsKeyboardFocus === true && ctrl.disableTrapsKeyboardFocus) {
+        ctrl.disableTrapsKeyboardFocus({ findNewTrap: false });
+      }
+    });
+  }
+
+  /**
+   * @param {'local' | 'global' | undefined} placementMode
+   */
+  informTrapsKeyboardFocusGotEnabled(placementMode) {
+    if (this.siblingsInert === false && placementMode === 'global') {
+      if (OverlaysManager.__globalRootNode) {
+        setSiblingsInert(this.globalRootNode);
+      }
+      this.__siblingsInert = true;
+    }
+  }
+
+  /**
+   * @param {{ disabledCtrl?:OverlayController, findNewTrap?:boolean }} options
+   */
+  informTrapsKeyboardFocusGotDisabled({ disabledCtrl, findNewTrap = true } = {}) {
+    const next = this.shownList.find(
+      ctrl => ctrl !== disabledCtrl && ctrl.trapsKeyboardFocus === true,
+    );
+    if (next) {
+      if (findNewTrap) {
+        next.enableTrapsKeyboardFocus();
+      }
+    } else if (this.siblingsInert === true) {
+      if (OverlaysManager.__globalRootNode) {
+        unsetSiblingsInert(this.globalRootNode);
+      }
+      this.__siblingsInert = false;
+    }
+  }
+
+  /** PreventsScroll */
+
+  // eslint-disable-next-line class-methods-use-this
+  requestToPreventScroll() {
+    // no check as classList will dedupe it anyways
+    document.body.classList.add('global-overlays-scroll-lock');
+    if (isIOS) {
+      // iOS has issues with overlays with input fields. This is fixed by applying
+      // position: fixed to the body. As a side effect, this will scroll the body to the top.
+      document.body.classList.add('global-overlays-scroll-lock-ios-fix');
+      document.documentElement.classList.add('global-overlays-scroll-lock-ios-fix');
+    }
+  }
+
+  requestToEnableScroll() {
+    if (!this.shownList.some(ctrl => ctrl.preventsScroll === true)) {
+      document.body.classList.remove('global-overlays-scroll-lock');
+      if (isIOS) {
+        document.body.classList.remove('global-overlays-scroll-lock-ios-fix');
+        document.documentElement.classList.remove('global-overlays-scroll-lock-ios-fix');
+      }
+    }
+  }
+
+  /**
+   * Blocking
+   * @param {OverlayController} blockingCtrl
+   */
+  requestToShowOnly(blockingCtrl) {
+    const controllersToHide = this.shownList.filter(ctrl => ctrl !== blockingCtrl);
+
+    controllersToHide.map(ctrl => ctrl.hide());
+    this.__blockingMap.set(blockingCtrl, controllersToHide);
+  }
+
+  /**
+   * @param {OverlayController} blockingCtrl
+   */
+  retractRequestToShowOnly(blockingCtrl) {
+    if (this.__blockingMap.has(blockingCtrl)) {
+      const controllersWhichGotHidden = /** @type {OverlayController[]} */ (
+        this.__blockingMap.get(blockingCtrl)
+      );
+      controllersWhichGotHidden.map(ctrl => ctrl.show());
+    }
+  }
+}
+/** @type {HTMLElement | undefined} */
+OverlaysManager.__globalRootNode = undefined;
+/** @type {HTMLStyleElement | undefined} */
+OverlaysManager.__globalStyleNode = undefined;

package/components/overlays/src/configurations/withBottomSheetConfig.js

@@ -0,0 +1,16 @@
+/**
+ * @typedef {import('../../types/OverlayConfig.js').OverlayConfig} OverlayConfig
+ */
+
+export const withBottomSheetConfig = () =>
+  /** @type {OverlayConfig} */ ({
+    hasBackdrop: true,
+    preventsScroll: true,
+    trapsKeyboardFocus: true,
+    hidesOnEsc: true,
+    placementMode: 'global',
+    viewportConfig: {
+      placement: 'bottom',
+    },
+    handlesAccessibility: true,
+  });

package/components/overlays/src/configurations/withDropdownConfig.js

@@ -0,0 +1,22 @@
+/**
+ * @typedef {import('../../types/OverlayConfig.js').OverlayConfig} OverlayConfig
+ */
+
+export const withDropdownConfig = () =>
+  /** @type {OverlayConfig} */ ({
+    placementMode: 'local',
+    inheritsReferenceWidth: 'min',
+    hidesOnOutsideClick: true,
+    hidesOnOutsideEsc: true,
+    hidesOnEsc: true,
+    popperConfig: {
+      placement: 'bottom-start',
+      modifiers: [
+        {
+          name: 'offset',
+          enabled: false,
+        },
+      ],
+    },
+    handlesAccessibility: true,
+  });

package/components/overlays/src/configurations/withModalDialogConfig.js

@@ -0,0 +1,16 @@
+/**
+ * @typedef {import('../../types/OverlayConfig.js').OverlayConfig} OverlayConfig
+ */
+
+export const withModalDialogConfig = () =>
+  /** @type {OverlayConfig} */ ({
+    placementMode: 'global',
+    viewportConfig: {
+      placement: 'center',
+    },
+    hasBackdrop: true,
+    preventsScroll: true,
+    trapsKeyboardFocus: true,
+    hidesOnEsc: true,
+    handlesAccessibility: true,
+  });