@ui5/webcomponents-base 0.0.0-dcd8e5389 → 0.0.0-ddc5fe31b

package/dist/UI5Element.d.ts

@@ -26,12 +26,9 @@ type InvalidationInfo = ChangeInfo & {
 type ChildChangeListener = (param: InvalidationInfo) => void;
 type SlotChangeListener = (this: HTMLSlotElement, ev: Event) => void;
 /**
+ * @class
  * Base class for all UI5 Web Components
  *
- * @class
- * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.base.UI5Element
  * @extends HTMLElement
  * @public
  */
@@ -39,7 +36,8 @@ declare abstract class UI5Element extends HTMLElement {
     __id?: string;
     _suppressInvalidation: boolean;
     _changedState: Array<ChangeInfo>;
-    _eventProvider: EventProvider<InvalidationInfo, void>;
+    _invalidationEventProvider: EventProvider<InvalidationInfo, void>;
+    _componentStateFinalizedEventProvider: EventProvider<void, void>;
     _inDOM: boolean;
     _fullyConnected: boolean;
     _childChangeListeners: Map<string, ChildChangeListener>;
@@ -49,7 +47,6 @@ declare abstract class UI5Element extends HTMLElement {
     };
     _doNotSyncAttributes: Set<string>;
     _state: State;
-    _onComponentStateFinalized?: () => void;
     _getRealDomRef?: () => HTMLElement;
     staticAreaItem?: StaticAreaItem;
     static template?: TemplateFunction;
@@ -125,22 +122,22 @@ declare abstract class UI5Element extends HTMLElement {
     /**
      * Attach a callback that will be executed whenever the component is invalidated
      *
-     * @param {InvalidationInfo} callback
+     * @param callback
      * @public
      */
     attachInvalidate(callback: (param: InvalidationInfo) => void): void;
     /**
      * Detach the callback that is executed whenever the component is invalidated
      *
-     * @param {InvalidationInfo} callback
+     * @param callback
      * @public
      */
     detachInvalidate(callback: (param: InvalidationInfo) => void): void;
     /**
      * Callback that is executed whenever a monitored child changes its state
      *
-     * @param {sting} slotName the slot in which a child was invalidated
-     * @param { ChangeInfo } childChangeInfo the changeInfo object for the child in the given slot
+     * @param slotName the slot in which a child was invalidated
+     * @param childChangeInfo the changeInfo object for the child in the given slot
      * @private
      */
     _onChildChange(slotName: string, childChangeInfo: ChangeInfo): void;
@@ -165,15 +162,13 @@ declare abstract class UI5Element extends HTMLElement {
      * Returns a singleton event listener for the "change" event of a child in a given slot
      *
      * @param slotName the name of the slot, where the child is
-     * @returns {ChildChangeListener}
      * @private
      */
-    _getChildChangeListener(slotName: string): ChildChangeListener | undefined;
+    _getChildChangeListener(slotName: string): ChildChangeListener;
     /**
      * Returns a singleton slotchange event listener that invalidates the component due to changes in the given slot
      *
      * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
-     * @returns {SlotChangeListener}
      * @private
      */
     _getSlotChangeListener(slotName: string): SlotChangeListener;
@@ -257,7 +252,7 @@ declare abstract class UI5Element extends HTMLElement {
     getFocusDomRefAsync(): Promise<HTMLElement | undefined>;
     /**
      * Set the focus to the element, returned by "getFocusDomRef()" (marked by "data-sap-focus-ref")
-     * @param {FocusOptions} focusOptions additional options for the focus
+     * @param focusOptions additional options for the focus
      * @public
      */
     focus(focusOptions?: FocusOptions): Promise<void>;
@@ -268,7 +263,7 @@ declare abstract class UI5Element extends HTMLElement {
      * @param data - additional data for the event
      * @param cancelable - true, if the user can call preventDefault on the event object
      * @param bubbles - true, if the event bubbles
-     * @returns {boolean} false, if the event was cancelled (preventDefault called), true otherwise
+     * @returns false, if the event was cancelled (preventDefault called), true otherwise
      */
     fireEvent<T>(name: string, data?: T, cancelable?: boolean, bubbles?: boolean): boolean;
     _fireEvent<T>(name: string, data?: T, cancelable?: boolean, bubbles?: boolean): boolean;
@@ -277,19 +272,33 @@ declare abstract class UI5Element extends HTMLElement {
      * Useful when there are transitive slots in nested component scenarios and you don't want to get a list of the slots, but rather of their content.
      * @public
      */
-    getSlottedNodes<T = Node>(slotName: string): T[];
+    getSlottedNodes<T = Node>(slotName: string): Array<T>;
+    /**
+     * Attach a callback that will be executed whenever the component's state is finalized
+     *
+     * @param callback
+     * @public
+     */
+    attachComponentStateFinalized(callback: () => void): void;
+    /**
+     * Detach the callback that is executed whenever the component's state is finalized
+     *
+     * @param callback
+     * @public
+     */
+    detachComponentStateFinalized(callback: () => void): void;
     /**
      * Determines whether the component should be rendered in RTL mode or not.
      * Returns: "rtl", "ltr" or undefined
      *
      * @public
-     * @returns {String|undefined}
+     * @default undefined
      */
     get effectiveDir(): string | undefined;
     /**
      * Used to duck-type UI5 elements without using instanceof
-     * @returns {boolean}
      * @public
+     * @default true
      */
     get isUI5Element(): boolean;
     get classes(): ClassMap;
@@ -342,37 +351,31 @@ declare abstract class UI5Element extends HTMLElement {
      *
      * @public
      */
-    static getUniqueDependencies(this: typeof UI5Element): (typeof UI5Element)[];
+    static getUniqueDependencies(this: typeof UI5Element): Array<typeof UI5Element>;
     /**
      * Returns a promise that resolves whenever all dependencies for this UI5 Web Component have resolved
-     *
-     * @returns {Promise}
      */
     static whenDependenciesDefined(): Promise<Array<typeof UI5Element>>;
     /**
      * Hook that will be called upon custom element definition
      *
      * @protected
-     * @returns {Promise<void>}
      */
     static onDefine(): Promise<void>;
     /**
      * Registers a UI5 Web Component in the browser window object
      * @public
-     * @returns {Promise<UI5Element>}
      */
     static define(): Promise<typeof UI5Element>;
     /**
      * Returns an instance of UI5ElementMetadata.js representing this UI5 Web Component's full metadata (its and its parents')
      * Note: not to be confused with the "get metadata()" method, which returns an object for this class's metadata only
      * @public
-     * @returns {UI5ElementMetadata}
      */
     static getMetadata(): UI5ElementMetadata;
 }
 /**
  * Always use duck-typing to cover all runtimes on the page.
- * @returns {boolean}
  */
 declare const instanceOfUI5Element: (object: any) => object is UI5Element;
 export default UI5Element;

package/dist/UI5Element.js

@@ -1,3 +1,5 @@
+// eslint-disable-next-line import/no-extraneous-dependencies
+// import "@ui5/webcomponents-base/dist/ssr-dom.js";
 import merge from "./thirdparty/merge.js";
 import { boot } from "./Boot.js";
 import UI5ElementMetadata from "./UI5ElementMetadata.js";
@@ -5,6 +7,7 @@ import EventProvider from "./EventProvider.js";
 import getSingletonElementInstance from "./util/getSingletonElementInstance.js";
 import StaticAreaItem from "./StaticAreaItem.js";
 import updateShadowRoot from "./updateShadowRoot.js";
+import { shouldIgnoreCustomElement } from "./IgnoreCustomElements.js";
 import { renderDeferred, renderImmediately, cancelRender } from "./Render.js";
 import { registerTag, isTagRegistered, recordTagRegistrationFailure } from "./CustomElementsRegistry.js";
 import { observeDOMNode, unobserveDOMNode } from "./DOMObserver.js";
@@ -35,15 +38,12 @@ function _invalidate(changeInfo) {
     this.onInvalidation(changeInfo);
     this._changedState.push(changeInfo);
     renderDeferred(this);
-    this._eventProvider.fireEvent("invalidate", { ...changeInfo, target: this });
+    this._invalidationEventProvider.fireEvent("invalidate", { ...changeInfo, target: this });
 }
 /**
+ * @class
  * Base class for all UI5 Web Components
  *
- * @class
- * @constructor
- * @author SAP SE
- * @alias sap.ui.webc.base.UI5Element
  * @extends HTMLElement
  * @public
  */
@@ -57,7 +57,8 @@ class UI5Element extends HTMLElement {
         this._fullyConnected = false; // A flag telling whether the UI5Element's onEnterDOM hook was called (since it's possible to have the element removed from DOM before that)
         this._childChangeListeners = new Map(); // used to store lazy listeners per slot for the child change event of every child inside that slot
         this._slotChangeListeners = new Map(); // used to store lazy listeners per slot for the slotchange event of all slot children inside that slot
-        this._eventProvider = new EventProvider(); // used by parent components for listening to changes to child components
+        this._invalidationEventProvider = new EventProvider(); // used by parent components for listening to changes to child components
+        this._componentStateFinalizedEventProvider = new EventProvider(); // used by friend classes for synchronization
         let deferredResolve;
         this._domRefReadyPromise = new Promise(resolve => {
             deferredResolve = resolve;
@@ -160,14 +161,16 @@ class UI5Element extends HTMLElement {
      */
     _startObservingDOMChildren() {
         const ctor = this.constructor;
-        const shouldObserveChildren = ctor.getMetadata().hasSlots();
+        const metadata = ctor.getMetadata();
+        const shouldObserveChildren = metadata.hasSlots();
         if (!shouldObserveChildren) {
             return;
         }
-        const canSlotText = ctor.getMetadata().canSlotText();
+        const canSlotText = metadata.canSlotText();
+        const hasClonedSlot = Object.keys(metadata.getSlots()).some(slotName => metadata.getSlots()[slotName].cloned);
         const mutationObserverOptions = {
             childList: true,
-            subtree: canSlotText,
+            subtree: canSlotText || hasClonedSlot,
             characterData: canSlotText,
         };
         observeDOMNode(this, this._processChildren.bind(this), mutationObserverOptions);
@@ -228,11 +231,11 @@ class UI5Element extends HTMLElement {
             // Await for not-yet-defined custom elements
             if (child instanceof HTMLElement) {
                 const localName = child.localName;
-                const isCustomElement = localName.includes("-");
-                if (isCustomElement) {
-                    const isDefined = window.customElements.get(localName);
+                const shouldWaitForCustomElement = localName.includes("-") && !shouldIgnoreCustomElement(localName);
+                if (shouldWaitForCustomElement) {
+                    const isDefined = customElements.get(localName);
                     if (!isDefined) {
-                        const whenDefinedPromise = window.customElements.whenDefined(localName); // Class registered, but instances not upgraded yet
+                        const whenDefinedPromise = customElements.whenDefined(localName); // Class registered, but instances not upgraded yet
                         let timeoutPromise = elementTimeouts.get(localName);
                         if (!timeoutPromise) {
                             timeoutPromise = new Promise(resolve => setTimeout(resolve, 1000));
@@ -240,7 +243,7 @@ class UI5Element extends HTMLElement {
                         }
                         await Promise.race([whenDefinedPromise, timeoutPromise]);
                     }
-                    window.customElements.upgrade(child);
+                    customElements.upgrade(child);
                 }
             }
             child = ctor.getMetadata().constructor.validateSlotValue(child, slotData);
@@ -315,26 +318,26 @@ class UI5Element extends HTMLElement {
     /**
      * Attach a callback that will be executed whenever the component is invalidated
      *
-     * @param {InvalidationInfo} callback
+     * @param callback
      * @public
      */
     attachInvalidate(callback) {
-        this._eventProvider.attachEvent("invalidate", callback);
+        this._invalidationEventProvider.attachEvent("invalidate", callback);
     }
     /**
      * Detach the callback that is executed whenever the component is invalidated
      *
-     * @param {InvalidationInfo} callback
+     * @param callback
      * @public
      */
     detachInvalidate(callback) {
-        this._eventProvider.detachEvent("invalidate", callback);
+        this._invalidationEventProvider.detachEvent("invalidate", callback);
     }
     /**
      * Callback that is executed whenever a monitored child changes its state
      *
-     * @param {sting} slotName the slot in which a child was invalidated
-     * @param { ChangeInfo } childChangeInfo the changeInfo object for the child in the given slot
+     * @param slotName the slot in which a child was invalidated
+     * @param childChangeInfo the changeInfo object for the child in the given slot
      * @private
      */
     _onChildChange(slotName, childChangeInfo) {
@@ -444,7 +447,6 @@ class UI5Element extends HTMLElement {
      * Returns a singleton event listener for the "change" event of a child in a given slot
      *
      * @param slotName the name of the slot, where the child is
-     * @returns {ChildChangeListener}
      * @private
      */
     _getChildChangeListener(slotName) {
@@ -457,7 +459,6 @@ class UI5Element extends HTMLElement {
      * Returns a singleton slotchange event listener that invalidates the component due to changes in the given slot
      *
      * @param slotName the name of the slot, where the slot element (whose slotchange event we're listening to) is
-     * @returns {SlotChangeListener}
      * @private
      */
     _getSlotChangeListener(slotName) {
@@ -533,9 +534,7 @@ class UI5Element extends HTMLElement {
         this._suppressInvalidation = true;
         this.onBeforeRendering();
         // Intended for framework usage only. Currently ItemNavigation updates tab indexes after the component has updated its state but before the template is rendered
-        if (this._onComponentStateFinalized) {
-            this._onComponentStateFinalized();
-        }
+        this._componentStateFinalizedEventProvider.fireEvent("componentStateFinalized");
         // resume normal invalidation handling
         this._suppressInvalidation = false;
         // Update the shadow root with the render result
@@ -635,7 +634,7 @@ class UI5Element extends HTMLElement {
     }
     /**
      * Set the focus to the element, returned by "getFocusDomRef()" (marked by "data-sap-focus-ref")
-     * @param {FocusOptions} focusOptions additional options for the focus
+     * @param focusOptions additional options for the focus
      * @public
      */
     async focus(focusOptions) {
@@ -652,13 +651,13 @@ class UI5Element extends HTMLElement {
      * @param data - additional data for the event
      * @param cancelable - true, if the user can call preventDefault on the event object
      * @param bubbles - true, if the event bubbles
-     * @returns {boolean} false, if the event was cancelled (preventDefault called), true otherwise
+     * @returns false, if the event was cancelled (preventDefault called), true otherwise
      */
     fireEvent(name, data, cancelable = false, bubbles = true) {
         const eventResult = this._fireEvent(name, data, cancelable, bubbles);
         const camelCaseEventName = kebabToCamelCase(name);
         if (camelCaseEventName !== name) {
-            return eventResult && this._fireEvent(camelCaseEventName, data, cancelable);
+            return eventResult && this._fireEvent(camelCaseEventName, data, cancelable, bubbles);
         }
         return eventResult;
     }
@@ -693,12 +692,30 @@ class UI5Element extends HTMLElement {
     getSlottedNodes(slotName) {
         return getSlottedNodesList(this[slotName]);
     }
+    /**
+     * Attach a callback that will be executed whenever the component's state is finalized
+     *
+     * @param callback
+     * @public
+     */
+    attachComponentStateFinalized(callback) {
+        this._componentStateFinalizedEventProvider.attachEvent("componentStateFinalized", callback);
+    }
+    /**
+     * Detach the callback that is executed whenever the component's state is finalized
+     *
+     * @param callback
+     * @public
+     */
+    detachComponentStateFinalized(callback) {
+        this._componentStateFinalizedEventProvider.detachEvent("componentStateFinalized", callback);
+    }
     /**
      * Determines whether the component should be rendered in RTL mode or not.
      * Returns: "rtl", "ltr" or undefined
      *
      * @public
-     * @returns {String|undefined}
+     * @default undefined
      */
     get effectiveDir() {
         markAsRtlAware(this.constructor); // if a UI5 Element calls this method, it's considered to be rtl-aware
@@ -706,8 +723,8 @@ class UI5Element extends HTMLElement {
     }
     /**
      * Used to duck-type UI5 elements without using instanceof
-     * @returns {boolean}
      * @public
+     * @default true
      */
     get isUI5Element() {
         return true;
@@ -886,8 +903,6 @@ class UI5Element extends HTMLElement {
     }
     /**
      * Returns a promise that resolves whenever all dependencies for this UI5 Web Component have resolved
-     *
-     * @returns {Promise}
      */
     static whenDependenciesDefined() {
         return Promise.all(this.getUniqueDependencies().map(dep => dep.define()));
@@ -896,7 +911,6 @@ class UI5Element extends HTMLElement {
      * Hook that will be called upon custom element definition
      *
      * @protected
-     * @returns {Promise<void>}
      */
     static async onDefine() {
         return Promise.resolve();
@@ -904,7 +918,6 @@ class UI5Element extends HTMLElement {
     /**
      * Registers a UI5 Web Component in the browser window object
      * @public
-     * @returns {Promise<UI5Element>}
      */
     static async define() {
         await boot();
@@ -921,7 +934,7 @@ class UI5Element extends HTMLElement {
         else if (!definedGlobally) {
             this._generateAccessors();
             registerTag(tag);
-            window.customElements.define(tag, this);
+            customElements.define(tag, this);
             preloadLinks(this);
         }
         return this;
@@ -930,7 +943,6 @@ class UI5Element extends HTMLElement {
      * Returns an instance of UI5ElementMetadata.js representing this UI5 Web Component's full metadata (its and its parents')
      * Note: not to be confused with the "get metadata()" method, which returns an object for this class's metadata only
      * @public
-     * @returns {UI5ElementMetadata}
      */
     static getMetadata() {
         if (this.hasOwnProperty("_metadata")) { // eslint-disable-line
@@ -954,7 +966,6 @@ class UI5Element extends HTMLElement {
 UI5Element.metadata = {};
 /**
  * Always use duck-typing to cover all runtimes on the page.
- * @returns {boolean}
  */
 const instanceOfUI5Element = (object) => {
     return "isUI5Element" in object;