Merge branch 'develop' into 'master' for 0.21.0 release

.prettierignore

@@ -30,8 +30,10 @@ browserslist
 /dist
 /out-tsc
 /coverage
+/docs/compodoc
 /junit.xml
 /tslint-rules/dist
+/tslint-rules/test
 /schematics/src/**/files/**
 /schematics/src/**/*.js
 /nginx/*.conf

.stylelintrc.json

@@ -5,7 +5,7 @@
     "stylelint-config-recess-order",
     "stylelint-prettier/recommended"
   ],
-  "ignoreFiles": ["**/node_modules/**", "**/dist/**"],
+  "ignoreFiles": ["**/node_modules/**", "**/dist/**", "**/compodoc/**"],
   "rules": {
     "at-rule-no-vendor-prefix": true,
     "color-named": "never",

CHANGELOG.md

@@ -7,6 +7,44 @@ kb_everyone
 
 # Changelog
 
+## [0.21.0](https://github.com/intershop/intershop-pwa/releases/tag/0.21.0) (2020-06-23)
+
+**required Intershop Commerce Management version: 7.10.19.2**
+
+### Features
+
+- add migration script for NgRx 8 creator functions ([5800cd2](https://github.com/intershop/intershop-pwa/commit/5800cd2))
+- **schematics:** add helper for adding destroy subject to Angular artifact ([4013ff6](https://github.com/intershop/intershop-pwa/commit/4013ff6))
+- **tslint-rules:** add rule for enforcing newline before root statements ([34c20e5](https://github.com/intershop/intershop-pwa/commit/34c20e5))
+- **tslint-rules:** add tslint rule force-jsdoc-comments for enforcing JSDoc usage ([26b25a7](https://github.com/intershop/intershop-pwa/commit/26b25a7))
+- **tslint-rules:** add rule for removing star imports in store ([3c0b528](https://github.com/intershop/intershop-pwa/commit/3c0b528))
+
+### Bug Fixes
+
+- add a product to order template on a product row (#271, #277) ([4714657](https://github.com/intershop/intershop-pwa/commit/4714657))
+
+### Documentation
+
+- update 0.20-to-0.21 migration guide ([6324ebe](https://github.com/intershop/intershop-pwa/commit/6324ebe))
+- update state management documentation regarding creator functions ([8818b16](https://github.com/intershop/intershop-pwa/commit/8818b16))
+- update for the new store structure ([2d9cafa](https://github.com/intershop/intershop-pwa/commit/2d9cafa))
+- new testing approach for NgRx ([b573e18](https://github.com/intershop/intershop-pwa/commit/b573e18))
+- update for using destroy Subject with takeUntil in Angular artifacts ([8331521](https://github.com/intershop/intershop-pwa/commit/8331521))
+
+### Code Refactoring
+
+- change sending of PGID for CMS calls according to ICM 7.10.19.2 CMS REST API changes (#192, #193) ([a5bfff5](https://github.com/intershop/intershop-pwa/commit/a5bfff5))
+- supply operators for resolving links via ApiService ([82e0de7](https://github.com/intershop/intershop-pwa/commit/82e0de7))
+- perform action creator migration ([31acf5d](https://github.com/intershop/intershop-pwa/commit/31acf5d))
+- new structure for core store ([0fe99e4](https://github.com/intershop/intershop-pwa/commit/0fe99e4))
+
+### BREAKING CHANGES
+
+- Pipable operators for resolving links are now ApiService members.
+- NgRx code artifacts are transformed to a new pattern, follow the instructions in the migration guide.
+- Core store was restructured. Follow instructions in the migration guide.
+- CMS service personalized content call adaptions to match CMS REST API changes in ICM.
+
 ## [0.20.0](https://github.com/intershop/intershop-pwa/releases/tag/0.20.0) (2020-05-29)
 
 **required Intershop Commerce Management version: 7.10.18.1**

Dockerfile_reports

@@ -9,7 +9,7 @@ RUN npm run postinstall
 RUN npm i --no-save tslint-html-report && (node reports/tslint-report || true)
 RUN npm i --no-save jest-html-reporter jest-junit && npx jest -c jest-reports.config.js --ci --testFailureExitCode 0
 RUN npx license-checker --csv --out reports/licenses/licenses.csv --customPath templates/3rd-party-licenses_format.json && npm i --no-save htmlify-csv && node node_modules/htmlify-csv/htmlify-csv convert reports/licenses/licenses.csv --output reports/licenses/index.html
-RUN npm run docs
+RUN npm run compodoc
 RUN npm i --no-save jscpd-html-reporter && node reports/jscpd-report
 RUN npm i -g webpack-bundle-analyzer
 RUN rm -Rf dist && npx ng build --progress false --aot --stats-json && webpack-bundle-analyzer dist/browser/stats-es2015.json dist/browser -r reports/bundle_aot/index.html -m static

docs/README.md

@@ -1,10 +1,3 @@
-<!--
-kb_concepts
-kb_pwa
-kb_everyone
-kb_sync_latest_only
--->
-
 # Documentation Overview
 
 ## Developers
@@ -27,12 +20,13 @@ kb_sync_latest_only
 ### Developing
 
 - [Guide - Development Environment](./guides/development.md)
+- [Guide - Angular Component Development](./guides/angular-component-development.md)
 - [Concept - Styling](./concepts/styling-behavior.md)
 - [Concept - Testing](./concepts/testing.md)
   - [Guide - Testing with Jest](./guides/testing-jest.md)
   - [Guide - Testing with Cypress](./guides/testing-cypress.md)
+  - [Guide - State Management > Testing](./guides/state-management.md#testing-ngrx-artifacts)
 - [Guide - Code Documentation](./guides/code-documentation.md)
-- [Guide - Angular Component Development](./guides/angular-component-development.md)
 - [Guide - Angular Change Detection](./guides/angular-change-detection.md)
 - [Guide - Data Handling with Mappers](./guides/data-handling-with-mappers.md)
 

docs/check-kb-labels.js

@@ -8,6 +8,9 @@ if (files.length === 0) {
   files = glob.sync('docs/**/*.md');
 }
 
+// ignore documentation overview
+files = files.filter(p => !p.endsWith(path.join('docs', 'README.md')));
+
 let isError = false;
 
 function getDefaultLabel(file) {

docs/concepts/configuration.md

@@ -181,6 +181,14 @@ export class SomeService {
 }
 ```
 
+### Unit Testing with Feature Toggles
+
+With Version 0.21 we introduced [`FeatureToggleModule.forTesting`][feature-toggle-module] which provides a shallow implementation for testing with feature toggles not depending on the state management.
+Use it in the `imports` of the `TestBed` declaration of the unit test.
+Switching features in tests can be triggered by calling [`FeatureToggleModule.switchTestingFeatures`][feature-toggle-module] with a new set of activated feature toggles.
+
+[feature-toggle-module]: ../../src/app/core/feature-toggle.module.ts
+
 ## Setting Default Locale
 
 You can set the default locale statically by modifying the order of the provided locales in the Angular CLI environment files.

docs/concepts/state-management.md

@@ -33,8 +33,9 @@ Selectors return observables which can be held in containers and be bound to in
 ### Actions
 
 Actions are simple objects used to alter the current state via reducers or trigger effects.
+They contain the type of the action and an optional payload.
+Action objects are not created directly but rather through action creator functions.
 Action creators are held in a separate file.
-The action class contains a type of the action and an optional payload.
 To alter the state synchronously, reducers have to be composed.
 To alter the state asynchronously, effects are used.
 
@@ -73,15 +74,15 @@ src/app/core
               |  └─ index.ts
               ├─ bar
               |  └─ ...
-              ├─ foobar.state.ts
-              └─ foobar.system.ts
+              ├─ foobar-store.ts
+              └─ foobar-store.module.ts
 ```
 
 An application module named `foobar` with substates named `foo` and `bar` serves as an example.
 The files handling NgRx store should then be contained in the folder `foobar`.
 Each substate should aggregate its store components in separate subfolders correspondingly named `foo` and `bar`:
 
-- _foo.actions.ts_: This file contains all action creators for the `foo` state. Additionally, a bundle type aggregating all action creators and an enum type with all action types is contained here.
+- _foo.actions.ts_: This file contains all action creators for the `foo` state.
 
 - _foo.effects.ts_: This file defines an effect class with all its containing effect implementations for the `FooState`.
 
@@ -93,60 +94,72 @@ Each substate should aggregate its store components in separate subfolders corre
 
 Furthermore, the state of foobar is aggregated in two files:
 
-- _foobar.state.ts_: Contains the `FoobarState` as an aggregate of the `foo` and `bar` states.
+- _foobar-store.ts_: Contains the `FoobarState` as an aggregate of the `foo` and `bar` states.
 
-- _foobar.system.ts_: Contains aggregations for `foobarReducers` and `foobarEffects` of the corresponding substates to be used in modules and `TestBed` declarations.
+- _foobar-store.module.ts_: Contains aggregations for `foobarReducers` and `foobarEffects` of the corresponding substates as well as the store module.
 
 Access to the state slice of `foobar` is provided with the `FoobarFacade` located in _foobar.facade.ts_
 
+## Core Store Structure
+
+The PWA has a core state initializing the [StoreModule.forRoot](https://ngrx.io/api/store/StoreModule#forroot) and multiple feature modules using [StoreModule.forFeature](https://ngrx.io/api/store/StoreModule#forfeature).
+
+- `core`: PWA runtime independent of the ICM like configuration, global error handling or [@ngrx/router-store](https://ngrx.io/guide/router-store) integration.
+- `shopping`: Logic and data for browsing the PWA independent of the current user.
+- `customer`: Everything user-related (anonymous or logged in) like the current basket or the user profile.
+- `content`: Everything related to the CMS.
+- `general`: Minor features that don't require a fully fledged feature store.
+- ...
+
+All store modules are aggregated and imported in the [`StateManagementModule`](../../src/app/core/state-management.module.ts).
+
 ## Naming
 
 Related to the example in the previous paragraph, we want to establish a particular naming scheme.
 
 ### Actions - Types
 
-Action types should be aggregated in an enum type.
-The enum should be composed of the substate name and 'ActionTypes'.
-The key of the type should be written in PascalCase.
 The string value of the type should contain the feature in brackets and a readable action description.
 The description should give hints about the dispatcher of the said action, i.e., actions dispatched due to a HTTP service response should have 'API' in their name, actions dispatched by other actions should have 'Internal' in their description.
 
 ```typescript
-export enum FooActionTypes {
-  LoadFoo = '[Foo Internal] Load Foo',
-  InsertFoo = '[Foo] Insert Foo',
-  LoadFooSuccess = '[Foo API] Load Foo Success',
+  '[Foo Internal] Load Foo',
+  '[Foo] Insert Foo',
+  '[Foo API] Load Foo Success',
   ...
-}
 ```
 
 ### Actions - Creators
 
-The action creator is a class with an optional payload member.
-Its PascalCase name should correspond to an action type.
-The name should not contain 'Action' as the action is always dispatched via the store and it is therefore implicitly correctly named.
-
-```typescript
-export class LoadFoo implements Action {
-  readonly type = FooActionTypes.LoadFoo;
-  constructor(public payload: string) {}
-}
-```
-
-### Actions - Bundle
-
-The file _actions.ts_ should also contain an action bundle type with the name of the substate + 'Action', which is to be used in the reducer and tests.
+The action creator is a function with a type argument and an optional payload argument.
+Its camelCase name should correspond to its type.
+The name should not contain 'Action' as the action is always dispatched via the store and is therefore implicitly correctly named.
+The action creator is defined using the [createAction](https://ngrx.io/api/store/createAction) function.
+To attach data to an action, use the payload or httpError adapters from [ngrx-creators.ts](../../src/app/core/utils/ngrx-creators.ts).
 
 ```typescript
-export type FooAction = LoadFoo | SaveFoo | ...
+export const loadFoo = createAction('[Foo Internal] Load Foo');
+export const loadFooSuccess = createAction('[Foo API] Load Foo Success', payload<{ foo: Foo[] }>());
+export const loadFooFail = createAction('[Foo API] Load Foo Fail', httpError());
 ```
 
 ### Reducer
 
 The exported function for the reducer should be named like the substate + 'Reducer' in camelCase.
+The reducer function is defined using the [createReducer](https://ngrx.io/api/store/createReducer) function.
+Associations between actions and state changes are defined via callbacks in the on function.
+To easily set loading or error states, use the setLoadingOn and setErrorOn helpers from [ngrx-creators.ts](../../src/app/core/utils/ngrx-creators.ts).
 
 ```typescript
-export function fooReducer(state = initialState, action: FooAction): FooState {
+export const fooReducer = createReducer(
+  initialState,
+  setLoadingOn(loadFoo),
+  setErrorOn(loadFooFail),
+  on(loadFooSuccess, (state: FooState, action) => {
+    // state changes
+  }),
+  ...
+)
 ```
 
 ### State

docs/guides/angular-component-development.md

@@ -105,10 +105,20 @@ export class AnyComponent implements OnInit, OnDestroy {
   ...
   ngOnDestroy() {
     this.destroy$.next();
+    this.destroy$.complete();
   }
 }
 ```
 
+The TSLint rule `rxjs-prefer-angular-takeuntil` enforces the usage of a `destroy$` Subject with `takeUntil` when subscribing in an Angular artifact.
+You can use the schematic `add-destroy` to automatically generate the required logic:
+
+```
+$ ng g add-destroy shared/components/common/accordion
+
+UPDATE src/app/shared/components/common/accordion/accordion.component.ts (425 bytes)
+```
+
 ## Use `OnPush` Change Detection if Possible
 
 To reduce the number of ChangeDetection computation cycles, all components should have their `Component` decorator property `changeDetection` set to `ChangeDetectionStrategy.OnPush`.
@@ -126,3 +136,13 @@ Consider splitting one into multiple components when:
 - **Async data**: Component relies on async data from the store which makes the component code unnecessarily complex. Use a container component then which resolves the observables at the outside of the child component and passes data in via property bindings. Do not do this for simple cases.
 
 Single-use dumb components are always okay if it improves readability.
+
+## Mock Facades in Tests
+
+Angular Artifacts like Components, Directives and Pipes should solely depend on facades to interact with the [State Management](../concepts/state-management.md).
+This is enforced with the TSLint rule `no-intelligence-in-artifacts` which rejects every usage of REST API Services and NgRx Artifacts.
+
+Use [ts-mockito](https://github.com/NagRock/ts-mockito) for creating and managing these mocks.
+Providers for Facades can easily be added by using the VSCode snippet `ish-provider-ts-mockito`:
+
+![ish-provider-ts-mockito](ish-provider-ts-mockito.gif 'VSCode snippet ish-provider-ts-mockito in action')

docs/guides/code-documentation.md

@@ -24,7 +24,7 @@ Examples for the comment styling pattern can be found here: [TypeDoc - DocCommen
 **Generate Code Documentation**
 
 ```bash
-npm run docs
+npm run compodoc
 ```
 
 The generated documentation can be called by _<project-home>/docs/compodoc/index.html_.
@@ -34,18 +34,12 @@ The generated documentation can be called by _<project-home>/docs/compodoc/index
 **Serve Generated Documentation with Compodoc**
 
 ```bash
-npm run docs:serve
+npm run compodoc:serve
 ```
 
 Documentation is generated at _<project-home>/docs/compodoc_ (output folder).
 The local HTTP server is launched at _http://localhost:8080_.
 
-**Watch Source Files After Serve and Force Documentation Rebuild**
-
-```bash
-npm run docs:watch
-```
-
 ## Comments
 
 ### General Information

docs/guides/migrations.md

@@ -7,6 +7,43 @@ kb_sync_latest_only
 
 # Migrations
 
+## 0.20 to 0.21
+
+We deprecated and reworked the way of testing with NgRx.
+The old format using `ngrxTesting` with `combineReducers` is now deprecated and replaced by the [new approach](./state-management.md#testing-ngrx-artifacts).
+The old testing mechanism will be removed in version 0.23.
+
+We introduced a way to do [shallow testing with feature toggles](../concepts/configuration.md#unit-testing-with-feature-toggles) and used it in the tests.
+
+We [reorganized the core store](../concepts/state-management.md#core-store-structure):
+
+- new `customer`
+  - store/addresses => store/**customer**/addresses
+  - store/checkout/basket => store/**customer**/basket
+  - store/orders => store/**customer**/orders
+  - store/restore => store/**customer**/restore
+  - store/user => store/**customer**/user
+- new `core`
+  - store/configuration => store/**core**/configuration
+  - store/error => store/**core**/error
+  - store/messages => store/**core**/messages
+  - store/router => store/**core**/router
+  - store/viewconf => store/**core**/viewconf
+- new `general`
+  - store/contact => store/**general**/contact
+  - store/countries => store/**general**/countries
+  - store/regions => store/**general**/regions
+
+TSLint rules are set up to automatically fix imports, so run `npm run check` after upgrading.
+
+In this version, we decided to start using the ngrx creator introduced in ngrx v8: [createAction](https://ngrx.io/api/store/createAction), [createReducer](https://ngrx.io/api/store/createReducer) and [createEffect](https://ngrx.io/api/effects/createEffect).
+This means that the old way of writing action classes, reducer switch statements and @Effect() decorators is deprecated from 0.21 onwards.
+
+Using these creator functions simplifies code and removes a lot of boiler plate from store files while providing type safety out-of-the-box.
+
+You can automatically migrate your existing code by executing `node schematics/migration/0.20-to-0.21`.
+Doing this will set related ts-lint rules and update each store or notify you of work previously needed.
+
 ## 0.19.1 to 0.20
 
 We upgraded from Angular 8 to version 9 and activated the new rendering engine Ivy with this (following the [official upgrade guide](https://update.angular.io/#8.0:9.0l3)).