ENG-40660 - Support Transitional Navigation (#231)

Adds support for conditionally enabled routes within a route hierarchy.
Routes that are disabled cannot be activated or made visible, and their
children are ignored.

Author: mcnielsen

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@al/core",
-  "version": "1.0.188",
+  "version": "1.0.189",
   "description": "Node Enterprise Packages for Alert Logic (NEPAL) Core Library",
   "main": "./dist/index.cjs.js",
   "types": "./dist/index.d.ts",

src/common/errors/al-error.types.ts

@@ -24,11 +24,13 @@ export class AlBaseError extends Error
      * this error.
      */
     public origin?:any;
+    public details?:any;
 
-    constructor( message?:string, derivedFrom?:any ) {
+    constructor( message?:string, derivedFrom?:any, details?:any ) {
         const trueProto = new.target.prototype;
         super(message);
         this.origin = derivedFrom;
+        this.details = details;
 
         this.__proto__ = trueProto;
     }
@@ -243,9 +245,9 @@ export class AlNotFoundError extends AlBaseError
  * @param inner - the underly error
  */
 export class AlWrappedError extends AlBaseError {
-    constructor( message:string, inner:any ) {
+    constructor( message:string, inner:any, details?:any ) {
         /* istanbul ignore next */
-        super( message, inner );
+        super( message, inner, details );
     }
 
     public getInnerError():any {

src/common/navigation/al-navigation.types.ts

@@ -49,6 +49,11 @@ export interface AlExperienceMapping
      */
     trigger:AlRouteCondition|AlRouteCondition[]|boolean;
 
+    /**
+     * If present and true, indicates the user can opt in or out of this experience, and their opt-in status should be "sticky."
+     */
+    optional?:boolean;
+
     /**
      * If provided, defines the zero state to provide when an experience isn't available.
      */

src/common/navigation/al-route.types.ts

@@ -171,9 +171,13 @@ export interface AlRouteDefinition {
     /* The caption of the menu item */
     caption:string;
 
-    /* An arbitrary id associated with this menu item.  This is most useful (practically) for retrieving specific menu items by code. */
+    /* An arbitrary identifier associated with this menu item.  This is most useful (practically) for retrieving specific menu items by code. */
     id?:string;
 
+    /* An arbitrary name associated with this menu item.  These augment named routes for conditional schema branches.  And if that sounds vaguely
+    * gibberishy -- (wasntme) */
+    name?:string;
+
     /* An arbitrary bookmark code for this menu item.  This allows a specific submenu to be retrieved and worked with programmatically. */
     bookmarkId?:string;
 
@@ -184,6 +188,10 @@ export interface AlRouteDefinition {
      * If the provided value is a string, it will be treated as a reference to a named route in the current schema. */
     action?:AlRouteAction|string;
 
+    /* A condition that can be evaluated to calculated the `enabled` property at any given moment.
+     * This can be a fixed boolean value, a shared condition ID (see AlNavigationSchema.conditions), or a condition literal. */
+    enabled?:AlRouteCondition|string|boolean;
+
     /* A condition that can be evaluated to calculate the `visible` property at any given moment.
      * This can be a fixed boolean value, a shared condition ID (see AlNavigationSchema.conditions), or a condition literal. */
     visible?:AlRouteCondition|string|boolean;
@@ -248,7 +256,7 @@ export class AlRoute {
     /* Is the menu item visible? */
     visible:boolean = true;
 
-    /* Is the menu item enabled?  This is provided for use by custom menu implementations, and no managed by this module. */
+    /* Is the menu item enabled?  Disabled menu items and their children will not be considered for activation. */
     enabled:boolean = true;
 
     /* Is the menu item locked?  This prevents refresh cycles from changing its state. */
@@ -374,6 +382,15 @@ export class AlRoute {
             return;
         }
 
+        if ( this.definition.enabled ) {
+            this.enabled = this.evaluateCondition( this.definition.enabled );
+            if ( ! this.enabled ) {
+                this.visible = false;
+                //  This item and its family tree are disabled, and thus not considered for visibility or activation.
+                return;
+            }
+        }
+
         state.depth++;
 
         /* Evaluate visibility */
@@ -728,7 +745,29 @@ export class AlRoute {
         return child || null;
     }
 
-
+    /**
+     * Generic method for recursing a menu hierarchy, using a callback to match the route.
+     *
+     * @param callback is a method that accepts a route (and optionally its definition) and returns
+     *          `true` if the route is the correct one, in which case it is the result of the search method.
+     *          `false` if the route is incorrect but its children should be iterated.
+     *          `null` if the route is incorrect and its children should be ignored
+     */
+    search( matcher:{(route:AlRoute, definition?:AlRouteDefinition):boolean}, enabledOnly:boolean = true ):AlRoute|undefined {
+        if ( this.enabled !== enabledOnly ) {
+            return;
+        }
+        if ( matcher( this, this.definition ) ) {
+            return this;
+        } else {
+            for ( let i = 0; i < this.children.length; i++ ) {
+                let target = this.children[i].search( matcher, enabledOnly );
+                if ( target ) {
+                    return target;
+                }
+            }
+        }
+    }
 
     /**
      * This method will return the deepest activated, childless route within its first activated child.  If this sounds obtuse,

src/common/utility/al-trigger.types.ts

@@ -76,7 +76,7 @@ export class AlTriggeredEvent<ResponseType=any>
  *
  * Callback type for triggered events.
  */
-export declare type AlTriggeredEventCallback<EventType> = {(event:EventType):void|boolean};
+export declare type AlTriggeredEventCallback<EventType> = {(event:EventType):void|boolean|Promise<void>};
 
 /**
  * @public