feat(workbench): support navigation of views in the initial layout (or perspective)

Previously, views in the initial layout (or perspective) were limited to only supporting empty-path routes and could not be navigated or opened multiple times.

closes #445

BREAKING CHANGE: Views in the initial layout (or perspective) must now be navigated.

Previously, no explicit navigation was required because view and route were coupled via route outlet and view id.

**Migrate the layout as follows:**

Explicitly navigate views, passing an empty array of commands and the view id as navigation hint.

```ts
// Before Migration
provideWorkbench({
  layout: (factory: WorkbenchLayoutFactory) => factory
    .addPart(MAIN_AREA)
    .addPart('left', {relativeTo: MAIN_AREA, align: 'left'})
    .addView('navigator', {partId: 'left', activateView: true}),
});

// After Migration
provideWorkbench({
  layout: (factory: WorkbenchLayoutFactory) => factory
    .addPart(MAIN_AREA)
    .addPart('left', {relativeTo: MAIN_AREA, align: 'left'})
    .addView('navigator', {partId: 'left', activateView: true})
    // Navigate view, passing hint to match route.
    .navigateView('navigator', [], {hint: 'navigator'}),
});
```

**Migrate the routes as follows:**
- Remove the outlet property;
- Add `canMatchWorkbenchView` guard and initialize it with the hint passed to the navigation;

```ts
// Before Migration
provideRouter([
  {
    path: '',
    outlet: 'navigator',
    loadComponent: () => ...,
  },
]);

// After Migration
provideRouter([
  {
    path: '',
    // Match route only if navigated with specified hint.
    canMatch: [canMatchWorkbenchView('navigator')],
    loadComponent: () => ...,
  },
]);
```

BREAKING CHANGE: Changed type of view id from `string` to `ViewId`

If storing the view id in a variable, change its type from `string` to `ViewId`.

Author: danielwiehl

README.md

@@ -16,12 +16,12 @@ SCION Workbench enables the creation of Angular web applications that require a
 - [**Getting Started**][link-getting-started]\
   Follow these steps to install the SCION Workbench in your project and start with a basic introduction to the SCION Workbench.
 
-#### Workbench Demo Applications
+#### Workbench Sample Applications
 
-- [**SCION Workbench Testing App**][link-testing-app]\
-  Visit our technical testing application to explore the workbench and experiment with its features.
+- [**Playground Application**][link-playground-app]\
+  Visit our playground application to explore the workbench and experiment with its features.
 
-- [**SCION Workbench Getting Started App**][link-getting-started-app]\
+- [**Getting Started Application**][link-getting-started-app]\
   Open the application developed in the [Getting Started][link-getting-started] guide.
 
 #### Documentation
@@ -72,7 +72,7 @@ SCION Workbench enables the creation of Angular web applications that require a
 [link-getting-started]: /docs/site/getting-started.md
 [link-howto]: /docs/site/howto/how-to.md
 [link-demo-app]: https://schweizerischebundesbahnen.github.io/scion-workbench-demo/#/(view.24:person/64//view.22:person/32//view.5:person/79//view.3:person/15//view.2:person/38//view.1:person/66//activity:person-list)?viewgrid=eyJpZCI6MSwic2FzaDEiOlsidmlld3BhcnQuMSIsInZpZXcuMSIsInZpZXcuMiIsInZpZXcuMSJdLCJzYXNoMiI6eyJpZCI6Miwic2FzaDEiOlsidmlld3BhcnQuMiIsInZpZXcuMyIsInZpZXcuMyJdLCJzYXNoMiI6eyJpZCI6Mywic2FzaDEiOlsidmlld3BhcnQuNCIsInZpZXcuMjQiLCJ2aWV3LjI0Il0sInNhc2gyIjpbInZpZXdwYXJ0LjMiLCJ2aWV3LjIyIiwidmlldy41Iiwidmlldy4yMiJdLCJzcGxpdHRlciI6MC41MTk0Mzg0NDQ5MjQ0MDY2LCJoc3BsaXQiOmZhbHNlfSwic3BsaXR0ZXIiOjAuNTU5NDI0MzI2ODMzNzk3NSwiaHNwbGl0Ijp0cnVlfSwic3BsaXR0ZXIiOjAuMzIyNjI3NzM3MjI2Mjc3MywiaHNwbGl0IjpmYWxzZX0%3D
-[link-testing-app]: https://scion-workbench-testing-app.vercel.app
+[link-playground-app]: https://scion-workbench-testing-app.vercel.app
 [link-getting-started-app]: https://scion-workbench-getting-started.vercel.app
 [link-features]: /docs/site/features.md
 [link-announcements]: /docs/site/announcements.md

apps/workbench-client-testing-app/src/app/app.component.html

@@ -1,6 +1,6 @@
 <ng-container *ngIf="workbenchContextActive | async; else workbench_context_note">
   <sci-viewport cdkTrapFocus>
-    <router-outlet></router-outlet>
+    <router-outlet/>
   </sci-viewport>
   <section class="metadata">
     <span class="chip has-focus e2e-has-focus" *ngIf="focusMonitor!.focus$ | async">has-focus</span>

apps/workbench-client-testing-app/src/app/css-class/css-class.component.html

@@ -0,0 +1 @@
+<input [formControl]="formControl" class="e2e-class" placeholder="class-1 class-2">

apps/workbench-client-testing-app/src/app/css-class/css-class.component.scss

@@ -0,0 +1,10 @@
+@use '@scion/components.internal/design' as sci-design;
+
+:host {
+  display: inline-grid;
+
+  > input {
+    @include sci-design.style-input-field();
+    min-width: 0;
+  }
+}

apps/workbench-client-testing-app/src/app/css-class/css-class.component.ts

@@ -0,0 +1,84 @@
+/*
+ * Copyright (c) 2018-2024 Swiss Federal Railways
+ *
+ * This program and the accompanying materials are made
+ * available under the terms of the Eclipse Public License 2.0
+ * which is available at https://www.eclipse.org/legal/epl-2.0/
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+
+import {Component, forwardRef} from '@angular/core';
+import {ControlValueAccessor, NG_VALUE_ACCESSOR, NonNullableFormBuilder, ReactiveFormsModule} from '@angular/forms';
+import {noop} from 'rxjs';
+import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
+import {Arrays} from '@scion/toolkit/util';
+
+@Component({
+  selector: 'app-css-class',
+  templateUrl: './css-class.component.html',
+  styleUrls: ['./css-class.component.scss'],
+  standalone: true,
+  imports: [
+    ReactiveFormsModule,
+  ],
+  providers: [
+    {provide: NG_VALUE_ACCESSOR, multi: true, useExisting: forwardRef(() => CssClassComponent)},
+  ],
+})
+export class CssClassComponent implements ControlValueAccessor {
+
+  private _cvaChangeFn: (cssClasses: string | string[] | undefined) => void = noop;
+  private _cvaTouchedFn: () => void = noop;
+
+  protected formControl = this._formBuilder.control<string>('');
+
+  constructor(private _formBuilder: NonNullableFormBuilder) {
+    this.formControl.valueChanges
+      .pipe(takeUntilDestroyed())
+      .subscribe(() => {
+        this._cvaChangeFn(this.parse(this.formControl.value));
+        this._cvaTouchedFn();
+      });
+  }
+
+  private parse(stringified: string): string[] | string | undefined {
+    const cssClasses = stringified.split(/\s+/).filter(Boolean);
+    switch (cssClasses.length) {
+      case 0:
+        return undefined;
+      case 1:
+        return cssClasses[0];
+      default:
+        return cssClasses;
+    }
+  }
+
+  private stringify(cssClasses: string | string[] | undefined | null): string {
+    return Arrays.coerce(cssClasses).join(' ');
+  }
+
+  /**
+   * Method implemented as part of `ControlValueAccessor` to work with Angular forms API
+   * @docs-private
+   */
+  public writeValue(cssClasses: string | string[] | undefined | null): void {
+    this.formControl.setValue(this.stringify(cssClasses), {emitEvent: false});
+  }
+
+  /**
+   * Method implemented as part of `ControlValueAccessor` to work with Angular forms API
+   * @docs-private
+   */
+  public registerOnChange(fn: any): void {
+    this._cvaChangeFn = fn;
+  }
+
+  /**
+   * Method implemented as part of `ControlValueAccessor` to work with Angular forms API
+   * @docs-private
+   */
+  public registerOnTouched(fn: any): void {
+    this._cvaTouchedFn = fn;
+  }
+}

apps/workbench-client-testing-app/src/app/dialog-opener-page/dialog-opener-page.component.html

@@ -27,7 +27,7 @@
     </sci-form-field>
 
     <sci-form-field label="CSS Class(es)">
-      <input [formControl]="form.controls.options.controls.cssClass" class="e2e-class" placeholder="Separate multiple CSS classes by space">
+      <app-css-class [formControl]="form.controls.options.controls.cssClass"/>
     </sci-form-field>
   </section>
 </form>

apps/workbench-client-testing-app/src/app/dialog-opener-page/dialog-opener-page.component.ts

@@ -10,13 +10,14 @@
 
 import {Component} from '@angular/core';
 import {FormGroup, NonNullableFormBuilder, ReactiveFormsModule, Validators} from '@angular/forms';
-import {WorkbenchDialogService, WorkbenchView} from '@scion/workbench-client';
+import {WorkbenchDialogService, WorkbenchView, ViewId} from '@scion/workbench-client';
 import {stringifyError} from '../common/stringify-error.util';
 import {SciFormFieldComponent} from '@scion/components.internal/form-field';
 import {KeyValueEntry, SciKeyValueFieldComponent} from '@scion/components.internal/key-value-field';
 import {SciCheckboxComponent} from '@scion/components.internal/checkbox';
 import {startWith} from 'rxjs/operators';
 import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
+import {CssClassComponent} from '../css-class/css-class.component';
 
 @Component({
   selector: 'app-dialog-opener-page',
@@ -28,6 +29,7 @@ import {takeUntilDestroyed} from '@angular/core/rxjs-interop';
     SciFormFieldComponent,
     SciKeyValueFieldComponent,
     SciCheckboxComponent,
+    CssClassComponent,
   ],
 })
 export default class DialogOpenerPageComponent {
@@ -46,9 +48,9 @@ export default class DialogOpenerPageComponent {
     options: this._formBuilder.group({
       params: this._formBuilder.array<FormGroup<KeyValueEntry>>([]),
       modality: this._formBuilder.control<'application' | 'view' | ''>(''),
-      contextualViewId: this._formBuilder.control(''),
+      contextualViewId: this._formBuilder.control<ViewId | ''>(''),
       animate: this._formBuilder.control(undefined),
-      cssClass: this._formBuilder.control(''),
+      cssClass: this._formBuilder.control<string | string[] | undefined>(undefined),
     }),
   });
 
@@ -76,7 +78,7 @@ export default class DialogOpenerPageComponent {
       context: {
         viewId: this.form.controls.options.controls.contextualViewId.value || undefined,
       },
-      cssClass: this.form.controls.options.controls.cssClass.value.split(/\s+/).filter(Boolean),
+      cssClass: this.form.controls.options.controls.cssClass.value,
     })
       .then(result => this.returnValue = result)
       .catch(error => this.dialogError = stringifyError(error) || 'Dialog was closed with an error');

apps/workbench-client-testing-app/src/app/message-box-opener-page/message-box-opener-page.component.html

@@ -44,7 +44,7 @@
     </sci-form-field>
 
     <sci-form-field label="CSS Class(es)">
-      <input [formControl]="form.controls.cssClass" class="e2e-class" placeholder="Separate multiple CSS classes by space">
+      <app-css-class [formControl]="form.controls.cssClass"/>
     </sci-form-field>
   </section>
 

apps/workbench-client-testing-app/src/app/message-box-opener-page/message-box-opener-page.component.ts

@@ -17,6 +17,7 @@ import {SciFormFieldComponent} from '@scion/components.internal/form-field';
 import {NgIf} from '@angular/common';
 import {stringifyError} from '../common/stringify-error.util';
 import {SciCheckboxComponent} from '@scion/components.internal/checkbox';
+import {CssClassComponent} from '../css-class/css-class.component';
 
 @Component({
   selector: 'app-message-box-opener-page',
@@ -29,6 +30,7 @@ import {SciCheckboxComponent} from '@scion/components.internal/checkbox';
     SciFormFieldComponent,
     SciKeyValueFieldComponent,
     SciCheckboxComponent,
+    CssClassComponent,
   ],
 })
 export default class MessageBoxOpenerPageComponent {
@@ -42,7 +44,7 @@ export default class MessageBoxOpenerPageComponent {
     severity: this._formBuilder.control<'info' | 'warn' | 'error' | ''>(''),
     modality: this._formBuilder.control<'application' | 'view' | ''>(''),
     contentSelectable: this._formBuilder.control(true),
-    cssClass: this._formBuilder.control(''),
+    cssClass: this._formBuilder.control<string | string[] | undefined>(undefined),
     viewContext: this._formBuilder.control(true),
   });
 
@@ -76,7 +78,7 @@ export default class MessageBoxOpenerPageComponent {
         severity: this.form.controls.severity.value || undefined,
         modality: this.form.controls.modality.value || undefined,
         contentSelectable: this.form.controls.contentSelectable.value || undefined,
-        cssClass: this.form.controls.cssClass.value.split(/\s+/).filter(Boolean),
+        cssClass: this.form.controls.cssClass.value,
       }, qualifier ?? undefined)
         .then(closeAction => this.closeAction = closeAction)
         .catch(error => this.openError = stringifyError(error));

apps/workbench-client-testing-app/src/app/notification-opener-page/notification-opener-page.component.html

@@ -43,7 +43,7 @@
     </sci-form-field>
 
     <sci-form-field label="CSS Class(es)">
-      <input [formControl]="form.controls.cssClass" class="e2e-class" placeholder="Separate multiple CSS classes by space">
+      <app-css-class [formControl]="form.controls.cssClass"/>
     </sci-form-field>
   </section>
 </form>