Merge branch 'main' into chore-shellbar-evolution

.github/workflows/release-experimental.yaml

@@ -23,4 +23,4 @@ jobs:
       env:
         NPM_AUTH_TOKEN: ${{ secrets.NPM_RELEASE_AUTH_TOKEN }}
       run: |
-        node ./.github/actions/release.js
+        node ./.github/actions/release.cjs

.gitignore

@@ -11,6 +11,7 @@ dist
 packages/compat/test/pages/scoped
 packages/main/test/pages/scoped
 packages/fiori/test/pages/scoped
+packages/ai/test/pages/scoped
 
 # Ignore npm files/folders
 node_modules

CONTRIBUTING.md

@@ -28,3 +28,8 @@ Due to legal reasons, contributors will be asked to accept a DCO before they sub
     - Note that the UI5 Web Components developers have many duties. So, depending on the required effort for reviewing, testing, and clarification, this may take a while.
 1. Once the change has been approved and merged, we will inform you in a comment.
 1. Celebrate!
+
+### Contributing with AI-generated code
+As artificial intelligence evolves, AI-generated code is becoming valuable for many software projects, including open-source initiatives. While we recognize the potential benefits of incorporating AI-generated content into our open-source projects there are certain requirements that need to be reflected and adhered to when making contributions.
+
+Please see our [guideline for AI-generated code contributions to SAP Open Source Software Projects](https://github.com/SAP/.github/blob/main/CONTRIBUTING_USING_GENAI.md) for these requirements.

docs/2-advanced/06-scoping.md

@@ -11,10 +11,13 @@ The `scoping` feature lets you add an arbitrary suffix to the names of all UI5 W
 Example:
 
 ```js
+// scoping-config.js
 import { setCustomElementsScopingSuffix } from "@ui5/webcomponents-base/dist/CustomElementsScope.js";
 setCustomElementsScopingSuffix("demo");
 ```
 
+** NOTE: ** Setting the scoping suffix should be done before importing any components, as they use the suffix at the top-level of the module - meaning when a component is imported, the suffix has to be known. For this to work, calling the method should be done in a separate module (`scoping-config.js` in the example above) and this module should be imported before any components are imported.
+
 Then all names can only be used with the supplied suffix:
 
 ```html
@@ -34,7 +37,7 @@ will not have any effect.
 
 ## When do I need to use the `scoping` feature?
 
-The `scoping` feature is completely optional. It is not needed for application development, but it is strongly recommended when building **libraries** and **micro-frontends**. 
+The `scoping` feature is completely optional. It is not needed for application development, but it is strongly recommended when building **libraries** and **micro-frontends**.
 It ensures that the custom elements that your code uses have not already been reserved by another library or an older version of UI5 Web Components.
 
 If, for example, your code may be loaded on demand by unknown applications as a third-party service, there is always the risk that the app

docs/2-advanced/11-styles.md

@@ -17,7 +17,7 @@ We designed some components such as Title, Label, Tag, Button, Input, and a few
     background: purple;
   }
 ```
-You can try this yourself on the Input [test page](https://sap.github.io/ui5-webcomponents/main/playground/main/pages/Input/). 
+You can try this yourself using the Input [sample](https://sap.github.io/ui5-webcomponents/components/Input/#custom-styling/). 
 
 Unfortunately, this can't be done for all components because it depends on the complexity of the DOM structure.
 

docs/3-frameworks/03-Vue.md

@@ -3,7 +3,6 @@
 In this tutorial you will learn how to add UI5 Web Components to your application. You can add UI5 Web Components both to new Vue.js applications and to already existing ones.
 
 ## Setting up a Vite and Vue.js project with UI5 Web Components
-<br/>
 
 ### Step 1. Setup a Vue project with Vite.
 
@@ -55,15 +54,20 @@ import "@ui5/webcomponents/dist/Button.js";
 ```bash
 npm run dev
 ```
-## Additional Info
 
-### Two-Way Data Binding
 
-`v-model` binding doesn't work for custom elements. In order to use two-way data binding, you need to bind and update the value yourself like this:
+## Two-Way Data Binding
+
+In order to use two-way data binding, use `v-model` as follows:
+
+```html
+<ui5-input v-model="inputValue"></ui5-input>
+```
+
+For the `CheckBox` and `RadioButton` web components, you need to include an additional `type` attribute. This informs the Vue compiler that these components use the `checked` property (unlike most input-type components that use the `value` property).
 
 ```html
-<ui5-input
-	:value="inputValue"
-	@input="inputValue = $event.target.value">
-</ui5-input>
+<ui5-radio-button type="radio" v-model="rbValue"></ui5-radio-button>
+<ui5-checkbox type="checkbox" v-model="cbValue"></ui5-checkbox>
 ```
+

docs/4-development/04-slots.md

@@ -8,14 +8,26 @@ Currently, there are two types of slots: "named" and "unnamed". The difference b
 
 ## Unnamed slots
 
-Use unnamed slots when your component does not need to know if any children have been passed to a certain slot, or generally interact with its children from the said slot.
-
-To define an unnamed slot, you simply add a `<slot>` element inside your `.hbs` template, for example:
+Use unnamed slots when your component doesn't need to be aware of or interact with the children passed to a specific slot.
+To define an unnamed slot, simply add a `<slot>` element within your `.hbs` template. For example:
 
 ```hbs
-<slot name="mySlot"></slot>
+{{!-- MyDemoComponent.hbs --}}
+<div>
+   <slot name="mySlot"></slot>
+</div>
 ```
 
+On the consuming side, elements can be passed to this slot using the `slot` attribute:
+
+```html
+<!-- index.html -->
+<my-demo-component>
+    <span slot="mySlot">Hello World</span>
+</my-demo-component>
+```
+
+
 **Note:** It is recommended to describe your unnamed slots inside a JSDoc comment that describes your class using the `@slot` tag, following the pattern `@slot {type} name - description`.
 
 ## Named slots and the `@slot` decorator
@@ -39,15 +51,15 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 
 @customElement("my-demo-component")
 class MyDemoComponent extends UI5Element {
-    @slot({ type: HTMLElement })
+    @slot()
     mySlot!: Array<HTMLElement>;
 }
 ```
 
 You can see the available options below.
 
-### type
-This option is required and accepts a type constructor (e.g., `HTMLElement`, `Node`) and is used to define the type of children that can be slotted inside the slot.
+### Type
+The `type` option accepts a type constructor (e.g., `HTMLElement`, `Node`) and is used to define the type of children that can be slotted inside the slot.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
@@ -67,10 +79,14 @@ Available types:
 | HTMLElement | Accepts HTML Elements only       |
 | Node        | Accepts both Text nodes and HTML Elements |
 
+**Note**: If the slot configuration object is not provided (e.g. `@slot()`), `HTMLElement` will be used as the default type.
+
+
 ### Default Slot
-This option accepts a boolean value and is used to define whether this slot is the default one.
 
-**Note:** The default slot is defined simply as an empty slot tag: `<slot></slot>` (without a `name` attribute).
+The `"default"` option accepts a boolean value and is used to define whether this slot is the default one.
+
+**Note:** The default slot is defined simply as an empty slot tag `<slot></slot>` (without a `name` attribute) in the component's template.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
@@ -79,13 +95,14 @@ import slot from "@ui5/webcomponents-base/dist/decorators/slot.js";
 
 @customElement("my-demo-component")
 class MyDemoComponent extends UI5Element {
-    @slot({ type: HTMLElement, default: true })
+    @slot({ type: HTMLElement, "default": true })
     mySlot!: Array<HTMLElement>;
 }
 ```
 
-### `individualSlots`
-This option accepts a boolean value and determines whether each child will have its own slot, allowing you to arrange or wrap the children arbitrarily. This means that you need to handle the rendering on your own.
+### Individual Slots
+
+The `individualSlots` option accepts a boolean value and determines whether each child will have its own slot, allowing you to arrange or wrap the children arbitrarily. This means that you need to handle the rendering on your own.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
@@ -99,7 +116,7 @@ class MyDemoComponent extends UI5Element {
 }
 ```
 
-To render individual slots, you have to iterate all children in that slot and use the `_individualSlot` property that the framework sets automatically set on each child:
+To render individual slots, you have to iterate all children in that slot and use the `_individualSlot` property that the framework sets automatically on each child:
 
 ```hbs
 {{#each mySlot}}
@@ -109,12 +126,11 @@ To render individual slots, you have to iterate all children in that slot and us
 
 **Note:** When this option is set to `true`, the `_individualSlot` property is set to each direct child, where `_individualSlot` returns a string following the pattern `{nameOfTheSlot}-{index}` and the slot attribute is changed based on that pattern.
 
-### `invalidateOnChildChange`
-This option accepts a boolean value or an object literal containing a configuration with more specific settings, determining whether the component should be invalidated on child change.
+### Invalidation upon child changes
 
-**NOTE: This is an experimental option and should not be used.**
+The `invalidateOnChildChange` option accepts a boolean value or an object literal containing a configuration with more specific settings, determining whether the component should be invalidated on child change.
 
-Important: `invalidateOnChildChange` is not meant to be used with standard DOM elements and is not to be confused with MutationObserver-like functionality. It targets the use case of components that slot abstract items (UI5Element instances without a template) and require invalidation whenever these items are invalidated.
+**Note**: `invalidateOnChildChange` is not meant to be used with standard DOM elements and is not to be confused with MutationObserver-like functionality. It targets the use case of components that slot UI5Element instances and require invalidation whenever these items are invalidated.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";

docs/4-development/05-events.md

@@ -4,7 +4,7 @@ In this article, we will discuss events in the context of UI5 Web Components.
 
 Components use `CustomEvent` to inform developers of important state changes in the components. For example, the `change` event is fired whenever the value of a `ui5-input` is changed.
 
-## `@event` Decorator
+## The `@event` Decorator
 
 To define your own custom event, you need to use the `@event` decorator.
 
@@ -28,9 +28,9 @@ class MyDemoComponent extends UI5Element {}
 
 **Note:** This decorator is used only to describe the events of the component and is not meant to create emitters.
 
-## How to use events
+## 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` method that comes from the `UI5Element` class.
+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.
 
 ```ts
 import UI5Element from "@ui5/webcomponents-base/dist/UI5Element.js";
@@ -46,21 +46,16 @@ class MyDemoComponent extends UI5Element {
 
     onNativeInputChange(e) {
         this.value = e.target.value;
-        this.fireEvent("change");
+        this.fireDecoratorEvent("change"); // or this.fireEvent("change");
     }
 }
 ```
 
-Events fired by the `fireEvent` method can be configurable, meaning you can decide whether the event should be cancelable or able to bubble. This can be done by setting the third and fourth parameters of the function to true, respectively.
+**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).
 
-```ts
-this.fireEvent("change", {}, cancelable, bubbles);
-```
+## Event Detail
 
-**Note:** By default, the `fireEvent` method returns a boolean value that helps you understand whether the event was canceled (i.e., if the `preventDefault` method was called).
-
-## Types
-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 `fireEvent` (which is also generic) and for ensuring type safety when listening for the event, so you know what kind of detail data to expect.
+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.
 
 **Note:** It's required to export all types that describe specific event details for all public events.
 
@@ -88,7 +83,7 @@ class MyDemoComponent extends UI5Element {
     value = "";
 
     onNativeInputChange(e: Event) {
-        this.fireEvent<MyDemoComponentChangeEventDetail>("change", {
+        this.fireDecoratorEvent<MyDemoComponentChangeEventDetail>("change", {
             valid: true,
         });
     }
@@ -97,7 +92,94 @@ class MyDemoComponent extends UI5Element {
 export { MyDemoComponent };
 ```
 
-## noConflict mode
+## Event Configuration
+
+### Bubbling and Preventing
+
+Whether the events should be cancelable or able to bubble is configurable.
+by setting `cancelable` and `bubbles` in the `@event` decorator.
+
+- `cancelable: true` means the event can be prevented by calling the native `preventDefault()` method in the event handler- by default it's `false`.
+
+- `bubbles: true` means the event will bubble - by default it's `false`.
+
+Since `v2.4.0` this can be configured in the `@event` decorator:
+
+```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";
+
+@customElement("my-demo-component")
+@event("change", {
+    bubbles: true // false by default
+    cancelable: true // false by default
+})
+class MyDemoComponent extends UI5Element {
+
+    onSomeAction() {
+        this.fireDecoratorEvent("change")
+    }
+}
+```
+
+### 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.
+
+Keep in mind that `cancelable` and `bubbles` are `false` by default and you must explicitly enable them in the `@event` decorator if required.
+
+- Fire event with default configuration
+
+```ts
+@event("change")
+```
+
+```ts
+// Fires the event as NOT preventable and NOT bubbling
+this.fireDecoratorEvent("change");
+```
+
+- Fire event with non-default configuration
+
+```ts
+@event("change", {
+    bubbles: true // false by default
+    cancelable: true // false by default
+})
+```
+
+```ts
+// Fires the event as preventable and bubbling
+this.fireDecoratorEvent("change");
+```
+
+**Note:** since `v2.4.0` it's recommended to describe the event in the `@event` decorator and use the `fireDecoratorEvent` method. 
+
+### The `fireEvent` method
+
+The method is available since the very beginning of the project and like `fireDecoratorEvent` fires a custom event, but does not consider the settings in the `@event` decorator. So, if you set `cancelable` and `bubbles` in the `@event` decorator, but fire the component events via `fireEvent`, the configured values won't be considered.
+
+Another difference is the default values of the event settings. When using `fireEvent` by default it assumes the event is bubbling (bubbles: true) and not preventable (cancelable: false).
+
+- Fire event with default configuration
+
+```ts
+// Fires the event as NOT preventable and bubbling
+this.fireEvent("change");
+```
+
+- Fire event with non-default configuration
+
+The method allows configuring the `cancelable` and `bubbles` fields via function arguments - the third and fourth parameters respectively.
+
+```ts
+// Fires the event as preventable and non-bubbling
+this.fireEvent("change", {}, true, false);
+```
+
+### noConflict mode
+
 By default, UI5 Web Components fire all custom events twice: once with their name (e.g., `change`) and once more with a `ui5-` prefix (e.g., `ui5-change`). For example, when the `ui5-switch` is toggled, it fires a `change` event and a `ui5-change` event.
 
 This `noConflict` setting allows us to prevent clashes between native and custom events.