@dwp/govuk-casa 8.2.1 → 8.2.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [8.2.3](https://github.com/dwp/govuk-casa/compare/8.2.2...8.2.3) (2022-05-23)
+
+### [8.2.2](https://github.com/dwp/govuk-casa/compare/8.2.1...8.2.2) (2022-05-23)
+
+
+### Bug Fixes
+
+* escape from sticky edit on return to edit origin in a proxied app ([9303af1](https://github.com/dwp/govuk-casa/commit/9303af140ec383801741d50f3404fd7cfe930d90))
+
 ### [8.2.1](https://github.com/dwp/govuk-casa/compare/8.2.0...8.2.1) (2022-05-20)
 
 

package/README.md

@@ -20,6 +20,7 @@ npm -E @dwp/govuk-casa
 ```
 
 * [Documentation](docs/index.md)
+* [API Reference](docs/api-reference.md)
 * [Examples](examples/)
 
 

package/dist/casa.d.ts

@@ -114,7 +114,7 @@ export type IPlugin = {
      */
     bootstrap?: Function | undefined;
 };
-export type PluginConfigureFunction = (con: object, : any) => any;
+export type PluginConfigureFunction = (config: object) => any;
 export type HelmetConfigurator = (config: object) => object;
 export type Mounter = (app: import('express').Express, opts: object, route?: string | undefined) => import('express').Express;
 export type MutableRouter = import('./lib/index').MutableRouter;
@@ -122,6 +122,10 @@ export type MutableRouter = import('./lib/index').MutableRouter;
  * Configuration options
  */
 export type ConfigurationOptions = {
+    /**
+     * Prefix for all URLS in browser address bar
+     */
+    mountUrl?: string | undefined;
     /**
      * Template directories
      */
@@ -208,6 +212,204 @@ export type ConfigureResult = {
      */
     mount: Mounter;
 };
+/**
+ * Configuration for generating a ValidationError.
+ * i.e. `new ValidationError(configObject)`
+ * <br/><br/>
+ *
+ * The `fieldKeySuffix` is used to differentiate errors attached to
+ * the same field name. For example, given these fields inputs ...
+ *
+ * <pre>
+ * &lt;input name="dateOfBirth[dd]" /&gt;
+ * &lt;input name="dateOfBirth[mm]" /&gt;
+ * &lt;input name="dateOfBirth[yyyy]" /&gt;
+ * </pre>
+ *
+ * If we wanted to generate an error specifically for the `dd`
+ * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
+ * config.
+ * <br/><br/>
+ *
+ * We can also use `focusSuffix` to control which properties of an
+ * object field should be highlighted with a red border when in error. Looking
+ * again at the `dateOfBirth` example above, if we did not specify
+ * any `focusSuffix`, then all three inputs would be highlighted.
+ * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
+ * the `[dd]` and `[yyyy]` inputs would be highlighted.
+ * <br/><br/>
+ *
+ * The `fieldHref` and `field` properties are strictly for
+ * internal use only and public access may be removed at any point.
+ */
+export type ErrorMessageConfigObject = {
+    /**
+     * Summary message
+     */
+    summary: string;
+    /**
+     * Inline message (@deprecated now uses summary everywhere)
+     */
+    inline?: string | undefined;
+    /**
+     * String(s) to append to URL hash for focusing inputs
+     */
+    focusSuffix?: string | string[] | undefined;
+    /**
+     * Object fields may use this to show errors per sub-property
+     */
+    fieldKeySuffix?: string | undefined;
+    /**
+     * Interpolation variables
+     */
+    variables?: object | ErrorMessageVariablesGenerator | undefined;
+    /**
+     * Name of the validator
+     */
+    validator?: string | undefined;
+    /**
+     * (internal) URL hash to link to field in UI, i.e `#f-..`
+     */
+    fieldHref?: string | undefined;
+    /**
+     * (internal) Field name, including any focus suffix
+     */
+    field?: string | undefined;
+};
+/**
+ * Function to generate interpolation variables for injecting into the error
+ * message string.
+ */
+export type ErrorMessageVariablesGenerator = (dataContext: ValidateContext) => object;
+export type ErrorMessageConfigGenerator = (dataContext: ValidateContext) => string | ErrorMessageConfigObject;
+export type ErrorMessageConfig = string | ErrorMessageConfigObject | ErrorMessageConfigGenerator | Error;
+/**
+ * Context passed to validate function
+ */
+export type ValidateContext = {
+    /**
+     * Journey context
+     */
+    journeyContext: JourneyContext;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * Name of field being processed
+     */
+    fieldName: string;
+    /**
+     * Current value of the field being validated
+     */
+    fieldValue?: any;
+    /**
+     * Name of the validator
+     */
+    validator?: string | undefined;
+};
+export type ValidateFunction = (value: any, context: ValidateContext) => ValidationError[];
+export type FieldProcessorFunction = (value: any) => any;
+export type Validator = {
+    /**
+     * Validation function
+     */
+    validate: ValidateFunction;
+    /**
+     * Sanitise a given value prior to validation
+     */
+    sanitise: FieldProcessorFunction;
+    /**
+     * Configuration
+     */
+    config: object;
+    /**
+     * Validator name
+     */
+    name: string;
+};
+export type ValidatorConditionFunctionParams = {
+    /**
+     * Field name
+     */
+    fieldName: string;
+    /**
+     * Field value
+     */
+    fieldValue: any;
+    /**
+     * Waypoint
+     */
+    waypoint: string;
+    /**
+     * [DEPRECATED] Waypoint (for backwards compatibility with v7)
+     */
+    waypointId: string;
+    /**
+     * Journey Context
+     */
+    journeyContext: JourneyContext;
+};
+/**
+ * Condition functions are executed unbound.
+ */
+export type ValidatorConditionFunction = (context: ValidatorConditionFunctionParams) => boolean;
+export type PlanRoute = {
+    /**
+     * Source waypoint
+     */
+    source: string;
+    /**
+     * Target waypoint
+     */
+    target: string;
+    /**
+     * Name
+     */
+    name: string;
+    /**
+     * Label
+     */
+    label: string;
+};
+export type PlanRouteCondition = (route: PlanRoute, context: JourneyContext) => boolean;
+export type PlanTraverseOptions = {
+    /**
+     * Waypoint from which to start (defaults to first in list)
+     */
+    startWaypoint?: string | undefined;
+    /**
+     * Follow routes matching this name (next | prev)
+     */
+    routeName: string;
+    /**
+     * Used to detect loops in traversal (INTERNAL USE ONLY)
+     */
+    history: Map<any, any>;
+    /**
+     * If true, traversal will be stopped (useful for performance)
+     */
+    stopCondition?: Function | undefined;
+    /**
+     * Mutliple target routes found, this decides which to use
+     */
+    arbiter?: string | PlanArbiter | undefined;
+};
+export type PlanArbiterParams = {
+    /**
+     * Potential target routes that need arbitration
+     */
+    targets: PlanRoute[];
+    /**
+     * Journey Context
+     */
+    journeyContext: JourneyContext;
+    /**
+     * Original traverse options passed to `traverse()`
+     */
+    traverseOptions: PlanTraverseOptions;
+};
+export type PlanArbiter = (route: PlanArbiterParams) => PlanRoute[];
 import configure from "./lib/configure.js";
 import validators from "./lib/validators/index.js";
 import field from "./lib/field.js";

package/dist/casa.js

@@ -104,8 +104,7 @@ exports.nunjucksFilters = nunjucksFilters;
  */
 /**
  * @callback PluginConfigureFunction
- * @param {object} con Options
- * @param {}
+ * @param {object} config Options
  */
 /**
  * @callback HelmetConfigurator
@@ -126,6 +125,7 @@ exports.nunjucksFilters = nunjucksFilters;
  * Configure some middleware for use in creating a new CASA app.
  *
  * @typedef {object} ConfigurationOptions Configuration options
+ * @property {string} [mountUrl] Prefix for all URLS in browser address bar
  * @property {string[]} [views=[]] Template directories
  * @property {SessionOptions} [session] Session configuration
  * @property {Page[]} [pages=[]] Pages the represent waypoints
@@ -150,3 +150,132 @@ exports.nunjucksFilters = nunjucksFilters;
  * @property {import('express').RequestHandler} bodyParserMiddleware Body parsing middleware
  * @property {Mounter} mount Function used to mount all CASA artifacts onto an ExpressJS app
  */
+/**
+ * Configuration for generating a ValidationError.
+ * i.e. `new ValidationError(configObject)`
+ * <br/><br/>
+ *
+ * The `fieldKeySuffix` is used to differentiate errors attached to
+ * the same field name. For example, given these fields inputs ...
+ *
+ * <pre>
+ * &lt;input name="dateOfBirth[dd]" /&gt;
+ * &lt;input name="dateOfBirth[mm]" /&gt;
+ * &lt;input name="dateOfBirth[yyyy]" /&gt;
+ * </pre>
+ *
+ * If we wanted to generate an error specifically for the `dd`
+ * element, then we'd include `{ fieldKeySuffix: '[dd]' }` in this
+ * config.
+ * <br/><br/>
+ *
+ * We can also use `focusSuffix` to control which properties of an
+ * object field should be highlighted with a red border when in error. Looking
+ * again at the `dateOfBirth` example above, if we did not specify
+ * any `focusSuffix`, then all three inputs would be highlighted.
+ * However, if we use `{ focusSuffix: ['[dd]', '[yyyy]'] }` then only
+ * the `[dd]` and `[yyyy]` inputs would be highlighted.
+ * <br/><br/>
+ *
+ * The `fieldHref` and `field` properties are strictly for
+ * internal use only and public access may be removed at any point.
+ *
+ * @typedef {object} ErrorMessageConfigObject
+ * @property {string} summary Summary message
+ * @property {string} [inline] Inline message (@deprecated now uses summary everywhere)
+ * @property {string|string[]} [focusSuffix] String(s) to append to URL hash for focusing inputs
+ * @property {string} [fieldKeySuffix] Object fields may use this to show errors per sub-property
+ * @property {object|ErrorMessageVariablesGenerator} [variables] Interpolation variables
+ * @property {string} [validator] Name of the validator
+ * @property {string} [fieldHref] (internal) URL hash to link to field in UI, i.e `#f-..`
+ * @property {string} [field] (internal) Field name, including any focus suffix
+ */
+/**
+ * Function to generate interpolation variables for injecting into the error
+ * message string.
+ *
+ * @callback ErrorMessageVariablesGenerator
+ * @param {ValidateContext} dataContext Data context
+ * @returns {object} Variables name:value hash
+ */
+/**
+ * @callback ErrorMessageConfigGenerator
+ * @param {ValidateContext} dataContext Data context
+ * @returns {string|ErrorMessageConfigObject} Compiled error mesasge config
+ */
+/**
+ * @typedef {string|ErrorMessageConfigObject|ErrorMessageConfigGenerator|Error} ErrorMessageConfig
+ */
+/**
+ * @typedef {object} ValidateContext Context passed to validate function
+ * @property {JourneyContext} journeyContext Journey context
+ * @property {string} waypoint Waypoint
+ * @property {string} fieldName Name of field being processed
+ * @property {any} [fieldValue] Current value of the field being validated
+ * @property {string} [validator] Name of the validator
+ */
+/**
+ * @callback ValidateFunction
+ * @param {any} value
+ * @param {ValidateContext} context Vaildation context
+ * @returns {ValidationError[]}
+ */
+/**
+ * @callback FieldProcessorFunction
+ * @param {any} value Value to be processed
+ * @returns {any}
+ */
+/**
+ * @typedef {object} Validator
+ * @property {ValidateFunction} validate Validation function
+ * @property {FieldProcessorFunction} sanitise Sanitise a given value prior to validation
+ * @property {object} config Configuration
+ * @property {string} name Validator name
+ */
+/**
+ * @typedef {object} ValidatorConditionFunctionParams
+ * @property {string} fieldName Field name
+ * @property {any} fieldValue Field value
+ * @property {string} waypoint Waypoint
+ * @property {string} waypointId [DEPRECATED] Waypoint (for backwards compatibility with v7)
+ * @property {JourneyContext} journeyContext Journey Context
+ */
+/**
+ * Condition functions are executed unbound.
+ *
+ * @callback ValidatorConditionFunction
+ * @param {ValidatorConditionFunctionParams} context Value to be processed
+ * @returns {boolean} True if the validators should be run
+ */
+/**
+ * @typedef {object} PlanRoute
+ * @property {string} source Source waypoint
+ * @property {string} target Target waypoint
+ * @property {string} name Name
+ * @property {string} label Label
+ */
+/**
+ * @callback PlanRouteCondition
+ * @param {PlanRoute} route Route metadata
+ * @param {JourneyContext} context Journey Context
+ * @returns {boolean} Returns true is route should be followed
+ */
+/**
+ * @typedef PlanTraverseOptions
+ * @property {string} [startWaypoint] Waypoint from which to start (defaults to first in list)
+ * @property {string} routeName Follow routes matching this name (next | prev)
+ * @property {Map} history Used to detect loops in traversal (INTERNAL USE ONLY)
+ * @property {Function} [stopCondition] If true, traversal will be stopped (useful for performance)
+ * @property {string|PlanArbiter} [arbiter] Mutliple target routes found, this decides which to use
+ */
+/**
+ * @typedef {object} PlanArbiterParams
+ * @property {PlanRoute[]} targets Potential target routes that need arbitration
+ * @property {JourneyContext} journeyContext Journey Context
+ * @property {PlanTraverseOptions} traverseOptions Original traverse options passed to `traverse()`
+ */
+/**
+ * @callback PlanArbiter
+ * @param {PlanArbiterParams} route Route metadata
+ * @returns {PlanRoute[]} Returns all routes, excluding those that the arbiter could eliminate
+ */

package/dist/lib/CasaTemplateLoader.d.ts

@@ -3,6 +3,10 @@
  * @param {string} templateName Path to the template being modified
  * @returns {string} The modified template source
  */
+/**
+ * @access private
+ * @augments FileSystemLoader
+ */
 export default class CasaTemplateLoader extends FileSystemLoader {
     /**
      * Constructor.

package/dist/lib/CasaTemplateLoader.js

@@ -14,6 +14,7 @@ var _CasaTemplateLoader_instances, _CasaTemplateLoader_blockModifiers, _CasaTemp
 Object.defineProperty(exports, "__esModule", { value: true });
 const nunjucks_1 = require("nunjucks");
 /**
+ * @access private
  * @typedef {import('nunjucks').FileSystemLoaderOptions} FileSystemLoaderOptions
  */
 const VALID_BLOCKS = [
@@ -36,6 +37,10 @@ const VALID_BLOCKS = [
  * @param {string} templateName Path to the template being modified
  * @returns {string} The modified template source
  */
+/**
+ * @access private
+ * @augments FileSystemLoader
+ */
 class CasaTemplateLoader extends nunjucks_1.FileSystemLoader {
     /**
      * Constructor.

package/dist/lib/JourneyContext.d.ts

@@ -1,13 +1,23 @@
 /**
+ * @access private
  * @typedef {import('../casa').Page} Page
  */
 /**
+ * @access private
  * @typedef {import('../casa').ContextEventHandler} ContextEventHandler
  */
 /**
+ * @access private
  * @typedef {import('../casa').ContextEvent} ContextEvent
  */
+/**
+ * @access private
+ * @typedef {import('express').Request} ExpressRequest
+ */
 export function validateObjectKey(key?: string): string;
+/**
+ * @memberof module:@dwp/govuk-casa
+ */
 export default class JourneyContext {
     static DEFAULT_CONTEXT_ID: string;
     /**
@@ -58,6 +68,14 @@ export default class JourneyContext {
      * @throws {SyntaxError} When id is not a valid uuid format
      */
     static validateContextId(id: string): string;
+    /**
+     * Retrieve the default Journey Context. This is just a convenient wrapper
+     * around `getContextById()`.
+     *
+     * @param {object} session Request session
+     * @returns {JourneyContext} The default Journey Context
+     */
+    static getDefaultContext(session: object): JourneyContext;
     /**
      * Lookup context from session using the ID.
      *
@@ -106,11 +124,48 @@ export default class JourneyContext {
      * @returns {void}
      */
     static removeContext(session: object, context: JourneyContext): void;
-    static removeContextById(session: any, id: any): void;
-    static removeContextByName(session: any, name: any): void;
-    static removeContextsByTag(session: any, tag: any): void;
-    static removeContexts(session: any): void;
-    static extractContextFromRequest(req: any): JourneyContext;
+    /**
+     * Remove context from session using the ID.
+     *
+     * @param {object} session Request session
+     * @param {string} id Context ID
+     * @returns {void}
+     */
+    static removeContextById(session: object, id: string): void;
+    /**
+     * Remove context from session using the name.
+     *
+     * @param {object} session Request session
+     * @param {string} name Context name
+     * @returns {void}
+     */
+    static removeContextByName(session: object, name: string): void;
+    /**
+     * Remove context from session using the tag.
+     *
+     * @param {object} session Request session
+     * @param {string} tag Context tag
+     * @returns {void}
+     */
+    static removeContextsByTag(session: object, tag: string): void;
+    /**
+     * Remove call contexts.
+     *
+     * @param {object} session Request session
+     * @returns {void}
+     */
+    static removeContexts(session: object): void;
+    /**
+     * Extract the Journey Context referred to in the incoming request.
+     *
+     * This will look in `req.params`, `req.query` and
+     * `req.body` for a `contextid` parameter, and use that
+     * to load the correct Journey Context from the session.
+     *
+     * @param {ExpressRequest} req ExpressJS incoming request
+     * @returns {JourneyContext} The Journey Context
+     */
+    static extractContextFromRequest(req: ExpressRequest): JourneyContext;
     /**
      * Constructor.
      *
@@ -154,6 +209,11 @@ export default class JourneyContext {
      * @throws {TypeError} When page is invalid.
      */
     getDataForPage(page: string | Page): object;
+    /**
+     * Get all data.
+     *
+     * @returns {object} Page data
+     */
     getData(): object;
     /**
      * Overwrite the data context with a new object.
@@ -165,11 +225,6 @@ export default class JourneyContext {
     /**
      * Write field form data from a page HTML form, into the `data` model.
      *
-     * By default this will store the data as-is, keyed against the page's
-     * waypoint ID. However, when passing a `Page` instance, its
-     * `fieldWriter()` method will be called to transform the provided formData
-     * before storing in `data`
-     *
      * @param {string | Page} page Page waypoint ID, or Page object
      * @param {object} webFormData Data to overwrite with
      * @returns {JourneyContext} Chain
@@ -218,7 +273,15 @@ export default class JourneyContext {
      * @returns {ValidationError[]} An array of errors
      */
     getValidationErrorsForPage(pageId: string): ValidationError[];
-    getValidationErrorsForPageByField(pageId: any): any;
+    /**
+     * Same as `getValidationErrorsForPage()`, but the return value is
+     * an object whose keys are the field names, and values are the list of errors
+     * associated with that particular field.
+     *
+     * @param {string} pageId Page ID.
+     * @returns {object} Object indexed by field names; values containing list of errors
+     */
+    getValidationErrorsForPageByField(pageId: string): object;
     /**
      * Determine whether the specified page has any errors in its validation
      * context.
@@ -268,9 +331,17 @@ export default class JourneyContext {
      * @returns {JourneyContext} Chain
      */
     addEventListeners(events: ContextEvent[]): JourneyContext;
+    /**
+     * Execute all listeners for the given event.
+     *
+     * @param {object} params Params
+     * @param {string} params.event Event (waypoint-change | context-change)
+     * @param {object} params.session Session
+     * @returns {JourneyContext} Chain
+     */
     applyEventListeners({ event, session }: {
-        event: any;
-        session: any;
+        event: string;
+        session: object;
     }): JourneyContext;
     /**
      * Convenience method to determine if this is the default context.
@@ -283,4 +354,5 @@ export default class JourneyContext {
 export type Page = import('../casa').Page;
 export type ContextEventHandler = import('../casa').ContextEventHandler;
 export type ContextEvent = import('../casa').ContextEvent;
+export type ExpressRequest = import('express').Request;
 import ValidationError from "./ValidationError.js";