feat(components/core): update SkyHelpService to allow for updating …

…global help and the utilization of a page default help key (#2734)
blackbaud · Sep 13, 2024 · def8123 · def8123
1 parent 01a1cc2
commit def8123
Show file tree

Hide file tree

Showing 9 changed files with 160 additions and 13 deletions.
diff --git a/apps/code-examples/src/app/code-examples/modals/modal/basic-with-controller/help.service.ts b/apps/code-examples/src/app/code-examples/modals/modal/basic-with-controller/help.service.ts
@@ -1,5 +1,9 @@
 import { Injectable } from '@angular/core';
-import { SkyHelpOpenArgs, SkyHelpService } from '@skyux/core';
+import {
+  SkyHelpOpenArgs,
+  SkyHelpService,
+  SkyHelpUpdateArgs,
+} from '@skyux/core';
 
 /**
  * This is a mock implementation of the help service. In a production scenario,
@@ -8,7 +12,19 @@ import { SkyHelpOpenArgs, SkyHelpService } from '@skyux/core';
  */
 @Injectable({ providedIn: 'root' })
 export class MyHelpService extends SkyHelpService {
-  public override openHelp(args: SkyHelpOpenArgs): void {
-    console.error(`Open help panel to key: ${args.helpKey}`);
+  public override openHelp(args?: SkyHelpOpenArgs): void {
+    if (args) {
+      console.error(`Open help panel to key: ${args.helpKey}`);
+    }
+  }
+
+  public override updateHelp(args: SkyHelpUpdateArgs): void {
+    if ('helpKey' in args) {
+      console.error(`help key update: ${args.helpKey}`);
+    }
+
+    if ('pageDefaultHelpKey' in args) {
+      console.error(`page default help key update: ${args.pageDefaultHelpKey}`);
+    }
   }
 }
diff --git a/apps/playground/src/app/components/help-inline/help-inline.component.ts b/apps/playground/src/app/components/help-inline/help-inline.component.ts
@@ -17,6 +17,10 @@ class DemoHelpService extends SkyHelpService {
   public override openHelp(): void {
     alert('Help opened!');
   }
+
+  public override updateHelp(): void {
+    alert('Help');
+  }
 }
 
 @Component({

diff --git a/apps/playground/src/app/shared/help.service.ts b/apps/playground/src/app/shared/help.service.ts
@@ -1,9 +1,25 @@
 import { Injectable } from '@angular/core';
-import { SkyHelpOpenArgs, SkyHelpService } from '@skyux/core';
+import {
+  SkyHelpOpenArgs,
+  SkyHelpService,
+  SkyHelpUpdateArgs,
+} from '@skyux/core';
 
 @Injectable()
 export class PlaygroundHelpService extends SkyHelpService {
-  public override openHelp(args: SkyHelpOpenArgs): void {
-    alert('help key: ' + args.helpKey);
+  public override openHelp(args?: SkyHelpOpenArgs): void {
+    if (args) {
+      alert('help key: ' + args.helpKey);
+    }
+  }
+
+  public override updateHelp(args: SkyHelpUpdateArgs): void {
+    if ('helpKey' in args) {
+      alert('help key update: ' + args.helpKey);
+    }
+
+    if ('pageDefaultHelpKey' in args) {
+      alert('page default help key update: ' + args.pageDefaultHelpKey);
+    }
   }
 }
diff --git a/libs/components/core/src/index.ts b/libs/components/core/src/index.ts
@@ -42,6 +42,7 @@ export { SkyAppFormat } from './lib/modules/format/app-format';
 export { SkyHelpGlobalOptions } from './lib/modules/help/help-global-options';
 export { SKY_HELP_GLOBAL_OPTIONS } from './lib/modules/help/help-global-options-token';
 export { SkyHelpOpenArgs } from './lib/modules/help/help-open-args';
+export { SkyHelpUpdateArgs } from './lib/modules/help/help-update-args';
 export { SkyHelpService } from './lib/modules/help/help.service';
 
 export { SkyIdModule } from './lib/modules/id/id.module';

diff --git a/libs/components/core/src/lib/modules/help/help-open-args.ts b/libs/components/core/src/lib/modules/help/help-open-args.ts
@@ -1,5 +1,5 @@
 /**
- * Options for displaying global help.
+ * Options for displaying a globally accessible help dialog.
  */
 export interface SkyHelpOpenArgs {
   /**

diff --git a/libs/components/core/src/lib/modules/help/help-update-args.ts b/libs/components/core/src/lib/modules/help/help-update-args.ts
@@ -0,0 +1,13 @@
+/**
+ *  Options for updating a globally accessible help dialog.
+ */
+export interface SkyHelpUpdateArgs {
+  /**
+   * A unique key that identifies the current help content to display. If set to `undefined`, the page's default help content will be displayed.
+   */
+  helpKey?: string;
+  /**
+   * A unique key that identifies the page's default help content to display. Set this property to `undefined` to unset the current page default help key.
+   * */
+  pageDefaultHelpKey?: string;
+}
diff --git a/libs/components/core/src/lib/modules/help/help.service.ts b/libs/components/core/src/lib/modules/help/help.service.ts
@@ -4,9 +4,10 @@ import { Injectable } from '@angular/core';
 import { Observable, of } from 'rxjs';
 
 import { SkyHelpOpenArgs } from './help-open-args';
+import { SkyHelpUpdateArgs } from './help-update-args';
 
 /**
- * Provides methods for opening a globally accessible help dialog.
+ * Provides methods for opening and updating a globally accessible help dialog.
  */
 @Injectable()
 export abstract class SkyHelpService {
@@ -21,5 +22,11 @@ export abstract class SkyHelpService {
    * Opens a globally accessible help dialog.
    * @param args The options for opening the help dialog.
    */
-  public abstract openHelp(args: SkyHelpOpenArgs): void;
+  public abstract openHelp(args?: SkyHelpOpenArgs): void;
+
+  /**
+   * Updates a globally accessible help dialog.
+   * @param args The options for updating the help dialog.
+   */
+  public abstract updateHelp(args: SkyHelpUpdateArgs): void;
 }
diff --git a/libs/components/core/testing/src/help/help-testing-controller.spec.ts b/libs/components/core/testing/src/help/help-testing-controller.spec.ts
@@ -25,6 +25,43 @@ describe('Help testing controller', () => {
     helpController.expectCurrentHelpKey('test');
   });
 
+  it('should validate current help key when a page default is used', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'test-page' });
+    helpSvc.openHelp();
+
+    helpController.expectCurrentHelpKey('test-page');
+  });
+
+  it('should validate current help key when a page default and open key is used', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'test-page' });
+    helpSvc.openHelp({ helpKey: 'test' });
+
+    helpController.expectCurrentHelpKey('test');
+  });
+
+  it('should validate current help key when it is updated', () => {
+    helpSvc.openHelp({ helpKey: 'test' });
+    helpSvc.updateHelp({ helpKey: 'updated-test' });
+
+    helpController.expectCurrentHelpKey('updated-test');
+  });
+
+  it('should validate current help key when it is cleared via an update', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'test-page' });
+    helpSvc.openHelp({ helpKey: 'test' });
+    helpSvc.updateHelp({ helpKey: undefined });
+
+    helpController.expectCurrentHelpKey('test-page');
+  });
+
+  it('should validate current help key when the current key and page default are cleared via an update', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'test-page' });
+    helpSvc.openHelp({ helpKey: 'test' });
+    helpSvc.updateHelp({ helpKey: undefined, pageDefaultHelpKey: undefined });
+
+    helpController.expectCurrentHelpKey(undefined);
+  });
+
   it('should throw an error when the current help key does not match the expected help key', () => {
     helpSvc.openHelp({ helpKey: 'test' });
 
@@ -53,6 +90,44 @@ describe('Help testing controller', () => {
     );
   });
 
+  it('should close help with a page default', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'page-test' });
+    helpSvc.openHelp({ helpKey: 'test' });
+
+    helpController.expectCurrentHelpKey('test');
+
+    helpController.closeHelp();
+
+    helpController.expectCurrentHelpKey('page-test');
+
+    expect(() => helpController.expectCurrentHelpKey('test')).toThrowError(
+      `Expected current help key to be 'test', but the current help key is 'page-test'.`,
+    );
+  });
+
+  it('should close help and reopen with a page default', () => {
+    helpSvc.updateHelp({ pageDefaultHelpKey: 'page-test' });
+    helpSvc.openHelp({ helpKey: 'test' });
+
+    helpController.expectCurrentHelpKey('test');
+
+    helpController.closeHelp();
+
+    helpController.expectCurrentHelpKey('page-test');
+
+    expect(() => helpController.expectCurrentHelpKey('test')).toThrowError(
+      `Expected current help key to be 'test', but the current help key is 'page-test'.`,
+    );
+
+    helpSvc.openHelp();
+
+    helpController.expectCurrentHelpKey('page-test');
+
+    expect(() => helpController.expectCurrentHelpKey('test')).toThrowError(
+      `Expected current help key to be 'test', but the current help key is 'page-test'.`,
+    );
+  });
+
   it('should set widget ready state to "true" on init', async () => {
     await expectAsync(
       firstValueFrom(helpSvc.widgetReadyStateChange),

diff --git a/libs/components/core/testing/src/help/help-testing.service.ts b/libs/components/core/testing/src/help/help-testing.service.ts
@@ -1,6 +1,10 @@
 import { Injectable } from '@angular/core';
 // eslint-disable-next-line @nx/enforce-module-boundaries
-import { SkyHelpOpenArgs, SkyHelpService } from '@skyux/core';
+import {
+  SkyHelpOpenArgs,
+  SkyHelpService,
+  SkyHelpUpdateArgs,
+} from '@skyux/core';
 
 import { Observable, of } from 'rxjs';
 
@@ -14,13 +18,24 @@ export class SkyHelpTestingService extends SkyHelpService {
   }
 
   #currentHelpKey: string | undefined;
+  #currentPageHelpKey: string | undefined;
 
-  public override openHelp(args: SkyHelpOpenArgs): void {
-    this.#currentHelpKey = args.helpKey;
+  public override openHelp(args?: SkyHelpOpenArgs): void {
+    this.#currentHelpKey = args?.helpKey;
+  }
+
+  public override updateHelp(args: SkyHelpUpdateArgs): void {
+    if ('pageDefaultHelpKey' in args) {
+      this.#currentPageHelpKey = args.pageDefaultHelpKey;
+    }
+
+    if ('helpKey' in args) {
+      this.#currentHelpKey = args.helpKey;
+    }
   }
 
   public getCurrentHelpKey(): string | undefined {
-    return this.#currentHelpKey;
+    return this.#currentHelpKey || this.#currentPageHelpKey;
   }
 
   public closeHelp(): void {