@brightspace-ui/core 3.298.0 → 3.299.0

package/components/dropdown/README.md

@@ -236,6 +236,7 @@ To make your usage of `d2l-dropdown-more` accessible, use the following property
 | Name | Description |
 |---|---|
 | `d2l-dropdown-open` | Dispatched when the dropdown is opened |
+| `d2l-dropdown-open-async` | Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content |
 | `d2l-dropdown-close` | dispatched when the dropdown is closed |
 | `d2l-dropdown-position` | Dispatched when the dropdown position finishes adjusting |
 | `d2l-dropdown-focus-enter` | dispatched when the 'trap-focus' attribute is applied and the focus-trap is entered (trap-focus option only) |
@@ -251,6 +252,35 @@ To make your usage of `d2l-dropdown-more` accessible, use the following property
 ### Methods
 * `async resize()`: Call if the size of the content changes due to a change in a nested component. The nested component may choose to fire a custom event, which the component containing the `d2l-dropdown-content` can catch and call this method. |
 
+### Asynchronous Content
+
+For dropdown content that's fetched asynchronously, the `d2l-dropdown-open-async` event can be leveraged to let `<d2l-dropdown-content>` know when things are ready. That way, automatic focus and sizing logic until can be delayed.
+
+- Add a listener for the `d2l-dropdown-open-async` event
+- In the handler, call `preventDefault()` on the event to let it know that the content will be loaded asynchronously
+- Fetch the content and when it's ready, call `complete()` on the event detail
+- Note: the `d2l-dropdown-open-async` event will only be dispatched the first time the dropdown is opened, so no need to ignore subsequent calls
+
+```javascript
+class MyElem extends LitElement {
+  render() {
+    const content = this._loading ? 'Loading...' : 'Loaded!';
+    return html`
+      <d2l-dropdown-content
+        @d2l-dropdown-open-async="${this.#handleDropdownOpenAsync}">
+        ${content}
+      </d2l-dropdown-content>
+    `;
+  }
+  async #handleDropdownOpenAsync(e) {
+    e.preventDefault();
+    await this.#fetchData();
+    this._loaded = true;
+    e.detail.complete();
+  }
+}
+```
+
 ## Content: Menu [d2l-dropdown-menu]
 `d2l-dropdown-menu` is a container for a [d2l-menu](https://github.com/BrightspaceUI/core/tree/main/components/menu) component. It provides additional support on top of `d2l-dropdown-content` for closing the menu when menu items are selected, resetting to the root of nested menus when reopening and automatic resizing when the menu resizes.
 

package/components/dropdown/dropdown-content.js

@@ -7,6 +7,8 @@ import { LitElement } from 'lit';
  * @slot header - Sticky container at the top of the dropdown
  * @slot footer - Sticky container at the bottom of the dropdown
  * @fires d2l-dropdown-open - Dispatched when the dropdown is opened
+ * @fires d2l-dropdown-open-async - Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content
+ * @fires d2l-popover-open-async - Ignore
  */
 class DropdownContent extends DropdownPopoverMixin(LitElement) { }
 customElements.define('d2l-dropdown-content', DropdownContent);

package/components/dropdown/dropdown-menu.js

@@ -11,6 +11,8 @@ const dropdownDelay = 300;
  * @slot header - Sticky container at the top of the dropdown
  * @slot footer - Sticky container at the bottom of the dropdown
  * @fires d2l-dropdown-open - Dispatched when the dropdown is opened
+ * @fires d2l-dropdown-open-async - Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content
+ * @fires d2l-popover-open-async - Ignore
  */
 class DropdownMenu extends ThemeMixin(DropdownPopoverMixin(LitElement)) {
 

package/components/dropdown/dropdown-popover-mixin.js

@@ -198,6 +198,7 @@ export const DropdownPopoverMixin = superclass => class extends LocalizeCoreElem
 			this.#resizeObserver.observe(this.#contentElement);
 		}
 		this.addEventListener('d2l-popover-open', this.#handlePopoverOpen);
+		this.addEventListener('d2l-popover-open-async', this.#handlePopoverOpenAsync);
 		this.addEventListener('d2l-popover-close', this.#handlePopoverClose);
 		this.addEventListener('d2l-popover-position', this.#handlePopoverPosition);
 		this.addEventListener('d2l-popover-focus-enter', this.#handlePopoverFocusEnter);
@@ -386,6 +387,22 @@ export const DropdownPopoverMixin = superclass => class extends LocalizeCoreElem
 		});
 	}
 
+	#handlePopoverOpenAsync(e) {
+		const openAsyncEvent = new CustomEvent(
+			'd2l-dropdown-open-async', {
+				bubbles: false,
+				cancelable: true,
+				composed: false,
+				detail: { complete: e.detail.complete }
+			}
+		);
+		/** @ignore */
+		this.dispatchEvent(openAsyncEvent);
+		if (openAsyncEvent.defaultPrevented) {
+			e.preventDefault();
+		}
+	}
+
 	#handlePopoverPosition() {
 		this.#toggleScrollStyles();
 

package/components/dropdown/dropdown-tabs.js

@@ -7,6 +7,8 @@ import { DropdownPopoverMixin } from './dropdown-popover-mixin.js';
  * @slot header - Sticky container at the top of the dropdown
  * @slot footer - Sticky container at the bottom of the dropdown
  * @fires d2l-dropdown-open - Dispatched when the dropdown is opened
+ * @fires d2l-dropdown-open-async - Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content
+ * @fires d2l-popover-open-async - Ignore
  */
 class DropdownTabs extends DropdownPopoverMixin(LitElement) {
 

package/components/popover/popover-mixin.js

@@ -10,6 +10,7 @@ import { _offscreenStyleDeclarations } from '../offscreen/offscreen.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { tryGetIfrauBackdropService } from '../../helpers/ifrauBackdropService.js';
+import { waitForElem } from '../../helpers/internal/waitForElem.js';
 
 export const positionLocations = Object.freeze({
 	blockEnd: 'block-end',
@@ -369,10 +370,12 @@ export const PopoverMixin = superclass => class extends superclass {
 
 		this._dismissibleId = setDismissible(() => this.close());
 
-		this.#focusContent(this);
-
 		this.#addRepositionHandlers();
 
+		await this.#waitForOpenAsync();
+
+		this.#focusContent(this);
+
 		/** @ignore */
 		this.dispatchEvent(new CustomEvent('d2l-popover-open', { bubbles: true, composed: true }));
 
@@ -582,6 +585,7 @@ export const PopoverMixin = superclass => class extends superclass {
 	}
 
 	#ancestorMutations;
+	#firstOpen = true;
 	#ifrauContextInfo;
 	#mediaQueryList;
 
@@ -1194,4 +1198,32 @@ export const PopoverMixin = superclass => class extends superclass {
 		removeResizeNoopEventListener(this.#handleResize);
 	}
 
+	async #waitForOpenAsync() {
+		if (!this.#firstOpen) return;
+		this.#firstOpen = false;
+
+		let doWait = false;
+		await new Promise(resolve => {
+			const openAsyncEvent = new CustomEvent(
+				'd2l-popover-open-async', {
+					bubbles: false,
+					cancelable: true,
+					composed: false,
+					detail: { complete: resolve }
+				}
+			);
+			/** @ignore */
+			this.dispatchEvent(openAsyncEvent);
+			if (!openAsyncEvent.defaultPrevented) {
+				resolve();
+			} else {
+				doWait = true;
+			}
+		});
+		if (doWait) {
+			await waitForElem(this.#getContentContainer());
+			await this.position();
+		}
+	}
+
 };

package/components/tooltip/tooltip.js

@@ -55,6 +55,7 @@ let activeTooltip = null;
  * @slot - Default content placed inside of the tooltip
  * @fires d2l-tooltip-show - Dispatched when the tooltip is opened
  * @fires d2l-tooltip-hide - Dispatched when the tooltip is closed
+ * @fires d2l-popover-open-async - Ignore
  */
 class Tooltip extends PopoverMixin(LitElement) {
 

package/custom-elements.json

@@ -3513,6 +3513,14 @@
           "name": "d2l-dropdown-open",
           "description": "Dispatched when the dropdown is opened"
         },
+        {
+          "name": "d2l-dropdown-open-async",
+          "description": "Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content"
+        },
+        {
+          "name": "d2l-popover-open-async",
+          "description": "Ignore"
+        },
         {
           "name": "d2l-dropdown-close",
           "description": "Dispatched when the dropdown is closed"
@@ -3884,6 +3892,14 @@
           "name": "d2l-dropdown-open",
           "description": "Dispatched when the dropdown is opened"
         },
+        {
+          "name": "d2l-dropdown-open-async",
+          "description": "Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content"
+        },
+        {
+          "name": "d2l-popover-open-async",
+          "description": "Ignore"
+        },
         {
           "name": "d2l-dropdown-close",
           "description": "Dispatched when the dropdown is closed"
@@ -4255,6 +4271,14 @@
           "name": "d2l-dropdown-open",
           "description": "Dispatched when the dropdown is opened"
         },
+        {
+          "name": "d2l-dropdown-open-async",
+          "description": "Dispatched before the dropdown is opened for the first time, giving an opportunity to load async content"
+        },
+        {
+          "name": "d2l-popover-open-async",
+          "description": "Ignore"
+        },
         {
           "name": "d2l-dropdown-close",
           "description": "Dispatched when the dropdown is closed"
@@ -13890,6 +13914,11 @@
           "type": "array",
           "default": "[\"styles\",null]"
         }
+      ],
+      "events": [
+        {
+          "name": "d2l-popover-open-async"
+        }
       ]
     },
     {
@@ -17313,6 +17342,10 @@
         {
           "name": "d2l-tooltip-hide",
           "description": "Dispatched when the tooltip is closed"
+        },
+        {
+          "name": "d2l-popover-open-async",
+          "description": "Ignore"
         }
       ],
       "slots": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "3.298.0",
+  "version": "3.299.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",