@benwatsonuk/govuk-pages-plugin 1.0.0

package/src/assets/styles/scss/_pages.scss

@@ -0,0 +1,169 @@
+.govuk-pages-plugin {
+
+  .screenPreviewContainer {
+    height: 400px;
+    overflow: hidden;
+    border: 1px solid #000;
+    .screenPreview {
+      width: 200%;
+      height: 800px;
+      transform: scale(0.5);
+      transform-origin: 0 0;
+      background: none;
+      border: 0;
+    }
+  }
+
+  .page-flow-feedback {
+    &--positive {
+      color: #00a33b;
+    }
+    &--negative {
+      color: #a33038;
+    }
+  }
+
+  .page-flow--stages, .user-flow--stages {
+    @extend .govuk-body;
+    padding: 0;
+  }
+  .user-flow-item--stage {
+    display: inline-block;
+  }
+
+  .user-flow-page-item {
+    border-top: 1px solid #333;
+    padding-top:1em;
+    //margin-bottom: 2em;
+  }
+
+  .page-flow-item--stage, .user-flow-item--stage {
+    border-top: 10px solid;
+    .page-flow-stage-descriptor {
+      padding: 2px 10px;
+      display: block;
+      //padding: 5px;
+    }
+    &--1 {
+      border-color: $stage-color--1;
+    }
+    &--2 {
+      border-color: $stage-color--2;
+    }
+    &--3 {
+      border-color: $stage-color--3;
+    }
+    &--4 {
+      border-color: $stage-color--4;
+    }
+    &--authentication {
+      border-color: $stage-color--authentication;
+    }
+    &--documents {
+      border-color: $stage-color--documents;
+    }
+    &--notifications, &--notifications {
+      border-color: $stage-color--notifications;
+    }
+    &:last-of-type {
+      .page-flow-item--page{
+        &:last-of-type {
+          &:before {
+            display: none;
+          }
+        }
+      }
+    }
+  }
+
+  .page-flow--pages, .user-flow--pages {
+    @extend .govuk-body;
+    padding: 0;
+    .page-flow-item--page {
+      display: inline-block;
+      font-size: 14px;
+      width: 130px;
+      //min-height: 200px;
+      vertical-align: top;
+      position: relative;
+      .page-flow-item-screen-icon {
+        width: 100px;
+        height: 100px;
+        display: block;
+        background-repeat: no-repeat;
+        &--email {
+          background-image: url($icons + '/email.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--text-input {
+          background-image: url($icons + '/text-input.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--dashboard, &--content-page {
+          background-image: url($icons + '/content-page.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--radio-input {
+          background-image: url($icons + '/radio-input.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--checkbox-input {
+          background-image: url($icons + '/checkbox-input.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--check-answers {
+          background-image: url($icons + '/check-answers.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--confirmation {
+          background-image: url($icons + '/confirmation.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--task-list {
+          background-image: url($icons + '/task-list.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--start-page {
+          background-image: url($icons + '/start-page.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+        &--checkbox-page {
+          background-image: url($icons + '/checkbox-page.svg');
+          -webkit-background-size: contain;
+          background-size: contain;
+        }
+      }
+    }
+  }
+  .user-flow--pages {
+    @extend .page-flow--pages;
+    .page-flow-item--page {
+      display: inline-block;
+      font-size: 14px;
+      width: 170px;
+      //min-height: 200px;
+      vertical-align: top;
+      position: relative;
+
+      &:before {
+        content: "";
+        position: absolute;
+        background: url($page-flow-images + '/arrow.svg') no-repeat;
+        background-size: contain;
+        width: 78px;
+        left: 92px;
+        height: 20px;
+        top: 35px;
+      }
+    }
+  }
+}

package/src/assets/styles/scss/_variables.scss

@@ -0,0 +1,19 @@
+// Assets - these can all be overridden
+$page-flow-assets: '/extension-assets/govuk-page-flow-plugin/app/assets/';
+$page-flow-images: $page-flow-assets + 'images/';
+$icons: $page-flow-images + 'page-types';
+
+// Stock colours for stages
+$stage-color--1: #006c56;
+$stage-color--2: #00beb7;
+$stage-color--3: pink;
+$stage-color--4: #f47738;
+$stage-color--5: #ccc;
+$stage-color--6: #005ea5;
+$stage-color--7: #004432;
+$stage-color--8: #f47738;
+$stage-color--9: #3b1f5f;
+$stage-color--10: #ffdd00;
+$stage-color--documents: purple;
+$stage-color--notifications: teal;
+$stage-color--authentication: crimson;

package/src/functions/pages/getPages.ts

@@ -0,0 +1,7 @@
+import { PagesArray } from "../../types"
+import { validatePagesArray } from "../../validate"
+
+export const getPages = (pages: PagesArray) => {
+  const validatedPages = validatePagesArray(pages)
+  return validatedPages
+}

package/src/functions/stages/getStages.ts

@@ -0,0 +1,78 @@
+import { PagesArray, StagesArray, StagesWithPagesArray } from "../../types"
+import { validatePagesArray, validateStagesArray } from "../../validate"
+
+// Get and validate stages from the provided input
+export const getStages = (stages: StagesArray) => {
+  const validatedStages = validateStagesArray(stages)
+  return validatedStages
+}
+
+// Get and validate stages and relevant pages from the provided input. Return an array of Stage objects containing relevant pages.
+export const getStagesWithPages = (stages: StagesArray, pages: PagesArray): StagesWithPagesArray => {
+  const validatedStages = validateStagesArray(stages)
+  const validatedPages = validatePagesArray(pages)
+  return mapPagesToStages(validatedStages, validatedPages)
+}
+
+// Below this point is just the helper function used internally for the above functions
+
+// This function does the heavy lifting of mapping pages to their relevant stages
+export const mapPagesToStages = (
+  stages: StagesArray,
+  pages: PagesArray
+): StagesWithPagesArray => {
+  let allPages = [...pages]; // Create a copy to avoid mutating the original
+
+  const stagesWithPages: StagesWithPagesArray = stages.map((stage) => {
+    // Filter pages that belong to this stage
+    const pagesForStage = pages.filter(
+      (page) => page.stage && page.stage.main === stage.id
+    )
+
+    // Only add the stage if it has pages (after all, why return empty stages?)
+    if (pagesForStage.length > 0) {
+
+      // Remove the filtered pages from allPages to get unused pages
+      allPages = allPages.filter(page => !pagesForStage.some(p => p.id === page.id));
+
+      // Map sub-stages with their relevant pages
+      let subStagesWithPages
+      if (stage.subStages) {
+        subStagesWithPages = stage.subStages.map((subStage) => {
+          // Filter pages that belong to this sub-stage
+          const pagesForSubStage = pagesForStage.filter(
+            (page) => page.stage && page.stage.subStage === subStage.id
+          )
+
+         if (pagesForSubStage.length > 0) {
+            return {
+              id: subStage.id,
+              title: subStage.title,
+              description: subStage.description,
+              pages: pagesForSubStage
+            }
+          }
+        }).filter(subStage => subStage !== undefined)
+      } 
+    
+      return {
+        id: stage.id,
+        title: stage.title,
+        description: stage.description,
+        subStages: subStagesWithPages,
+        pages: pagesForStage
+      }
+    }
+  }).filter(stage => stage !== undefined);
+  
+  // add allPages to a misc category and bolt on to stagesWithPages
+  if (allPages.length > 0) {
+    stagesWithPages.push({
+      id: "unassigned",
+      title: "Unassigned",
+      description: "Pages not assigned to any stage or sub-stage",
+      pages: allPages
+    })
+  }
+  return stagesWithPages
+}

package/src/index.ts

@@ -0,0 +1,40 @@
+import {Router} from "express"
+import { getPages } from "./functions/pages/getPages"
+import { getStagesWithPages } from "./functions/stages/getStages"
+import { PagesArray, StagesArray } from "./types"
+
+/*--- UTILITIES (used by supplied routes AND made available to plugin users) ---*/
+
+export const pageIndexData = (pages: PagesArray) => {
+  return getPages(pages)
+}
+
+export const pageIndex = (pages: PagesArray, pageType: string) => {
+  pageType = pageType || "page-index"
+  return (req: any, res: any) => {
+    res.render(pageType, { pages: pages })
+  }
+}
+
+export const stageIndexData = (stages: StagesArray, pages: PagesArray) => {
+  return getStagesWithPages(stages, pages)
+}
+
+export const stageIndex = (stages: StagesArray, pages: PagesArray, pageType?: string) => {
+  pageType = pageType || "stage-index"
+  return (req: any, res: any) => {
+    res.render(pageType, { stages: stageIndexData(stages, pages) })
+  }
+}
+
+// Add user flows, etc here later
+
+/*--- THE MAIN USER ROUTES ---*/
+
+export const govukPagesPlugin = (pages: PagesArray, stages?: StagesArray, pageType?: string) => {
+  pageType = pageType || "page-index" // Options can be 'all', 'page-index', 'stage-index' - in future could be 'user-flow-index', etc
+  const router = Router()
+  // This is the default offering from the plugin - it is expected that must users will use this. It should be robust
+  router.get("/", pageIndex(pageIndexData(pages), pageType))
+  return router
+} 

package/src/schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["mode"],
+  "properties": {
+    "mode": {
+      "type": "string",
+      "enum": ["pages", "stages"]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": { "mode": { "const": "pages" } }
+      },
+      "then": { "$ref": "#/definitions/pages" },
+      "else": { "$ref": "#/definitions/stages" }
+    }
+  ],
+  "definitions": {
+    "pages": {
+      "type": "object",
+      "required": ["mode", "pages"],
+      "properties": {
+        "mode": { "const": "pages" },
+        "pages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "route"],
+            "properties": {
+              "id": { "type": "integer" },
+              "title": { "type": "string" },
+              "route": { "type": "string" },
+              "type": { "type": ["string", "null"] },
+              "stage": {
+                "type": ["object"],
+                "properties": {
+                  "main": { "type": ["string"] },
+                  "subStage": { "type": ["integer", "string"] }
+                },
+                "additionalProperties": false
+              },
+              "description": { "type": ["string", "null"] }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "stages": {
+      "type": "object",
+      "required": ["mode", "stages"],
+      "properties": {
+        "mode": { "const": "stages" },
+        "stages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "title", "route"],
+            "properties": {
+              "id": { "type": "string" },
+              "title": { "type": "string" },
+              "route": { "type": "string" },
+              "description": { "type": ["string", "null"] },
+              "subStages": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["id", "title"],
+                  "properties": {
+                    "id": { "type": ["string", "integer"] },
+                    "title": { "type": "string" },
+                    "route": { "type": "string" },
+                    "description": { "type": ["string", "null"] }
+                  },
+                  "additionalProperties": true
+                }
+              }
+            },
+            "additionalProperties": true
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,40 @@
+export interface Page {
+  id: number
+  title: string
+  type: string
+  route: string
+  description?: string
+  stage?: {
+    main: string,
+    subStage?: number | string
+  }
+}
+
+type SubStage = Omit<Stage, 'id' | 'subStages'> & {
+  id: number
+}
+
+type SubStageWithPages = Omit<StageWithPages, 'id' | 'subStages'> & {
+  id: number | string
+}
+
+export interface Stage {
+  id: string
+  title: string
+  route?: string
+  description: string | null
+  subStages?: SubStage[]
+}
+
+export interface StageWithPages {
+  id: string
+  title: string
+  description: string | null
+  subStages?: SubStageWithPages[]
+  pages: Page[]
+}
+
+
+export type StagesArray = Stage[];
+export type PagesArray = Page[];
+export type StagesWithPagesArray = StageWithPages[] | [];

package/src/validate.ts

@@ -0,0 +1,35 @@
+import Ajv from "ajv"
+import schema from "./schema.json"
+import { PagesArray, StagesArray } from "./types"
+
+const ajv = new Ajv({ allErrors: true, strict: false })
+
+const validate = ajv.compile(schema)
+
+export function validatePagesArray(pages: unknown): PagesArray {
+  if (!validate({ mode: "pages", pages: pages })) {
+    const message = validate.errors
+      ?.map(err => `${err.instancePath || "Pages"} ${err.message}`)
+      .join("\n")
+
+    throw new Error(
+      `Invalid array of PAGES passed to govuk-pages-plugin - please check the documentation to ensure the JSON schema you are passing matches what is expected:\n${message}`
+    )
+  }
+
+  return pages as PagesArray
+}
+
+export function validateStagesArray(stages: unknown): StagesArray {
+  if (!validate({ mode: "stages", stages: stages })) {
+    const message = validate.errors
+      ?.map(err => `${err.instancePath || "Stages"} ${err.message}`)
+      .join("\n")
+
+    throw new Error(
+      `Invalid array of STAGES passed to govuk-pages-plugin - please check the documentation to ensure the JSON schema you are passing matches what is expected:\n${message}`
+    )
+  }
+
+  return stages as StagesArray
+}

package/src/views/page-index.html

@@ -0,0 +1,34 @@
+{% extends "layouts/main.html" %}
+
+{% block pageTitle %}
+  Page Index
+{% endblock %}
+
+{% block beforeContent %}
+  {% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+
+  {{ govukBackLink({
+    text: "Back",
+    href: "javascript:history.back(-1);"
+  }) }}
+{% endblock %}
+
+{% block content %}
+
+      <div class="page-index ">
+        <h1 class="govuk-heading-l">Page Index</h1>
+        {% from "govuk/components/details/macro.njk" import govukDetails %}
+
+        {{ govukDetails({
+          summaryText: "What is the 'Page Index'?",
+          html: "<p>This page contains links to tracked pages in this prototype. It is useful for navigating the prototype without having to go through flows.</p><p class='govuk-body-s'> Note, the prototype might contain more pages than are listed here.</p>"
+        }) }} 
+
+        <ul class="govuk-list govuk-list--number">
+          {% for page in pages %}
+            <li><a href="{{ page.route }}">{{ page.title }}</a></li>
+          {% endfor %}
+        </ul>
+      </div>
+
+{% endblock %}

package/src/views/stage-index.html

@@ -0,0 +1,41 @@
+{% extends "layouts/main.html" %}
+
+{% block pageTitle %}
+  Stage Index
+{% endblock %}
+
+{% block beforeContent %}
+  {% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+
+  {{ govukBackLink({
+    text: "Back",
+    href: "javascript:history.back(-1);"
+  }) }}
+{% endblock %}
+
+{% block content %}
+
+      <div class="page-index ">
+        <h1 class="govuk-heading-l">Stage Index</h1>
+        {% from "govuk/components/details/macro.njk" import govukDetails %}
+
+        {{ govukDetails({
+          summaryText: "What is the 'Stage Index'?",
+          html: "<p>This page contains links to tracked pages in this prototype, these pages are grouped by the 'stages' that they are assigned to. It is useful for navigating the prototype without having to go through flows.</p><p>'Stages' are defined by the plugin user but can be throught about as logical groups of pages that work to achieve a common goal, such as 'authenticating' or 'registering'.</p><p class='govuk-body-s'> Note, the prototype might contain more pages than are listed here.</p>"
+        }) }} 
+        <!-- {{ stages | dump  }} -->
+          {% for stage in stages %}
+            <h2>{{ stage.title }}</h2>
+            {% if stage.description %}
+            <p class="govuk-body-s">{{ stage.description }}</p>
+            {% endif %}
+            <ol>
+            {% for page in stage.pages %}
+              <li><a href="{{ page.route }}">{{ page.title }}</a>{% if page.description %} - <span class="govuk-body-s">{{ page.description }}</span> {% endif %}</li>
+            {% endfor %}
+            </ol>
+            <hr/>
+          {% endfor %}
+      </div>
+
+{% endblock %}