Merge branch 'main' into chore-shellbar-evolution

CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.5.0](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.3...v2.5.0) (2024-12-05)
+
+**Note:** Version bump only for package ui5-webcomponents
+
+
+
+
+
+# [2.5.0-rc.3](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.2...v2.5.0-rc.3) (2024-12-05)
+
+
+### Bug Fixes
+
+* **ui5-li:** address additional text contrast issue ([#10269](https://github.com/SAP/ui5-webcomponents/issues/10269)) ([6cf15d9](https://github.com/SAP/ui5-webcomponents/commit/6cf15d922276898614b758532923af98557a929d)), closes [#9869](https://github.com/SAP/ui5-webcomponents/issues/9869)
+* **ui5-list:** enable focusin event bubbling ([#10156](https://github.com/SAP/ui5-webcomponents/issues/10156)) ([3b6cc84](https://github.com/SAP/ui5-webcomponents/commit/3b6cc8457ab47c1651a34f04b9401ee3112bd8c5)), closes [#9787](https://github.com/SAP/ui5-webcomponents/issues/9787)
+* **ui5-menu:** provide a way to focus items on fetch ([#10210](https://github.com/SAP/ui5-webcomponents/issues/10210)) ([073f0f6](https://github.com/SAP/ui5-webcomponents/commit/073f0f6fa11e34d5a831a401c711449ef44a2995)), closes [#7237](https://github.com/SAP/ui5-webcomponents/issues/7237)
+* **ui5-popover:** search for the opener in the correct root ([#10284](https://github.com/SAP/ui5-webcomponents/issues/10284)) ([ee08efa](https://github.com/SAP/ui5-webcomponents/commit/ee08efa855dd502fba09fcfa7bf8d6853f44a612))
+* **ui5-rating-indicator:** correct half icon appearance ([#10263](https://github.com/SAP/ui5-webcomponents/issues/10263)) ([3032393](https://github.com/SAP/ui5-webcomponents/commit/30323935ba1ef56665b0b3c82d1f7e5f6a5d26bd)), closes [#10155](https://github.com/SAP/ui5-webcomponents/issues/10155)
+* **ui5-rating-indicator:** outline border is visible when focus ([#10205](https://github.com/SAP/ui5-webcomponents/issues/10205)) ([eaa6f04](https://github.com/SAP/ui5-webcomponents/commit/eaa6f0411f877c9448bc5da4d15589f67614e7a1))
+* **ui5-tag:** correct hover background color for Set 2 Color Scheme 9 ([#10229](https://github.com/SAP/ui5-webcomponents/issues/10229)) ([1b2eaed](https://github.com/SAP/ui5-webcomponents/commit/1b2eaedf6a9effdf728d3e41b9cf56e0c2aa1c96)), closes [#10164](https://github.com/SAP/ui5-webcomponents/issues/10164)
+* **ui5-view-settings-dialog:** adjust dialog heading level ([#10289](https://github.com/SAP/ui5-webcomponents/issues/10289)) ([08d48a3](https://github.com/SAP/ui5-webcomponents/commit/08d48a3eb5e16708242b4a721ead74aebb8bb8ae))
+
+
+### Features
+
+* **framework:** add strict event type checking ([#10235](https://github.com/SAP/ui5-webcomponents/issues/10235)) ([4ff8ab7](https://github.com/SAP/ui5-webcomponents/commit/4ff8ab7c34db5058b92511767be1b96c69a91cb5))
+* **table:** table virtualization ([#10182](https://github.com/SAP/ui5-webcomponents/issues/10182)) ([bf4c859](https://github.com/SAP/ui5-webcomponents/commit/bf4c8596611bf61435809b1bf42766db83aea002))
+* **ui5-bar:** add shadow parts ([#10271](https://github.com/SAP/ui5-webcomponents/issues/10271)) ([9114a82](https://github.com/SAP/ui5-webcomponents/commit/9114a82ecc14ae3dbf118bd8ad835a6a16949298)), closes [#10101](https://github.com/SAP/ui5-webcomponents/issues/10101)
+* **ui5-button, ui5-link:** support accessibile description ([#10212](https://github.com/SAP/ui5-webcomponents/issues/10212)) ([51139c2](https://github.com/SAP/ui5-webcomponents/commit/51139c2df3daf2a892b924b51d260f561b867e5b)), closes [#5310](https://github.com/SAP/ui5-webcomponents/issues/5310) [#3993](https://github.com/SAP/ui5-webcomponents/issues/3993)
+* **ui5-list:** handle arrow up and down navigation for load more button ([#10251](https://github.com/SAP/ui5-webcomponents/issues/10251)) ([3150793](https://github.com/SAP/ui5-webcomponents/commit/31507939da6051750bcae0a900f6bc1cfce2f926))
+* **ui5-user-menu:** introduce new component ([#10244](https://github.com/SAP/ui5-webcomponents/issues/10244)) ([1558499](https://github.com/SAP/ui5-webcomponents/commit/15584993472c2a9d34349da999da74bfe450e76e))
+
+
+
+
+
 # [2.5.0-rc.2](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.1...v2.5.0-rc.2) (2024-11-28)
 
 

docs/4-development/05-events.md

@@ -6,31 +6,32 @@ Components use `CustomEvent` to inform developers of important state changes in
 
 ## The `@event` Decorator
 
-To define your own custom event, you need to use the `@event` decorator.
+There are two `@event` decorators available with the following imports:
+```ts
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js"; // recommended for new develompent
+// or
+import event from "@ui5/webcomponents-base/dist/decorators/event.js"; // deprecated
+```
 
-The `event` decorator is a class decorator that takes one required argument as a string to define the event name and an optional argument as an object literal to describe details of the custom element.
+To define your own custom event, you need to use the `@event` decorator.
 
-The details object allows developers to describe more information about the event.
+The `event` decorator is a class decorator that takes one required argument as a string to define the event name
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
-import event from "@ui5/webcomponents-base/dist/decorators/event.js";
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js";
 
 @customElement("my-demo-component")
-@event("change", {
-	detail: {
-		valid: { type: Boolean },
-	},
-})
+@event("change")
 class MyDemoComponent extends UI5Element {}
 ```
 
-**Note:** This decorator is used only to describe the events of the component and is not meant to create emitters.
+**Note:** This decorator is used only to describe the events of the component and is not meant to create emitters. See `fireDecoratorEvent` below.
 
 ## Usage
 
-As mentioned earlier, the `@event` decorator doesn't create event emitters. To notify developers of component changes, we have to fire events ourselves. This can be done using the `fireEvent` and the newer `fireDecoratorEvent` methods that comes from the `UI5Element` class. The difference between the methods is explained below.
+As mentioned earlier, the `@event` decorator doesn't create event emitters. To notify developers of component changes, we have to fire events ourselves. This can be done using the `fireEventDecoratorEvent` and the deprecated `fireEvent` methods that come from the `UI5Element` class. The difference between the methods is explained below.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
@@ -53,7 +54,43 @@ class MyDemoComponent extends UI5Element {
 
 **Note:** By default, the `fireDecoratorEvent` (and `fireEvent`) method returns a boolean value that helps you understand whether the event was canceled (i.e., if the `preventDefault` method was called).
 
-## Event Detail
+## `eventDetails` (recommended)
+The `eventDetails` class field is used to describe the types of events that the component emits. The strict event decorator is using this information for type checking the names.
+
+```ts
+class MyComponent extends UI5Element {
+  eventDetails!: {
+    "selection-change": SelectionChangeDetails
+    "delete": void
+  }
+}
+```
+
+This field doesn't have runtime semantics, it is only used to provide type information about the events that the component is firing and the corresponding types of the detail parameter.
+
+### Extending the `eventDetails` with more events
+If your component extends another component and you try to add new events, you will get a TypeScript error that the new events cannot be assigned to the same field in the base class
+
+```ts
+class TimeSelectionClocks extends TimePickerInternals {
+  eventDetails!: { // ts-error
+    "close-picker": void,
+  };
+
+// Property 'eventDetails' in type 'TimeSelectionClocks' is not assignable to the same property in base type 'TimePickerInternals'.
+```
+
+In order to correctly extend the base class events, you need to add them as a type as well like this TimePickerInternals["eventDetails"]
+
+```ts
+class TimeSelectionClocks extends TimePickerInternals {
+  eventDetails!: TimePickerInternals["eventDetails"] & {
+    "close-picker": void,
+  };
+}
+```
+
+## Event Detail (deprecated)
 
 The `@event` decorator is generic and accepts a TypeScript type that describes its detail. This type is crucial for preventing incorrect detail data when the event is fired using `fireDecoratorEvent` and `fireEvent` methods (both generic) and for ensuring type safety when listening for the event, so you know what kind of detail data to expect.
 
@@ -83,7 +120,7 @@ class MyDemoComponent extends UI5Element {
     value = "";
 
     onNativeInputChange(e: Event) {
-        this.fireDecoratorEvent<MyDemoComponentChangeEventDetail>("change", {
+        this.fireEvent("change", {
             valid: true,
         });
     }
@@ -92,7 +129,7 @@ class MyDemoComponent extends UI5Element {
 export { MyDemoComponent };
 ```
 
-## Event Configuration
+## Event Configuration (both event decorators)
 
 ### Bubbling and Preventing
 
@@ -125,7 +162,7 @@ class MyDemoComponent extends UI5Element {
 
 ### The `fireDecoratorEvent` method
 
-The method is available since version `v2.4.0` and it fires a custom event and gets the configuration for the event from the `@event` decorator. In case you rely on the decorator settings, you must use the `fireDecoratorEvent` method.
+The method is available since version `v2.4.0` and it fires a custom event and gets the configuration for the event from the `@event` decorator. It also strictly checks the details parameter agains the `eventDetails` type for the same event name.
 
 Keep in mind that `cancelable` and `bubbles` are `false` by default and you must explicitly enable them in the `@event` decorator if required.
 
@@ -154,7 +191,7 @@ this.fireDecoratorEvent("change");
 this.fireDecoratorEvent("change");
 ```
 
-**Note:** since `v2.4.0` it's recommended to describe the event in the `@event` decorator and use the `fireDecoratorEvent` method. 
+**Note:** since `v2.4.0` it's recommended to describe the event in the `@event` decorator and use the `fireDecoratorEvent` method.
 
 ### The `fireEvent` method
 

lerna.json

@@ -14,7 +14,7 @@
     "packages/create-package",
     "packages/compat"
   ],
-  "version": "2.5.0-rc.2",
+  "version": "2.5.0",
   "command": {
     "publish": {
       "allowBranch": "*",

packages/ai/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.5.0](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.3...v2.5.0) (2024-12-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-ai
+
+
+
+
+
+# [2.5.0-rc.3](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.2...v2.5.0-rc.3) (2024-12-05)
+
+
+### Features
+
+* **framework:** add strict event type checking ([#10235](https://github.com/SAP/ui5-webcomponents/issues/10235)) ([4ff8ab7](https://github.com/SAP/ui5-webcomponents/commit/4ff8ab7c34db5058b92511767be1b96c69a91cb5))
+
+
+
+
+
 # [2.5.0-rc.2](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.1...v2.5.0-rc.2) (2024-11-28)
 
 **Note:** Version bump only for package @ui5/webcomponents-ai

packages/ai/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui5/webcomponents-ai",
-  "version": "2.5.0-rc.2",
+  "version": "2.5.0",
   "description": "UI5 Web Components: webcomponents.ai",
   "ui5": {
     "webComponentsPackage": true
@@ -45,13 +45,13 @@
     "directory": "packages/ai"
   },
   "dependencies": {
-    "@ui5/webcomponents": "2.5.0-rc.2",
-    "@ui5/webcomponents-base": "2.5.0-rc.2",
-    "@ui5/webcomponents-icons": "2.5.0-rc.2",
-    "@ui5/webcomponents-theming": "2.5.0-rc.2"
+    "@ui5/webcomponents": "2.5.0",
+    "@ui5/webcomponents-base": "2.5.0",
+    "@ui5/webcomponents-icons": "2.5.0",
+    "@ui5/webcomponents-theming": "2.5.0"
   },
   "devDependencies": {
-    "@ui5/webcomponents-tools": "2.5.0-rc.2",
+    "@ui5/webcomponents-tools": "2.5.0",
     "chromedriver": "^131.0.0"
   }
 }

packages/ai/src/Button.ts

@@ -2,7 +2,7 @@ import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import { renderFinished } from "@ui5/webcomponents-base/dist/Render.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
-import event from "@ui5/webcomponents-base/dist/decorators/event.js";
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
 import MainButton from "@ui5/webcomponents/dist/Button.js";
@@ -63,6 +63,9 @@ import ButtonCss from "./generated/themes/Button.css.js";
 	bubbles: true,
 })
 class Button extends UI5Element {
+	eventDetails!: {
+		click: void,
+	}
 	/**
 	 * Defines the component design.
 	 * @default "Default"

packages/ai/src/PromptInput.ts

@@ -1,7 +1,7 @@
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
 import customElement from "@ui5/webcomponents-base/dist/decorators/customElement.js";
 import property from "@ui5/webcomponents-base/dist/decorators/property.js";
-import event from "@ui5/webcomponents-base/dist/decorators/event.js";
+import event from "@ui5/webcomponents-base/dist/decorators/event-strict.js";
 import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 import i18n from "@ui5/webcomponents-base/dist/decorators/i18n.js";
 import litRender from "@ui5/webcomponents-base/dist/renderer/LitRenderer.js";
@@ -87,6 +87,11 @@ import PromptInputCss from "./generated/themes/PromptInput.css.js";
 	bubbles: true,
 })
 class PromptInput extends UI5Element {
+	eventDetails!: {
+		submit: void;
+		input: void;
+		change: void;
+	}
 	/**
 	 * Defines the value of the component.
 	 *

packages/base/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [2.5.0](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.3...v2.5.0) (2024-12-05)
+
+**Note:** Version bump only for package @ui5/webcomponents-base
+
+
+
+
+
+# [2.5.0-rc.3](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.2...v2.5.0-rc.3) (2024-12-05)
+
+
+### Features
+
+* **framework:** add strict event type checking ([#10235](https://github.com/SAP/ui5-webcomponents/issues/10235)) ([4ff8ab7](https://github.com/SAP/ui5-webcomponents/commit/4ff8ab7c34db5058b92511767be1b96c69a91cb5))
+
+
+
+
+
 # [2.5.0-rc.2](https://github.com/SAP/ui5-webcomponents/compare/v2.5.0-rc.1...v2.5.0-rc.2) (2024-11-28)
 
 **Note:** Version bump only for package @ui5/webcomponents-base

packages/base/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ui5/webcomponents-base",
-  "version": "2.5.0-rc.2",
+  "version": "2.5.0",
   "description": "UI5 Web Components: webcomponents.base",
   "author": "SAP SE (https://www.sap.com)",
   "license": "Apache-2.0",
@@ -52,7 +52,7 @@
   },
   "devDependencies": {
     "@openui5/sap.ui.core": "1.120.17",
-    "@ui5/webcomponents-tools": "2.5.0-rc.2",
+    "@ui5/webcomponents-tools": "2.5.0",
     "chromedriver": "^131.0.0",
     "clean-css": "^5.2.2",
     "copy-and-watch": "^0.1.5",

packages/base/src/UI5Element.ts

@@ -139,6 +139,10 @@ function getPropertyDescriptor(proto: any, name: PropertyKey): PropertyDescripto
 		proto = Object.getPrototypeOf(proto);
 	} while (proto && proto !== HTMLElement.prototype);
 }
+export type NotEqual<X, Y> = true extends Equal<X, Y> ? false : true
+export type Equal<X, Y> =
+  (<T>() => T extends X ? 1 : 2) extends
+  (<T>() => T extends Y ? 1 : 2) ? true : false
 
 /**
  * @class
@@ -148,6 +152,9 @@ function getPropertyDescriptor(proto: any, name: PropertyKey): PropertyDescripto
  * @public
  */
 abstract class UI5Element extends HTMLElement {
+	eventDetails!: NotEqual<typeof this, typeof UI5Element> extends true ? object : {
+		[k: string]: any
+	};
 	__id?: string;
 	_suppressInvalidation: boolean;
 	_changedState: Array<ChangeInfo>;
@@ -970,13 +977,13 @@ abstract class UI5Element extends HTMLElement {
 	 * @param data - additional data for the event
 	 * @returns false, if the event was cancelled (preventDefault called), true otherwise
 	 */
-	fireDecoratorEvent<T>(name: string, data?: T): boolean {
-		const eventData = this.getEventData(name);
+	fireDecoratorEvent<N extends keyof this["eventDetails"]>(name: N, data?: this["eventDetails"][N] | undefined): boolean {
+		const eventData = this.getEventData(name as string);
 		const cancellable = eventData ? eventData.cancelable : false;
 		const bubbles = eventData ? eventData.bubbles : false;
 
-		const eventResult = this._fireEvent(name, data, cancellable, bubbles);
-		const pascalCaseEventName = kebabToPascalCase(name);
+		const eventResult = this._fireEvent(name as string, data, cancellable, bubbles);
+		const pascalCaseEventName = kebabToPascalCase(name as string);
 
 		// pascal events are more convinient for native react usage
 		// live-change:

packages/base/src/UI5ElementMetadata.ts

@@ -29,7 +29,7 @@ type Property = {
 
 type PropertyValue = boolean | number | string | object | undefined | null;
 
-type EventData = Record<string, { detail: Record<string, object>, cancelable: boolean, bubbles: boolean }>;
+type EventData = Record<string, { detail?: Record<string, object>, cancelable?: boolean, bubbles?: boolean }>;
 
 type I18nBundleAccessorValue = {
 	bundleName: string,

packages/base/src/decorators.ts

@@ -1,11 +1,13 @@
 import customElement from "./decorators/customElement.js";
 import event from "./decorators/event.js";
+import eventStrict from "./decorators/event-strict.js";
 import property from "./decorators/property.js";
 import slot from "./decorators/slot.js";
 
 export {
 	customElement,
 	event,
+	eventStrict,
 	property,
 	slot,
 };