Merge remote-tracking branch 'origin/new-cem' into rd-new-cem

SAP · Nov 23, 2023 · d456375 · d456375
2 parents cf7d315 + 04598ad
commit d456375
Show file tree

Hide file tree

Showing 148 changed files with 6,729 additions and 675 deletions.
diff --git a/CHANGELOG.md b/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.
 
+# [1.20.0-rc.1](https://github.com/SAP/ui5-webcomponents/compare/v1.20.0-rc.0...v1.20.0-rc.1) (2023-11-16)
+
+
+### Bug Fixes
+
+* declare webpackChunkName in generated dynamic imports for readable runtime bundle names ([#7835](https://github.com/SAP/ui5-webcomponents/issues/7835)) ([592a10b](https://github.com/SAP/ui5-webcomponents/commit/592a10b25a14da89885874c40c5c7a192b8b4d85))
+* **ui5-list:** shift+tab navigation in List ([#7728](https://github.com/SAP/ui5-webcomponents/issues/7728)) ([399b941](https://github.com/SAP/ui5-webcomponents/commit/399b941ebeae7b44f6dba9cd4e8ec7ebb6f283c6))
+
+
+### Features
+
+* **ui5-illustrated-message:** titleLevel property added ([#7771](https://github.com/SAP/ui5-webcomponents/issues/7771)) ([2883c58](https://github.com/SAP/ui5-webcomponents/commit/2883c587f367e51e0f08065498b990f86e60e88c)), closes [#7037](https://github.com/SAP/ui5-webcomponents/issues/7037)
+
+
+
+
+
+# [1.20.0-rc.0](https://github.com/SAP/ui5-webcomponents/compare/v1.19.0...v1.20.0-rc.0) (2023-11-09)
+
+
+### Bug Fixes
+
+* **ItemNavigation:** more than 1 ItemNavigation per component allowed ([#7798](https://github.com/SAP/ui5-webcomponents/issues/7798)) ([b1019af](https://github.com/SAP/ui5-webcomponents/commit/b1019aff6c4aced61458c1b718ffe0a3a7802ae2))
+* **ui5-segmented-button:** check for items before applying settings ([#7792](https://github.com/SAP/ui5-webcomponents/issues/7792)) ([7f11274](https://github.com/SAP/ui5-webcomponents/commit/7f112746d50381474ec86da5e428df79c17c6499)), closes [#7788](https://github.com/SAP/ui5-webcomponents/issues/7788)
+* **ui5-time-picker:** check value before formatting ([#7793](https://github.com/SAP/ui5-webcomponents/issues/7793)) ([70deda8](https://github.com/SAP/ui5-webcomponents/commit/70deda85293d5e62e99530c9dc0747071d9ee59c)), closes [#7790](https://github.com/SAP/ui5-webcomponents/issues/7790)
+
+
+### Features
+
+* **ui5-illustrated-message:** added new TNT illustrations ([#7773](https://github.com/SAP/ui5-webcomponents/issues/7773)) ([03f28b9](https://github.com/SAP/ui5-webcomponents/commit/03f28b90df0b2a28c0f09f67caaa0a5a1e63c4f3))
+* **ui5-side-navigation:** added href and target properties ([#7682](https://github.com/SAP/ui5-webcomponents/issues/7682)) ([7530f00](https://github.com/SAP/ui5-webcomponents/commit/7530f00b589d0b95dcbee49f6ed980e9d36ba58b))
+
+
+
+
+
 # [1.19.0](https://github.com/SAP/ui5-webcomponents/compare/v1.19.0-rc.3...v1.19.0) (2023-11-02)
 
 **Note:** Version bump only for package ui5-webcomponents

diff --git a/docs/1-getting-started/06-using-features.md b/docs/1-getting-started/06-using-features.md
@@ -16,7 +16,7 @@ Import the feature file from the respective NPM package:
 
 `import "@ui5/<PACKAGE-NAME>/dist/features/<FEATURE-NAME>.js`
 
-## Component features 
+## Component features
 
 Currently, only a few components offer additional features:
 
@@ -31,22 +31,28 @@ Currently, only a few components offer additional features:
 | `localization` | Multiple (`ui5-date-picker`, etc...)              | `@ui5/webcomponents-localization/dist/features/calendar/Japanese.js` | Japanese calendar support                                                                               |
 | `localization` | Multiple (`ui5-date-picker`, etc...)              | `@ui5/webcomponents-localization/dist/features/calendar/Persian.js`  | Persian calendar support                                                                                |
 
+<b>Note:</b> Features must be imported before all components modules,
+so that the feature is enabled before the components' definition.
+
 For example:
 
 ```js
 import "@ui5/webcomponents/dist/features/ColorPaletteMoreColors.js;";
+
+import "@ui5/webcomponents/dist/Button.js";
+import "@ui5/webcomponents/dist/Link.js";
+import "@ui5/webcomponents/dist/Input.js";
 ```
 
-## Framework features 
+## Framework features
 
 | Package        | Affects                                           | Feature Import                                                       | Description                                                                                             |
 |----------------|---------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|
 | `base`         | Framework                                         | `@ui5/webcomponents-base/dist/features/OpenUI5Support.js`            | Integration with the OpenUI5 framework, allowing synchronization and resources re-use                   |
 | `base`         | Multiple components within all libraries          | `@ui5/webcomponents-base/dist/features/F6Navigation.js`              | Support for F6 fast groups navigation                                                                   |
 | `base`         | Date related components                           | `@ui5/webcomponents-base/dist/features/LegacyDateFormats.js`         | Support for legacy date formats                                                                         |
-|
 
-Framework-level features must be imported before all components modules,
+<b>Note:</b> Framework-level features must be imported before all components modules,
 so that the feature is enabled upon framework boot, before the components' definition.
 
 For example:

diff --git a/docs/4-frameworks/01-React.md b/docs/4-frameworks/01-React.md
@@ -2,7 +2,7 @@
 
 In this tutorial, you will learn how to add UI5 Web Components to your application. You can add UI5 Web Components both to new React applications and to already existing ones.
 
-**Important:** The get the best development experience, we recommend using the [UI5 Web Components for React](https://github.com/SAP/ui5-webcomponents-react) and follow the [UI5 Web Components for React Тutorial](https://developers.sap.com/mission.react-spa.html). UI5 Web Components for React library is a React implementation of UI5 Web Components which overcomes several limitations of React in handling web components in general, explained in the "Additional Info" section below.
+**Important:** To get the best development experience, we recommend using the [UI5 Web Components for React](https://github.com/SAP/ui5-webcomponents-react) and follow the [UI5 Web Components for React Тutorial](https://developers.sap.com/mission.react-spa.html). UI5 Web Components for React library is a React implementation of UI5 Web Components which overcomes several limitations of React in handling web components in general, explained in the "Additional Info" section below.
 
 Here are the steps to use pure UI5 Web Components in React:
 

diff --git a/docs/4-frameworks/02-Angular.md b/docs/4-frameworks/02-Angular.md
@@ -1,6 +1,10 @@
 # Get Started with UI5 Web Components & Angular
 
-In this tutorial, you will learn how to add UI5 Web Components to your application. The UI5 Web Components can be added both to new Angular applications and to already existing ones.
+In this tutorial, you will learn how to use `UI5 Web Components` in an Angular application. In the second part, we will introduce `UI5 Web Components for Angular` - wrapper library for UI5 Web Components, improving their integration with Angular.
+
+**Note:** To get the best development experience, we recommend using the [UI5 Web Components for Angular](https://ui5-webcomponents-ngx.netlify.app). The library removes the need for `CUSTOM_ELEMENTS_SCHEMA` and `NO_ERRORS_SCHEMA` schemas, and supports all Angular-specific features out-of-the-box.
+
+## UI5 Web Components
 
 ### Step 1. Install Angular CLI.
 
@@ -10,26 +14,30 @@ npm install -g @angular/cli
 
 ### Step 2. Create a new Angular application.
 
+Use the standard path to setup a new Angular app.
+
 ```bash
 ng new ui5-web-components-application
 cd ui5-web-components-application
 ```
 
-### Step 3. Add UI5 Web Components.
+### Step 3. Install UI5 Web Components.
 
 ```bash
-npm install @ui5/webcomponents --save
+npm install @ui5/webcomponents
 ```
 
-### Step 4. Allow the use of custom elements in Angular.
+### Step 4. Allow Custom Elements in Angular.
 
-Before using UI5 Web Components, you have to allow the use of custom elements in Angular. To do so, import CUSTOM_ELEMENTS_SCHEMA in ```app.module.ts``` :
+Before using UI5 Web Components, you have to allow the use of custom elements via the `CUSTOM_ELEMENTS_SCHEMA`. This allows an NgModule to contain Non-Angular elements named with dash.
+
+-  Import `CUSTOM_ELEMENTS_SCHEMA` in `app.module.ts`:
 
 ```js
 import { ..., CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
 ```
 
-After importing it, add it to the schemas array:
+- Add `CUSTOM_ELEMENTS_SCHEMA` to the schemas array:
 
 ```js
 imports: [
@@ -40,13 +48,30 @@ schemas: [
 ]
 ```
 
-### Step 5. Import the components you are going to use.
+### Step 5. Import UI5 Web Components.
+
+Import the components you are going to use.
+
+Let's import the Button in `app.component.ts`:
 
 ```js
-import "@ui5/webcomponents/dist/Button.js";
+import { Component } from '@angular/core';
+
+import '@ui5/webcomponents/dist/Button.js';
+
+@Component({
+  selector: 'app-root',
+  templateUrl: './app.component.html',
+})
+export class AppComponent {
+}
 ```
 
-### Step 6. Use the imported elements in your application.
+### Step 6. Use UI5 Web Components.
+
+Use the imported components in your application by their tag names - as any other HTML element.
+
+Let's add the button into the `app.component.html` template:
 
 ```html
 <ui5-button>Hello world!</ui5-button>
@@ -58,73 +83,181 @@ import "@ui5/webcomponents/dist/Button.js";
 ng serve -o
 ```
 
-## Additional Info
+After the development server starts, the UI5 Web Components Button will be rendered in the test page. Now that you've seen how easy it is to use the UI5 Web Components, you can continue with adding more components in the same manner.
+
+
+## UI5 Web Components For Angular
+
+UI5 Web Components for Angular is a wrapper library for UI5 Web Components. This means that for every UI5 Web Component, there is a corresponding Angular wrapper component available.
 
-### Two-Way Data Binding
+**For Example:**
 
-You can use two-way data binding with the following components: CheckBox, RadioButton, Input, DatePicker, Switch, TextArea.
-In order to use it, you have to use a library called [Origami](https://github.com/hotforfeature/origami) that provides advanced support for two-way data binding of custom elements.
+- The native Button web component 
+```js
+import '@ui5/webcomponents/dist/Button.js';
+```
+
+- The "ngx" Button wrapper component
+```js
+import { ButtonComponent } from '@ui5/webcomponents-ngx/main/button';
+```
 
-Example:
+These wrappers supports all Angular-specific features out-of-the-box, f.e. two-way data binding with `NgModel`, as they are native to Angular.
+
+### Angular Form with `NgModel`
+
+The following section demonstrates how to build template-driven Angular form (following the oficial [Angular documentation](https://angular.io/guide/forms)) with UI5 Web Components For Angular. It illustrates the usage of two-way data binding to update the data model in the component as changes are made in the template and vice versa.
+
+### Step 1. Setup Angular project
+
+```bash
+npm install -g @angular/cli
+ng new ui5-web-components-ngx-application
+cd ui5-web-components-ngx-application
+```
+
+### Step 2. Install UI5 Web Components for Angular.
 
-#### 1. Install Origami.
 
 ```bash
-npm install @codebakery/origami
+npm install @ui5/webcomponents-ngx
 ```
 
-#### 2. Import the OrigamiFormsModule from Origami.
+### Step 3. Build Angular form.
+
+To build an Angular Form, we will include the required infrastructure such as the `FormsModule`, track input validity and status using `ngModel` and make use of some form components from `@ui5/webcomponents-ngx`.
+
+
+- Import `FormsModule` in `app.module.ts` and add it to the imports array.
 
 ```js
-import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
 import { BrowserModule } from '@angular/platform-browser';
-import { OrigamiFormsModule } from '@codebakery/origami/forms';
+
 import { AppComponent } from './app.component';
 
 @NgModule({
-  imports: [BrowserModule, OrigamiFormsModule],
-  declarations: [AppComponent],
-  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  declarations: [
+    AppComponent
+  ],
+  imports: [
+    BrowserModule,
+    FormsModule,
+  ],
+  providers: [],
   bootstrap: [AppComponent]
 })
-export class AppModule {}
-```
-
-#### 3. Use Origami in your template.
-
-```html
-<ui5-input [(ngModel)]="value" origami></ui5-input>
+export class AppModule {
+}
 ```
 
-#### 4. Make Angular boot after UI5 Web Components are defined.
+- Import `Label`, `Input` and `Button` components from `@ui5/webcomponents-ngx` in `app.module.ts` and add them to the imports array.
 
-Add the ```APP_INITIALIZER``` provider to the module where you are using UI5 Web Components. In order to do so, import ```APP_INITIALIZER``` and add it to the providers array like this (in this example we will add it to the ```app.module.ts```):
 ```js
-import { ..., APP_INITIALIZER  } from '@angular/core';
+import { NgModule } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { BrowserModule } from '@angular/platform-browser';
 
-import CheckBox from "@ui5/webcomponents/dist/CheckBox";
+import { AppComponent } from './app.component';
 
-function onAppInit(): () => Promise<any> {
-  return (): Promise<any> => {
-    return CheckBox.define();
-  };
-}
+// UI5 Web Components For Angular
+import { LabelComponent } from '@ui5/webcomponents-ngx/main/label';
+import { ButtonComponent } from '@ui5/webcomponents-ngx/main/button';
+import { InputComponent } from '@ui5/webcomponents-ngx/main/input';
 
 @NgModule({
   declarations: [
-        ...
+    AppComponent
   ],
   imports: [
-        ...
-  ],
-  providers: [
-    {
-        provide: APP_INITIALIZER,
-        useFactory: onAppInit,
-        multi: true
-    },
+    BrowserModule,
+    FormsModule,
+    LabelComponent,
+    InputComponent,
+    ButtonComponent
   ],
-  schemas: [ CUSTOM_ELEMENTS_SCHEMA ],
+  providers: [],
   bootstrap: [AppComponent]
 })
+export class AppModule {
+}
+```
+
+### Step 4. Define a Data Model.
+
+- Add the following object, that will serve as a data model, to the `AppComponent`:
+
+```js
+// app.component.ts
+import { Component } from '@angular/core';
+
+export class AppComponent {
+  model = {
+    firstName: "",
+    lastName: ""
+  };
+}
+```
+
+### Step 5. Create the Form UI.
+
+- Add the following inline template to the `AppComponent`.
+- Bind form components to data properties using the `ngModel` directive and two-way data-binding syntax.
+- Name form controls (e.g. add `name` attribute) to make them accessible to `ngModel`.
+
+```js
+// app.component.ts
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-root',
+  template: `<h1>Form Works!</h1>
+
+  <form #heroForm="ngForm">
+    <div>
+      <ui5-label for="inp1">First Name:</ui5-label>
+      <ui5-input id="inp1" [(ngModel)]="model.firstName" name="firstName" [required]="true"></ui5-input>
+    </div>
+
+    <div>
+      <ui5-label for="inp2">Last Name:</ui5-label>
+      <input id="inp2" type="text" [(ngModel)]="model.lastName" name="lastName" required/>
+    </div>
+    
+    <ui5-button [submits]="true">Submit</ui5-button> 
+
+    Form Value: {{heroForm.value | json}}
+    Form Status: {{heroForm.status}}
+  </form>`,
+})
+export class AppComponent {
+  model = {
+    firstName: "",
+    lastName: ""
+  };
+}
+```
+
+### Step 5. Launch the application.
+
+```bash
+ng serve -o
 ```
+
+After the development server starts, a simple form will be rendered in the test page.
+
+Initially, the model is empty and the form is invalid:
+
+```js
+// Form Value: { "firstName": "", "lastName": "" }
+// Form Status: "Invalid"
+```
+
+Start typing in the input fields and you will notice how the form model and form status are updated.
+
+Good job, the Form works!
+
+## Summary
+
+Angular provides good support of web components and `UI5 Web Components` are working perfectly in the majority of use-cases. However, for an enhanced development experience and better support for both template-driven and Reactive forms,  the `UI5 Web Components for Angular` is the recommended choice.