placementt-core 1.400.1055 → 1.400.1056

package/lib/index.d.ts

@@ -29,6 +29,7 @@ export * from "./tutorialTips";
 export * from "./constants";
 export * from "./dataViewerReload";
 export * from "./hooks";
+export * from "./workflowBands";
 export * from "./util";
 export * from "./images/GatsbyBenchmarks";
 export * from "./databaseTypes";

package/lib/index.js

@@ -49,6 +49,7 @@ __exportStar(require("./tutorialTips"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./dataViewerReload"), exports);
 __exportStar(require("./hooks"), exports);
+__exportStar(require("./workflowBands"), exports);
 __exportStar(require("./util"), exports);
 __exportStar(require("./images/GatsbyBenchmarks"), exports);
 __exportStar(require("./databaseTypes"), exports);

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,8CAA4B;AAC5B,kDAAgC;AAChC,kDAAgC;AAChC,qDAAmC;AACnC,mDAAiC;AACjC,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,wCAAsB;AACtB,oDAAkC;AAClC,4CAA0B;AAC1B,2CAAyB;AACzB,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,iDAA+B;AAC/B,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,qDAAmC;AACnC,0CAAwB;AACxB,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,iEAA+C;AAC/C,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AACA,sDAAoC;AACpC,gEAA8C;AAC9C,0DAAwC;AACxC,2DAAyC;AACzC,kDAAgC;AAChC,uDAAqC;AACrC,4DAA0C;AAC1C,2DAAyC;AAEzC,oDAAkC;AAClC,8CAA4B;AAC5B,kDAAgC;AAChC,kDAAgC;AAChC,qDAAmC;AACnC,mDAAiC;AACjC,qDAAmC;AACnC,mDAAiC;AACjC,+CAA6B;AAC7B,wCAAsB;AACtB,oDAAkC;AAClC,4CAA0B;AAC1B,2CAAyB;AACzB,kDAAgC;AAChC,uDAAqC;AACrC,kDAAgC;AAChC,iDAA+B;AAC/B,2DAAyC;AACzC,uDAAqC;AACrC,iDAA+B;AAC/B,8CAA4B;AAC5B,qDAAmC;AACnC,0CAAwB;AACxB,kDAAgC;AAChC,yCAAuB;AACvB,4DAA0C;AAC1C,kDAAgC;AAChC,iDAA+B;AAC/B,2CAAyB;AACzB,4DAA0C;AAC1C,oEAAiD;AACjD,yEAAuD;AACvD,kEAAgD;AAChD,kEAAgD;AAChD,oEAAkD;AAClD,yGAAuF;AACvF,0GAAwF;AACxF,+FAA6E;AAC7E,4DAA0C;AAC1C,oEAAkD;AAClD,iEAA+C;AAC/C,gEAA8C;AAC9C,2EAAyD;AACzD,6CAA2B;AAC3B,+CAA6B;AAC7B,8CAA4B;AAC5B,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB"}

package/lib/typeDefinitions.d.ts

@@ -48,6 +48,10 @@ export type Products = "institutes" | "providers" | "students" | "admin";
 export type StudentPlacementData = {
     title: string;
     reqUserType: "Students" | "Staff" | "Provider" | "Parent";
+    reqUserTypes?: ("Students" | "Staff" | "Provider" | "Parent")[];
+    /** Set while a completion is claiming the band's single advance, so two
+     * parties finishing at once cannot both move the placement on. */
+    advancingFrom?: number;
     lastStageChange?: string;
     uid: string;
     startDate: string;
@@ -751,6 +755,7 @@ export type WorkflowStage = {
         y: number;
     };
     userType?: "Students" | "Staff" | "Provider" | "Parent";
+    concurrentWithNext?: boolean;
     forms?: string[];
     files?: string[];
     deadline?: string;

package/lib/workflowBands.d.ts

@@ -0,0 +1,33 @@
+import { WorkflowStage } from "./typeDefinitions";
+/**
+ * Concurrent sign-off bands.
+ *
+ * Deliberately free of any firebase import so it can be unit tested and pulled
+ * into the backend, the external review payload and the staff UI alike.
+ */
+/**
+ * The stage that starts the concurrent band `stageId` belongs to.
+ *
+ * A band is a run of stages chained by their first button where every stage but
+ * the last carries `concurrentWithNext`. The head is the stage a placement's
+ * `status` points at while the band is open, which is what lets `status` stay a
+ * single number: the band only changes who we ask, not where the placement is.
+ */
+export declare const getBandHead: (workflow: WorkflowStage[], stageId: number) => WorkflowStage | undefined;
+/**
+ * Every stage that runs at the same time as `stageId`, in workflow order.
+ *
+ * Returns just the stage itself when nothing is marked concurrent, so callers can
+ * use this unconditionally and existing workflows behave exactly as before.
+ */
+export declare const getConcurrentBand: (workflow: WorkflowStage[], stageId: number) => WorkflowStage[];
+/** True when the workflow asks more than one party at this point. */
+export declare const isConcurrentBand: (workflow: WorkflowStage[], stageId: number) => boolean;
+/** The band's stages that nobody has signed off yet. */
+export declare const getBandOutstanding: (band: WorkflowStage[], completedStages?: number[]) => WorkflowStage[];
+/** Distinct user types the band is still waiting on, in workflow order. */
+export declare const getBandOutstandingUserTypes: (band: WorkflowStage[], completedStages?: number[]) => NonNullable<"Students" | "Staff" | "Provider" | "Parent" | undefined>[];
+/** Where the placement goes once every stage in the band is signed off. */
+export declare const getBandExitStageId: (band: WorkflowStage[]) => number | undefined;
+/** The label to show staff for a band, e.g. "Employer review & parental consent". */
+export declare const getBandName: (band: WorkflowStage[]) => string;

package/lib/workflowBands.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBandName = exports.getBandExitStageId = exports.getBandOutstandingUserTypes = exports.getBandOutstanding = exports.isConcurrentBand = exports.getConcurrentBand = exports.getBandHead = void 0;
+/**
+ * Concurrent sign-off bands.
+ *
+ * Deliberately free of any firebase import so it can be unit tested and pulled
+ * into the backend, the external review payload and the staff UI alike.
+ */
+/**
+ * The stage that starts the concurrent band `stageId` belongs to.
+ *
+ * A band is a run of stages chained by their first button where every stage but
+ * the last carries `concurrentWithNext`. The head is the stage a placement's
+ * `status` points at while the band is open, which is what lets `status` stay a
+ * single number: the band only changes who we ask, not where the placement is.
+ */
+const getBandHead = (workflow, stageId) => {
+    let stage = workflow.find((s) => s.id === stageId);
+    if (!stage)
+        return undefined;
+    const visited = new Set([stage.id]);
+    for (;;) {
+        const previous = workflow.find((s) => s.concurrentWithNext && s.buttons?.[0]?.id === stage?.id);
+        // No flagged predecessor means we are already at the head.
+        if (!previous || visited.has(previous.id))
+            return stage;
+        visited.add(previous.id);
+        stage = previous;
+    }
+};
+exports.getBandHead = getBandHead;
+/**
+ * Every stage that runs at the same time as `stageId`, in workflow order.
+ *
+ * Returns just the stage itself when nothing is marked concurrent, so callers can
+ * use this unconditionally and existing workflows behave exactly as before.
+ */
+const getConcurrentBand = (workflow, stageId) => {
+    const head = (0, exports.getBandHead)(workflow, stageId);
+    if (!head)
+        return [];
+    const band = [head];
+    const visited = new Set([head.id]);
+    let stage = head;
+    while (stage?.concurrentWithNext) {
+        const nextId = stage.buttons?.[0]?.id;
+        // A flagged stage with nowhere to go, or a loop, ends the band rather
+        // than stranding the caller.
+        if (nextId === undefined || visited.has(nextId))
+            break;
+        stage = workflow.find((s) => s.id === nextId);
+        if (!stage)
+            break;
+        visited.add(stage.id);
+        band.push(stage);
+    }
+    return band;
+};
+exports.getConcurrentBand = getConcurrentBand;
+/** True when the workflow asks more than one party at this point. */
+const isConcurrentBand = (workflow, stageId) => (0, exports.getConcurrentBand)(workflow, stageId).length > 1;
+exports.isConcurrentBand = isConcurrentBand;
+/** The band's stages that nobody has signed off yet. */
+const getBandOutstanding = (band, completedStages = []) => band.filter((stage) => !completedStages.includes(stage.id));
+exports.getBandOutstanding = getBandOutstanding;
+/** Distinct user types the band is still waiting on, in workflow order. */
+const getBandOutstandingUserTypes = (band, completedStages = []) => (0, exports.getBandOutstanding)(band, completedStages)
+    .map((stage) => stage.userType)
+    .filter((userType, i, all) => Boolean(userType) && all.indexOf(userType) === i);
+exports.getBandOutstandingUserTypes = getBandOutstandingUserTypes;
+/** Where the placement goes once every stage in the band is signed off. */
+const getBandExitStageId = (band) => band[band.length - 1]?.buttons?.[0]?.id;
+exports.getBandExitStageId = getBandExitStageId;
+/** The label to show staff for a band, e.g. "Employer review & parental consent". */
+const getBandName = (band) => band.map((stage) => stage.name).join(" & ");
+exports.getBandName = getBandName;
+//# sourceMappingURL=workflowBands.js.map

package/lib/workflowBands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowBands.js","sourceRoot":"","sources":["../src/workflowBands.ts"],"names":[],"mappings":"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"}

package/lib/workflowBands.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/workflowBands.test.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workflowBands_1 = require("./workflowBands");
+describe("Concurrent bands", () => {
+    // A typical work experience chain: staff check, then employer review, then
+    // parental consent, then the placement start stage.
+    const stage = (id, userType, next, concurrentWithNext) => ({
+        id,
+        name: `Stage ${id}`,
+        userType,
+        concurrentWithNext,
+        buttons: next === undefined ? [] : [{ id: next, name: "Continue", required: true }],
+    });
+    const sequential = [
+        stage(1, "Students", 2),
+        stage(2, "Staff", 3),
+        stage(3, "Provider", 4),
+        stage(4, "Parent", 6),
+        stage(6, undefined),
+    ];
+    // Same workflow, but employer review and parental consent run together.
+    const banded = [
+        stage(1, "Students", 2),
+        stage(2, "Staff", 3),
+        stage(3, "Provider", 4, true),
+        stage(4, "Parent", 6),
+        stage(6, undefined),
+    ];
+    it("returns just the stage when nothing is marked concurrent", () => {
+        expect((0, workflowBands_1.getConcurrentBand)(sequential, 3).map((s) => s.id)).toEqual([3]);
+        expect((0, workflowBands_1.getConcurrentBand)(sequential, 4).map((s) => s.id)).toEqual([4]);
+        expect((0, workflowBands_1.isConcurrentBand)(sequential, 3)).toBe(false);
+    });
+    it("resolves the same band from any member", () => {
+        expect((0, workflowBands_1.getConcurrentBand)(banded, 3).map((s) => s.id)).toEqual([3, 4]);
+        expect((0, workflowBands_1.getConcurrentBand)(banded, 4).map((s) => s.id)).toEqual([3, 4]);
+        expect((0, workflowBands_1.isConcurrentBand)(banded, 3)).toBe(true);
+    });
+    it("resolves a band of three from the middle", () => {
+        const three = [
+            stage(2, "Staff", 3, true),
+            stage(3, "Provider", 4, true),
+            stage(4, "Parent", 6),
+            stage(6, undefined),
+        ];
+        expect((0, workflowBands_1.getConcurrentBand)(three, 3).map((s) => s.id)).toEqual([2, 3, 4]);
+        expect((0, workflowBands_1.getBandHead)(three, 4)?.id).toEqual(2);
+    });
+    it("does not pull in the stage after the band", () => {
+        expect((0, workflowBands_1.getConcurrentBand)(banded, 3).some((s) => s.id === 6)).toBe(false);
+        expect((0, workflowBands_1.getBandExitStageId)((0, workflowBands_1.getConcurrentBand)(banded, 3))).toEqual(6);
+    });
+    it("terminates on a cycle", () => {
+        // The builder stops a school authoring this, but a hand-edited workflow
+        // must not hang or repeat a stage. A cycle has no real head, so only the
+        // membership is meaningful here, not the order.
+        const looped = [
+            stage(3, "Provider", 4, true),
+            stage(4, "Parent", 3, true),
+        ];
+        const ids = (0, workflowBands_1.getConcurrentBand)(looped, 3).map((s) => s.id);
+        expect(ids.slice().sort()).toEqual([3, 4]);
+        expect(new Set(ids).size).toEqual(ids.length);
+    });
+    it("terminates when a flagged stage points nowhere", () => {
+        const dangling = [stage(3, "Provider", undefined, true)];
+        expect((0, workflowBands_1.getConcurrentBand)(dangling, 3).map((s) => s.id)).toEqual([3]);
+    });
+    it("returns nothing for a stage that is not in the workflow", () => {
+        expect((0, workflowBands_1.getConcurrentBand)(banded, 99)).toEqual([]);
+    });
+    it("reports what the band is still waiting on", () => {
+        const band = (0, workflowBands_1.getConcurrentBand)(banded, 3);
+        expect((0, workflowBands_1.getBandOutstanding)(band, []).map((s) => s.id)).toEqual([3, 4]);
+        expect((0, workflowBands_1.getBandOutstandingUserTypes)(band, [])).toEqual(["Provider", "Parent"]);
+        // The employer has signed off, so only the parent is still owed.
+        expect((0, workflowBands_1.getBandOutstanding)(band, [3]).map((s) => s.id)).toEqual([4]);
+        expect((0, workflowBands_1.getBandOutstandingUserTypes)(band, [3])).toEqual(["Parent"]);
+        expect((0, workflowBands_1.getBandOutstanding)(band, [3, 4])).toEqual([]);
+        expect((0, workflowBands_1.getBandOutstandingUserTypes)(band, [3, 4])).toEqual([]);
+    });
+    it("does not repeat a user type that owns two stages in the band", () => {
+        const twoProviderStages = [
+            stage(3, "Provider", 4, true),
+            stage(4, "Provider", 5, true),
+            stage(5, "Parent", 6),
+            stage(6, undefined),
+        ];
+        const band = (0, workflowBands_1.getConcurrentBand)(twoProviderStages, 3);
+        expect((0, workflowBands_1.getBandOutstandingUserTypes)(band, [])).toEqual(["Provider", "Parent"]);
+    });
+    it("names the band for staff", () => {
+        expect((0, workflowBands_1.getBandName)((0, workflowBands_1.getConcurrentBand)(banded, 3))).toEqual("Stage 3 & Stage 4");
+        expect((0, workflowBands_1.getBandName)((0, workflowBands_1.getConcurrentBand)(sequential, 3))).toEqual("Stage 3");
+    });
+});
+//# sourceMappingURL=workflowBands.test.js.map

package/lib/workflowBands.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflowBands.test.js","sourceRoot":"","sources":["../src/workflowBands.test.ts"],"names":[],"mappings":";;AAAA,mDAC6F;AAG7F,QAAQ,CAAC,kBAAkB,EAAE,GAAG,EAAE;IAC9B,2EAA2E;IAC3E,oDAAoD;IACpD,MAAM,KAAK,GAAG,CAAC,EAAU,EAAE,QAAmC,EAAE,IAAa,EAAE,kBAA4B,EAAiB,EAAE,CAAC,CAAC;QAC5H,EAAE;QACF,IAAI,EAAE,SAAS,EAAE,EAAE;QACnB,QAAQ;QACR,kBAAkB;QAClB,OAAO,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAC,CAAC;KACpF,CAAC,CAAC;IAEH,MAAM,UAAU,GAAoB;QAChC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QACvB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACpB,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QACvB,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;KACtB,CAAC;IAEF,wEAAwE;IACxE,MAAM,MAAM,GAAoB;QAC5B,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC;QACvB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;QACpB,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC;QAC7B,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;QACrB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;KACtB,CAAC;IAEF,EAAE,CAAC,0DAA0D,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,IAAA,iCAAiB,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,CAAC,IAAA,iCAAiB,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,MAAM,CAAC,IAAA,gCAAgB,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wCAAwC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,CAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,CAAC,IAAA,gCAAgB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAChD,MAAM,KAAK,GAAoB;YAC3B,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,CAAC;YAC1B,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC;YAC7B,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YACrB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;SACtB,CAAC;QACF,MAAM,CAAC,IAAA,iCAAiB,EAAC,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxE,MAAM,CAAC,IAAA,2BAAW,EAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACjD,MAAM,CAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACzE,MAAM,CAAC,IAAA,kCAAkB,EAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uBAAuB,EAAE,GAAG,EAAE;QAC7B,wEAAwE;QACxE,yEAAyE;QACzE,gDAAgD;QAChD,MAAM,MAAM,GAAoB;YAC5B,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC;YAC7B,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC;SAC9B,CAAC;QACF,MAAM,GAAG,GAAG,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC1D,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gDAAgD,EAAE,GAAG,EAAE;QACtD,MAAM,QAAQ,GAAoB,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,CAAC,IAAA,iCAAiB,EAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACzE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QAC/D,MAAM,CAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,2CAA2C,EAAE,GAAG,EAAE;QACjD,MAAM,IAAI,GAAG,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC1C,MAAM,CAAC,IAAA,kCAAkB,EAAC,IAAI,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACtE,MAAM,CAAC,IAAA,2CAA2B,EAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;QAE9E,iEAAiE;QACjE,MAAM,CAAC,IAAA,kCAAkB,EAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpE,MAAM,CAAC,IAAA,2CAA2B,EAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;QAEnE,MAAM,CAAC,IAAA,kCAAkB,EAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACrD,MAAM,CAAC,IAAA,2CAA2B,EAAC,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAClE,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,8DAA8D,EAAE,GAAG,EAAE;QACpE,MAAM,iBAAiB,GAAoB;YACvC,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC;YAC7B,KAAK,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,CAAC;YAC7B,KAAK,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;YACrB,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC;SACtB,CAAC;QACF,MAAM,IAAI,GAAG,IAAA,iCAAiB,EAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC;QACrD,MAAM,CAAC,IAAA,2CAA2B,EAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAChC,MAAM,CAAC,IAAA,2BAAW,EAAC,IAAA,iCAAiB,EAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAC/E,MAAM,CAAC,IAAA,2BAAW,EAAC,IAAA,iCAAiB,EAAC,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACP,CAAC,CAAC,CAAC"}

package/package.json

@@ -2,7 +2,7 @@
   "private": false,
   "name": "placementt-core",
   "author": "Placementt",
-  "version": "1.400.1055",
+  "version": "1.400.1056",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "scripts": {

package/src/index.ts

@@ -31,6 +31,7 @@ export * from "./tutorialTips";
 export * from "./constants";
 export * from "./dataViewerReload";
 export * from "./hooks";
+export * from "./workflowBands";
 export * from "./util";
 export * from "./images/GatsbyBenchmarks";
 export * from "./databaseTypes";

package/src/typeDefinitions.ts

@@ -36,6 +36,10 @@ export type Products = "institutes"|"providers"|"students"|"admin";
 export type StudentPlacementData = {
     title: string,
     reqUserType: "Students" | "Staff" | "Provider" | "Parent",
+    reqUserTypes?: ("Students" | "Staff" | "Provider" | "Parent")[],
+    /** Set while a completion is claiming the band's single advance, so two
+     * parties finishing at once cannot both move the placement on. */
+    advancingFrom?: number,
     lastStageChange?: string // yyyy-mm-dd Set every time a stage changes!
     uid: string,
     startDate: string,
@@ -65,8 +69,6 @@ export type StudentPlacementData = {
     locality: string,
     postal_code: string,
     remote?: boolean;
-    // The employer contact for this placement is the student's parent or
-    // guardian, so parent and employer sign-off are the same person.
     parentIsEmployer?: boolean;
     what3Words?: string,
     country: string,
@@ -756,6 +758,7 @@ export type WorkflowStage = {
     buttons?: {id: number, name: string|false, description?: string, required: boolean}[],
     pos?: { x: number, y: number },
     userType?: "Students" | "Staff" | "Provider" | "Parent",
+    concurrentWithNext?: boolean,
     forms?: string[],
     files?: string[],
     deadline?: string,

package/src/workflowBands.test.ts

@@ -0,0 +1,111 @@
+import {getBandExitStageId, getBandHead, getBandName, getBandOutstanding,
+    getBandOutstandingUserTypes, getConcurrentBand, isConcurrentBand} from "./workflowBands";
+import {WorkflowStage} from "./typeDefinitions";
+
+describe("Concurrent bands", () => {
+    // A typical work experience chain: staff check, then employer review, then
+    // parental consent, then the placement start stage.
+    const stage = (id: number, userType: WorkflowStage["userType"], next?: number, concurrentWithNext?: boolean): WorkflowStage => ({
+        id,
+        name: `Stage ${id}`,
+        userType,
+        concurrentWithNext,
+        buttons: next === undefined ? [] : [{id: next, name: "Continue", required: true}],
+    });
+
+    const sequential: WorkflowStage[] = [
+        stage(1, "Students", 2),
+        stage(2, "Staff", 3),
+        stage(3, "Provider", 4),
+        stage(4, "Parent", 6),
+        stage(6, undefined),
+    ];
+
+    // Same workflow, but employer review and parental consent run together.
+    const banded: WorkflowStage[] = [
+        stage(1, "Students", 2),
+        stage(2, "Staff", 3),
+        stage(3, "Provider", 4, true),
+        stage(4, "Parent", 6),
+        stage(6, undefined),
+    ];
+
+    it("returns just the stage when nothing is marked concurrent", () => {
+        expect(getConcurrentBand(sequential, 3).map((s) => s.id)).toEqual([3]);
+        expect(getConcurrentBand(sequential, 4).map((s) => s.id)).toEqual([4]);
+        expect(isConcurrentBand(sequential, 3)).toBe(false);
+    });
+
+    it("resolves the same band from any member", () => {
+        expect(getConcurrentBand(banded, 3).map((s) => s.id)).toEqual([3, 4]);
+        expect(getConcurrentBand(banded, 4).map((s) => s.id)).toEqual([3, 4]);
+        expect(isConcurrentBand(banded, 3)).toBe(true);
+    });
+
+    it("resolves a band of three from the middle", () => {
+        const three: WorkflowStage[] = [
+            stage(2, "Staff", 3, true),
+            stage(3, "Provider", 4, true),
+            stage(4, "Parent", 6),
+            stage(6, undefined),
+        ];
+        expect(getConcurrentBand(three, 3).map((s) => s.id)).toEqual([2, 3, 4]);
+        expect(getBandHead(three, 4)?.id).toEqual(2);
+    });
+
+    it("does not pull in the stage after the band", () => {
+        expect(getConcurrentBand(banded, 3).some((s) => s.id === 6)).toBe(false);
+        expect(getBandExitStageId(getConcurrentBand(banded, 3))).toEqual(6);
+    });
+
+    it("terminates on a cycle", () => {
+        // The builder stops a school authoring this, but a hand-edited workflow
+        // must not hang or repeat a stage. A cycle has no real head, so only the
+        // membership is meaningful here, not the order.
+        const looped: WorkflowStage[] = [
+            stage(3, "Provider", 4, true),
+            stage(4, "Parent", 3, true),
+        ];
+        const ids = getConcurrentBand(looped, 3).map((s) => s.id);
+        expect(ids.slice().sort()).toEqual([3, 4]);
+        expect(new Set(ids).size).toEqual(ids.length);
+    });
+
+    it("terminates when a flagged stage points nowhere", () => {
+        const dangling: WorkflowStage[] = [stage(3, "Provider", undefined, true)];
+        expect(getConcurrentBand(dangling, 3).map((s) => s.id)).toEqual([3]);
+    });
+
+    it("returns nothing for a stage that is not in the workflow", () => {
+        expect(getConcurrentBand(banded, 99)).toEqual([]);
+    });
+
+    it("reports what the band is still waiting on", () => {
+        const band = getConcurrentBand(banded, 3);
+        expect(getBandOutstanding(band, []).map((s) => s.id)).toEqual([3, 4]);
+        expect(getBandOutstandingUserTypes(band, [])).toEqual(["Provider", "Parent"]);
+
+        // The employer has signed off, so only the parent is still owed.
+        expect(getBandOutstanding(band, [3]).map((s) => s.id)).toEqual([4]);
+        expect(getBandOutstandingUserTypes(band, [3])).toEqual(["Parent"]);
+
+        expect(getBandOutstanding(band, [3, 4])).toEqual([]);
+        expect(getBandOutstandingUserTypes(band, [3, 4])).toEqual([]);
+    });
+
+    it("does not repeat a user type that owns two stages in the band", () => {
+        const twoProviderStages: WorkflowStage[] = [
+            stage(3, "Provider", 4, true),
+            stage(4, "Provider", 5, true),
+            stage(5, "Parent", 6),
+            stage(6, undefined),
+        ];
+        const band = getConcurrentBand(twoProviderStages, 3);
+        expect(getBandOutstandingUserTypes(band, [])).toEqual(["Provider", "Parent"]);
+    });
+
+    it("names the band for staff", () => {
+        expect(getBandName(getConcurrentBand(banded, 3))).toEqual("Stage 3 & Stage 4");
+        expect(getBandName(getConcurrentBand(sequential, 3))).toEqual("Stage 3");
+    });
+});

package/src/workflowBands.ts

@@ -0,0 +1,82 @@
+import {WorkflowStage} from "./typeDefinitions";
+
+/**
+ * Concurrent sign-off bands.
+ *
+ * Deliberately free of any firebase import so it can be unit tested and pulled
+ * into the backend, the external review payload and the staff UI alike.
+ */
+
+/**
+ * The stage that starts the concurrent band `stageId` belongs to.
+ *
+ * A band is a run of stages chained by their first button where every stage but
+ * the last carries `concurrentWithNext`. The head is the stage a placement's
+ * `status` points at while the band is open, which is what lets `status` stay a
+ * single number: the band only changes who we ask, not where the placement is.
+ */
+export const getBandHead = (workflow: WorkflowStage[], stageId: number): WorkflowStage|undefined => {
+    let stage = workflow.find((s) => s.id === stageId);
+    if (!stage) return undefined;
+
+    const visited = new Set<number>([stage.id]);
+
+    for (;;) {
+        const previous = workflow.find((s) => s.concurrentWithNext && s.buttons?.[0]?.id === stage?.id);
+        // No flagged predecessor means we are already at the head.
+        if (!previous || visited.has(previous.id)) return stage;
+        visited.add(previous.id);
+        stage = previous;
+    }
+};
+
+/**
+ * Every stage that runs at the same time as `stageId`, in workflow order.
+ *
+ * Returns just the stage itself when nothing is marked concurrent, so callers can
+ * use this unconditionally and existing workflows behave exactly as before.
+ */
+export const getConcurrentBand = (workflow: WorkflowStage[], stageId: number): WorkflowStage[] => {
+    const head = getBandHead(workflow, stageId);
+    if (!head) return [];
+
+    const band = [head];
+    const visited = new Set<number>([head.id]);
+
+    let stage: WorkflowStage|undefined = head;
+    while (stage?.concurrentWithNext) {
+        const nextId: number|undefined = stage.buttons?.[0]?.id;
+        // A flagged stage with nowhere to go, or a loop, ends the band rather
+        // than stranding the caller.
+        if (nextId === undefined || visited.has(nextId)) break;
+        stage = workflow.find((s) => s.id === nextId);
+        if (!stage) break;
+        visited.add(stage.id);
+        band.push(stage);
+    }
+
+    return band;
+};
+
+/** True when the workflow asks more than one party at this point. */
+export const isConcurrentBand = (workflow: WorkflowStage[], stageId: number) =>
+    getConcurrentBand(workflow, stageId).length > 1;
+
+/** The band's stages that nobody has signed off yet. */
+export const getBandOutstanding = (band: WorkflowStage[], completedStages: number[] = []) =>
+    band.filter((stage) => !completedStages.includes(stage.id));
+
+/** Distinct user types the band is still waiting on, in workflow order. */
+export const getBandOutstandingUserTypes = (band: WorkflowStage[], completedStages: number[] = []) =>
+    getBandOutstanding(band, completedStages)
+        .map((stage) => stage.userType)
+        .filter((userType, i, all): userType is NonNullable<WorkflowStage["userType"]> =>
+            Boolean(userType) && all.indexOf(userType) === i);
+
+/** Where the placement goes once every stage in the band is signed off. */
+export const getBandExitStageId = (band: WorkflowStage[]) =>
+    band[band.length - 1]?.buttons?.[0]?.id;
+
+/** The label to show staff for a band, e.g. "Employer review & parental consent". */
+export const getBandName = (band: WorkflowStage[]) =>
+    band.map((stage) => stage.name).join(" & ");