@gov-cy/govcy-express-services 1.8.2 → 1.9.0

package/README.md

@@ -34,6 +34,7 @@ This readme file describes the definition of these APIs and how to use them. If
     - [cyLogin Access Policies](#cylogin-access-policies)
   - [🧩 Dynamic services](#-dynamic-services)
     - [Pages](#pages)
+    - [Task list pages](#task-list-pages)
     - [Form vs static pages](#form-vs-static-pages)
     - [Update my details pages](#update-my-details-pages)
     - [Multiple things pages (repeating group of inputs)](#multiple-things-pages-repeating-group-of-inputs)
@@ -942,6 +943,82 @@ Lets break down the JSON config for this page:
 
 ------------------------------------------
 
+#### Task list pages
+
+![Task list pages](docs/img/express-task-list.png)
+
+Task lists act as navigation hubs that show the completion state of one or more pages in the journey. They are defined by adding a `taskList` block alongside `pageData`:
+
+```json
+{
+  "pageData": {
+    "url": "task-list",
+    "title": {
+      "el": "Η αίτησή σας",
+      "en": "Your application"
+    },
+    "layout": "layouts/govcyBase.njk",
+    "mainLayout": "two-third",
+    "nextPage": "options"
+  },
+  "taskList": {
+    "topElements": [
+      { 
+        "element": "progressList", 
+        "params": { "id": "steps", "current": "2", "total": "3" } 
+      },
+      {
+        "element": "textElement",
+        "params": {
+          "type": "h1",
+          "text": {
+            "el": "Αίτηση για ISBN (Task List)",
+            "en": "Apply for an ISBN (Task List)"
+          }
+        }
+      }
+    ],
+    "taskPages": [
+        "index",
+        "book-title",
+        "publishing-details",
+        "authors",
+        "book-theme",
+        "book-series",
+        "reprint",
+        "translation",
+        "book-form",
+        "physical-description",
+        "collaborators"
+    ],
+    "hasBackLink": true,
+    "showSkippedTasks": true,
+    "linkToContinue": false
+  }
+}
+```
+
+- `taskPages` is an ordered list of page URLs. Each entry becomes a GOV.CY task row with the page title, link, and status.
+- `showSkippedTasks` toggles whether conditionally hidden pages appear in the UI with a “Not applicable” tag.
+- `linkToContinue` (default `false`) enables the renderer’s “Continue without completing all sections” link when POST validation fails.
+- `topElements` and `hasBackLink` reuse the usual renderer elements and layout helpers so the page can include progress lists, headings, or lead paragraphs.
+
+##### How statuses are calculated
+
+Task list statuses are produced by the same validation logic as the Review page (`computePageTaskStatus`). Each page can be in one of four states: `NOT_STARTED`, `IN_PROGRESS`, `COMPLETED`, or `SKIPPED` (when a page is hidden by conditions or a custom page opts out). The helper inspects the stored session data per page type:
+
+| Page type | When it becomes **NOT_STARTED** | When it is **IN_PROGRESS** | When it is **COMPLETED** |
+|-----------|---------------------------------|----------------------------|--------------------------|
+| **Standard form pages** | No `formData` captured yet | `formData` exists but field validation fails | Field validation succeeds (identical to Review) |
+| **Multiple things hubs** | No items and the hub hasn’t been posted yet | Fails per-item or min/max validation | All min/max checks pass or the user explicitly posts an empty-but-allowed hub |
+| **Update my details** | Data has not been fetched/posted | API result present but local validations fail | Data fetched and passes the same validation used on Review |
+| **Custom pages** | Missing status in custom session store | `setCustomPageTaskStatus` sets `IN_PROGRESS` | Custom implementation marks it `COMPLETED` |
+| **Nested task lists** | Any child task is `NOT_STARTED` | Mixed child statuses or explicit `IN_PROGRESS` | Every child task is `COMPLETED` or `SKIPPED` |
+
+Because the logic reuses the Review pipeline, you only have to define task lists in JSON; they immediately reflect file uploads, conditional skips, posted multiple entries, and custom page states without extra code.
+
+POSTing a task-list page re-runs these computations. If every section is complete, the user is redirected to `pageData.nextPage` (or `/review` when the request came from `?route=review`). Otherwise, the middleware stores a per-task error summary in the session so the renderer can show contextual guidance. Optional `linkToContinue` text and the global “Complete all sections before continuing.” message are also inserted automatically.
+
 #### Form vs static pages
 
 - If the `pageTemplate` includes a `form` element in the `main` section and `button` element, the system will treat it as form and will:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gov-cy/govcy-express-services",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "An Express-based system that dynamically renders services using @gov-cy/govcy-frontend-renderer and posts data to a submission API.",
   "author": "DMRID - DSF Team",
   "license": "MIT",

package/src/middleware/govcyFormsPostHandler.mjs

@@ -8,6 +8,7 @@ import { getFormData } from "../utils/govcyFormHandling.mjs"
 import { evaluatePageConditions } from "../utils/govcyExpressions.mjs";
 import { tempSaveIfConfigured } from "../utils/govcyTempSave.mjs";
 import { validateMultipleThings } from "../utils/govcyMultipleThingsValidation.mjs";
+import { handleTaskListPost } from "./govcyTaskListHandler.mjs";
 
 
 /**
@@ -32,6 +33,11 @@ export function govcyFormsPostHandler() {
                 return res.redirect(govcyResources.constructPageUrl(siteId, conditionResult.redirect));
             }
 
+            // ----- Task list handling (no <form> block)
+            if (page.taskList) {
+                return handleTaskListPost(req, res, next, { page, service, siteId, pageUrl });
+            }
+
             // 🔍 Find the form definition inside `pageTemplate.sections`
             let formElement = null;
             for (const section of page.pageTemplate.sections) {
@@ -61,6 +67,9 @@ export function govcyFormsPostHandler() {
                     return res.redirect(govcyResources.constructErrorSummaryUrl(req.originalUrl));
                 }
 
+                // Mark hub as posted so task lists can treat optional hubs as complete
+                dataLayer.setPagePosted(req.session, siteId, pageUrl, true);
+
                 // No validation errors, proceed to next page
                 logger.debug("✅ multipleThings hub validated successfully:", items, req);
                 logger.info("✅ multipleThings hub validated successfully:", req.originalUrl);
@@ -126,3 +135,4 @@ export function govcyFormsPostHandler() {
         }
     };
 }
+

package/src/middleware/govcyPageHandler.mjs

@@ -6,6 +6,7 @@ import { logger } from "../utils/govcyLogger.mjs";
 import { evaluatePageConditions } from "../utils/govcyExpressions.mjs";
 import { govcyMultipleThingsHubHandler } from "./govcyMultipleThingsHubHandler.mjs";
 import { govcyUpdateMyDetailsHandler } from "./govcyUpdateMyDetails.mjs";
+import { govcyTaskListHandler } from "./govcyTaskListHandler.mjs";
 // import {flattenContext, evaluateExpressionWithFlattening, evaluatePageConditions } from "../utils/govcyExpressions.mjs";
 
 /**
@@ -39,6 +40,11 @@ export function govcyPageHandler() {
         return res.redirect(`/${req.params.siteId}/${result.redirect}`);
       }
 
+      // ----- `taskList` handling
+      if (page.taskList) {
+        return govcyTaskListHandler(req, res, next, page, serviceCopy);
+      }
+
       // ----- `updateMyDetails` handling
       if (page.updateMyDetails) {
         return await govcyUpdateMyDetailsHandler(req, res, next, page, serviceCopy);

package/src/middleware/govcyReviewPostHandler.mjs

@@ -38,6 +38,12 @@ export function govcyReviewPostHandler() {
                     updateMyDetailsData = dataLayer.getPageUpdateMyDetails(req.session, siteId, pageUrl);
                 }
 
+                // ----- taskList handling
+                // Task list pages are navigation wrappers; skip validation here
+                if (page.taskList) {
+                    continue;
+                }
+
                 // ----- Conditional logic comes here
                 // ✅ Skip validation if page is conditionally excluded
                 const conditionResult = evaluatePageConditions(page, req.session, siteId, req);

package/src/middleware/govcyServiceEligibilityHandler.mjs

@@ -26,8 +26,8 @@ export function govcyServiceEligibilityHandler(checkForForm = false) {
                 if (!pageUrl) pageUrl = "index";
                 // 🔍 Find the page by pageUrl
                 const page = getPageConfigData(service, pageUrl);
-                // ----- `updateMyDetails` handling. always run eligibility for updateMyDetails
-                if (!page.updateMyDetails) {
+                // ----- `updateMyDetails` & `taskList` handling. Always run eligibility for these types
+                if (!page.updateMyDetails && !page.taskList) {
                     if (!page || !page.pageTemplate) return next(); // Defensive: skip if no template
                     // Deep copy pageTemplate to avoid modifying the original
                     const pageTemplateCopy = JSON.parse(JSON.stringify(page.pageTemplate));
@@ -106,4 +106,4 @@ export function govcyServiceEligibilityHandler(checkForForm = false) {
             return next(err); // Pass error to govcyHttpErrorHandler
         }
     };
-}
+}