diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 00000000..d74bd7fd --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,21 @@ +# Benefit Decision Toolkit + +Tools for building, previewing, and publishing benefit eligibility screeners. + +## Language + +**Screener**: +A form an author builds that asks people questions and tells them which benefits they may qualify for. +_Avoid_: Survey, questionnaire + +**Published screener**: +A snapshot of a screener that people being screened can open, on its own or from a connected CRM. +_Avoid_: Live screener, public form + +**Preview**: +The editor's view of a screener as a person being screened would see it, evaluated against the author's unpublished work. +_Avoid_: Test mode, sandbox + +**Screening session**: +One person's pass through a screener, in Preview or on a published screener: their answers, the evaluations of those answers, and the latest results. +_Avoid_: Screening flow, form session, evaluation flow diff --git a/builder-frontend/README.md b/builder-frontend/README.md index 1064ffb6..69d35ee7 100644 --- a/builder-frontend/README.md +++ b/builder-frontend/README.md @@ -29,7 +29,8 @@ Learn more about deploying your application with the [documentations](https://vi ## Screening results in custom form fields -Both live form renderers and the editor register `screeningResultsModule` from +The screening session (`src/components/shared/screeningSession/screeningSession.tsx`) +and the editor register `screeningResultsModule` from `src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.ts`. Each form has its own service. Preact custom fields can read its reactive snapshot with `useScreeningResults()` from the adjacent `useScreeningResults.ts`: @@ -44,7 +45,7 @@ arrive, including the debounce interval and failed requests. `failed` is true wh the latest evaluation failed, until one succeeds, so a field can show an error instead of waiting indefinitely. Previous results remain available while pending. Snapshots and their results are frozen copies; copy them before sorting or annotating. -The parents handle stale responses before updating the service. +The screening session drops outdated responses before updating the service. `mode` is `live` for published screeners and preview, and `editor` for sample results in the editing canvas. Editor samples use the configured benefit IDs and @@ -58,6 +59,14 @@ viewer fields. Consumers outside Preact can use `getSnapshot()` and `subscribe() on the service; `subscribe()` returns an unsubscribe function and updates fire `screeningResults.changed` on the form's event bus. +## Testing with a real form-js form + +Tests that type into a rendered form-js form use `src/testing/formJs.ts`. form-js +redraws a form about 60ms after an import, wiping anything typed before then, and +passes typed text on only after a 300ms pause or when the field loses focus +(`focusout`, which Preact uses for `onBlur`). The helpers wait out the redraw and +send `focusout` so each answer reaches the form at once. + ## Print summary Analysts can place a **Print summary** component anywhere in the form. It opens diff --git a/builder-frontend/src/components/screener/FormRenderer.test.tsx b/builder-frontend/src/components/screener/FormRenderer.test.tsx deleted file mode 100644 index 4533a1ef..00000000 --- a/builder-frontend/src/components/screener/FormRenderer.test.tsx +++ /dev/null @@ -1,288 +0,0 @@ -// @vitest-environment jsdom -import { createSignal } from "solid-js"; -import { render } from "solid-js/web"; -import { afterEach, describe, expect, it, vi } from "vitest"; -import FormRenderer from "./FormRenderer"; - -const schema = { - type: "default", - id: "Form_test", - schemaVersion: 18, - components: [ - { - type: "checkbox", - id: "cash", - key: "custom.wantsExtraCash", - label: "Interested in cash assistance", - }, - { type: "textfield", id: "city", key: "custom.city", label: "City" }, - { - type: "checkbox", - id: "resident", - key: "simpleChecks.livesInPhiladelphiaPa", - label: "Philadelphia resident", - }, - ], -}; - -describe("FormRenderer host prefill", () => { - let dispose: (() => void) | undefined; - afterEach(() => { - dispose?.(); - document.body.innerHTML = ""; - }); - - it("exports only the currently visible saved content and unregisters on unmount", async () => { - const register = vi.fn(); - const container = document.body.appendChild(document.createElement("div")); - dispose = render( - () => ( - ({ show: true })} - hiddenQuestionPaths={() => []} - submitForm={() => {}} - registerNextStepsProvider={register} - /> - ), - container, - ); - await vi.waitFor(() => expect(register).toHaveBeenCalledOnce()); - const results = { - benefit: { name: "Benefit", result: "TRUE" as const, check_results: {} }, - }; - const provider = register.mock.calls[0][0]; - expect(provider(results).benefit.body.text).toBe("Saved instructions"); - container - .querySelector('input[type="checkbox"]')! - .click(); - // Follows the answers at once, without waiting for form-js to repaint. - expect(provider(results)).toBeUndefined(); - dispose(); - dispose = undefined; - expect(register).toHaveBeenLastCalledWith(undefined); - }); - - it("reads visibility from conditions, including groups, while the form re-imports", async () => { - const register = vi.fn(); - const [hidden, setHidden] = createSignal([]); - const content = (body: string) => ({ - benefit: { eligible: { body } }, - }); - dispose = render( - () => ( - ({})} - hiddenQuestionPaths={hidden} - submitForm={() => {}} - registerNextStepsProvider={register} - /> - ), - document.body.appendChild(document.createElement("div")), - ); - await vi.waitFor(() => expect(register).toHaveBeenCalledOnce()); - const results = { - benefit: { name: "Benefit", result: "TRUE" as const, check_results: {} }, - }; - const provider = register.mock.calls[0][0]; - expect(provider(results).benefit.body.text).toBe("Shown group"); - // Hiding a question re-imports the form; the export must not see a gap. - setHidden(["city"]); - expect(provider(results).benefit.body.text).toBe("Shown group"); - }); - - it("exports visible instructions from a dynamic list with repetition disabled", async () => { - const register = vi.fn(); - const container = document.body.appendChild(document.createElement("div")); - dispose = render( - () => ( - ({ person: { show: true } })} - hiddenQuestionPaths={() => []} - submitForm={() => {}} - registerNextStepsProvider={register} - /> - ), - container, - ); - await vi.waitFor(() => expect(register).toHaveBeenCalledOnce()); - const exported = register.mock.calls[0][0]({ - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }); - expect(exported.benefit.body.text).toBe("Single-person instructions"); - }); - - it.each([ - [[{ show: false }, { show: true }], "Per item"], - [[{ show: false }], undefined], - ])( - "checks Next steps in a repeated group against each item (%j)", - async (people, body) => { - const register = vi.fn(); - dispose = render( - () => ( - ({ people })} - hiddenQuestionPaths={() => []} - submitForm={() => {}} - registerNextStepsProvider={register} - /> - ), - document.body.appendChild(document.createElement("div")), - ); - await vi.waitFor(() => expect(register).toHaveBeenCalledOnce()); - const exported = register.mock.calls[0][0]({ - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }); - expect(exported?.benefit.body?.text).toBe(body); - }, - ); - - it("evaluates unknown host answers as null until the user answers them", async () => { - const submitForm = vi.fn(); - const container = document.body.appendChild(document.createElement("div")); - dispose = render( - () => ( - ({ - custom: { wantsExtraCash: null }, - simpleChecks: { livesInPhiladelphiaPa: false }, - })} - hiddenQuestionPaths={() => []} - submitForm={submitForm} - evaluateInitialData - /> - ), - container, - ); - await vi.waitFor(() => expect(submitForm).toHaveBeenCalledOnce()); - expect(submitForm).toHaveBeenLastCalledWith({ - custom: { wantsExtraCash: null, city: null }, - simpleChecks: { livesInPhiladelphiaPa: false }, - }); - - const cash = container.querySelector( - 'input[type="checkbox"]', - )!; - cash.click(); - cash.click(); - await vi.waitFor(() => expect(submitForm).toHaveBeenCalledTimes(2), { - timeout: 3000, - }); - expect(submitForm).toHaveBeenLastCalledWith({ - custom: { wantsExtraCash: false, city: null }, - simpleChecks: { livesInPhiladelphiaPa: false }, - }); - }); -}); diff --git a/builder-frontend/src/components/screener/FormRenderer.tsx b/builder-frontend/src/components/screener/FormRenderer.tsx deleted file mode 100644 index 9b82e890..00000000 --- a/builder-frontend/src/components/screener/FormRenderer.tsx +++ /dev/null @@ -1,149 +0,0 @@ -import { Accessor, createEffect, on, onCleanup, onMount } from "solid-js"; - -import debounce from "lodash.debounce"; -import cloneDeep from "lodash/cloneDeep"; -import isEqual from "lodash/isEqual"; -import { Form } from "@bpmn-io/form-js-viewer"; -import { State } from "@bpmn-io/form-js-viewer/dist/types/Form"; - -import CustomFormFieldsModule from "../screenerEditor/formJsExtensions/customFormFields"; -import { - connectScreeningResults, - screeningResultsModule, -} from "../screenerEditor/formJsExtensions/screeningResults/screeningResults"; -import { firstVisibleNextSteps } from "../screenerEditor/formJsExtensions/nextSteps/selection"; -import { - projectNextSteps, - type NextStepsProvider, -} from "@/integrations/nextSteps"; -import type { ScreenerResult } from "@/types"; -import { hideQuestions } from "@/utils/questionVotes"; -import { normalizeArrayFieldData } from "@/utils/arrayFieldData"; -import { - findFilledUnknownPaths, - keepUnansweredPaths, - restoreUnknownAnswers, -} from "@/utils/unknownAnswers"; - -import "@bpmn-io/form-js/dist/assets/form-js.css"; - -function FormRenderer({ - schema, - formData, - hiddenQuestionPaths, - submitForm, - evaluateInitialData = false, - onDataChange, - results = () => undefined, - pending = () => false, - failed = () => false, - onNextStepsShownChange, - screenerName, - registerNextStepsProvider, -}: { - registerNextStepsProvider?: (provider: NextStepsProvider | undefined) => void; - schema: { [key: string]: any }; - formData: Accessor; - hiddenQuestionPaths: Accessor; - submitForm: (data: any) => void; - /** Evaluate host prefill on load, keeping its unknown answers null until answered. */ - evaluateInitialData?: boolean; - onDataChange?: () => void; - screenerName?: Accessor; - results?: Accessor; - pending?: Accessor; - failed?: Accessor; - /** Whether a Next steps field is rendered, so the page can skip its own completion message. */ - onNextStepsShownChange?: (shown: boolean) => void; -}) { - let container: Element | null = null; - let form: Form | undefined; - let currentData: any = {}; - let importing = false; - let disposed = false; - let unknownPaths: string[][] = []; - const evaluationData = (data: any) => - normalizeArrayFieldData(schema, restoreUnknownAnswers(data, unknownPaths)); - - const importVisibleSchema = async () => { - if (!form) return; - importing = true; - try { - // Preserve the live form state, not the last submitted data: answers - // typed since the pending submit would otherwise be discarded. - const preservedData = cloneDeep(currentData); - await form.importSchema( - hideQuestions(schema, hiddenQuestionPaths()), - preservedData, - ); - } finally { - importing = false; - } - }; - - createEffect( - on(hiddenQuestionPaths, () => void importVisibleSchema(), { defer: true }), - ); - - onMount(() => { - form = new Form({ - container, - additionalModules: [CustomFormFieldsModule, screeningResultsModule], - }); - connectScreeningResults(form, { - schema: () => schema, - evaluatedAnswers: formData, - results, - screenerName, - pending, - failed, - onNextStepsShownChange, - }); - currentData = cloneDeep(formData()); - - const debouncedSubmit = debounce((data) => { - submitForm(evaluationData(data)); - }, 1000); - - form - .importSchema(hideQuestions(schema, hiddenQuestionPaths()), formData()) - .then(() => { - if (disposed) return; - registerNextStepsProvider?.((results) => - projectNextSteps( - results, - firstVisibleNextSteps((name) => form!.get(name)), - ), - ); - currentData = cloneDeep(form?._getState().data || formData()); - if (evaluateInitialData) { - unknownPaths = findFilledUnknownPaths(formData(), currentData); - submitForm(evaluationData(currentData)); - } - form?.on("changed", (event: State) => { - const dataChanged = !isEqual(currentData, event.data); - currentData = cloneDeep(event.data); - if (importing || !dataChanged) return; - unknownPaths = keepUnansweredPaths(unknownPaths, event.data); - onDataChange?.(); - debouncedSubmit(event.data); - }); - }) - .catch(console.error); - - onCleanup(() => { - disposed = true; - registerNextStepsProvider?.(undefined); - debouncedSubmit.cancel(); - form?.destroy(); - }); - }); - - return ( -
-
(container = el)} /> -
- ); -} - -export default FormRenderer; diff --git a/builder-frontend/src/components/screener/Screener.test.tsx b/builder-frontend/src/components/screener/Screener.test.tsx index f20adaa2..fb12b19f 100644 --- a/builder-frontend/src/components/screener/Screener.test.tsx +++ b/builder-frontend/src/components/screener/Screener.test.tsx @@ -1,5 +1,4 @@ // @vitest-environment jsdom -import { onMount } from "solid-js"; import { render } from "solid-js/web"; import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import Screener from "./Screener"; @@ -8,6 +7,7 @@ import { fetchPublishedScreener, } from "@/api/publishedScreener"; import type { ScreenerResult } from "@/types"; +import { input, settle, type, until } from "@/testing/formJs"; const integration = vi.hoisted(() => ({ enabled: true, @@ -21,8 +21,15 @@ const integration = vi.hoisted(() => ({ error: vi.fn(), fail: vi.fn(), origin: "https://crm.example", - registerNextStepsProvider: undefined as unknown, })); +const formSchema = { + type: "default", + id: "published-test", + schemaVersion: 18, + components: [ + { id: "city", type: "textfield", key: "custom.city", label: "City" }, + ], +}; vi.mock("@solidjs/router", () => ({ useParams: () => ({ publishedScreenerId: "published-id" }), @@ -30,7 +37,7 @@ vi.mock("@solidjs/router", () => ({ vi.mock("@/api/publishedScreener", () => ({ fetchPublishedScreener: vi.fn(async () => ({ screenerName: "Test", - formSchema: {}, + formSchema, integrationOrigins: ["https://crm.example"], })), evaluatePublishedScreener: vi.fn(), @@ -48,42 +55,10 @@ vi.mock("@/integrations/screenerBridge", () => ({ return integration.enabled ? integration : undefined; }, })); -vi.mock("./FormRenderer", () => ({ - default: (props: any) => { - integration.registerNextStepsProvider = props.registerNextStepsProvider; - onMount(() => { - if (props.evaluateInitialData) props.submitForm(props.formData()); - }); - return ( - <> - - - - ); - }, -})); - const result = (value: "TRUE" | "FALSE"): ScreenerResult => ({ benefit: { name: "Benefit", result: value, check_results: {} }, }); -const initialData = { custom: { householdIncome: 30000 } }; -function deferred() { - let resolve!: (value: ScreenerResult) => void; - let reject!: (error: Error) => void; - const promise = new Promise((yes, no) => { - resolve = yes; - reject = no; - }); - return { promise, resolve, reject }; -} +const initialData = { custom: { city: "Philadelphia" } }; describe("published screener integration lifecycle", () => { let container: HTMLDivElement; @@ -98,73 +73,59 @@ describe("published screener integration lifecycle", () => { afterEach(() => { dispose?.(); container.remove(); + vi.restoreAllMocks(); }); - it("waits for prefill, then ignores an old response when a newer evaluation finishes", async () => { - const old = deferred(); + it("waits for prefill, then sends results for the latest answers to the host", async () => { vi.mocked(evaluatePublishedScreener) - .mockReturnValueOnce(old.promise) + .mockResolvedValueOnce(result("TRUE")) .mockResolvedValueOnce(result("FALSE")); dispose = render(() => , container); await vi.waitFor(() => expect(integration.start).toHaveBeenCalledOnce()); expect(container.textContent).toContain("Waiting for information"); expect(evaluatePublishedScreener).not.toHaveBeenCalled(); integration.initialize!(initialData); - await vi.waitFor(() => - expect(evaluatePublishedScreener).toHaveBeenCalledWith( - "published-id", + await until(() => + expect(integration.result).toHaveBeenCalledExactlyOnceWith( initialData, + result("TRUE"), + undefined, ), ); - expect(integration.registerNextStepsProvider).toBeTypeOf("function"); - container.querySelector("button")!.click(); - await vi.waitFor(() => expect(integration.result).toHaveBeenCalledOnce()); + expect(evaluatePublishedScreener).toHaveBeenCalledWith( + "published-id", + initialData, + ); + expect(input("City")!.value).toBe("Philadelphia"); + + await settle(); + type("City", "Pittsburgh"); + await until(() => expect(integration.result).toHaveBeenCalledTimes(2)); expect(integration.result).toHaveBeenLastCalledWith( - { custom: { householdIncome: 50000 } }, + { custom: { city: "Pittsburgh" } }, result("FALSE"), undefined, ); - old.resolve(result("TRUE")); - await old.promise; - expect(integration.result).toHaveBeenCalledOnce(); expect(container.textContent).toContain("Ineligible"); }); - it("does not send an old evaluation to the CRM after an edit awaiting submission", async () => { - const old = deferred(); - vi.mocked(evaluatePublishedScreener).mockReturnValueOnce(old.promise); + it("tells the person and the host when evaluating the latest answers fails", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.mocked(evaluatePublishedScreener).mockRejectedValueOnce( + new Error("Unavailable"), + ); dispose = render(() => , container); integration.initialize!(initialData); - await vi.waitFor(() => - expect(evaluatePublishedScreener).toHaveBeenCalledOnce(), - ); - container.querySelectorAll("button")[1].click(); - old.resolve(result("TRUE")); - await old.promise; + await until(() => expect(integration.error).toHaveBeenCalledOnce()); + expect(container.textContent).toContain("We couldn't update your results"); expect(integration.result).not.toHaveBeenCalled(); - expect(container.textContent).not.toContain("Eligible"); }); - it("ignores old failures and pending responses after unmount", async () => { - const old = deferred(); - const current = deferred(); - vi.mocked(evaluatePublishedScreener) - .mockReturnValueOnce(old.promise) - .mockReturnValueOnce(current.promise); + it("disposes the bridge when the page closes", async () => { dispose = render(() => , container); - integration.initialize!(initialData); - await vi.waitFor(() => - expect(evaluatePublishedScreener).toHaveBeenCalledOnce(), - ); - container.querySelector("button")!.click(); - old.reject(new Error("Old request failed")); - await old.promise.catch(() => {}); - expect(integration.error).not.toHaveBeenCalled(); + await vi.waitFor(() => expect(integration.start).toHaveBeenCalledOnce()); dispose(); expect(integration.dispose).toHaveBeenCalledOnce(); - current.resolve(result("TRUE")); - await current.promise; - expect(integration.result).not.toHaveBeenCalled(); }); it("tells the user and the host when the screener can't be loaded", async () => { @@ -180,7 +141,7 @@ describe("published screener integration lifecycle", () => { expect(container.textContent).not.toContain("Waiting for information"); integration.initialize!(initialData); await Promise.resolve(); - expect(container.querySelector("button")).toBeNull(); + expect(input("City")).toBeUndefined(); }); it("starts the bridge only after the screener loads", async () => { @@ -193,7 +154,7 @@ describe("published screener integration lifecycle", () => { expect(integration.start).not.toHaveBeenCalled(); load({ screenerName: "Test", - formSchema: {}, + formSchema, integrationOrigins: ["https://crm.example"], }); await vi.waitFor(() => expect(integration.start).toHaveBeenCalledOnce()); @@ -203,7 +164,7 @@ describe("published screener integration lifecycle", () => { it("refuses a host whose origin the screener doesn't allow", async () => { vi.mocked(fetchPublishedScreener).mockResolvedValueOnce({ screenerName: "Test", - formSchema: {}, + formSchema, integrationOrigins: ["https://other-crm.example"], }); vi.mocked(evaluatePublishedScreener).mockResolvedValue(result("TRUE")); @@ -212,9 +173,7 @@ describe("published screener integration lifecycle", () => { expect(integration.fail).toHaveBeenCalledExactlyOnceWith( "ORIGIN_NOT_ALLOWED", ); - await vi.waitFor(() => - expect(container.querySelector("button")).not.toBeNull(), - ); + await until(() => expect(input("City")).toBeDefined()); expect(container.textContent).toContain( "isn’t set up to send results to https://crm.example", ); @@ -229,9 +188,7 @@ describe("published screener integration lifecycle", () => { dispose = render(() => , container); await vi.waitFor(() => expect(integration.start).toHaveBeenCalledOnce()); integration.disconnect!("timeout"); - await vi.waitFor(() => - expect(container.querySelector("button")).not.toBeNull(), - ); + await until(() => expect(input("City")).toBeDefined()); expect(container.textContent).not.toContain("Waiting for information"); expect(container.textContent).toContain("couldn’t connect"); expect(evaluatePublishedScreener).not.toHaveBeenCalled(); @@ -248,7 +205,7 @@ describe("published screener integration lifecycle", () => { await vi.waitFor(() => expect(container.textContent).toContain("no longer connected"), ); - expect(container.querySelector("button")).not.toBeNull(); + expect(input("City")).toBeDefined(); expect(evaluatePublishedScreener).toHaveBeenCalledOnce(); }); @@ -256,14 +213,12 @@ describe("published screener integration lifecycle", () => { integration.enabled = false; vi.mocked(evaluatePublishedScreener).mockResolvedValue(result("TRUE")); dispose = render(() => , container); - await vi.waitFor(() => - expect(container.querySelector("button")).not.toBeNull(), - ); + await until(() => expect(input("City")).toBeDefined()); expect(container.textContent).not.toContain("Waiting for information"); expect(evaluatePublishedScreener).not.toHaveBeenCalled(); - container.querySelector("button")!.click(); - await vi.waitFor(() => expect(container.textContent).toContain("Eligible")); + await settle(); + type("City", "Pittsburgh"); + await until(() => expect(container.textContent).toContain("Eligible")); expect(integration.result).not.toHaveBeenCalled(); - expect(integration.registerNextStepsProvider).toBeUndefined(); }); }); diff --git a/builder-frontend/src/components/screener/Screener.tsx b/builder-frontend/src/components/screener/Screener.tsx index 0b386788..c009b7c4 100644 --- a/builder-frontend/src/components/screener/Screener.tsx +++ b/builder-frontend/src/components/screener/Screener.tsx @@ -1,14 +1,12 @@ import { createSignal, createResource, - createMemo, createEffect, Show, onCleanup, } from "solid-js"; import { useParams } from "@solidjs/router"; -import FormRenderer from "./FormRenderer"; import Loading from "@/components/Loading"; import EligibilityResults from "./EligibilityResults"; @@ -19,14 +17,16 @@ import { import HiddenQuestionsNotice from "@/components/shared/HiddenQuestionsNotice"; import ScreeningComplete from "@/components/shared/ScreeningComplete"; +import { + createScreeningSession, + type ScreeningAnswers, +} from "@/components/shared/screeningSession/screeningSession"; -import type { PublishedScreener, ScreenerResult } from "@/types"; +import type { PublishedScreener } from "@/types"; import { - getUnneededQuestionPaths, - haveSameQuestionPaths, -} from "@/utils/questionVotes"; -import type { NextStepsProvider } from "@/integrations/nextSteps"; -import { createScreeningBridge } from "@/integrations/screenerBridge"; + createScreeningBridge, + type ScreeningBridge, +} from "@/integrations/screenerBridge"; export default function Screener() { const params = useParams(); @@ -34,14 +34,14 @@ export default function Screener() { const [screener] = createResource(() => fetchPublishedScreener(params.publishedScreenerId), ); - const [screenerResult, setScreenerResult] = createSignal(); - const [formData, setFormData] = createSignal({}); + // Answers a connected host provided; a standalone screener has none. + const [hostAnswers, setHostAnswers] = createSignal(); const [disconnectReason, setDisconnectReason] = createSignal< "timeout" | "closed" | "notAllowed" >(); const bridge = createScreeningBridge(params.publishedScreenerId, { initialize: (data) => { - setFormData(data); + setHostAnswers(data); setIntegrationReady(true); }, // Keep the form usable, but make clear results no longer reach the host. @@ -51,8 +51,6 @@ export default function Screener() { }, }); const [integrationReady, setIntegrationReady] = createSignal(!bridge); - let evaluationSequence = 0; - let nextStepsProvider: NextStepsProvider | undefined; // Start once the screener loads, so the host's origin can be checked against // the origins its builder allowed. Only an allowed host gets answers. let bridgeStarted = false; @@ -70,54 +68,7 @@ export default function Screener() { bridgeStarted = true; bridge.start(); }); - onCleanup(() => { - evaluationSequence++; - bridge?.dispose(); - }); - // True from an edit until results for the latest answers arrive, so a failed evaluation - // keeps the previous results visible without announcing that screening is complete. - const [resultsStale, setResultsStale] = createSignal(false); - const [evaluationFailed, setEvaluationFailed] = createSignal(false); - const [showAllQuestions, setShowAllQuestions] = createSignal(false); - // A rendered Next steps field shows completion in its heading instead. - const [nextStepsShown, setNextStepsShown] = createSignal(false); - const unneededQuestionPaths = createMemo( - () => getUnneededQuestionPaths(screenerResult()), - undefined, - { equals: haveSameQuestionPaths }, - ); - const hiddenQuestionPaths = createMemo( - () => (showAllQuestions() ? [] : unneededQuestionPaths()), - undefined, - { equals: haveSameQuestionPaths }, - ); - - const submitForm = async (data: any) => { - const sequence = ++evaluationSequence; - setResultsStale(true); - try { - setFormData(data); - let evaluationResult: ScreenerResult = await evaluatePublishedScreener( - params.publishedScreenerId, - data, - ); - if (sequence !== evaluationSequence) return; - setScreenerResult(evaluationResult); - setResultsStale(false); - setEvaluationFailed(false); - bridge?.result( - data, - evaluationResult, - nextStepsProvider?.(evaluationResult), - ); - } catch (err) { - if (sequence !== evaluationSequence) return; - setEvaluationFailed(true); - bridge?.error(); - console.log(err); - } - }; - + onCleanup(() => bridge?.dispose()); return (
{screener.loading && } @@ -146,59 +97,68 @@ export default function Screener() {

)} - {!screener.error && screener() && integrationReady() && ( -
-
- { - nextStepsProvider = provider; - }) - } - screenerName={() => screener()?.screenerName ?? ""} - schema={screener()?.formSchema || {}} - formData={formData} - hiddenQuestionPaths={hiddenQuestionPaths} - results={screenerResult} - pending={resultsStale} - failed={evaluationFailed} - submitForm={submitForm} - evaluateInitialData={!!bridge && !disconnectReason()} - onNextStepsShownChange={setNextStepsShown} - onDataChange={() => { - evaluationSequence++; - setResultsStale(true); - }} - /> - - - - - - - unneededQuestionPaths().length} - showAllQuestions={showAllQuestions} - onToggleShowAllQuestions={() => - setShowAllQuestions((current) => !current) - } - /> -
- -
- -
-
-
- )} + + +
); } + +function PublishedScreening(props: { + publishedScreenerId: string; + screener: PublishedScreener; + initialAnswers?: ScreeningAnswers; + bridge?: ScreeningBridge; +}) { + const { bridge } = props; + const session = createScreeningSession({ + schema: () => props.screener.formSchema || {}, + evaluate: (answers) => + evaluatePublishedScreener(props.publishedScreenerId, answers), + initialAnswers: props.initialAnswers, + // A connected host expects results for its answers right away. + evaluateOnLoad: props.initialAnswers !== undefined, + screenerName: () => props.screener.screenerName ?? "", + // Only a CRM host receives next steps; standalone screeners skip the projection. + onResults: + bridge && + ((answers, results) => + bridge.result(answers, results, session.projectNextSteps(results))), + onEvaluationFailed: bridge && (() => bridge.error()), + }); + + return ( +
+
+ + + + + + + + +
+ +
+ +
+
+
+ ); +} diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.integration.test.tsx b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.integration.test.tsx index 49854de9..8d1906fe 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.integration.test.tsx +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.integration.test.tsx @@ -1,10 +1,10 @@ // @vitest-environment jsdom -import { createSignal } from "solid-js"; -import { render } from "solid-js/web"; +import { createRoot, createSignal } from "solid-js"; import { h } from "preact"; import { afterEach, describe, expect, it, vi } from "vitest"; import type { ScreenerResult } from "@/types"; import { + connectScreeningResults, screeningResultsModule, type ScreeningResultsService, } from "./screeningResults"; @@ -29,8 +29,6 @@ vi.mock("@bpmn-io/form-js-viewer", async (importOriginal) => { }); import { Form, Text } from "@bpmn-io/form-js-viewer"; import { FormEditor } from "@bpmn-io/form-js-editor"; -import PublishedForm from "@/components/screener/FormRenderer"; -import PreviewForm from "@/components/screenerEditor/preview/FormRenderer"; function Probe() { return h( @@ -57,187 +55,178 @@ const schema = { ], }; -describe.each(["published", "preview"])( - "screening results in the real %s form", - (mode) => { - const disposers: (() => void)[] = []; - afterEach(() => { - disposers.splice(0).forEach((dispose) => dispose()); - forms.length = 0; - document.body.replaceChildren(); - }); +describe("screening results in a real form", () => { + const disposers: (() => void)[] = []; + afterEach(() => { + disposers.splice(0).forEach((dispose) => dispose()); + forms.length = 0; + document.body.replaceChildren(); + }); - async function mount( - data: object = { answer: "Keep this answer" }, - formSchema: object = schema, - ) { - const [results, setResults] = createSignal(); - const [pending, setPending] = createSignal(false); - const [failed, setFailed] = createSignal(false); - const container = document.body.appendChild( - document.createElement("div"), - ); - const common = { - formData: () => data, - hiddenQuestionPaths: () => [], - submitForm: vi.fn(), + async function mount( + data: object = { answer: "Keep this answer" }, + formSchema: object = schema, + ) { + const [results, setResults] = createSignal(); + const [pending, setPending] = createSignal(false); + const [failed, setFailed] = createSignal(false); + const container = document.body.appendChild(document.createElement("div")); + const form = new Form({ + container, + additionalModules: [screeningResultsModule], + }); + createRoot((dispose) => { + disposers.push(() => { + dispose(); + form.destroy(); + }); + connectScreeningResults(form, { + schema: () => formSchema as any, + evaluatedAnswers: () => data, results, pending, failed, - }; - disposers.push( - render( - () => - mode === "published" ? ( - - ) : ( - formSchema} {...common} /> - ), - container, - ), - ); - await vi.waitFor(() => - expect(container.querySelector("output")).not.toBeNull(), - ); - const form = forms[forms.length - 1]; - const snapshot = () => - JSON.parse(container.querySelector("output")!.textContent!); - return { - container, - form, - snapshot, - setResults, - setPending, - setFailed, - common, - }; - } + }); + }); + await form.importSchema(formSchema, data); + await vi.waitFor(() => + expect(container.querySelector("output")).not.toBeNull(), + ); + const snapshot = () => + JSON.parse(container.querySelector("output")!.textContent!); + return { + container, + form, + snapshot, + setResults, + setPending, + setFailed, + }; + } - it("maps unanswered inputs to question labels and clears them after a decision", async () => { - const s = await mount({ answer: "" }); - s.setResults({ - benefit: { - name: "Benefit", - result: "UNABLE_TO_DETERMINE", - check_results: { - missing: { - result: "UNABLE_TO_DETERMINE", - inputPaths: ["answer"], - } as any, - }, + it("maps unanswered inputs to question labels and clears them after a decision", async () => { + const s = await mount({ answer: "" }); + s.setResults({ + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { + missing: { + result: "UNABLE_TO_DETERMINE", + inputPaths: ["answer"], + } as any, }, - }); - await vi.waitFor(() => - expect(s.snapshot().unansweredQuestions).toEqual({ - benefit: ["Answer"], - }), - ); - expect(s.snapshot()).not.toHaveProperty("answers"); - const service = s.form.get("screeningResults") as ScreeningResultsService; - const questions = service.getSnapshot().unansweredQuestions; - s.setResults({ - benefit: { - name: "Benefit", - result: "UNABLE_TO_DETERMINE", - check_results: { - missing: { - result: "UNABLE_TO_DETERMINE", - inputPaths: ["answer"], - } as any, - }, + }, + }); + await vi.waitFor(() => + expect(s.snapshot().unansweredQuestions).toEqual({ + benefit: ["Answer"], + }), + ); + expect(s.snapshot()).not.toHaveProperty("answers"); + const service = s.form.get("screeningResults") as ScreeningResultsService; + const questions = service.getSnapshot().unansweredQuestions; + s.setResults({ + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { + missing: { + result: "UNABLE_TO_DETERMINE", + inputPaths: ["answer"], + } as any, }, - }); - expect(service.getSnapshot().unansweredQuestions).toBe(questions); - s.setResults({ - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }); - await vi.waitFor(() => - expect(s.snapshot().unansweredQuestions).toEqual({}), - ); + }, }); + expect(service.getSnapshot().unansweredQuestions).toBe(questions); + s.setResults({ + benefit: { name: "Benefit", result: "TRUE", check_results: {} }, + }); + await vi.waitFor(() => + expect(s.snapshot().unansweredQuestions).toEqual({}), + ); + }); - it("leaves out unanswered questions a condition hides", async () => { - const s = await mount( - { answer: "", married: false }, - { - ...schema, - components: [ - ...schema.components, - { - id: "married", - type: "checkbox", - key: "married", - label: "Married", - }, - { - id: "spouseIncome", - type: "number", - key: "spouse.income", - label: "Spouse income", - conditional: { hide: "=married != true" }, - }, - ], - }, - ); - s.setResults({ - benefit: { - name: "Benefit", - result: "UNABLE_TO_DETERMINE", - check_results: { - missing: { - result: "UNABLE_TO_DETERMINE", - inputPaths: ["answer", "spouse.income"], - } as any, + it("leaves out unanswered questions a condition hides", async () => { + const s = await mount( + { answer: "", married: false }, + { + ...schema, + components: [ + ...schema.components, + { + id: "married", + type: "checkbox", + key: "married", + label: "Married", }, + { + id: "spouseIncome", + type: "number", + key: "spouse.income", + label: "Spouse income", + conditional: { hide: "=married != true" }, + }, + ], + }, + ); + s.setResults({ + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { + missing: { + result: "UNABLE_TO_DETERMINE", + inputPaths: ["answer", "spouse.income"], + } as any, }, - }); - await vi.waitFor(() => - expect(s.snapshot().unansweredQuestions).toEqual({ - benefit: ["Answer"], - }), - ); + }, }); + await vi.waitFor(() => + expect(s.snapshot().unansweredQuestions).toEqual({ + benefit: ["Answer"], + }), + ); + }); - it("updates custom fields without reimporting the schema or submitting answers", async () => { - const s = await mount(); - const importSchema = vi.spyOn(s.form, "importSchema"); - const decided: ScreenerResult = { - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }; - s.setResults(decided); - await vi.waitFor(() => expect(s.snapshot().results).toEqual(decided)); - s.setPending(true); - await vi.waitFor(() => expect(s.snapshot().pending).toBe(true)); - expect(s.snapshot().results).toEqual(decided); - s.setFailed(true); - await vi.waitFor(() => expect(s.snapshot().failed).toBe(true)); - expect(s.snapshot().pending).toBe(true); - s.setFailed(false); - s.setResults({ - benefit: { ...decided.benefit, result: "UNABLE_TO_DETERMINE" }, - }); - - s.setPending(false); - await vi.waitFor(() => expect(s.snapshot().pending).toBe(false)); - expect(s.snapshot().results.benefit.result).toBe("UNABLE_TO_DETERMINE"); - expect(s.form._getState().data).toEqual({ answer: "Keep this answer" }); - expect(importSchema).not.toHaveBeenCalled(); - expect(s.common.submitForm).not.toHaveBeenCalled(); - expect(s.snapshot().mode).toBe("live"); + it("updates custom fields without reimporting the schema", async () => { + const s = await mount(); + const importSchema = vi.spyOn(s.form, "importSchema"); + const decided: ScreenerResult = { + benefit: { name: "Benefit", result: "TRUE", check_results: {} }, + }; + s.setResults(decided); + await vi.waitFor(() => expect(s.snapshot().results).toEqual(decided)); + s.setPending(true); + await vi.waitFor(() => expect(s.snapshot().pending).toBe(true)); + expect(s.snapshot().results).toEqual(decided); + s.setFailed(true); + await vi.waitFor(() => expect(s.snapshot().failed).toBe(true)); + expect(s.snapshot().pending).toBe(true); + s.setFailed(false); + s.setResults({ + benefit: { ...decided.benefit, result: "UNABLE_TO_DETERMINE" }, }); - it("isolates service state between simultaneous forms", async () => { - const first = await mount(); - const second = await mount(); - first.setPending(true); - await vi.waitFor(() => expect(first.snapshot().pending).toBe(true)); - expect(second.snapshot().pending).toBe(false); - expect(first.form.get("screeningResults")).not.toBe( - second.form.get("screeningResults"), - ); - }); - }, -); + s.setPending(false); + await vi.waitFor(() => expect(s.snapshot().pending).toBe(false)); + expect(s.snapshot().results.benefit.result).toBe("UNABLE_TO_DETERMINE"); + expect(s.form._getState().data).toEqual({ answer: "Keep this answer" }); + expect(importSchema).not.toHaveBeenCalled(); + expect(s.snapshot().mode).toBe("live"); + }); + + it("isolates service state between simultaneous forms", async () => { + const first = await mount(); + const second = await mount(); + first.setPending(true); + await vi.waitFor(() => expect(first.snapshot().pending).toBe(true)); + expect(second.snapshot().pending).toBe(false); + expect(first.form.get("screeningResults")).not.toBe( + second.form.get("screeningResults"), + ); + }); +}); it("renders custom fields with no results in a form without the module", async () => { const container = document.body.appendChild(document.createElement("div")); diff --git a/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx b/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx deleted file mode 100644 index 6405373e..00000000 --- a/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx +++ /dev/null @@ -1,121 +0,0 @@ -import { Accessor, createEffect, on, onCleanup, onMount } from "solid-js"; -import debounce from "lodash.debounce"; -import cloneDeep from "lodash/cloneDeep"; -import isEqual from "lodash/isEqual"; - -import { Form } from "@bpmn-io/form-js-viewer"; - -import { PreviewFormData } from "./types"; -import CustomFormFieldsModule from "../formJsExtensions/customFormFields"; -import { - connectScreeningResults, - screeningResultsModule, -} from "../formJsExtensions/screeningResults/screeningResults"; -import type { ScreenerResult } from "@/types"; -import { hideQuestions } from "@/utils/questionVotes"; -import { normalizeArrayFieldData } from "@/utils/arrayFieldData"; - -import "@bpmn-io/form-js/dist/assets/form-js.css"; - -function FormRenderer({ - schema, - formData, - hiddenQuestionPaths, - submitForm, - onDataChange, - results = () => undefined, - pending = () => false, - failed = () => false, - onNextStepsShownChange, - screenerName, -}: { - schema: Accessor; - formData: Accessor; - hiddenQuestionPaths: Accessor; - submitForm: (data: PreviewFormData) => void; - onDataChange?: () => void; - screenerName?: Accessor; - results?: Accessor; - pending?: Accessor; - failed?: Accessor; - /** Whether a Next steps field is rendered, so the page can skip its own completion message. */ - onNextStepsShownChange?: (shown: boolean) => void; -}) { - let container: HTMLDivElement | undefined; - let form: Form | undefined; - let currentData: PreviewFormData = {}; - let importing = false; - - const importVisibleSchema = async () => { - if (!form) return; - importing = true; - try { - // Preserve the live form state, not the last submitted data: answers - // typed since the pending submit would otherwise be discarded. - const preservedData = cloneDeep(currentData); - await form.importSchema( - hideQuestions(schema(), hiddenQuestionPaths()), - preservedData, - ); - } finally { - importing = false; - } - }; - - createEffect( - on( - () => [schema(), hiddenQuestionPaths()] as const, - () => void importVisibleSchema(), - { defer: true }, - ), - ); - - onMount(() => { - form = new Form({ - container, - additionalModules: [CustomFormFieldsModule, screeningResultsModule], - }); - connectScreeningResults(form, { - schema, - evaluatedAnswers: formData, - results, - screenerName, - pending, - failed, - onNextStepsShownChange, - }); - currentData = cloneDeep(formData()); - - const debouncedSubmit = debounce( - (data: PreviewFormData) => - submitForm(normalizeArrayFieldData(schema(), data)), - 500, - ); - - form - .importSchema(hideQuestions(schema(), hiddenQuestionPaths()), formData()) - .then(() => { - form?.on("changed", (event) => { - const dataChanged = !isEqual(currentData, event.data); - currentData = cloneDeep(event.data); - if (importing || !dataChanged) return; - onDataChange?.(); - debouncedSubmit(event.data); - }); - }) - .catch(console.error); - - onCleanup(() => { - debouncedSubmit.cancel(); - form?.destroy(); - }); - }); - - return ( -
-
(container = el)} /> -
- ); -} - -export default FormRenderer; diff --git a/builder-frontend/src/components/screenerEditor/preview/Preview.test.tsx b/builder-frontend/src/components/screenerEditor/preview/Preview.test.tsx new file mode 100644 index 00000000..f8bd835b --- /dev/null +++ b/builder-frontend/src/components/screenerEditor/preview/Preview.test.tsx @@ -0,0 +1,83 @@ +// @vitest-environment jsdom +import { render } from "solid-js/web"; +import { afterEach, expect, it, vi } from "vitest"; + +import type { ScreenerResult } from "@/types"; +import { input, settle, type, until } from "@/testing/formJs"; + +const previewResults = vi.hoisted(() => ({ props: undefined as any })); +vi.mock("@/api/screener", () => ({ evaluateScreener: vi.fn() })); +vi.mock("./Results", () => ({ + default: (props: any) => { + previewResults.props = props; + return
; + }, +})); +vi.mock("@/components/shared/Tooltip", () => ({ default: () =>
})); + +import { evaluateScreener } from "@/api/screener"; +import Preview from "./Preview"; + +const decided: ScreenerResult = { + benefit: { name: "Benefit", result: "TRUE", check_results: {} }, +}; +const schema = { + type: "default", + id: "preview-test", + schemaVersion: 18, + components: [ + { id: "answer", type: "textfield", key: "answer", label: "Answer" }, + ], +}; + +let dispose: (() => void) | undefined; +afterEach(() => { + dispose?.(); + document.body.replaceChildren(); + vi.restoreAllMocks(); +}); + +it("evaluates the working screener on open and keeps the last results when an evaluation fails", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + vi.mocked(evaluateScreener) + .mockResolvedValueOnce(decided) + .mockResolvedValueOnce(decided) + .mockRejectedValueOnce(new Error("Unavailable")); + const container = document.body.appendChild(document.createElement("div")); + dispose = render( + () => ( + ({ id: "working" })} formSchema={() => schema} /> + ), + container, + ); + await until(() => expect(input("Answer")).toBeDefined()); + await until(() => + expect(evaluateScreener).toHaveBeenCalledExactlyOnceWith("working", { + answer: "", + }), + ); + await settle(); + + type("Answer", "first"); + await until(() => expect(evaluateScreener).toHaveBeenCalledTimes(2)); + await until(() => + expect(container.querySelector('[role="status"]')?.textContent).toContain( + "Screening complete", + ), + ); + expect(evaluateScreener).toHaveBeenLastCalledWith( + "working", + expect.objectContaining({ answer: "first" }), + ); + expect(previewResults.props.results()).toEqual(decided); + expect(previewResults.props.inputData()).toEqual( + expect.objectContaining({ answer: "first" }), + ); + + type("Answer", "second"); + await until(() => + expect(container.querySelector('[role="alert"]')).not.toBeNull(), + ); + expect(container.querySelector('[role="status"]')).toBeNull(); + expect(previewResults.props.results()).toEqual(decided); +}); diff --git a/builder-frontend/src/components/screenerEditor/preview/Preview.tsx b/builder-frontend/src/components/screenerEditor/preview/Preview.tsx index b6eec45f..5fa8ebdf 100644 --- a/builder-frontend/src/components/screenerEditor/preview/Preview.tsx +++ b/builder-frontend/src/components/screenerEditor/preview/Preview.tsx @@ -1,43 +1,15 @@ -import { Accessor, createMemo, createSignal, Show } from "solid-js"; +import { Accessor, Show } from "solid-js"; -import FormRenderer from "./FormRenderer"; import Results from "./Results"; import { evaluateScreener } from "../../../api/screener"; -import { PreviewFormData, ScreenerResult } from "./types"; import Tooltip from "@/components/shared/Tooltip"; import HiddenQuestionsNotice from "@/components/shared/HiddenQuestionsNotice"; import ScreeningComplete from "@/components/shared/ScreeningComplete"; -import { - getUnneededQuestionPaths, - haveSameQuestionPaths, -} from "@/utils/questionVotes"; +import { createScreeningSession } from "@/components/shared/screeningSession/screeningSession"; const Preview = ({ screener, formSchema }) => { - const [lastInputDataSent, setLastInputDataSent] = - createSignal({}); - const [results, setResults] = createSignal(); - const [resultsLoading, setResultsLoading] = createSignal(false); - // True from an edit until results for the latest answers arrive. Hides the completion - // message without blanking the Results panel on every keystroke. - const [resultsStale, setResultsStale] = createSignal(false); - const [evaluationFailed, setEvaluationFailed] = createSignal(false); - let evaluationVersion = 0; - const [showAllQuestions, setShowAllQuestions] = createSignal(false); - // A rendered Next steps field shows completion in its heading instead. - const [nextStepsShown, setNextStepsShown] = createSignal(false); - const unneededQuestionPaths = createMemo( - () => getUnneededQuestionPaths(results()), - undefined, - { equals: haveSameQuestionPaths }, - ); - const hiddenQuestionPaths = createMemo( - () => (showAllQuestions() ? [] : unneededQuestionPaths()), - undefined, - { equals: haveSameQuestionPaths }, - ); - let schema: Accessor = () => { if (formSchema()) { return formSchema(); @@ -51,60 +23,35 @@ const Preview = ({ screener, formSchema }) => { }; }; - const handleSubmitForm = async (data: PreviewFormData) => { - const version = ++evaluationVersion; - setLastInputDataSent(data); - setResultsStale(true); - setResultsLoading(true); - try { - const apiResult = await evaluateScreener(screener().id, data); - if (version === evaluationVersion) { - setResults(apiResult); - setResultsStale(false); - setEvaluationFailed(false); - } - } catch (error) { - if (version === evaluationVersion) setEvaluationFailed(true); - console.error("Could not evaluate the screener", error); - } finally { - if (version === evaluationVersion) setResultsLoading(false); - } - }; + const session = createScreeningSession({ + schema, + evaluate: (answers) => evaluateScreener(screener().id, answers), + // Authors see results for an unanswered form as soon as Preview opens. + evaluateOnLoad: true, + screenerName: () => screener()?.screenerName ?? "", + }); return (
Form
- screener()?.screenerName ?? ""} - schema={schema} - formData={lastInputDataSent} - hiddenQuestionPaths={hiddenQuestionPaths} - results={results} - pending={resultsStale} - failed={evaluationFailed} - onNextStepsShownChange={setNextStepsShown} - submitForm={handleSubmitForm} - onDataChange={() => { - evaluationVersion++; - setResultsStale(true); - }} - /> - + + - - + + unneededQuestionPaths().length} - showAllQuestions={showAllQuestions} - onToggleShowAllQuestions={() => - setShowAllQuestions((current) => !current) - } + unneededQuestionCount={session.unneededQuestionCount} + showAllQuestions={session.showAllQuestions} + onToggleShowAllQuestions={session.toggleShowAllQuestions} />
@@ -127,9 +74,9 @@ const Preview = ({ screener, formSchema }) => {
diff --git a/builder-frontend/src/components/shared/screeningCompletionFlow.test.tsx b/builder-frontend/src/components/shared/screeningCompletionFlow.test.tsx deleted file mode 100644 index 6e12da39..00000000 --- a/builder-frontend/src/components/shared/screeningCompletionFlow.test.tsx +++ /dev/null @@ -1,231 +0,0 @@ -// @vitest-environment jsdom - -import { render } from "solid-js/web"; -import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; -import type { ScreenerResult } from "@/types"; - -const renderer = vi.hoisted(() => ({ props: undefined as any })); -const previewResults = vi.hoisted(() => ({ props: undefined as any })); -vi.mock("@solidjs/router", () => ({ - useParams: () => ({ publishedScreenerId: "published" }), -})); -vi.mock("@/api/screener", () => ({ evaluateScreener: vi.fn() })); -vi.mock("@/api/publishedScreener", () => ({ - fetchPublishedScreener: vi.fn(), - evaluatePublishedScreener: vi.fn(), -})); -vi.mock("@/components/screenerEditor/preview/FormRenderer", () => ({ - default: (props: any) => { - renderer.props = props; - return
; - }, -})); -vi.mock("@/components/screener/FormRenderer", () => ({ - default: (props: any) => { - renderer.props = props; - return
; - }, -})); -vi.mock("@/components/screenerEditor/preview/Results", () => ({ - default: (props: any) => { - previewResults.props = props; - return
; - }, -})); -vi.mock("@/components/screener/EligibilityResults", () => ({ - default: (props: any) => ( -
- {Object.keys(props.screenerResult() ?? {}).join(",")} -
- ), -})); -vi.mock("@/components/shared/Tooltip", () => ({ default: () =>
})); - -import { evaluateScreener } from "@/api/screener"; -import { - evaluatePublishedScreener, - fetchPublishedScreener, -} from "@/api/publishedScreener"; -import Preview from "@/components/screenerEditor/preview/Preview"; -import Screener from "@/components/screener/Screener"; - -describe.each(["preview", "published"])("completion in %s", (mode) => { - let dispose: (() => void) | undefined; - const api = () => - mode === "preview" - ? vi.mocked(evaluateScreener) - : vi.mocked(evaluatePublishedScreener); - const decided: ScreenerResult = { - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }; - beforeEach(() => { - vi.clearAllMocks(); - renderer.props = undefined; - vi.mocked(fetchPublishedScreener).mockResolvedValue({ - id: "published", - screenerName: "Test", - formSchema: { components: [] }, - } as any); - }); - afterEach(() => { - dispose?.(); - document.body.replaceChildren(); - }); - - async function mount(schema = { components: [] } as any) { - const container = document.body.appendChild(document.createElement("div")); - dispose = render( - () => - mode === "preview" ? ( - ({ id: "working" })} - formSchema={() => schema} - /> - ) : ( - - ), - container, - ); - await vi.waitFor(() => expect(renderer.props).toBeDefined()); - return container; - } - - it("uses a rendered component's heading instead of a second completion message", async () => { - const schema = { - components: [{ type: "group", components: [{ type: "next_steps" }] }], - }; - vi.mocked(fetchPublishedScreener).mockResolvedValueOnce({ - screenerName: "Test", - formSchema: schema, - }); - api().mockResolvedValueOnce(decided); - const container = await mount(schema); - await renderer.props.submitForm({ answer: true }); - // Until the component renders (for example, while a condition hides it). - expect(container.textContent).toContain("Screening complete"); - renderer.props.onNextStepsShownChange(true); - expect(container.textContent).not.toContain("Screening complete"); - renderer.props.onNextStepsShownChange(false); - expect(container.textContent).toContain("Screening complete"); - }); - - it("ignores an older decided result while the latest answers remain undecided", async () => { - let finishOlder!: (value: ScreenerResult) => void; - let finishLatest!: (value: ScreenerResult) => void; - api() - .mockReturnValueOnce( - new Promise((resolve) => { - finishOlder = resolve; - }), - ) - .mockReturnValueOnce( - new Promise((resolve) => { - finishLatest = resolve; - }), - ); - const container = await mount(); - renderer.props.onDataChange(); - const older = renderer.props.submitForm({ answer: true }); - renderer.props.onDataChange(); - const latest = renderer.props.submitForm({ answer: false }); - finishOlder(decided); - await older; - expect(renderer.props.pending()).toBe(true); - expect(renderer.props.results()).toBeUndefined(); - expect(container.querySelector('[role="status"]')).toBeNull(); - finishLatest({ - benefit: { ...decided.benefit, result: "UNABLE_TO_DETERMINE" }, - }); - await latest; - expect(renderer.props.pending()).toBe(false); - expect(renderer.props.results().benefit.result).toBe("UNABLE_TO_DETERMINE"); - expect(container.querySelector('[role="status"]')).toBeNull(); - }); - - it("hides completion immediately on edit and does not restore it after an evaluation error", async () => { - vi.spyOn(console, "error").mockImplementation(() => {}); - vi.spyOn(console, "log").mockImplementation(() => {}); - try { - api() - .mockResolvedValueOnce(decided) - .mockRejectedValueOnce(new Error("Unavailable")); - const container = await mount(); - await renderer.props.submitForm({ answer: true }); - expect(renderer.props.failed()).toBe(false); - expect(container.querySelector('[role="status"]')?.textContent).toContain( - "Screening complete", - ); - renderer.props.onDataChange(); - expect(renderer.props.pending()).toBe(true); - expect(container.querySelector('[role="status"]')).toBeNull(); - await renderer.props.submitForm({ answer: false }); - expect(renderer.props.pending()).toBe(true); - expect(renderer.props.failed()).toBe(true); - expect(renderer.props.results()).toEqual(decided); - expect(container.querySelector('[role="status"]')).toBeNull(); - } finally { - vi.restoreAllMocks(); - } - }); - - it("keeps the last results and reports a failed evaluation", async () => { - vi.spyOn(console, "error").mockImplementation(() => {}); - vi.spyOn(console, "log").mockImplementation(() => {}); - try { - api() - .mockResolvedValueOnce(decided) - .mockRejectedValueOnce(new Error("Unavailable")) - .mockResolvedValueOnce(decided); - const container = await mount(); - await renderer.props.submitForm({ answer: true }); - renderer.props.onDataChange(); - await renderer.props.submitForm({ answer: false }); - expect(container.querySelector('[role="alert"]')).not.toBeNull(); - if (mode === "preview") { - expect(previewResults.props.results()).toEqual(decided); - } else { - expect( - container.querySelector('[data-testid="eligibility-results"]') - ?.textContent, - ).toBe("benefit"); - } - renderer.props.onDataChange(); - await renderer.props.submitForm({ answer: true }); - expect(container.querySelector('[role="alert"]')).toBeNull(); - expect(container.querySelector('[role="status"]')).not.toBeNull(); - } finally { - vi.restoreAllMocks(); - } - }); -}); - -describe("preview results while typing", () => { - let dispose: (() => void) | undefined; - afterEach(() => { - dispose?.(); - document.body.replaceChildren(); - }); - - it("keeps showing results until the debounced evaluation starts", async () => { - vi.clearAllMocks(); - renderer.props = undefined; - vi.mocked(evaluateScreener).mockResolvedValue({ - benefit: { name: "Benefit", result: "TRUE", check_results: {} }, - }); - const container = document.body.appendChild(document.createElement("div")); - dispose = render( - () => ( - ({ id: "working" })} - formSchema={() => ({ components: [] })} - /> - ), - container, - ); - await vi.waitFor(() => expect(renderer.props).toBeDefined()); - await renderer.props.submitForm({ answer: true }); - renderer.props.onDataChange(); - expect(previewResults.props.resultsLoading()).toBe(false); - expect(container.querySelector('[role="status"]')).toBeNull(); - }); -}); diff --git a/builder-frontend/src/components/shared/screeningSession/screeningSession.test.tsx b/builder-frontend/src/components/shared/screeningSession/screeningSession.test.tsx new file mode 100644 index 00000000..a12e905e --- /dev/null +++ b/builder-frontend/src/components/shared/screeningSession/screeningSession.test.tsx @@ -0,0 +1,451 @@ +// @vitest-environment jsdom +import { createRoot, createSignal } from "solid-js"; +import { insert } from "solid-js/web"; +import { afterEach, describe, expect, it, vi } from "vitest"; + +import type { ScreenerResult } from "@/types"; +import { + createScreeningSession, + type ScreeningAnswers, + type ScreeningSessionOptions, +} from "./screeningSession"; +import { input, settle, type, until } from "@/testing/formJs"; + +const schema = { + type: "default", + id: "session-test", + schemaVersion: 18, + components: [ + { id: "answer", type: "textfield", key: "answer", label: "Answer" }, + { id: "income", type: "number", key: "income", label: "Income" }, + { id: "married", type: "checkbox", key: "married", label: "Married" }, + ], +}; + +const result = ( + value: "TRUE" | "FALSE" | "UNABLE_TO_DETERMINE", + inputPaths: string[] = [], +): ScreenerResult => ({ + benefit: { + name: "Benefit", + result: value, + check_results: { + check: { name: "Check", result: value, inputPaths } as any, + }, + }, +}); + +function deferred() { + let resolve!: (value: ScreenerResult) => void; + let reject!: (error: Error) => void; + const promise = new Promise((yes, no) => { + resolve = yes; + reject = no; + }); + return { promise, resolve, reject }; +} + +const disposers: (() => void)[] = []; +afterEach(() => { + disposers.splice(0).forEach((dispose) => dispose()); + document.body.replaceChildren(); + vi.restoreAllMocks(); +}); + +async function start( + options: Partial & { + evaluate: ScreeningSessionOptions["evaluate"]; + }, + formSchema: object = schema, +) { + const container = document.body.appendChild(document.createElement("div")); + const [currentSchema, setSchema] = createSignal(formSchema); + let dispose!: () => void; + const session = createRoot((disposeRoot) => { + dispose = disposeRoot; + const created = createScreeningSession({ + schema: currentSchema, + ...options, + }); + insert(container, () => ); + return created; + }); + disposers.push(dispose); + await until(() => + expect(container.querySelector(".fjs-form")).not.toBeNull(), + ); + await settle(); + return { session, container, dispose, setSchema }; +} + +describe("screening session", () => { + it("evaluates the latest answers once they stop changing", async () => { + const evaluate = vi.fn(async () => result("TRUE")); + const { session } = await start({ evaluate }); + expect(evaluate).not.toHaveBeenCalled(); + + type("Answer", "fir"); + await until(() => expect(session.stale()).toBe(true)); + type("Answer", "first"); + expect(session.loading()).toBe(false); + + await until(() => expect(evaluate).toHaveBeenCalledOnce()); + expect(evaluate).toHaveBeenCalledWith( + expect.objectContaining({ answer: "first" }), + ); + await until(() => expect(session.results()).toEqual(result("TRUE"))); + expect(session.stale()).toBe(false); + expect(session.loading()).toBe(false); + expect(session.answersSent()).toEqual( + expect.objectContaining({ answer: "first" }), + ); + }); + + it("ignores an older evaluation that finishes after a newer one", async () => { + const older = deferred(); + const onResults = vi.fn(); + const evaluate = vi + .fn<(answers: ScreeningAnswers) => Promise>() + .mockReturnValueOnce(older.promise) + .mockResolvedValueOnce(result("FALSE")); + const { session } = await start({ evaluate, onResults }); + + type("Answer", "older"); + await until(() => expect(evaluate).toHaveBeenCalledOnce()); + expect(session.loading()).toBe(true); + type("Answer", "newer"); + await until(() => expect(session.results()).toEqual(result("FALSE"))); + older.resolve(result("TRUE")); + await older.promise; + + expect(session.results()).toEqual(result("FALSE")); + expect(onResults).toHaveBeenCalledOnce(); + expect(onResults).toHaveBeenCalledWith( + expect.objectContaining({ answer: "newer" }), + result("FALSE"), + ); + }); + + it("outdates an evaluation in flight as soon as an answer changes", async () => { + const inFlight = deferred(); + const onResults = vi.fn(); + const evaluate = vi.fn(() => inFlight.promise); + const { session } = await start({ evaluate, onResults }); + + type("Answer", "first"); + await until(() => expect(evaluate).toHaveBeenCalledOnce()); + type("Answer", "second"); + inFlight.resolve(result("TRUE")); + await inFlight.promise; + + expect(session.results()).toBeUndefined(); + expect(session.stale()).toBe(true); + expect(onResults).not.toHaveBeenCalled(); + }); + + it("keeps the last results when an evaluation fails, until one succeeds", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const onEvaluationFailed = vi.fn(); + const evaluate = vi + .fn<(answers: ScreeningAnswers) => Promise>() + .mockResolvedValueOnce(result("TRUE")) + .mockRejectedValueOnce(new Error("Unavailable")) + .mockResolvedValueOnce(result("FALSE")); + const { session } = await start({ evaluate, onEvaluationFailed }); + + type("Answer", "first"); + await until(() => expect(session.results()).toEqual(result("TRUE"))); + type("Answer", "second"); + await until(() => expect(session.failed()).toBe(true)); + expect(session.results()).toEqual(result("TRUE")); + expect(session.stale()).toBe(true); + expect(session.loading()).toBe(false); + expect(onEvaluationFailed).toHaveBeenCalledOnce(); + + type("Answer", "third"); + await until(() => expect(session.results()).toEqual(result("FALSE"))); + expect(session.failed()).toBe(false); + }); + + it("ignores a failure of an outdated evaluation", async () => { + vi.spyOn(console, "error").mockImplementation(() => {}); + const older = deferred(); + const onEvaluationFailed = vi.fn(); + const evaluate = vi + .fn<(answers: ScreeningAnswers) => Promise>() + .mockReturnValueOnce(older.promise) + .mockResolvedValueOnce(result("TRUE")); + const { session } = await start({ evaluate, onEvaluationFailed }); + + type("Answer", "older"); + await until(() => expect(evaluate).toHaveBeenCalledOnce()); + type("Answer", "newer"); + older.reject(new Error("Unavailable")); + await until(() => expect(session.results()).toEqual(result("TRUE"))); + + expect(session.failed()).toBe(false); + expect(onEvaluationFailed).not.toHaveBeenCalled(); + }); + + it("hides questions no benefit needs, keeping typed answers, until asked to show them", async () => { + const evaluate = vi.fn(async () => result("FALSE", ["income"])); + const { session } = await start({ evaluate }); + + type("Answer", "kept"); + await until(() => expect(input("Income")).toBeUndefined()); + expect(session.unneededQuestionCount()).toBe(1); + expect(input("Answer")!.value).toBe("kept"); + + session.toggleShowAllQuestions(); + await until(() => expect(input("Income")).toBeDefined()); + expect(session.showAllQuestions()).toBe(true); + expect(input("Answer")!.value).toBe("kept"); + expect(evaluate).toHaveBeenCalledOnce(); + }); + + it("shows a changed schema without losing answers", async () => { + const evaluate = vi.fn(async () => result("TRUE")); + const { setSchema } = await start({ evaluate }); + + type("Answer", "kept"); + setSchema({ + ...schema, + components: [ + ...schema.components, + { id: "age", type: "number", key: "age", label: "Age" }, + ], + }); + await until(() => expect(input("Age")).toBeDefined()); + expect(input("Answer")!.value).toBe("kept"); + }); + + it("evaluates provided answers on load, sending unknown ones as null until answered", async () => { + const onResults = vi.fn(); + const evaluate = vi.fn(async () => result("TRUE")); + const { session } = await start({ + evaluate, + onResults, + initialAnswers: { answer: "From the host", married: null }, + evaluateOnLoad: true, + }); + + await until(() => expect(onResults).toHaveBeenCalledOnce()); + expect(evaluate).toHaveBeenLastCalledWith( + expect.objectContaining({ answer: "From the host", married: null }), + ); + expect(session.answersSent()).toEqual( + expect.objectContaining({ married: null }), + ); + + type("Answer", "Edited"); + await until(() => expect(evaluate).toHaveBeenCalledTimes(2)); + expect(evaluate).toHaveBeenLastCalledWith( + expect.objectContaining({ answer: "Edited", married: null }), + ); + + // Answering "No" is still an answer, even though it looks unanswered. + input("Married")!.click(); + input("Married")!.click(); + await until(() => expect(evaluate).toHaveBeenCalledTimes(3)); + expect(evaluate).toHaveBeenLastCalledWith( + expect.objectContaining({ answer: "Edited", married: false }), + ); + }); + + it("treats every missing provided answer as unknown", async () => { + const evaluate = vi.fn(async () => result("TRUE")); + const { session } = await start({ + evaluate, + initialAnswers: {}, + evaluateOnLoad: true, + }); + + await until(() => expect(session.results()).toEqual(result("TRUE"))); + expect(evaluate).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ answer: null, married: null }), + ); + }); + + it("evaluates form-js's empty values on load when no answers were provided", async () => { + const evaluate = vi.fn(async () => result("FALSE")); + const { session } = await start({ evaluate, evaluateOnLoad: true }); + + await until(() => expect(session.results()).toEqual(result("FALSE"))); + expect(evaluate).toHaveBeenCalledExactlyOnceWith( + expect.objectContaining({ answer: "", married: false }), + ); + }); + + it("waits for an edit unless asked to evaluate on load", async () => { + const evaluate = vi.fn(async () => result("TRUE")); + const { session } = await start({ + evaluate, + initialAnswers: { answer: "From the host" }, + }); + + await new Promise((resolve) => setTimeout(resolve, 600)); + expect(evaluate).not.toHaveBeenCalled(); + expect(session.stale()).toBe(false); + }); + + it("drops a pending edit and an evaluation in flight when disposed", async () => { + const inFlight = deferred(); + const onResults = vi.fn(); + const evaluate = vi.fn(() => inFlight.promise); + const first = await start({ evaluate, onResults }); + + type("Answer", "sent"); + await until(() => expect(evaluate).toHaveBeenCalledOnce()); + first.dispose(); + inFlight.resolve(result("TRUE")); + await inFlight.promise; + expect(onResults).not.toHaveBeenCalled(); + expect(first.session.results()).toBeUndefined(); + + const second = await start({ evaluate }); + type("Answer", "never sent"); + second.dispose(); + await new Promise((resolve) => setTimeout(resolve, 1000)); + expect(evaluate).toHaveBeenCalledOnce(); + }); +}); + +describe("next steps for CRM hosts", () => { + const decided = result("TRUE"); + const evaluate = async () => decided; + const nextSteps = (id: string, body: string, field: object = {}) => ({ + id, + type: "next_steps", + benefitContent: { benefit: { eligible: { body } } }, + ...field, + }); + const form = (components: object[]) => ({ + type: "default", + id: "next-steps-form", + schemaVersion: 18, + components, + }); + + it("follows what the form shows, and projects nothing once disposed", async () => { + const { session, dispose } = await start( + { evaluate, initialAnswers: { show: true } }, + form([ + { id: "show", type: "checkbox", key: "show", label: "Show" }, + nextSteps("next", "Saved instructions", { + conditional: { hide: "=not(show)" }, + }), + ]), + ); + expect(session.projectNextSteps(decided)?.benefit.body?.text).toBe( + "Saved instructions", + ); + input("Show")!.click(); + // Follows the answers at once, without waiting for form-js to repaint. + expect(session.projectNextSteps(decided)).toBeUndefined(); + input("Show")!.click(); + expect(session.projectNextSteps(decided)).toBeDefined(); + dispose(); + expect(session.projectNextSteps(decided)).toBeUndefined(); + }); + + it("reads visibility from conditions, including groups, while hidden questions re-import the form", async () => { + const projected: unknown[] = []; + const { session } = await start( + { + evaluate: async () => result("FALSE", ["city"]), + onResults: () => projected.push(session.projectNextSteps(decided)), + }, + form([ + { id: "city", type: "textfield", key: "city", label: "City" }, + { + id: "hiddenGroup", + type: "group", + conditional: { hide: "=true" }, + components: [nextSteps("inHidden", "Hidden group")], + }, + { + id: "shownGroup", + type: "group", + components: [nextSteps("inShown", "Shown group")], + }, + ]), + ); + expect(session.projectNextSteps(decided)?.benefit.body?.text).toBe( + "Shown group", + ); + + type("City", "Philadelphia"); + await until(() => expect(projected).toHaveLength(1)); + expect(input("City")).toBeUndefined(); + expect(projected[0]).toEqual(session.projectNextSteps(decided)); + expect(session.projectNextSteps(decided)?.benefit.body?.text).toBe( + "Shown group", + ); + }); + + it("reports whether a Next steps field is showing, so the page can skip its own completion message", async () => { + const { session } = await start( + { evaluate }, + form([ + { id: "show", type: "checkbox", key: "show", label: "Show" }, + nextSteps("next", "Saved instructions", { + conditional: { hide: "=not(show)" }, + }), + ]), + ); + expect(session.nextStepsShown()).toBe(false); + input("Show")!.click(); + await until(() => expect(session.nextStepsShown()).toBe(true)); + input("Show")!.click(); + await until(() => expect(session.nextStepsShown()).toBe(false)); + }); + + it("projects visible instructions from a dynamic list with repetition disabled", async () => { + const { session } = await start( + { evaluate, initialAnswers: { person: { show: true } } }, + form([ + { + id: "person", + type: "dynamiclist", + path: "person", + isRepeating: false, + components: [ + { id: "show", type: "checkbox", key: "show", label: "Show" }, + nextSteps("next", "Single-person instructions", { + conditional: { hide: "=not(person.show)" }, + }), + ], + }, + ]), + ); + expect(session.projectNextSteps(decided)?.benefit.body?.text).toBe( + "Single-person instructions", + ); + }); + + it.each([ + [[{ show: false }, { show: true }], "Per item"], + [[{ show: false }], undefined], + ])( + "checks Next steps in a repeated group against each item (%j)", + async (people, body) => { + const { session } = await start( + { evaluate, initialAnswers: { people } }, + form([ + { + id: "people", + type: "dynamiclist", + path: "people", + components: [ + { id: "show", type: "checkbox", key: "show", label: "Show" }, + nextSteps("next", "Per item", { + conditional: { hide: "=not(this.show)" }, + }), + ], + }, + ]), + ); + expect(session.projectNextSteps(decided)?.benefit?.body?.text).toBe(body); + }, + ); +}); diff --git a/builder-frontend/src/components/shared/screeningSession/screeningSession.tsx b/builder-frontend/src/components/shared/screeningSession/screeningSession.tsx new file mode 100644 index 00000000..630d1ff3 --- /dev/null +++ b/builder-frontend/src/components/shared/screeningSession/screeningSession.tsx @@ -0,0 +1,260 @@ +import { + type Accessor, + type Component, + createEffect, + createMemo, + createSignal, + on, + onCleanup, + onMount, +} from "solid-js"; +import debounce from "lodash.debounce"; +import cloneDeep from "lodash/cloneDeep"; +import isEqual from "lodash/isEqual"; +import { Form } from "@bpmn-io/form-js-viewer"; +import type { State } from "@bpmn-io/form-js-viewer/dist/types/Form"; + +import CustomFormFieldsModule from "@/components/screenerEditor/formJsExtensions/customFormFields"; +import { + connectScreeningResults, + screeningResultsModule, +} from "@/components/screenerEditor/formJsExtensions/screeningResults/screeningResults"; +import { firstVisibleNextSteps } from "@/components/screenerEditor/formJsExtensions/nextSteps/selection"; +import { + projectNextSteps as projectFieldNextSteps, + type CrmNextSteps, +} from "@/integrations/nextSteps"; +import type { ScreenerResult } from "@/types"; +import { normalizeArrayFieldData } from "@/utils/arrayFieldData"; +import { + getUnneededQuestionPaths, + haveSameQuestionPaths, + hideQuestions, +} from "@/utils/questionVotes"; +import { + findFilledUnknownPaths, + keepUnansweredPaths, + restoreUnknownAnswers, +} from "@/utils/unknownAnswers"; + +import "@bpmn-io/form-js/dist/assets/form-js.css"; + +export type ScreeningAnswers = Record; + +/** How long answers must stay unchanged before they are evaluated. */ +export const EVALUATION_DELAY_MS = 500; + +export interface ScreeningSessionOptions { + schema: Accessor; + /** Evaluate normalized answers, against the working screener or a published one. */ + evaluate: (answers: ScreeningAnswers) => Promise; + /** + * Answers a host provided. Answers missing or null here stay null until the person + * answers them, rather than taking form-js's empty values. + */ + initialAnswers?: ScreeningAnswers; + /** Evaluate as soon as the form loads, rather than waiting for the first edit. */ + evaluateOnLoad?: boolean; + screenerName?: Accessor; + /** Called only for the latest answers, never for an evaluation an edit outdated. */ + onResults?: (answers: ScreeningAnswers, results: ScreenerResult) => void; + /** Called only when evaluating the latest answers fails. */ + onEvaluationFailed?: () => void; +} + +export interface ScreeningSession { + results: Accessor; + /** True from an edit until results for the latest answers arrive. */ + stale: Accessor; + failed: Accessor; + /** True only while the latest answers are being evaluated, not while waiting to send them. */ + loading: Accessor; + /** The normalized answers last sent for evaluation. */ + answersSent: Accessor; + unneededQuestionCount: Accessor; + showAllQuestions: Accessor; + toggleShowAllQuestions: () => void; + /** Whether a Next steps field is rendered, so the page can skip its own completion message. */ + nextStepsShown: Accessor; + /** The saved next steps the form currently shows for these results, for CRM hosts. */ + projectNextSteps: (results: ScreenerResult) => CrmNextSteps | undefined; + /** The form the person answers. Render it once. */ + Form: Component; +} + +/** One person's pass through a screener, in Preview or on a published screener. */ +export function createScreeningSession( + options: ScreeningSessionOptions, +): ScreeningSession { + const { + schema, + evaluate, + initialAnswers, + evaluateOnLoad, + onResults, + onEvaluationFailed, + } = options; + const [results, setResults] = createSignal(); + const [answersSent, setAnswersSent] = createSignal( + initialAnswers ?? {}, + ); + // A failed evaluation keeps the previous results visible while stale, without + // announcing that screening is complete. + const [stale, setStale] = createSignal(false); + const [failed, setFailed] = createSignal(false); + const [loading, setLoading] = createSignal(false); + const [showAllQuestions, setShowAllQuestions] = createSignal(false); + const [nextStepsShown, setNextStepsShown] = createSignal(false); + const unneededQuestionPaths = createMemo( + () => getUnneededQuestionPaths(results()), + undefined, + { equals: haveSameQuestionPaths }, + ); + const hiddenQuestionPaths = createMemo( + () => (showAllQuestions() ? [] : unneededQuestionPaths()), + undefined, + { equals: haveSameQuestionPaths }, + ); + + // Each edit and each evaluation outdates every evaluation still in flight. + let latestEvaluation = 0; + onCleanup(() => latestEvaluation++); + + const submit = async (answers: ScreeningAnswers) => { + const evaluation = ++latestEvaluation; + setAnswersSent(answers); + setStale(true); + setLoading(true); + try { + const evaluated = await evaluate(answers); + if (evaluation !== latestEvaluation) return; + setResults(evaluated); + setStale(false); + setFailed(false); + onResults?.(answers, evaluated); + } catch (error) { + if (evaluation !== latestEvaluation) return; + setFailed(true); + onEvaluationFailed?.(); + console.error("Could not evaluate the screener", error); + } finally { + if (evaluation === latestEvaluation) setLoading(false); + } + }; + + let form: Form | undefined; + // Next steps are judged against the imported schema and answers. + let imported = false; + + function ScreeningForm() { + let container!: HTMLDivElement; + let currentData: ScreeningAnswers = cloneDeep(initialAnswers ?? {}); + let importing = false; + let unknownPaths: string[][] = []; + const evaluationAnswers = (data: ScreeningAnswers) => + normalizeArrayFieldData( + schema(), + restoreUnknownAnswers(data, unknownPaths), + ); + + const importVisibleSchema = async () => { + if (!form) return; + importing = true; + try { + // Preserve the live form state, not the last submitted data: answers + // typed since the pending submit would otherwise be discarded. + await form.importSchema( + hideQuestions(schema(), hiddenQuestionPaths()), + cloneDeep(currentData), + ); + } finally { + importing = false; + } + }; + + createEffect( + on( + () => [schema(), hiddenQuestionPaths()] as const, + () => void importVisibleSchema(), + { defer: true }, + ), + ); + + onMount(() => { + const mounted = new Form({ + container, + additionalModules: [CustomFormFieldsModule, screeningResultsModule], + }); + form = mounted; + let disposed = false; + connectScreeningResults(mounted, { + schema, + evaluatedAnswers: answersSent, + results, + screenerName: options.screenerName, + pending: stale, + failed, + onNextStepsShownChange: setNextStepsShown, + }); + const debouncedSubmit = debounce( + (data: ScreeningAnswers) => void submit(evaluationAnswers(data)), + EVALUATION_DELAY_MS, + ); + + mounted + .importSchema( + hideQuestions(schema(), hiddenQuestionPaths()), + initialAnswers ?? {}, + ) + .then(() => { + if (disposed) return; + imported = true; + currentData = cloneDeep(mounted._getState().data); + if (initialAnswers) { + unknownPaths = findFilledUnknownPaths(initialAnswers, currentData); + } + if (evaluateOnLoad) void submit(evaluationAnswers(currentData)); + mounted.on("changed", (event: State) => { + const dataChanged = !isEqual(currentData, event.data); + currentData = cloneDeep(event.data); + if (importing || !dataChanged) return; + unknownPaths = keepUnansweredPaths(unknownPaths, event.data); + latestEvaluation++; + setStale(true); + debouncedSubmit(event.data); + }); + }) + .catch(console.error); + + onCleanup(() => { + disposed = true; + imported = false; + form = undefined; + debouncedSubmit.cancel(); + mounted.destroy(); + }); + }); + + return
; + } + + return { + results, + stale, + failed, + loading, + answersSent, + unneededQuestionCount: () => unneededQuestionPaths().length, + showAllQuestions, + toggleShowAllQuestions: () => setShowAllQuestions((shown) => !shown), + nextStepsShown, + projectNextSteps: (evaluated) => + form && imported + ? projectFieldNextSteps( + evaluated, + firstVisibleNextSteps((name) => form!.get(name)), + ) + : undefined, + Form: ScreeningForm, + }; +} diff --git a/builder-frontend/src/testing/formJs.ts b/builder-frontend/src/testing/formJs.ts new file mode 100644 index 00000000..c97fe1b5 --- /dev/null +++ b/builder-frontend/src/testing/formJs.ts @@ -0,0 +1,23 @@ +import { vi } from "vitest"; + +/** Helpers for tests that answer a real form-js form the way a person would. */ + +export const input = (label: string) => + Array.from(document.querySelectorAll("label")).find((element) => + element.textContent?.trim().startsWith(label), + )?.control as HTMLInputElement | null | undefined; + +// form-js renders once more just after an import, resetting what was typed before it. +export const settle = () => new Promise((resolve) => setTimeout(resolve, 100)); + +// The session waits for answers to stop changing. +export const until = (assertion: () => void) => + vi.waitFor(assertion, { timeout: 3000 }); + +export function type(label: string, value: string) { + const field = input(label)!; + field.value = value; + field.dispatchEvent(new Event("input", { bubbles: true })); + // Leaving the field hands the answer to the form without form-js's typing delay. + field.dispatchEvent(new FocusEvent("focusout", { bubbles: true })); +}