feat(tour): implement a guided tour module (#801)

- [x] implement a simple guided tour module for use with components;

.eslint/.eslintrc.module-boundaries.client.js

@@ -36,6 +36,10 @@ exports.constraints = [
     onlyDependOnLibsWithTags: [],
     sourceTag: 'scope:client-material',
   },
+  {
+    onlyDependOnLibsWithTags: [],
+    sourceTag: 'scope:client-guided-tour',
+  },
   {
     onlyDependOnLibsWithTags: [],
     sourceTag: 'scope:client-pwa-offline',
@@ -221,6 +225,7 @@ exports.constraints = [
       'scope:client-diagnostics',
       'scope:client-gql',
       'scope:client-grpc',
+      'scope:client-guided-tour',
       'scope:client-material',
       'scope:client-pwa-offline',
       'scope:client-service-worker',

.github/workflows/publish-packages.yml

@@ -63,6 +63,28 @@ jobs:
           library-name: client-d3-charts
           npm-automation-token: ${{ secrets.NPM_AUTOMATION_TOKEN }}
 
+  publish-client-guided-tour:
+    needs: checks
+    if: ${{ needs.checks.outputs.origin == 'true' && fromJSON(needs.checks.outputs.changes).packageGuidedTour == 'true' }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v3
+
+      - name: Setup environment
+        uses: ./.github/actions/setup-environment
+        with:
+          compodoc: false
+          cypress: false
+          firebase-tools: false
+
+      - name: NPM publish
+        uses: ./.github/actions/npm-publish
+        with:
+          library-name: client-guided-tour
+          npm-automation-token: ${{ secrets.NPM_AUTOMATION_TOKEN }}
+
   publish-client-pwa-offline:
     needs: checks
     if: ${{ needs.checks.outputs.origin == 'true' && fromJSON(needs.checks.outputs.changes).packagePwaOffline == 'true' }}

README.md

@@ -106,7 +106,7 @@ npx nx generate client-feature client-<feature-name> --tags=scope:client-<featur
 #### `ui` library
 
 ```bash
-npx nx generate client-ui client-ui-<feature-name> --tags=scope:client-ui-<feature-name>,type:ui
+npx nx generate client-ui client-<feature-name> --tags=scope:client-<feature-name>,type:ui
 ```
 
 #### `data-access` library

apps/client/src/app/client-routing.module.ts

@@ -24,6 +24,11 @@ export const routes: Route[] = [
     data: { feature: 'chatbot', icon: 'chat' },
     loadChildren: () => import('@app/client-chatbot').then(mod => mod.AppChatbotModule),
   },
+  {
+    path: 'guided-tour',
+    data: { feature: 'guided-tour', icon: 'tour' },
+    loadChildren: () => import('@app/client-guided-tour').then(mod => mod.AppGuidedTourExampleModule),
+  },
   {
     path: '',
     outlet: 'sidebar',

libs/client-dashboards/src/lib/dashboards.module.ts

@@ -19,8 +19,8 @@ import { AppTableControlsModule } from './modules/table-controls/table-controls.
     MatButtonModule,
     MatIconModule,
     AppTableControlsModule,
-    AppDashboardsRoutingModule,
     AppDirectivesModule,
+    AppDashboardsRoutingModule,
   ],
   declarations: [AppDashboardsComponent, AppTableComponent],
 })

libs/client-guided-tour/.eslintrc.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../.eslintrc.js", "../../.eslintrc.angular.js"],
+  "ignorePatterns": ["!**/*"]
+}

libs/client-guided-tour/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 rfprod.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

libs/client-guided-tour/README.md

@@ -0,0 +1,117 @@
+# Guided Tour Module for Angular
+
+Guided tour feature for Angular clients.
+
+## Description
+
+TBD
+
+## Usage
+
+### Within the development workspace
+
+Import the module
+
+```typescript
+...
+import { AppGuidedTourModule } from '@app/client-guided-tour';
+
+@NgModule({
+  imports: [
+    ...
+    AppGuidedTourModule,
+    ...
+  ],
+  ...
+})
+export class AppModule {}
+```
+
+### As an external package
+
+Install the package
+
+```bash
+yarn add @rfprodz/client-guided-tour @angular/cdk @angular/common @angular/core @angular/material
+```
+
+Import the module
+
+```typescript
+...
+import { AppGuidedTourModule } from '@rfprodz/client-guided-tour';
+
+@NgModule({
+  imports: [
+    ...
+    AppGuidedTourModule,
+    ...
+  ],
+  ...
+})
+export class AppModule {}
+```
+
+Use in components
+
+```html
+...
+<p>... Some content ...</p>
+
+<div [appGuidedTour]="config.at(0)" [highlightElement]="false">first item to explain</div>
+
+<p>... Some content ...</p>
+
+<div [appGuidedTour]="config.at(1)" [highlightElement]="true">second item to explain</div>
+...
+```
+
+```typescript
+@Component({
+  ...
+  providers: [AppGuidedTourService], // <-- declare a service
+  ...
+})
+export class GuidedComponent implements AfterViewInit {
+  /** Locate steps. */
+  @ViewChildren(AppGuidedTourDirective) public steps!: QueryList<AppGuidedTourDirective>;
+
+  /** Configure the tour. */
+  public tourConig$ = signal<IGuidedTourData[]>([
+    {
+      index: 0,
+      title: 'first',
+      subtitle: 'First step',
+      description: 'The first step. Highlighting disabled.',
+      first: true,
+      last: false,
+    },
+    {
+      index: 1,
+      title: 'second',
+      subtitle: 'Second step',
+      description: 'The second step. Highlighting enabled.',
+      first: false,
+      last: true,
+    },
+  ]);
+
+  constructor(public readonly tour: AppGuidedTourService) {}
+
+  public ngAfterViewInit(): void {
+    this.tour.configuration = this.steps; // <-- add steps to the service
+  }
+}
+```
+
+## Developer commands reference
+
+```bash
+npx nx run tools:help --search client-guided-tour:
+```
+
+## References
+
+- [Nx](https://nx.dev)
+- [Angular](https://angular.io)
+- [Angular Material](https://material.angular.io)

libs/client-guided-tour/jest.config.ts

@@ -0,0 +1,22 @@
+import { Config } from '@jest/types';
+
+const jestPresetAngularSerializers = require('jest-preset-angular/build/serializers');
+
+const config: Config.InitialOptions = {
+  coverageDirectory: '../../coverage/libs/client-guided-tour',
+  coverageThreshold: {
+    // TODO: bump unit test coverage and remove this override
+    global: {
+      branches: 0,
+      functions: 27,
+      lines: 32,
+      statements: 35,
+    },
+  },
+  displayName: 'client-guided-tour',
+  preset: '../../jest.preset.js',
+  setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
+  snapshotSerializers: jestPresetAngularSerializers,
+};
+
+export default config;

libs/client-guided-tour/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "../../dist/libs/client-guided-tour",
+  "lib": {
+    "entryFile": "src/index.ts"
+  }
+}

libs/client-guided-tour/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@rfprodz/client-guided-tour",
+  "version": "1.0.0",
+  "description": "Guided tour feature for Angular clients.",
+  "keywords": [
+    "angular-module",
+    "angular-directive",
+    "angular-component",
+    "angular-service"
+  ],
+  "homepage": "https://github.com/rfprod/nx-ng-starter",
+  "bugs": {
+    "url": "https://github.com/rfprod/nx-ng-starter/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rfprod/nx-ng-starter"
+  },
+  "license": "MIT",
+  "author": "rfprod <[email protected]>",
+  "dependencies": {
+    "tslib": "2.6.2"
+  },
+  "peerDependencies": {
+    "@angular/cdk": "17.0.3",
+    "@angular/common": "17.0.6",
+    "@angular/core": "17.0.6",
+    "@angular/material": "17.0.3",
+    "@angular/router": "17.0.6"
+  }
+}

libs/client-guided-tour/project.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "name": "client-guided-tour",
+  "prefix": "app",
+  "projectType": "library",
+  "sourceRoot": "libs/client-guided-tour/src",
+  "tags": ["scope:client-guided-tour", "type:ui"],
+  "targets": {
+    "build": {
+      "configurations": {
+        "development": {
+          "tsConfig": "libs/client-guided-tour/tsconfig.lib.json"
+        },
+        "production": {
+          "tsConfig": "libs/client-guided-tour/tsconfig.lib.prod.json"
+        }
+      },
+      "defaultConfiguration": "production",
+      "executor": "@angular-devkit/build-angular:ng-packagr",
+      "options": {
+        "project": "libs/client-guided-tour/ng-package.json"
+      },
+      "outputs": ["{workspaceRoot}/dist/libs/client-guided-tour"]
+    },
+    "lint": {
+      "executor": "@angular-eslint/builder:lint",
+      "options": {
+        "eslintConfig": "libs/client-guided-tour/.eslintrc.json",
+        "lintFilePatterns": ["libs/client-guided-tour/**/*.ts"]
+      },
+      "outputs": ["{options.outputFile}"]
+    },
+    "prettier-check": {
+      "executor": "./tools/executors/prettier:check",
+      "options": {
+        "config": ""
+      },
+      "outputs": ["{workspaceRoot}/dist/prettier/libs/client-guided-tour"]
+    },
+    "stylelint-check": {
+      "executor": "./tools/executors/stylelint:check",
+      "options": {
+        "config": ""
+      },
+      "outputs": ["{workspaceRoot}/dist/stylelint/libs/client-guided-tour"]
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "options": {
+        "jestConfig": "libs/client-guided-tour/jest.config.ts"
+      },
+      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"]
+    },
+    "tsc-check": {
+      "executor": "./tools/executors/tsc:check",
+      "options": {
+        "tsConfig": "libs/client-guided-tour/tsconfig.lib.json"
+      },
+      "outputs": ["{workspaceRoot}/dist/out-tsc/libs/client-guided-tour"]
+    }
+  }
+}

libs/client-guided-tour/src/index.ts

@@ -0,0 +1,4 @@
+export * from './lib/components';
+export * from './lib/guided-tour.module';
+export * from './lib/guided-tour-example.module';
+export * from './lib/services';

libs/client-guided-tour/src/lib/components/guided-tour-example/guided-tour-example.component.html

@@ -0,0 +1,21 @@
+<p>... Some content ...</p>
+
+<ng-container *ngIf="tourConig$() as config">
+  <div [appGuidedTour]="config.at(1)" [highlightElement]="true">second item to explain</div>
+
+  <p>... Some content ...</p>
+
+  <div [appGuidedTour]="config.at(2)" [highlightElement]="true">third item to explain</div>
+
+  <p>... Some content ...</p>
+
+  <div [appGuidedTour]="config.at(0)">first item to explain</div>
+</ng-container>
+
+<p>... Some content ...</p>
+
+@if (!tour.active) {
+  <button mat-raised-button color="accent" (click)="tour.next()">Start tour</button>
+} @else {
+  <button mat-raised-button color="warn" (click)="tour.end()">End tour</button>
+}

libs/client-guided-tour/src/lib/components/guided-tour-example/guided-tour-example.component.scss

@@ -0,0 +1,4 @@
+:host {
+  display: block;
+  padding: 16px;
+}