@lion/ui 0.20.0 → 0.21.1-menu-system.0

package/components/overlays/src/OverlayMixin.js

@@ -1,6 +1,5 @@
 import { dedupeMixin } from '@open-wc/dedupe-mixin';
 import { OverlayController } from './OverlayController.js';
-import { isEqualConfig } from './utils/is-equal-config.js';
 
 /**
  * @typedef {<T>(ingOverlayHost:T) => void} PostProcessor
@@ -29,14 +28,10 @@ export function _addOverlayMixinPostProcessor(postProcessor) {
  * @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,
-        },
+        opened: { type: Boolean, reflect: true },
       };
     }
 
@@ -70,13 +65,13 @@ export const OverlayMixinImplementation = superclass => {
 
     /** @param {OverlayConfig} value */
     set config(value) {
-      const shouldUpdate = !isEqualConfig(this.config, value);
-
-      if (this._overlayCtrl && shouldUpdate) {
+      // The OverlayController already guards against redundant updates
+      // (see OverlayController#updateConfig), so we delegate unconditionally here.
+      if (this._overlayCtrl) {
         this._overlayCtrl.updateConfig(value);
       }
       this.__config = value;
-      if (this._overlayCtrl && shouldUpdate) {
+      if (this._overlayCtrl) {
         this.__syncToOverlayController();
       }
     }
@@ -161,6 +156,8 @@ export const OverlayMixinImplementation = superclass => {
      */
     // eslint-disable-next-line class-methods-use-this
     _setupOpenCloseListeners() {
+      // Keeps the close-overlay event private for the controller.
+      // (we already have )
       /**
        * @param {{ stopPropagation: () => void; }} ev
        */
@@ -218,12 +215,6 @@ export const OverlayMixinImplementation = superclass => {
     // @ts-expect-error
     static enabledWarnings = super.enabledWarnings?.filter(w => w !== 'change-in-update') || [];
 
-    get _overlayInvokerNode() {
-      return /** @type {HTMLElement | undefined} */ (
-        Array.from(this.children).find(child => child.slot === 'invoker')
-      );
-    }
-
     /**
      * @overridable
      */
@@ -256,17 +247,82 @@ export const OverlayMixinImplementation = superclass => {
       );
     }
 
+    /**
+     * Returns the element that can actually receive focus inside the passed
+     * invoker (wrapper) element: the element itself when it is focusable,
+     * otherwise the first focusable descendant.
+     * @param {Element|null|undefined} focusableElOrWrapper
+     * @returns {Element|null}
+     */
+    static _getFocusableInvokerEl(focusableElOrWrapper) {
+      if (!focusableElOrWrapper) return null;
+      const focusableSelector = '[tabindex], button, a[href], [role=button]';
+      return focusableElOrWrapper.matches(focusableSelector)
+        ? focusableElOrWrapper
+        : focusableElOrWrapper.querySelector(focusableSelector);
+    }
+
+    /**
+     * The node that opens/closes this overlay.
+     *
+     * Resolved in a stable, declarative way (independent of the exact DOM order)
+     * by looking, in order, for:
+     * 1. a child with `[slot="invoker"]`
+     * 2. any element in the same root that opts in via `[data-invoker]` and
+     *    references this host by id (`for="<id>"`)
+     * 3. a preceding sibling that opts in via `[data-invoker]`
+     * @protected
+     */
+    get _overlayInvokerNode() {
+      if (!this.__invokerNode) {
+        this.__invokerNode = this._getInvokerNode();
+      }
+      return this.__invokerNode;
+    }
+
+    /**
+     * @protected
+     * @returns {Element|null}
+     */
+    _getInvokerNode() {
+      const ctor = /** @type {typeof OverlayMixin} */ (this.constructor);
+
+      const slottedNode = Array.from(this.children).find(child => child.slot === 'invoker');
+      if (slottedNode) {
+        return ctor._getFocusableInvokerEl(slottedNode);
+      }
+
+      if (this.id) {
+        // Reference the invoker declaratively: `<button data-invoker for="my-menu">`
+        const root = /** @type {Document|ShadowRoot} */ (this.getRootNode());
+        const explicitInvoker = root.querySelector?.(`[data-invoker][for="${this.id}"]`);
+        if (explicitInvoker) {
+          return ctor._getFocusableInvokerEl(explicitInvoker);
+        }
+      }
+
+      // Fall back to a preceding sibling that opted in via [data-invoker]
+      const { previousElementSibling } = this;
+      return previousElementSibling && previousElementSibling.hasAttribute('data-invoker')
+        ? ctor._getFocusableInvokerEl(previousElementSibling)
+        : null;
+    }
+
     /** @protected */
     _setupOverlayCtrl() {
       if (this.#hasSetup) return;
+
+      const invokerNode = this._overlayInvokerNode;
+
       const config = {
         contentNode: this._overlayContentNode,
         contentWrapperNode: this._overlayContentWrapperNode,
-        invokerNode: this._overlayInvokerNode,
+        invokerNode: invokerNode && invokerNode instanceof HTMLElement ? invokerNode : undefined,
         referenceNode: this._overlayReferenceNode,
         backdropNode: this._overlayBackdropNode,
       };
 
+      // @ts-ignore [ts7-2565] TS7 checks definite assignment on this inferred field; assigned from another method: declare the field with an explicit `| undefined` in its JSDoc type
       if (this._overlayCtrl) {
         // when `lit` `cache` attaches node to the DOM, register the controller back in the OverlaysManager
         this._overlayCtrl.updateConfig(config);
@@ -282,6 +338,8 @@ export const OverlayMixinImplementation = superclass => {
 
     /** @protected */
     _teardownOverlayCtrl() {
+      // Make sure that dynamic behavior (e.g. responsive) is possible by allowing multiple setups and teardowns of the overlay controller.
+      this.#hasSetup = false;
       if (!this._overlayCtrl) return;
 
       this._teardownOpenCloseListeners();
@@ -434,6 +492,7 @@ export const OverlayMixinImplementation = superclass => {
   for (const postProcessor of overlayMixinPostProcessors) {
     postProcessor(OverlayMixin);
   }
-  return /** @type {* & OverlayMixin} */ (OverlayMixin);
+  // @ts-ignore https://github.com/microsoft/TypeScript/issues/36821#issuecomment-588375051
+  return OverlayMixin;
 };
 export const OverlayMixin = dedupeMixin(OverlayMixinImplementation);

package/components/overlays/src/OverlaysManager.js

@@ -12,6 +12,9 @@ import { overlayDocumentStyle } from './overlayDocumentStyle.js';
  * `OverlaysManager` which manages overlays which are rendered into the body
  */
 export class OverlaysManager {
+  /** @type {HTMLStyleElement | undefined} */
+  static __globalStyleNode = undefined;
+
   static __createGlobalStyleNode() {
     const styleTag = document.createElement('style');
     styleTag.setAttribute('data-overlays', '');
@@ -36,36 +39,46 @@ export class OverlaysManager {
     return this.__shownList;
   }
 
+  /**
+   * @type {OverlayController[]}
+   * @private
+   */
+  __list;
+
+  /**
+   * @type {OverlayController[]}
+   * @private
+   */
+  __shownList;
+
+  /** @protected */
+  _siblingsInert;
+
+  /**
+   * @type {WeakMap<OverlayController, OverlayController[]>}
+   * @private
+   */
+  __blockingMap;
+
+  /**
+   * @private
+   * @type {{
+   *   preventScrollCount: number;
+   *   clientWidth: number | undefined;
+   *   clientHeight: number | undefined;
+   *   marginRightInline: string | undefined;
+   *   marginBottomInline: string | undefined;
+   *   marginRight: number | undefined;
+   *   marginBottom: number | undefined;
+   * }}
+   */
+  __bodySizeVars;
+
   constructor() {
-    /**
-     * @type {OverlayController[]}
-     * @private
-     */
     this.__list = [];
-    /**
-     * @type {OverlayController[]}
-     * @private
-     */
     this.__shownList = [];
-    /** @protected */
     this._siblingsInert = false;
-    /**
-     * @type {WeakMap<OverlayController, OverlayController[]>}
-     * @private
-     */
     this.__blockingMap = new WeakMap();
-    /**
-     * @private
-     * @type {{
-     *   preventScrollCount: number;
-     *   clientWidth: number | undefined;
-     *   clientHeight: number | undefined;
-     *   marginRightInline: string | undefined;
-     *   marginBottomInline: string | undefined;
-     *   marginRight: number | undefined;
-     *   marginBottom: number | undefined;
-     * }}
-     */
     this.__bodySizeVars = {
       preventScrollCount: 0,
       clientWidth: undefined,
@@ -296,6 +309,3 @@ export class OverlaysManager {
     }
   }
 }
-
-/** @type {HTMLStyleElement | undefined} */
-OverlaysManager.__globalStyleNode = undefined;

package/components/overlays/src/utils/adopt-styles.js

@@ -56,7 +56,7 @@ function adoptStyleWhenAdoptedStylesheetsNotSupported(
     const styleEl = document.createElement('style');
     // keep notation, so it's not renamed in minification/build
     // eslint-disable-next-line dot-notation
-    const nonce = window['litNonce'];
+    const nonce = /** @type {{ litNonce?: string }} */ (window)['litNonce'];
     if (nonce !== undefined) {
       styleEl.setAttribute('nonce', nonce);
     }
@@ -124,7 +124,7 @@ export function adoptStyle(renderRoot, style, { teardown = false } = {}) {
   if (!teardown) {
     // @ts-ignore
     // eslint-disable-next-line no-param-reassign
-    renderRoot.adoptedStyleSheets = [...renderRoot.adoptedStyleSheets, sheet];
+    renderRoot.adoptedStyleSheets = [...(renderRoot.adoptedStyleSheets || []), sheet];
   } else if (renderRoot.adoptedStyleSheets.includes(sheet)) {
     // @ts-ignore
     // eslint-disable-next-line no-param-reassign

package/components/overlays/src/utils/get-focusable-elements.js

@@ -10,18 +10,28 @@ import { sortByTabIndex } from './sort-by-tabindex.js';
 // IE11 supports matches as 'msMatchesSelector'
 const matchesFunc = 'matches' in Element.prototype ? 'matches' : 'msMatchesSelector';
 
+/**
+ * @param {HTMLElement} element
+ * @param {string} selector
+ * @returns {boolean}
+ */
+function elementMatches(element, selector) {
+  // @ts-ignore [dynamic-method-name]: 'matches', or its legacy 'msMatchesSelector' alias
+  return element[matchesFunc](selector);
+}
+
 /**
  * @param {HTMLElement} element
  * @returns {boolean} Whether the element matches
  */
 function isFocusable(element) {
   // Elements that cannot be focused if they have [disabled] attribute.
-  if (element[matchesFunc]('input, select, textarea, button, object')) {
-    return element[matchesFunc](':not([disabled])');
+  if (elementMatches(element, 'input, select, textarea, button, object')) {
+    return elementMatches(element, ':not([disabled])');
   }
 
   // Elements that can be focused even if they have [disabled] attribute.
-  return element[matchesFunc]('a[href], area[href], iframe, [tabindex], [contentEditable]');
+  return elementMatches(element, 'a[href], area[href], iframe, [tabindex], [contentEditable]');
 }
 
 /**

package/components/overlays/src/utils/is-equal-config.js

@@ -12,13 +12,24 @@
  */
 export function isEqualConfig(a, b) {
   if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null) {
+    if (typeof a === 'function' && typeof b === 'function') {
+      return /** @type {Function} */ (a).toString() === /** @type {Function} */ (b).toString();
+    }
     return a === b;
   }
+  if (a instanceof Node && b instanceof Node) {
+    return a === b;
+  }
+
   const aProps = Object.keys(a);
   const bProps = Object.keys(b);
   if (aProps.length !== bProps.length) {
     return false;
   }
-  const isEqual = /** @param {string} prop */ prop => isEqualConfig(a[prop], b[prop]);
-  return aProps.every(isEqual);
+  return aProps.every(
+    prop =>
+      Object.prototype.hasOwnProperty.call(b, prop) &&
+      // @ts-ignore - dynamic property access
+      isEqualConfig(a[prop], b[prop]),
+  );
 }

package/components/overlays/test/ArrowMixin.test.js

@@ -27,6 +27,7 @@ describe('ArrowMixin', () => {
     }
 
     __toggle() {
+      // @ts-ignore [ts7-2565] TS7 checks definite assignment on this inferred field; Lit reactive property: read through a typed local instead (e.g. const next = this.x ?? DEFAULT) - a class field would shadow the accessor Lit creates from static properties
       this.opened = !this.opened;
     }
 

package/components/overlays/test/OverlayController.test.js

@@ -115,26 +115,35 @@ const withLocalTestConfig = () =>
  */
 async function createNestedEscControllers(parentContent) {
   const childContent = /** @type {HTMLDivElement} */ (parentContent.querySelector('div[id]'));
-  // Assert valid fixure
-  const isValidFixture =
-    (parentContent.id.startsWith('parent-overlay--hidesOnEsc') ||
-      parentContent.id.startsWith('parent-overlay--hidesOnOutsideEsc')) &&
-    (childContent.id.startsWith('child-overlay--hidesOnEsc') ||
-      childContent.id.startsWith('child-overlay--hidesOnOutsideEsc'));
-  if (!isValidFixture) {
-    throw new Error('Provide a valid fixture');
-  }
 
   if (parentContent.hasAttribute('data-convert-to-shadow-root')) {
     const shadowRootParent = parentContent.attachShadow({ mode: 'open' });
     shadowRootParent.appendChild(childContent);
   }
 
+  const parentConfig = {};
+  const childConfig = {};
+
   const parentHasOutsideOnEsc = parentContent.id.startsWith('parent-overlay--hidesOnOutsideEsc');
   const childHasOutsideOnEsc = childContent.id.startsWith('child-overlay--hidesOnOutsideEsc');
 
-  const parentConfig = parentHasOutsideOnEsc ? { hidesOnOutsideEsc: true } : { hidesOnEsc: true };
-  const childConfig = childHasOutsideOnEsc ? { hidesOnOutsideEsc: true } : { hidesOnEsc: true };
+  if (parentHasOutsideOnEsc) {
+    parentConfig.hidesOnOutsideEsc = true;
+  } else {
+    parentConfig.hidesOnEsc = true;
+  }
+  if (childHasOutsideOnEsc) {
+    childConfig.hidesOnOutsideEsc = true;
+  } else {
+    childConfig.hidesOnEsc = true;
+  }
+
+  const parentHasSyncChildrenCloseState =
+    parentContent.dataset.syncChildrenCloseState !== undefined;
+
+  if (parentHasSyncChildrenCloseState) {
+    parentConfig.syncChildrenCloseState = true;
+  }
 
   const parentOverlay = new OverlayController({
     ...withGlobalTestConfig(),
@@ -283,8 +292,9 @@ describe('OverlayController', () => {
             contentNode,
           });
         };
+
         expect(createOverlayController).to.throw(
-          '[OverlayController] Could not find a render target, since the provided contentNode is not connected to the DOM. Make sure that it is connected, e.g. by doing "document.body.appendChild(contentNode)", before passing it on.',
+          '[OverlayController] Could not find a render target, makes sure contentNode has a parent element (or contentWrapperNode is connected)',
         );
       });
 
@@ -346,6 +356,21 @@ describe('OverlayController', () => {
       await ctrl.hide();
       expect(ctrl.isShown).to.be.false;
     });
+
+    it('cleans up the dom structure it created', async () => {
+      const contentNode = /** @type {HTMLElement} */ (fixtureSync(html`<div>my content</div>`));
+      const ctrl = new OverlayController({
+        placementMode: 'global',
+        contentNode,
+      });
+      await ctrl.show();
+      expect(ctrl.contentWrapperNode).to.exist;
+      expect(ctrl.__wrappingDialogNode).to.exist;
+
+      await ctrl.teardown();
+      expect(ctrl.contentWrapperNode).to.not.exist;
+      expect(ctrl.__wrappingDialogNode).to.not.exist;
+    });
   });
 
   describe('Node Configuration', () => {
@@ -403,7 +428,7 @@ describe('OverlayController', () => {
               { ignoreAttributes: ['closedby'] },
             );
 
-            expect(el).lightDom.to.equal(`<div slot="content">projected</div>`);
+            expect(el).lightDom.to.equal(`<div data-content="" slot="content">projected</div>`);
           });
         });
 
@@ -425,7 +450,7 @@ describe('OverlayController', () => {
               `
               <dialog data-overlay-outer-wrapper="" open="" role="none" style="${wrappingDialogNodeStyle}">
                 <div data-id="content-wrapper">
-                  <div id="content">non projected</div>
+                  <div data-content="" id="content">non projected</div>
                 </div>
               </dialog>
           `,
@@ -620,6 +645,7 @@ describe('OverlayController', () => {
     });
   });
 
+  // TODO: make features modular (so they can be treeshaken) and test their lifecycle within this desrcibe
   describe('Feature Configuration', () => {
     describe('trapsKeyboardFocus', () => {
       it('focuses the overlay on show', async () => {
@@ -863,10 +889,7 @@ describe('OverlayController', () => {
 
     describe('Nested hidesOnEsc / hidesOnOutsideEsc', () => {
       describe('Parent has hidesOnEsc and child has hidesOnOutsideEsc', () => {
-        // TODO: This test is flaky. We need to investigate why the child overlay
-        // is not staying shown after the parent overlay is hidden. The failing line
-        // is highlighted below.
-        it.skip('on [Escape] press in child overlay: parent hides, child stays shown', async () => {
+        it('on [Escape] press in child overlay: parent hides, child stays shown', async () => {
           const parentContent = /** @type {HTMLDivElement} */ (
             await fixture(
               html` <!-- -->
@@ -877,12 +900,16 @@ describe('OverlayController', () => {
           );
           const { parentOverlay, childOverlay } = await createNestedEscControllers(parentContent);
           await mimicEscapePress(childOverlay.contentNode);
-          await waitUntil(() => !parentOverlay.isShown);
-
-          // TODO: This is the failing line ("sometimes").
-          // The child overlay is not staying shown after the parent overlay is hidden.
-          await waitUntil(() => childOverlay.isShown);
-
+          await childOverlay._showComplete;
+          await parentOverlay._showComplete;
+          await childOverlay._hideComplete;
+          await parentOverlay._hideComplete;
+          if (!childOverlay.isShown) {
+            await waitUntil(() => childOverlay.isShown);
+          }
+          if (parentOverlay.isShown) {
+            await waitUntil(() => !parentOverlay.isShown);
+          }
           await childOverlay.teardown();
           await parentOverlay.teardown();
         });
@@ -988,6 +1015,7 @@ describe('OverlayController', () => {
         });
       });
     });
+
     describe('hidesOnOutsideClick', () => {
       it('hides on outside click', async () => {
         const contentNode = /** @type {HTMLElement} */ (await fixture('<div>Content</div>'));
@@ -1708,6 +1736,97 @@ describe('OverlayController', () => {
         expect(ctrl1.hasActiveBackdrop).to.be.true;
       });
     });
+
+    describe('elementToFocusOnShow', () => {
+      it('adds tabindex="-1" to the content node when elementToFocusOnShow is true', async () => {
+        const ctrl = new OverlayController({
+          ...withGlobalTestConfig(),
+          isBlocking: false,
+          elementToFocusOnShow: true,
+        });
+        const contentNode = /** @type {HTMLElement} */ (await fixture('<div>Content</div>'));
+        ctrl.updateConfig({ contentNode });
+        await ctrl.show();
+        expect(contentNode.getAttribute('tabindex')).to.equal('-1');
+      });
+
+      it('makes contentNode the root of "next tab flow"', async () => {
+        const ctrl = new OverlayController({
+          ...withGlobalTestConfig(),
+          isBlocking: false,
+          elementToFocusOnShow: true,
+        });
+        const contentNode = /** @type {HTMLElement} */ (
+          await fixture('<div><button>Button</button></div>')
+        );
+        ctrl.updateConfig({ contentNode });
+        await ctrl.show();
+        const button = /** @type {HTMLButtonElement} */ (contentNode.querySelector('button'));
+        button.focus();
+        expect(isActiveElement(button)).to.be.true;
+      });
+    });
+
+    describe('syncChildrenCloseState', () => {
+      it('does not close all children of nested controllers when syncChildrenCloseState is false', async () => {
+        const parentContent = /** @type {HTMLDivElement} */ (
+          await fixture(
+            html` <!-- -->
+              <div data-sync-children-close-state id="parent-overlay">
+                <div id="child-overlay">we open our child and it will close when parent does</div>
+              </div>`,
+          )
+        );
+        const { parentOverlay, childOverlay } = await createNestedEscControllers(parentContent);
+        expect(parentOverlay.isShown).to.be.true;
+        expect(childOverlay.isShown).to.be.true;
+
+        await parentOverlay.hide();
+        await childOverlay._hideComplete;
+        expect(parentOverlay.isShown).to.be.false;
+        expect(childOverlay.isShown).to.be.false;
+      });
+
+      it('does not close all children of nested controllers when syncChildrenCloseState is false', async () => {
+        const parentContent = /** @type {HTMLDivElement} */ (
+          await fixture(
+            html` <!-- -->
+              <div id="parent-overlay">
+                <div id="child-overlay">
+                  we open our child and it will not close when parent does
+                </div>
+              </div>`,
+          )
+        );
+        const { parentOverlay, childOverlay } = await createNestedEscControllers(parentContent);
+        expect(parentOverlay.isShown).to.be.true;
+        expect(childOverlay.isShown).to.be.true;
+
+        await parentOverlay.hide();
+        expect(parentOverlay.isShown).to.be.false;
+        expect(childOverlay.isShown).to.be.true;
+      });
+    });
+
+    describe('isActivated', () => {
+      it('allows to conditionally disable overlay/openable functionality (for responsive context like nav menus, accordions/collapsibles vs plain headings/content etc.)', async () => {
+        const ctrl = new OverlayController({
+          ...withGlobalTestConfig(),
+          isActivated: false,
+        });
+        expect(ctrl.__hasSetup).to.be.false;
+        ctrl.updateConfig({
+          isActivated: true,
+        });
+        expect(ctrl.__hasSetup).to.be.true;
+      });
+    });
+
+    // TODO
+    describe('hideVisually', () => {});
+
+    // TODO
+    describe('requireConnectedNodes', () => {});
   });
 
   describe('Show / Hide / Toggle', () => {
@@ -2298,6 +2417,7 @@ describe('OverlayController', () => {
     });
 
     it('should run with scroll prevention', async () => {
+      await overlayControllerPreventsScroll.hide();
       await overlayControllerPreventsScroll.show();
 
       expect(

package/components/overlays/test/local-positioning.test.js

@@ -61,8 +61,10 @@ describe('Local Positioning', () => {
         ...withLocalTestConfig(),
       });
       await ctrl.show();
+      // @ts-ignore [popper-instance-access-in-test]
       expect(ctrl._popper.state.modifiersData).to.exist;
       await ctrl.hide();
+      // @ts-ignore [popper-instance-access-in-test]
       expect(ctrl._popper.state.modifiersData).to.exist;
     });
 
@@ -203,6 +205,7 @@ describe('Local Positioning', () => {
       `);
 
       await ctrl.show();
+      // @ts-ignore [popper-instance-access-in-test]
       expect(ctrl._popper.state.modifiersData.offset.auto).to.eql({ x: 0, y: 16 });
     });
 
@@ -296,6 +299,7 @@ describe('Local Positioning', () => {
         },
       });
       await ctrl.show();
+      // @ts-ignore [popper-instance-access-in-test]
       expect(ctrl._popper.options.modifiers.offset.offset).to.equal('0, 20px');
       expect(normalizeTransformStyle(ctrl.contentWrapperNode.style.transform)).to.equal(
         'translate3d(10px, -40px, 0px)',