@hmcts/opal-frontend-common 0.0.36 → 0.0.37

package/fesm2022/hmcts-opal-frontend-common-guards-has-url-state-match.mjs

@@ -0,0 +1,51 @@
+import { inject } from '@angular/core';
+import { Router } from '@angular/router';
+
+/**
+ * Creates a route guard that checks whether the current URL state matches specific conditions.
+ *
+ * This function returns a CanActivate guard function that performs the following steps:
+ * 1. Retrieves the current state using the provided getState function.
+ * 2. Checks the route using the checkRoute function.
+ * 3. Evaluates the state and route using the checkCondition function.
+ * 4. If the route or condition check fails, it redirects to a URL created by the getNavigationPath function
+ *    while preserving query parameters and the URL fragment.
+ *
+ * @typeParam T The type of the state returned by getState.
+ *
+ * @param getState - A function that returns the current state.
+ * @param hasRouteParams - A function that receives an ActivatedRouteSnapshot and returns a boolean indicating whether the route meets certain criteria.
+ * @param checkCondition - A function that evaluates whether the current state satisfies the necessary condition based on the ActivatedRouteSnapshot.
+ * @param getNavigationPath - A function that receives an ActivatedRouteSnapshot and returns the navigation path as a string for redirection.
+ *
+ * @returns A function implementing the CanActivate guard that returns `true` if the route and state meet the required conditions,
+ *          or a UrlTree for redirection if they do not.
+ */
+function hasUrlStateMatchGuard(getState, hasRouteParams, checkCondition, getNavigationPath) {
+    return (route) => {
+        const router = inject(Router);
+        const state = getState();
+        const { queryParams, fragment } = route;
+        const createRedirectUrlTree = () => {
+            const hasQueryParams = Object.keys(queryParams || {}).length > 0;
+            return router.createUrlTree([getNavigationPath(route)], {
+                queryParams: hasQueryParams ? queryParams : undefined,
+                fragment: fragment ?? undefined,
+            });
+        };
+        if (!hasRouteParams(route)) {
+            return createRedirectUrlTree();
+        }
+        if (!checkCondition(state, route)) {
+            return createRedirectUrlTree();
+        }
+        return true;
+    };
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { hasUrlStateMatchGuard };
+//# sourceMappingURL=hmcts-opal-frontend-common-guards-has-url-state-match.mjs.map

package/fesm2022/hmcts-opal-frontend-common-guards-has-url-state-match.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hmcts-opal-frontend-common-guards-has-url-state-match.mjs","sources":["../../../projects/opal-frontend-common/guards/has-url-state-match/has-url-state-match.guard.ts","../../../projects/opal-frontend-common/guards/has-url-state-match/hmcts-opal-frontend-common-guards-has-url-state-match.ts"],"sourcesContent":["import { inject } from '@angular/core';\nimport { ActivatedRouteSnapshot, CanActivateFn, Router } from '@angular/router';\n\n/**\n * Creates a route guard that checks whether the current URL state matches specific conditions.\n *\n * This function returns a CanActivate guard function that performs the following steps:\n * 1. Retrieves the current state using the provided getState function.\n * 2. Checks the route using the checkRoute function.\n * 3. Evaluates the state and route using the checkCondition function.\n * 4. If the route or condition check fails, it redirects to a URL created by the getNavigationPath function\n *    while preserving query parameters and the URL fragment.\n *\n * @typeParam T The type of the state returned by getState.\n *\n * @param getState - A function that returns the current state.\n * @param hasRouteParams - A function that receives an ActivatedRouteSnapshot and returns a boolean indicating whether the route meets certain criteria.\n * @param checkCondition - A function that evaluates whether the current state satisfies the necessary condition based on the ActivatedRouteSnapshot.\n * @param getNavigationPath - A function that receives an ActivatedRouteSnapshot and returns the navigation path as a string for redirection.\n *\n * @returns A function implementing the CanActivate guard that returns `true` if the route and state meet the required conditions,\n *          or a UrlTree for redirection if they do not.\n */\nexport function hasUrlStateMatchGuard<T>(\n  getState: () => T,\n  hasRouteParams: (route: ActivatedRouteSnapshot) => boolean,\n  checkCondition: (state: T, route: ActivatedRouteSnapshot) => boolean,\n  getNavigationPath: (route: ActivatedRouteSnapshot) => string,\n): CanActivateFn {\n  return (route: ActivatedRouteSnapshot) => {\n    const router = inject(Router);\n    const state = getState();\n    const { queryParams, fragment } = route;\n\n    const createRedirectUrlTree = () => {\n      const hasQueryParams = Object.keys(queryParams || {}).length > 0;\n      return router.createUrlTree([getNavigationPath(route)], {\n        queryParams: hasQueryParams ? queryParams : undefined,\n        fragment: fragment ?? undefined,\n      });\n    };\n\n    if (!hasRouteParams(route)) {\n      return createRedirectUrlTree();\n    }\n\n    if (!checkCondition(state, route)) {\n      return createRedirectUrlTree();\n    }\n\n    return true;\n  };\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './public-api';\n"],"names":[],"mappings":";;;AAGA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,qBAAqB,CACnC,QAAiB,EACjB,cAA0D,EAC1D,cAAoE,EACpE,iBAA4D,EAAA;IAE5D,OAAO,CAAC,KAA6B,KAAI;AACvC,QAAA,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;AAC7B,QAAA,MAAM,KAAK,GAAG,QAAQ,EAAE;AACxB,QAAA,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,GAAG,KAAK;QAEvC,MAAM,qBAAqB,GAAG,MAAK;AACjC,YAAA,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC;YAChE,OAAO,MAAM,CAAC,aAAa,CAAC,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE;gBACtD,WAAW,EAAE,cAAc,GAAG,WAAW,GAAG,SAAS;gBACrD,QAAQ,EAAE,QAAQ,IAAI,SAAS;AAChC,aAAA,CAAC;AACJ,QAAA,CAAC;AAED,QAAA,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE;YAC1B,OAAO,qBAAqB,EAAE;QAChC;QAEA,IAAI,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE;YACjC,OAAO,qBAAqB,EAAE;QAChC;AAEA,QAAA,OAAO,IAAI;AACb,IAAA,CAAC;AACH;;ACpDA;;AAEG;;;;"}

package/guards/has-url-state-match/README.md

@@ -0,0 +1,160 @@
+# Has URL State Match Guard
+
+This Angular guard validates URLs and application state, redirecting when either the URL format is invalid or when the state doesn't match the URL parameters. The guard performs two main checks:
+
+1. **URL Validation**: Ensures the URL structure is canonical/valid
+2. **State Validation**: Verifies that the application state matches the URL parameters
+
+If either check fails, the guard redirects to a specified path while preserving query parameters and fragments.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Selector](#selector)
+- [Usage](#usage)
+- [Inputs](#inputs)
+- [Outputs](#outputs)
+- [Methods](#methods)
+- [Testing](#testing)
+- [Contributing](#contributing)
+
+## Installation
+
+```typescript
+import { hasUrlStateMatchGuard } from '@hmcts/opal-frontend-common/guards/has-url-state-match';
+```
+
+Ensure the guard is imported in your route configuration:
+
+```typescript
+import { hasUrlStateMatchGuard } from '@hmcts/opal-frontend-common/guards/has-url-state-match';
+
+const routes: Routes = [
+  {
+    path: 'account/:accountNumber/summary',
+    component: AccountSummaryComponent,
+    canActivate: [yourGuardInstance],
+  },
+];
+```
+
+## Selector
+
+Use this guard factory function to create route guards.
+
+hasUrlStateMatchGuard
+
+## Usage
+
+The guard performs validation in the following order:
+
+1. **URL Validation**: Calls `hasRouteParams(route)` to check if the URL format is valid
+   - If `false`, redirects immediately
+   - If `true`, proceeds to state validation
+
+2. **State Validation**: Calls `checkCondition(state, route)` to validate state against URL
+   - If `false`, redirects
+   - If `true`, allows access
+
+3. **Query Parameters & Fragments**: When redirecting, preserves existing query parameters and fragments
+
+You can create a guard instance by calling the factory function:
+
+```typescript
+export const accountValidationGuard = hasUrlStateMatchGuard(
+  () => accountService.getState(),
+  (route) => !!route.params['accountNumber'], // Returns true if URL is canonical/valid
+  (state, route) => state.selectedAccount?.accountNumber === route.params['accountNumber'],
+  (route) => `/account/${route.params['accountNumber']}/details`,
+);
+```
+
+### Advanced Example
+
+```typescript
+export const userAccountGuard = hasUrlStateMatchGuard(
+  // Get current state
+  () => authService.getCurrentUserState(),
+
+  // Check if URL format is valid (has required parameters)
+  (route) => {
+    const accountId = route.params['accountId'];
+    const userId = route.queryParams['userId'];
+    return !!(accountId && userId && accountId.match(/^\d+$/));
+  },
+
+  // Validate state matches URL parameters
+  (state, route) => {
+    if (!state.user || !state.selectedAccount) return false;
+    return state.user.id === route.queryParams['userId'] && state.selectedAccount.id === route.params['accountId'];
+  },
+
+  // Redirect path when validation fails
+  (route) => '/dashboard',
+);
+```
+
+## Inputs
+
+| Input               | Type                                                   | Description                                                             |
+| ------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| `getState`          | `() => T`                                              | Function that returns the current application state                     |
+| `hasRouteParams`    | `(route: ActivatedRouteSnapshot) => boolean`           | Function that checks if the route params valid (return `true` if valid) |
+| `checkCondition`    | `(state: T, route: ActivatedRouteSnapshot) => boolean` | Function that validates state against route (return `true` if valid)    |
+| `getNavigationPath` | `(route: ActivatedRouteSnapshot) => string`            | Function that returns the redirect path when validation fails           |
+
+Example usage of inputs:
+
+```typescript
+export const userContextGuard = hasUrlStateMatchGuard(
+  () => userService.getCurrentUser(),
+  (route) => !!route.queryParams['userId'], // Returns true if URL contains required userId
+  (state, route) => state?.id === route.queryParams['userId'],
+  () => '/login',
+);
+```
+
+## Outputs
+
+| Output          | Type                 | Description                                                       |
+| --------------- | -------------------- | ----------------------------------------------------------------- |
+| `CanActivateFn` | `boolean \| UrlTree` | Returns `true` if access is allowed, or `UrlTree` for redirection |
+
+Example of using the output in routes:
+
+```typescript
+const routes: Routes = [
+  {
+    path: 'account/:accountNumber/summary',
+    component: AccountSummaryComponent,
+    canActivate: [accountValidationGuard],
+  },
+];
+```
+
+## Methods
+
+There are no custom methods for this guard. It returns a `CanActivateFn` that follows Angular's route guard pattern.
+
+### Error Handling
+
+The guard does not catch errors thrown by the provided functions. If any of the callback functions (`getState`, `isCanonicalUrl`, `checkCondition`, or `getNavigationPath`) throw an error, it will bubble up and should be handled by your application's error handling mechanisms.
+
+### Query Parameters and Fragments
+
+When redirecting, the guard:
+
+- Preserves existing query parameters (only if they exist and are non-empty)
+- Preserves URL fragments
+- Passes both to the redirect URL
+
+## Testing
+
+```bash
+yarn test
+```
+
+## Contributing
+
+Feel free to submit issues or pull requests to improve this guard.
+If you encounter any bugs or missing functionality, please raise an issue.

package/guards/has-url-state-match/index.d.ts

@@ -0,0 +1,25 @@
+import { ActivatedRouteSnapshot, CanActivateFn } from '@angular/router';
+
+/**
+ * Creates a route guard that checks whether the current URL state matches specific conditions.
+ *
+ * This function returns a CanActivate guard function that performs the following steps:
+ * 1. Retrieves the current state using the provided getState function.
+ * 2. Checks the route using the checkRoute function.
+ * 3. Evaluates the state and route using the checkCondition function.
+ * 4. If the route or condition check fails, it redirects to a URL created by the getNavigationPath function
+ *    while preserving query parameters and the URL fragment.
+ *
+ * @typeParam T The type of the state returned by getState.
+ *
+ * @param getState - A function that returns the current state.
+ * @param hasRouteParams - A function that receives an ActivatedRouteSnapshot and returns a boolean indicating whether the route meets certain criteria.
+ * @param checkCondition - A function that evaluates whether the current state satisfies the necessary condition based on the ActivatedRouteSnapshot.
+ * @param getNavigationPath - A function that receives an ActivatedRouteSnapshot and returns the navigation path as a string for redirection.
+ *
+ * @returns A function implementing the CanActivate guard that returns `true` if the route and state meet the required conditions,
+ *          or a UrlTree for redirection if they do not.
+ */
+declare function hasUrlStateMatchGuard<T>(getState: () => T, hasRouteParams: (route: ActivatedRouteSnapshot) => boolean, checkCondition: (state: T, route: ActivatedRouteSnapshot) => boolean, getNavigationPath: (route: ActivatedRouteSnapshot) => string): CanActivateFn;
+
+export { hasUrlStateMatchGuard };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmcts/opal-frontend-common",
-  "version": "0.0.36",
+  "version": "0.0.37",
   "license": "MIT",
   "peerDependencies": {
     "@angular/common": "^18.2.0 || ^19.0.0 || ^20.0.0",
@@ -547,6 +547,11 @@
       "types": "./guards/has-flow-state/index.d.ts",
       "default": "./fesm2022/hmcts-opal-frontend-common-guards-has-flow-state.mjs"
     },
+    "./guards/has-url-state-match": {
+      "import": "./fesm2022/hmcts-opal-frontend-common-guards-has-url-state-match.mjs",
+      "types": "./guards/has-url-state-match/index.d.ts",
+      "default": "./fesm2022/hmcts-opal-frontend-common-guards-has-url-state-match.mjs"
+    },
     "./guards/helpers": {
       "import": "./fesm2022/hmcts-opal-frontend-common-guards-helpers.mjs",
       "types": "./guards/helpers/index.d.ts",