From bba71d95adf6cf759279093c1426efa1b0ae2b18 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Wed, 9 Oct 2024 10:14:41 +0200 Subject: [PATCH 1/2] fix(Ui5DomRef - TypeScript): update types --- packages/main/src/types/Ui5DomRef.ts | 104 +++++++++++++++++++++------ 1 file changed, 81 insertions(+), 23 deletions(-) diff --git a/packages/main/src/types/Ui5DomRef.ts b/packages/main/src/types/Ui5DomRef.ts index e19d60794e1..2ddaab57839 100644 --- a/packages/main/src/types/Ui5DomRef.ts +++ b/packages/main/src/types/Ui5DomRef.ts @@ -1,16 +1,52 @@ +import type { PropertyValue, SlotValue } from '@ui5/webcomponents-base/UI5ElementMetadata.js'; + +type ChangeInfo = { + type: 'property' | 'slot'; + name: string; + reason?: string; + child?: SlotValue; + target?: Ui5DomRef; + newValue?: PropertyValue; + oldValue?: PropertyValue; +}; + +type InvalidationInfo = ChangeInfo & { target: Ui5DomRef }; + export interface Ui5DomRef extends Omit { + /** + * Called every time before the component renders. + * @public + */ + onBeforeRendering(): void; + /** + * Called every time after the component renders. + * @public + */ + onAfterRendering(): void; + /** + * Called on connectedCallback - added to the DOM. + * @public + */ + onEnterDOM(): void; + /** + * Called on disconnectedCallback - removed from the DOM. + * @public + */ + onExitDOM(): void; /** * Attach a callback that will be executed whenever the component is invalidated * * @param callback + * @public */ - attachInvalidate: (callback) => void; + attachInvalidate(callback: (param: InvalidationInfo) => void): void; /** * Detach the callback that is executed whenever the component is invalidated * * @param callback + * @public */ - detachInvalidate: (callback) => void; + detachInvalidate(callback: (param: InvalidationInfo) => void): void; /** * A callback that is executed each time an already rendered component is invalidated (scheduled for re-rendering) * @@ -26,9 +62,9 @@ export interface Ui5DomRef extends Omit { * 1) children: immediate children (HTML elements or text nodes) were added, removed or reordered in the slot * 2) textcontent: text nodes in the slot changed value (or nested text nodes were added or changed value). Can only trigger for slots of "type: Node" * 3) slotchange: a slot element, slotted inside that slot had its "slotchange" event listener called. This practically means that transitively slotted children changed. - * Can only trigger if the child of a slot is a slot element itself. + * Can only trigger if the child of a slot is a slot element itself. * 4) childchange: indicates that a UI5Element child in that slot was invalidated and in turn invalidated the component. - * Can only trigger for slots with "invalidateOnChildChange" metadata descriptor + * Can only trigger for slots with "invalidateOnChildChange" metadata descriptor * * - newValue: the new value of the property (for type="property" only) * @@ -36,58 +72,80 @@ export interface Ui5DomRef extends Omit { * * - child the child that was changed (for type="slot" and reason="childchange" only) * + * @public */ - onInvalidation: (changeInfo) => void; + onInvalidation(changeInfo: ChangeInfo): void; /** * Returns the DOM Element inside the Shadow Root that corresponds to the opening tag in the UI5 Web Component's template - * - * __Note:__ For logical (abstract) elements (items, options, etc...), returns the part of the parent's DOM that represents this option - * + * *Note:* For logical (abstract) elements (items, options, etc...), returns the part of the parent's DOM that represents this option * Use this method instead of "this.shadowRoot" to read the Shadow DOM, if ever necessary + * + * @public */ - getDomRef: () => HTMLElement; + getDomRef(): HTMLElement | undefined; + /** - * Returns the DOM Element marked with `data-sap-focus-ref` inside the template. + * Returns the DOM Element marked with "data-sap-focus-ref" inside the template. * This is the element that will receive the focus by default. + * @public */ - getFocusDomRef: () => HTMLElement; + getFocusDomRef(): HTMLElement | undefined; + /** - * Returns the DOM Element marked with `data-sap-focus-ref` inside the template. + * Waits for dom ref and then returns the DOM Element marked with "data-sap-focus-ref" inside the template. * This is the element that will receive the focus by default. + * @public */ - getFocusDomRefAsync: () => Promise; + getFocusDomRefAsync(): Promise; /** * 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; + focus(focusOptions?: FocusOptions): Promise; /** * + * @public * @param name - name of the event * @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: string, data?: T, cancelable?: boolean, bubbles?: boolean) => boolean; + fireEvent(name: string, data?: T, cancelable?: boolean, bubbles?: boolean): boolean; /** * Returns the actual children, associated with a slot. * 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: (slotName: string) => Array; + getSlottedNodes(slotName: string): Array; + /** + * 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 * - * @returns {string|undefined} + * @public + * @default undefined */ readonly effectiveDir: string | undefined; + /** * Used to duck-type UI5 elements without using instanceof + * @public + * @default true */ readonly isUI5Element: boolean; - /** - * Returns the `staticAreaItem` DOM Element. - */ - getStaticAreaItemDomRef: () => Promise; } From 43b7f65b842abb24905ba525a6cf2c33aa3f4bd3 Mon Sep 17 00:00:00 2001 From: Lukas Harbarth Date: Thu, 10 Oct 2024 11:53:20 +0200 Subject: [PATCH 2/2] Update Ui5DomRef.ts --- packages/main/src/types/Ui5DomRef.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/main/src/types/Ui5DomRef.ts b/packages/main/src/types/Ui5DomRef.ts index 2ddaab57839..c7a8bea0d1d 100644 --- a/packages/main/src/types/Ui5DomRef.ts +++ b/packages/main/src/types/Ui5DomRef.ts @@ -1,4 +1,4 @@ -import type { PropertyValue, SlotValue } from '@ui5/webcomponents-base/UI5ElementMetadata.js'; +import type { PropertyValue, SlotValue } from '@ui5/webcomponents-base/dist/UI5ElementMetadata.js'; type ChangeInfo = { type: 'property' | 'slot';