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.

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.

closes #445

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

Previously, no explicit navigation was required as the view and route were coupled via the route's outlet and the view's id.

**Migrate the layout as follows:**
- Navigate views added to the layout;
- Pass an empty commands array to match routes with an empty path;
- Pass a navigation hint to differentiate between routes with empty paths; you can use the same value as before for the view id;

```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; you can use the same value as before for the outlet name;

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

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

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>