@umbraco-cms/backoffice 17.2.1 → 17.3.0-rc

package/dist-cms/packages/core/extension-registry/components/extension-slot/extension-slot.element.js

@@ -9,11 +9,78 @@ import { css, repeat, customElement, property, state, html, nothing } from '../.
 import { UmbExtensionsElementInitializer, } from '../../../../../libs/extension-api/index.js';
 import { UmbLitElement } from '../../../lit-element/index.js';
 /**
+ * A custom element that dynamically renders extensions registered in the extension registry.
+ *
+ * This element observes the extension registry and renders all permitted extensions matching the specified type(s).
+ * Extensions are automatically filtered by their conditions and can be further filtered using the `filter` property.
+ * The element handles extension lifecycle, property passing, and event binding.
  * @element umb-extension-slot
- * @description A element which renderers the extensions of a given type or types.
- * @slot default - slot for inserting additional things into this slot.
- * @class UmbExtensionSlot
- * @augments {UmbLitElement}
+ * @slot default - Fallback content shown when no extensions are permitted (unless `fallbackRenderMethod` is provided).
+ * @example Basic usage - Render all extensions of a type
+ * ```html
+ * <umb-extension-slot type="workspaceFooterApp"></umb-extension-slot>
+ * ```
+ * @example Multiple types - Render extensions from multiple types
+ * ```html
+ * <umb-extension-slot .type=${['headerApp', 'headerAppButton']}></umb-extension-slot>
+ * ```
+ * @example Single extension - Only render the first matching extension
+ * ```html
+ * <umb-extension-slot type="menu" single></umb-extension-slot>
+ * ```
+ * @example With filter - Filter extensions by manifest properties
+ * ```html
+ * <umb-extension-slot
+ *     type="menu"
+ *     .filter=${(manifest) => manifest.alias === 'My.Menu.Alias'}>
+ * </umb-extension-slot>
+ * ```
+ * @example With props - Pass data to extension elements
+ * ```html
+ * <umb-extension-slot
+ *     type="searchResultItem"
+ *     .props=${{ item: searchResult }}>
+ * </umb-extension-slot>
+ * ```
+ * @example With default element - Specify fallback element for extensions without one
+ * ```html
+ * <umb-extension-slot
+ *     type="menu"
+ *     default-element="umb-menu">
+ * </umb-extension-slot>
+ * ```
+ * @example Combined usage - Filter, props, default element, and single
+ * ```html
+ * <umb-extension-slot
+ *     type="searchResultItem"
+ *     single
+ *     .filter=${(manifest) => manifest.forEntityTypes.includes(item.entityType)}
+ *     .props=${{ item }}
+ *     default-element="umb-search-result-item">
+ * </umb-extension-slot>
+ * ```
+ * @example Custom render method - Control how extensions are rendered
+ * ```html
+ * <umb-extension-slot
+ *     type="blockEditorCustomView"
+ *     single
+ *     .filter=${this.#extensionSlotFilterMethod}
+ *     .renderMethod=${(ext, index) => html`<div class="wrapper">${ext.component}</div>`}
+ *     .props=${this._blockViewProps}>
+ * </umb-extension-slot>
+ * ```
+ * @example Fallback content - Shows the slotted content when no extensions match
+ * ```html
+ * <umb-extension-slot type="myExtensionType">
+ *     <p>No extensions available</p>
+ * </umb-extension-slot>
+ * ```
+ * @example Fallback render method - Shows the result of the fallbackRenderMethod when no extensions match
+ * ```html
+ * <umb-extension-slot type="myExtensionType">
+ *     .fallbackRenderMethod=${() => html`<p>No extensions available</p>`}
+ * </umb-extension-slot>
+ * ```
  */
 // TODO: Refactor extension-slot and extension-with-api slot.
 // TODO: Fire change event.
@@ -21,14 +88,18 @@ import { UmbLitElement } from '../../../lit-element/index.js';
 let UmbExtensionSlotElement = class UmbExtensionSlotElement extends UmbLitElement {
     #attached = false;
     #extensionsController;
+    #disconnectAC;
     /**
-     * The type or types of extensions to render.
-     * @type {string | string[]}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-slot type="my-extension-type"></umb-extension-slot>
-     * or multiple:
+     * The type or types of extensions to render. Required for the slot to display anything.
+     * Can be a single type string or an array of type strings to render extensions from multiple types.
+     * @example Single type
+     * ```html
+     * <umb-extension-slot type="workspaceFooterApp"></umb-extension-slot>
+     * ```
+     * @example Multiple types
+     * ```html
      * <umb-extension-slot .type=${['my-extension-type','another-extension-type']}></umb-extension-slot>
+     * ```
      */
     set type(value) {
         if (value === this.#type)
@@ -41,12 +112,24 @@ let UmbExtensionSlotElement = class UmbExtensionSlotElement extends UmbLitElemen
     }
     #type;
     /**
-     * Filter method for extension manifests.
-     * This is an initial filter taking effect before conditions or overwrites, the extensions will still be filtered by the conditions defined in the manifest.
-     * @type {(manifest: any) => boolean}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-slot type="my-extension-type" .filter=${(ext) => ext.meta.anyPropToFilter === 'foo'}></umb-extension-slot>
+     * Filter function for extension manifests.
+     * This is an initial filter taking effect before conditions or overwrites are applied.
+     * Extensions will still be filtered by their manifest-defined conditions after this filter.
+     * The filter function receives the extension manifest and should return true to include it.
+     * @example Filter by manifest alias
+     * ```html
+     * <umb-extension-slot
+     *     type="menu"
+     *     .filter=${(manifest) => manifest.alias === 'My.Menu.Alias'}>
+     * </umb-extension-slot>
+     * ```
+     * @example Filter by meta properties
+     * ```html
+     * <umb-extension-slot
+     *     type="searchResultItem"
+     *     .filter=${(manifest) => manifest.forEntityTypes.includes(entityType)}>
+     * </umb-extension-slot>
+     * ```
      */
     set filter(value) {
         if (value === this.#filter)
@@ -59,12 +142,16 @@ let UmbExtensionSlotElement = class UmbExtensionSlotElement extends UmbLitElemen
     }
     #filter = () => true;
     /**
-     * Properties to pass to the extensions elements.
-     * Notice: The individual manifest of the extension is parsed to each extension element no matter if this is set or not.
-     * @type {Record<string, any>}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-slot type="my-extension-type" .props=${{foo: 'bar'}}></umb-extension-slot>
+     * Properties to pass to all rendered extension elements.
+     * These properties are spread onto each extension element instance.
+     * Note: The extension's manifest is always passed automatically regardless of this setting.
+     * @example Pass data to extension elements
+     * ```html
+     * <umb-extension-slot
+     *     type="searchResultItem"
+     *     .props=${{ item: searchResult, showDetails: true }}>
+     * </umb-extension-slot>
+     * ```
      */
     set props(newVal) {
         this.#props = newVal;
@@ -76,6 +163,21 @@ let UmbExtensionSlotElement = class UmbExtensionSlotElement extends UmbLitElemen
         return this.#props;
     }
     #props = {};
+    /**
+     * Event listeners to attach to all rendered extension elements.
+     * The key is the event name, and the value is the event handler function.
+     * Listeners are automatically added when extensions are rendered and removed on disconnect.
+     * @example Listen for custom events from extensions
+     * ```html
+     * <umb-extension-slot
+     *     type="myExtensionType"
+     *     .events=${{
+     *         'item-selected': (e) => this.#handleItemSelected(e),
+     *         'action-clicked': (e) => this.#handleAction(e)
+     *     }}>
+     * </umb-extension-slot>
+     * ```
+     */
     set events(newVal) {
         this.#events = newVal;
         if (this.#extensionsController) {
@@ -89,15 +191,33 @@ let UmbExtensionSlotElement = class UmbExtensionSlotElement extends UmbLitElemen
     connectedCallback() {
         super.connectedCallback();
         this.#attached = true;
+        // Cancel any pending destruction if we're being reconnected (e.g., during a DOM move/sort)
+        if (this.#disconnectAC) {
+            this.#disconnectAC.abort();
+            this.#disconnectAC = undefined;
+            // Only skip re-initialization if the controller still exists
+            if (this.#extensionsController) {
+                return;
+            }
+        }
         this.#observeExtensions();
     }
     disconnectedCallback() {
-        // _permitted is reset as the extensionsController fires a callback on destroy.
-        this.#removeEventListenersFromExtensionElement();
-        this.#attached = false;
-        this.#extensionsController?.destroy();
-        this.#extensionsController = undefined;
         super.disconnectedCallback();
+        this.#attached = false;
+        // Abort any previously pending disconnect before scheduling a new one
+        this.#disconnectAC?.abort();
+        // Defer destruction to allow for reconnection during DOM moves/sorting
+        // If reconnected before the microtask resolves, the AbortController cancels the callback
+        const abortController = (this.#disconnectAC = new AbortController());
+        queueMicrotask(() => {
+            if (!abortController.signal.aborted) {
+                this.#disconnectAC = undefined;
+                this.#removeEventListenersFromExtensionElement();
+                this.#extensionsController?.destroy();
+                this.#extensionsController = undefined;
+            }
+        });
     }
     #observeExtensions() {
         if (!this.#attached)

package/dist-cms/packages/core/extension-registry/components/extension-with-api-slot/extension-with-api-slot.element.d.ts

@@ -3,70 +3,251 @@ import { nothing } from '../../../../../external/lit/index.js';
 import { type UmbExtensionElementAndApiInitializer, type UmbApiConstructorArgumentsMethodType, type ApiLoaderProperty } from '../../../../../libs/extension-api/index.js';
 import { UmbLitElement } from '../../../lit-element/index.js';
 /**
+ * A custom element that dynamically renders extensions with both UI elements and API classes.
+ *
+ * Similar to `umb-extension-slot`, this element observes the extension registry and renders permitted extensions.
+ * The key difference is that this slot also initializes an API class for each extension, allowing extensions
+ * to have both a visual component and associated business logic. The API instance is created with configurable
+ * constructor arguments and can receive properties.
  * @element umb-extension-with-api-slot
- * @description A element which renderers the extensions of a given type or types.
- * @slot default - slot for inserting additional things into this slot.
- * @class UmbExtensionSlot
- * @augments {UmbLitElement}
+ * @slot default - Fallback content shown when no extensions are permitted (unless `fallbackRenderMethod` is provided).
+ * @example Basic usage - Render extensions with APIs
+ * ```html
+ * <umb-extension-with-api-slot type="entityAction"></umb-extension-with-api-slot>
+ * ```
+ * @example Multiple types - Render extensions from multiple types
+ * ```html
+ * <umb-extension-with-api-slot .type=${['workspaceAction', 'workspaceActionMenuItem']}></umb-extension-with-api-slot>
+ * ```
+ * @example Single extension - Only render the first matching extension
+ * ```html
+ * <umb-extension-with-api-slot type="collectionTextFilter" single></umb-extension-with-api-slot>
+ * ```
+ * @example With filter - Filter extensions by manifest properties
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="entityAction"
+ *     .filter=${(manifest) => manifest.forEntityTypes.includes(entityType)}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example With element props - Pass data to extension elements
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="entityAction"
+ *     .elementProps=${{ entityType, unique }}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example With API args - Pass constructor arguments to extension APIs
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="workspaceAction"
+ *     .apiArgs=${[workspaceContext]}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example With API args method - Dynamic constructor arguments based on manifest
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="workspaceAction"
+ *     .apiArgs=${(manifest) => [workspaceContext, manifest.meta]}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example Combined usage - Filter, element props, and API args
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="entityAction"
+ *     .filter=${this._filter}
+ *     .elementProps=${this._props}
+ *     .apiArgs=${this._apiArgs}
+ *     .renderMethod=${(ext, index) => ext.component}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example Custom render method - Control how extensions are rendered
+ * ```html
+ * <umb-extension-with-api-slot
+ *     type="menuItem"
+ *     .renderMethod=${(ext, index) => html`
+ *         <div class="menu-item-wrapper">
+ *             ${ext.component}
+ *         </div>
+ *     `}>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example Fallback content - Shows the slotted content when no extensions match
+ * ```html
+ * <umb-extension-with-api-slot type="myExtensionType">
+ *     <p>No actions available</p>
+ * </umb-extension-with-api-slot>
+ * ```
+ * @example Fallback render method - Shows the result of the fallbackRenderMethod when no extensions match
+ * ```html
+ * <umb-extension-with-api-slot type="myExtensionType">
+ *     .fallbackRenderMethod=${() => html`<p>No extensions available</p>`}
+ * </umb-extension-with-api-slot>
+ * ```
  */
 export declare class UmbExtensionWithApiSlotElement extends UmbLitElement {
     #private;
     private _permitted?;
-    single?: boolean;
     /**
-     * The type or types of extensions to render.
-     * @type {string | string[]}
-     * @memberof UmbExtensionSlot
+     * When true, only renders the highest weighted permitted extension.
+     * Useful for extension types where only one instance should be displayed.
      * @example
-     * <umb-extension-with-api-slot type="my-extension-type"></umb-extension-with-api-slot>
-     * or multiple:
-     * <umb-extension-with-api-slot .type=${['my-extension-type','another-extension-type']}></umb-extension-with-api-slot>
+     * ```html
+     * <umb-extension-with-api-slot type="collectionTextFilter" single></umb-extension-with-api-slot>
+     * ```
+     */
+    single?: boolean;
+    /**
+     * The type or types of extensions to render. Required for the slot to display anything.
+     * Can be a single type string or an array of type strings to render extensions from multiple types.
+     * @example Single type
+     * ```html
+     * <umb-extension-with-api-slot type="entityAction"></umb-extension-with-api-slot>
+     * ```
+     * @example Multiple types
+     * ```html
+     * <umb-extension-with-api-slot .type=${['workspaceAction', 'workspaceActionMenuItem']}></umb-extension-with-api-slot>
+     * ```
      */
     get type(): string | string[] | undefined;
     set type(value: string | string[] | undefined);
     /**
-     * Filter method for extension manifests.
-     * This is an initial filter taking effect before conditions or overwrites, the extensions will still be filtered by the conditions defined in the manifest.
-     * @type {(manifest: any) => boolean}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-with-api-slot type="my-extension-type" .filter=${(ext) => ext.meta.anyPropToFilter === 'foo'}></umb-extension-with-api-slot>
+     * Filter function for extension manifests.
+     * This is an initial filter taking effect before conditions or overwrites are applied.
+     * Extensions will still be filtered by their manifest-defined conditions after this filter.
+     * The filter function receives the extension manifest and should return true to include it.
+     * @example Filter by entity type
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .filter=${(manifest) => manifest.forEntityTypes.includes(entityType)}>
+     * </umb-extension-with-api-slot>
+     * ```
+     * @example Filter by meta properties
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="workspaceAction"
+     *     .filter=${(manifest) => manifest.meta.look === 'primary'}>
+     * </umb-extension-with-api-slot>
+     * ```
      */
     get filter(): (manifest: any) => boolean;
     set filter(value: (manifest: any) => boolean);
     /**
-     * Properties to pass to the extensions elements.
-     * Notice: The individual manifest of the extension is parsed to each extension element no matter if this is set or not.
-     * @type {Record<string, any>}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-with-api-slot type="my-extension-type" .elementProps=${{foo: 'bar'}}></umb-extension-with-api-slot>
+     * Properties to pass to all rendered extension elements.
+     * These properties are spread onto each extension element instance.
+     * Note: The extension's manifest is always passed automatically regardless of this setting.
+     * @example Pass entity context to extension elements
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .elementProps=${{ entityType: 'document', unique: documentId }}>
+     * </umb-extension-with-api-slot>
+     * ```
      */
     get elementProps(): Record<string, unknown> | undefined;
     set elementProps(newVal: Record<string, unknown> | undefined);
     /**
-     * constructor arguments to pass to the extensions apis.
-     * Notice: The host argument will be prepended as the first argument no matter if this is set or not.
-     * @type {Array<unknown>}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-with-api-slot type="my-extension-type" .apiArgs=${{foo: 'bar'}}></umb-extension-with-api-slot>
+     * Constructor arguments to pass when instantiating the extension APIs.
+     * Can be an array of arguments or a function that receives the manifest and returns arguments.
+     * Note: The host controller is always prepended as the first argument automatically.
+     * @example Static array of arguments
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="workspaceAction"
+     *     .apiArgs=${[workspaceContext]}>
+     * </umb-extension-with-api-slot>
+     * ```
+     * @example Dynamic arguments based on manifest
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .apiArgs=${(manifest) => [entityContext, manifest.meta.actionType]}>
+     * </umb-extension-with-api-slot>
+     * ```
      */
     get apiArgs(): Array<unknown> | UmbApiConstructorArgumentsMethodType<any> | undefined;
     set apiArgs(newVal: Array<unknown> | UmbApiConstructorArgumentsMethodType<any> | undefined);
     /**
-     * Properties to pass to the extensions apis.
-     * Notice: The individual manifest of the extension is parsed to each extension api no matter if this is set or not.
-     * @type {Record<string, any>}
-     * @memberof UmbExtensionSlot
-     * @example
-     * <umb-extension-with-api-slot type="my-extension-type" .apiProps=${{foo: 'bar'}}></umb-extension-with-api-slot>
+     * Properties to pass to all extension API instances after construction.
+     * These properties are spread onto each API instance.
+     * Note: The extension's manifest is always passed automatically regardless of this setting.
+     * @example Pass configuration to extension APIs
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="workspaceAction"
+     *     .apiProps=${{ saveOnClick: true, validateFirst: false }}>
+     * </umb-extension-with-api-slot>
+     * ```
      */
     get apiProps(): Record<string, unknown> | undefined;
     set apiProps(newVal: Record<string, unknown> | undefined);
+    /**
+     * Fallback element tag name to use when an extension manifest doesn't specify its own element.
+     * This allows extensions to rely on a default UI implementation while still being registered.
+     * @example Provide a default action element
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     default-element="umb-entity-action">
+     * </umb-extension-with-api-slot>
+     * ```
+     */
     defaultElement?: string;
+    /**
+     * Fallback API loader to use when an extension manifest doesn't specify its own API.
+     * This allows extensions to rely on a default API implementation while still being registered.
+     * Can be a string path to the API module or an API loader function.
+     * @example Provide a default API
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="workspaceAction"
+     *     .defaultApi=${() => import('./default-workspace-action.api.js')}>
+     * </umb-extension-with-api-slot>
+     * ```
+     */
     defaultApi?: ApiLoaderProperty;
+    /**
+     * Custom render function for controlling how each extension is rendered.
+     * When provided, this function is called for each permitted extension instead of the default rendering.
+     * The function receives the extension initializer (with `component`, `api`, and `manifest` properties) and the index,
+     * and should return a TemplateResult, HTMLElement, null, or nothing.
+     * @example Wrap extensions in custom markup
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .renderMethod=${(ext, index) => html`
+     *         <div class="action-wrapper" data-index=${index}>
+     *             ${ext.component}
+     *         </div>
+     *     `}>
+     * </umb-extension-with-api-slot>
+     * ```
+     * @example Access API from render method
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .renderMethod=${(ext, index) => {
+     *         console.log('API instance:', ext.api);
+     *         return ext.component;
+     *     }}>
+     * </umb-extension-with-api-slot>
+     * ```
+     */
     renderMethod?: (extension: UmbExtensionElementAndApiInitializer, index: number) => TemplateResult | TemplateResult<1> | HTMLElement | null | undefined | typeof nothing;
+    /**
+     * Render function called when no extensions are permitted.
+     * When provided, this function is called instead of rendering the default slot content.
+     * Useful for providing custom empty states or fallback UI.
+     * The function should return a TemplateResult, HTMLElement, null, or nothing.
+     * @example Custom empty state
+     * ```html
+     * <umb-extension-with-api-slot
+     *     type="entityAction"
+     *     .fallbackRenderMethod=${() => html`<div class="no-actions">No actions available</div>`}>
+     * </umb-extension-with-api-slot>
+     * ```
+     */
     fallbackRenderMethod?: () => TemplateResult | TemplateResult<1> | HTMLElement | null | undefined | typeof nothing;
     connectedCallback(): void;
     disconnectedCallback(): void;