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

package/src/utils/govcyCustomPages.mjs

@@ -1,4 +1,12 @@
-import * as govcyResources from "../resources/govcyResources.mjs";
+import * as govcyResources from "../resources/govcyResources.mjs";
+
+const ALLOWED_TASK_STATUSES = new Set(["NOT_STARTED", "IN_PROGRESS", "COMPLETED"]);
+
+function normalizeTaskStatus(statusKey = "NOT_STARTED") {
+    if (typeof statusKey !== "string") return "NOT_STARTED";
+    const normalized = statusKey.toUpperCase();
+    return ALLOWED_TASK_STATUSES.has(normalized) ? normalized : "NOT_STARTED";
+}
 
 /**
  * Defines custom pages for a given siteId and pageUrl.
@@ -9,21 +17,23 @@ import * as govcyResources from "../resources/govcyResources.mjs";
  * @param {string} pageTitle The title of the custom page (e.g., `{ en: "My custom section", el: "Προσαρμοσμένη ενότητα" }`)
  * @param {string} insertAfterPageUrl The page URL to insert the custom page after (e.g., `"qualifications"`)
  * @param {array} errors An array of error objects (e.g., `[{ id: "error1", text: { en: "Error 1", el: "Error 1"} }, { id: "error2", text: { en: "Error 2", el: "Error 2"} }]`)
- * @param {array} summaryElements An array of summary element objects (e.g., `{ key: { en: "Extra value", el: "Πρόσθετη τιμή" }, value: [] }` )
- * @param {boolean} summaryHtml Optional HTML content for the summary (e.g., `{ en: "<strong>Summary HTML</strong>", el: "<strong>Περίληψη HTML</strong>" }`)
- * @param {object} [extraProps={}] Optional extra metadata (e.g., `{ nextPage: "confirmation", requiresOTP: true }`)
- */
-export function defineCustomPages(
-    store,
-    siteId,
+ * @param {array} summaryElements An array of summary element objects (e.g., `{ key: { en: "Extra value", el: "Πρόσθετη τιμή" }, value: [] }` )
+ * @param {boolean} summaryHtml Optional HTML content for the summary (e.g., `{ en: "<strong>Summary HTML</strong>", el: "<strong>Περίληψη HTML</strong>" }`)
+ * @param {string} taskStatus Optional default task status for task lists (NOT_STARTED/IN_PROGRESS/COMPLETED)
+ * @param {object} [extraProps={}] Optional extra metadata (e.g., `{ nextPage: "confirmation", requiresOTP: true }`)
+ */
+export function defineCustomPages(
+    store,
+    siteId,
     pageUrl,
     pageTitle,
     insertAfterPageUrl,
     errors,
-    summaryElements,
-    summaryHtml = false,
-    extraProps = {}
-) {
+    summaryElements,
+    summaryHtml = false,
+    taskStatus = "NOT_STARTED",
+    extraProps = {}
+) {
     // Initialize custom pages in session if not already set
     store.siteData ??= {};
     store.siteData[siteId] ??= {};
@@ -44,15 +54,16 @@ export function defineCustomPages(
     let summaryActions = [];
 
     // Base definition
-    const definition = {
-        pageTitle,
-        insertAfterPageUrl,
-        summaryElements: summaryElements || [],
-        errors: normalizedErrors,
-        summaryActions: summaryActions,
-        ...(summaryHtml ? { summaryHtml } : {}),
-        ...extraProps // ✅ Merge any additional developer-defined properties
-    };
+    const definition = {
+        pageTitle,
+        insertAfterPageUrl,
+        summaryElements: summaryElements || [],
+        errors: normalizedErrors,
+        summaryActions: summaryActions,
+        taskStatus: normalizeTaskStatus(taskStatus),
+        ...(summaryHtml ? { summaryHtml } : {}),
+        ...extraProps // ✅ Merge any additional developer-defined properties
+    };
 
     // Construct default summaryActions
     if (pageTitle && pageUrl) {
@@ -234,7 +245,7 @@ export function clearCustomPageErrors(store, siteId, pageUrl) {
  * @param {string} errorId - Unique identifier for the error.
  * @param {Object} errorTextObject - Multilingual Object containing localized error texts.
  */
-export function addCustomPageError(store, siteId, pageUrl, errorId, errorTextObject) {
+export function addCustomPageError(store, siteId, pageUrl, errorId, errorTextObject) {
     const normalizedPageUrl = pageUrl.replace(/^\/+/, "");
 
     const target =
@@ -257,4 +268,35 @@ export function addCustomPageError(store, siteId, pageUrl, errorId, errorTextObj
         pageUrl: normalizedPageUrl,
     });
 
-}
+}
+
+/**
+ * Sets the task status for a custom page so task-list pages can show progress.
+ *
+ * @param {object} store Session store (req.session)
+ * @param {string} siteId Current site id
+ * @param {string} pageUrl Custom page url
+ * @param {string} statusKey One of NOT_STARTED/IN_PROGRESS/COMPLETED
+ */
+export function setCustomPageTaskStatus(store, siteId, pageUrl, statusKey = "NOT_STARTED") {
+    const target = store?.siteData?.[siteId]?.customPages?.[pageUrl];
+    if (!target) {
+        console.warn(`⚠️ setCustomPageTaskStatus: page '${pageUrl}' not found for site '${siteId}'`);
+        return;
+    }
+    target.taskStatus = normalizeTaskStatus(statusKey);
+}
+
+/**
+ * Retrieves the stored task status for a custom page.
+ *
+ * @param {object} store Session store (req.session)
+ * @param {string} siteId Current site id
+ * @param {string} pageUrl Custom page url
+ * @returns {string} Task status key
+ */
+export function getCustomPageTaskStatus(store, siteId, pageUrl) {
+    const target = store?.siteData?.[siteId]?.customPages?.[pageUrl];
+    if (!target) return "NOT_STARTED";
+    return normalizeTaskStatus(target.taskStatus);
+}

package/src/utils/govcyDataLayer.mjs

@@ -106,18 +106,43 @@ export function storePageValidationErrors(store, siteId, pageUrl, validationErro
  * @param {string} pageUrl The page url 
  * @param {object} formData The form data to be stored 
  */
-export function storePageData(store, siteId, pageUrl, formData) {
-    // Ensure session structure is initialized
-    initializeSiteData(store, siteId, pageUrl);
-
-    store.siteData[siteId].inputData[pageUrl]["formData"] = formData;
-}
-
-export function storePageDataElement(store, siteId, pageUrl, elementName, value) {
-    // Ensure session structure is initialized
-    initializeSiteData(store, siteId, pageUrl);
-
-    // Store the element value
+export function storePageData(store, siteId, pageUrl, formData) {
+    // Ensure session structure is initialized
+    initializeSiteData(store, siteId, pageUrl);
+
+    store.siteData[siteId].inputData[pageUrl]["formData"] = formData;
+}
+
+/**
+ * Marks whether a page has been posted/submitted at least once.
+ *
+ * @param {object} store Session store (req.session)
+ * @param {string} siteId Site id
+ * @param {string} pageUrl Page url
+ * @param {boolean} posted Flag indicating post action (defaults to true)
+ */
+export function setPagePosted(store, siteId, pageUrl, posted = true) {
+    initializeSiteData(store, siteId, pageUrl);
+    store.siteData[siteId].inputData[pageUrl]["posted"] = Boolean(posted);
+}
+
+/**
+ * Returns true if the user has already posted/submitted the page.
+ *
+ * @param {object} store Session store (req.session)
+ * @param {string} siteId Site id
+ * @param {string} pageUrl Page url
+ * @returns {boolean}
+ */
+export function isPagePosted(store, siteId, pageUrl) {
+    return Boolean(store?.siteData?.[siteId]?.inputData?.[pageUrl]?.posted);
+}
+
+export function storePageDataElement(store, siteId, pageUrl, elementName, value) {
+    // Ensure session structure is initialized
+    initializeSiteData(store, siteId, pageUrl);
+
+    // Store the element value
     store.siteData[siteId].inputData[pageUrl].formData[elementName] = value;
 }
 /**

package/src/utils/govcySubmitData.mjs

@@ -42,6 +42,11 @@ export function prepareSubmissionData(req, siteId, service) {
 
     // Loop through every page in the service definition
     for (const page of service.pages) {
+        
+        // ----- taskList handling
+        if (page.taskList) {
+            continue; // Task list pages do not contribute submission payloads
+        }
         const pageUrl = page.pageData.url || "";
 
         // Find the <form> element in the page
@@ -347,12 +352,16 @@ export function preparePrintFriendlyData(req, siteId, service) {
         if (conditionResult.result === false) {
             continue; // ⛔ Skip this page from print-friendly data
         }
+        // ----- taskList handling
+        if (page.taskList) {
+            continue; // Task list hub is a navigation shell, no print-friendly entry
+        }
 
         let pageTemplate = page.pageTemplate;
         let pageTitle = page.pageData.title || {};
 
 
-        // ----- MultipleThings hub handling
+        // ----- updateMyDetails hub handling
         if (page.updateMyDetails) {
             // create the page template
             pageTemplate = createUmdManualPageTemplate(siteId, service.site.lang, page, req);

package/src/utils/govcyTaskList.mjs

@@ -0,0 +1,284 @@
+import { getPageConfigData } from "./govcyLoadConfigData.mjs";
+import { evaluatePageConditions } from "./govcyExpressions.mjs";
+import { validateFormElements } from "./govcyValidator.mjs";
+import { validateMultipleThings } from "./govcyMultipleThingsValidation.mjs";
+import { createUmdManualPageTemplate } from "../middleware/govcyUpdateMyDetails.mjs";
+import * as dataLayer from "./govcyDataLayer.mjs";
+import { logger } from "./govcyLogger.mjs";
+import * as govcyResources from "../resources/govcyResources.mjs";
+import { getCustomPageTaskStatus } from "./govcyCustomPages.mjs";
+
+/**
+ * Computes the completion status for a single page.
+ * Mirrors review-stage validation so task lists use the same rules.
+ */
+export function computePageTaskStatus(req, siteId, service, pageUrl, visitedPages = new Set()) {
+    if (!req || !req.session) {
+        logger.error("computePageTaskStatus called without session", { siteId, pageUrl });
+        throw new Error("computePageTaskStatus: request with session is required");
+    }
+    if (!service || !Array.isArray(service.pages)) {
+        logger.error("computePageTaskStatus service missing pages array", { siteId, pageUrl });
+        throw new Error("computePageTaskStatus: service.pages is required");
+    }
+    if (!pageUrl) {
+        logger.error("computePageTaskStatus missing pageUrl", { siteId });
+        throw new Error("computePageTaskStatus: pageUrl is required");
+    }
+
+    // Handle custom pages first
+    const customPage = dataLayer.getSiteCustomPages(req.session, siteId)?.[pageUrl];
+    if (customPage) {
+        return {
+            pageUrl,
+            title: customPage?.pageTitle || {},
+            type: "custom",
+            status: getCustomPageTaskStatus(req.session, siteId, pageUrl),
+            hasData: Boolean(customPage?.data),
+            custom: true
+        };
+    }
+
+    const page = getPageConfigData(service, pageUrl);
+    if (!page) {
+        logger.error("computePageTaskStatus page not found", { siteId, pageUrl });
+        throw new Error("computePageTaskStatus: page '" + pageUrl + "' not found in service configuration");
+    }
+
+    // Use a composite key so nested task-list evaluation can detect circular references.
+    const cycleKey = siteId + ":" + pageUrl;
+    if (visitedPages.has(cycleKey)) {
+        const cyclePath = [...visitedPages, cycleKey].map(key => key.split(":")[1]);
+        logger.error("computePageTaskStatus circular task list reference detected", {
+            siteId,
+            cycle: cyclePath
+        });
+        throw new Error("Task list configuration contains a circular reference: " + cyclePath.join(" -> "));
+    }
+
+    visitedPages.add(cycleKey);
+
+    try {
+        // Reuse the same condition logic as page rendering – if a page would redirect,
+        // we treat it as skipped so task lists never block on hidden sections.
+        const conditionResult = evaluatePageConditions(page, req.session, siteId, req);
+        if (conditionResult?.result === false) {
+            return buildStatusResult(page, determinePageType(page), pageUrl, false, "SKIPPED", conditionResult);
+        }
+
+        const pageType = determinePageType(page);
+        if (pageType === "taskList") {
+            // For task list pages, recurse into each configured children and aggregate their status.
+            const taskPages = Array.isArray(page?.taskList?.taskPages) ? page.taskList.taskPages : [];
+            const summary = computeTaskListStatus(req, siteId, service, taskPages, visitedPages);
+            const result = buildStatusResult(page, pageType, pageUrl, summary.status !== "NOT_STARTED", summary.status);
+            result.taskList = summary;
+            return result;
+        }
+
+        // Below covers all data-entry pages (normal, multipleThings, updateMyDetails)
+        // For form-based pages, inspect the session data and validation results.
+        let storedData = dataLayer.getPageData(req.session, siteId, pageUrl);
+        const postedFlag = dataLayer.isPagePosted(req.session, siteId, pageUrl);
+
+        // Multiple things hubs always expect an array, so normalize bad shapes.
+        if (pageType === "multipleThings" && !Array.isArray(storedData)) {
+            storedData = [];
+        }
+        // All other page types expect an object. When nothing is stored yet, fall back to {}.
+        if (!storedData || typeof storedData !== "object") {
+            storedData = Array.isArray(storedData) ? storedData : {};
+        }
+
+        const hasData = determineHasData(storedData, pageType, postedFlag);
+        if (!hasData) {
+            return buildStatusResult(page, pageType, pageUrl, false, "NOT_STARTED");
+        }
+
+        // For form-based pages, inspect the session data and validation results.
+        const hasErrors = hasValidationErrors({
+            page,
+            pageType,
+            storedData,
+            req,
+            service,
+            siteId
+        });
+
+        return buildStatusResult(
+            page,
+            pageType,
+            pageUrl,
+            true,
+            hasErrors ? "IN_PROGRESS" : "COMPLETED"
+        );
+    } finally {
+        visitedPages.delete(cycleKey);
+    }
+}
+
+/**
+ * Computes statuses for all pages listed in taskPages and derives overall status.
+ */
+export function computeTaskListStatus(req, siteId, service, taskPages = [], visitedPages = new Set()) {
+    if (!Array.isArray(taskPages)) {
+        logger.error("computeTaskListStatus expects taskPages array", { siteId });
+        throw new Error("taskPages must be an array");
+    }
+
+    const tasks = taskPages.map(pageUrl => computePageTaskStatus(req, siteId, service, pageUrl, visitedPages));
+    const status = deriveTaskListStatus(tasks);
+    return { status, tasks };
+}
+
+/**
+ * Returns a normalized type string so callers can branch per page category.
+ *
+ * @param {object} page Page configuration object
+ * @returns {"taskList"|"updateMyDetails"|"multipleThings"|"normal"}
+ */
+function determinePageType(page) {
+    if (page?.taskList) return "taskList";
+    if (page?.updateMyDetails) return "updateMyDetails";
+    if (page?.multipleThings) return "multipleThings";
+    return "normal";
+}
+
+/**
+ * Determines whether the stored data should count as "started".
+ *
+ * @param {object|Array} storedData Data retrieved from the session
+ * @param {string} pageType Derived page type
+ * @param {boolean} postedFlag For multipleThings pages, whether user pressed continue at least once
+ * @returns {boolean}
+ */
+function determineHasData(storedData, pageType, postedFlag = false) {
+    
+    if (Array.isArray(storedData)) {
+        if (storedData.length > 0) return true;
+        return pageType === "multipleThings" && postedFlag;
+    }
+    if (storedData && typeof storedData === "object") {
+        const hasKeys = Object.keys(storedData).length > 0;
+        if (hasKeys) return true;
+    }
+    if (pageType === "multipleThings" && postedFlag) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Mirrors review validation to decide if a page currently has outstanding errors.
+ *
+ * @param {object} opts Inputs bundle
+ * @returns {boolean}
+ */
+function hasValidationErrors({ page, pageType, storedData, req, service, siteId }) {
+    if (pageType === "multipleThings") {
+        const lang = service?.site?.lang || req?.globalLang || "el";
+        const errors = validateMultipleThings(page, storedData, lang);
+        return Object.keys(errors || {}).length > 0;
+    }
+
+    const formElement = getFormElementForPage({ page, pageType, req, service, siteId });
+    if (!formElement) {
+        return false;
+    }
+
+    const errors = validateFormElements(
+        formElement.params?.elements || [],
+        storedData,
+        page?.pageData?.url
+    );
+
+    return Object.keys(errors || {}).length > 0;
+}
+
+/**
+ * Retrieves a form element definition so the validator can run against it.
+ *
+ * @param {object} params Inputs bundle
+ * @returns {object|null}
+ */
+function getFormElementForPage({ page, pageType, req, service, siteId }) {
+    if (pageType === "updateMyDetails") {
+        const lang = service?.site?.lang || req?.globalLang || "el";
+        const template = createUmdManualPageTemplate(siteId, lang, page, req, true);
+        return findFormElement(template?.sections);
+    }
+
+    return findFormElement(page?.pageTemplate?.sections);
+}
+
+/**
+ * Depth-first scan for the first form element within renderer sections.
+ *
+ * @param {Array} sections Renderer sections array
+ * @returns {object|null}
+ */
+function findFormElement(sections = []) {
+    if (!Array.isArray(sections)) return null;
+    for (const section of sections) {
+        const elements = section?.elements || [];
+        for (const element of elements) {
+            if (element?.element === "form") {
+                return element;
+            }
+        }
+    }
+    return null;
+}
+
+/**
+ * Constructs the canonical payload returned by computePageTaskStatus.
+ *
+ * @param {object} page Page config
+ * @param {string} pageType Derived type string
+ * @param {string} pageUrl Page identifier
+ * @param {boolean} hasData Whether any user input exists
+ * @param {string} status Status flag
+ * @param {object|null} conditionResult Optional condition evaluation details
+ * @returns {object}
+ */
+function buildStatusResult(page, pageType, pageUrl, hasData, status, conditionResult = null) {
+    const result = {
+        pageUrl,
+        title: pageType === "updateMyDetails"
+            ? govcyResources.staticResources.text.updateMyDetailsTitle
+            : (page?.pageData?.title || {}),
+        type: pageType,
+        status,
+        hasData
+    };
+
+    if (conditionResult) {
+        result.conditionResult = conditionResult;
+    }
+
+    return result;
+}
+
+/**
+ * Collapses individual task statuses into a single overall status.
+ *
+ * @param {Array<{status:string}>} tasks Task descriptors
+ * @returns {"NOT_STARTED"|"IN_PROGRESS"|"COMPLETED"}
+ */
+function deriveTaskListStatus(tasks = []) {
+    const relevant = tasks.filter(task => task.status !== "SKIPPED");
+    if (relevant.length === 0) return "COMPLETED";
+
+    const statuses = relevant.map(task => task.status);
+    const hasNotStarted = statuses.includes("NOT_STARTED");
+    const hasCompleted = statuses.includes("COMPLETED");
+    const hasInProgress = statuses.includes("IN_PROGRESS");
+
+    if (hasInProgress || (hasCompleted && hasNotStarted)) {
+        return "IN_PROGRESS";
+    }
+    if (hasNotStarted) {
+        return "NOT_STARTED";
+    }
+    return "COMPLETED";
+}