diff --git a/builder-frontend/README.md b/builder-frontend/README.md index 7ad9a04c..64c0f3bc 100644 --- a/builder-frontend/README.md +++ b/builder-frontend/README.md @@ -104,3 +104,22 @@ The component renders sanitized Markdown without template evaluation. Web links accept HTTP(S) URLs and open in a new tab. Pending or failed evaluations hide old instructions until fresh decisions arrive. Forms containing the component use its progress heading; existing forms without it keep the legacy completion message. + +## Unanswered questions in Next steps + +For an undecided benefit, Next steps lists the form's question labels for missing +inputs used by that benefit's undecided checks. Shared inputs are deduplicated; +inputs used only by decided checks are omitted. Fields sharing a label add their +group's label, and items of a repeated section with more than one item are +numbered, such as "Age (Household member #2)". Questions a form condition +currently hides are left out, since no one can answer them. Zero, No, and explicit None +answers remain answered. The list uses the same normalized data sent to the +eligibility service, including unknown CRM prefill preserved as null. + +Published screeners, Preview, and the print summary share these labels. Pending +or failed evaluations suppress old prompts along with old instructions, and +prompts disappear when the benefit is decided. Labels are kept separately from +answers in the results snapshot; answers and technical input paths are never +printed by this feature. If an input has no static form label, Next steps keeps +its general need-more-information message rather than inventing a question. +The CRM `nextSteps` extension continues to contain decided benefits only. diff --git a/builder-frontend/src/components/screener/FormRenderer.tsx b/builder-frontend/src/components/screener/FormRenderer.tsx index c77f83cc..9b82e890 100644 --- a/builder-frontend/src/components/screener/FormRenderer.tsx +++ b/builder-frontend/src/components/screener/FormRenderer.tsx @@ -91,6 +91,8 @@ function FormRenderer({ additionalModules: [CustomFormFieldsModule, screeningResultsModule], }); connectScreeningResults(form, { + schema: () => schema, + evaluatedAnswers: formData, results, screenerName, pending, diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.test.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.test.ts index fd0d5632..beb56805 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.test.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.test.ts @@ -96,6 +96,34 @@ it("shows decided benefits immediately, preserves answers/schema, and lists unde expect((form as any)._getState().data).toEqual({}); }); +it("lists missing questions for undecided benefits and hides stale questions while pending", async () => { + const { container, service } = await mount(); + const current = result(); + service.update(current, false, false, { + food: ["Your date of birth", "Annual income"], + }); + await vi.waitFor(() => + expect(container.textContent).toContain("Find answers to these questions"), + ); + expect(container.textContent).toContain("Your date of birth"); + service.update(current, true, false, { food: ["Your date of birth"] }); + await vi.waitFor(() => + expect(container.textContent).not.toContain("Your date of birth"), + ); + service.update( + { ...current, food: { ...current.food, result: "TRUE" } }, + false, + false, + {}, + ); + await vi.waitFor(() => + expect(container.textContent).toContain("Screening complete"), + ); + expect(container.textContent).not.toContain( + "Find answers to these questions", + ); +}); + it("uses failed check aliases with name fallback and the analyst's note", async () => { const { container, service } = await mount(); const results = result("FALSE"); diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.ts index 71860c8f..866512da 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.ts @@ -7,6 +7,7 @@ import { Text, } from "@bpmn-io/form-js-viewer"; import type { BenefitResult } from "@/types"; +import type { UnansweredQuestions } from "@/utils/unansweredQuestions"; import { useScreeningResults } from "../screeningResults/useScreeningResults"; import { NEXT_STEPS_TYPE, @@ -106,7 +107,8 @@ export function NextSteps({ field }: { field: NextStepsField }) { () => getService("screeningResults", false)?.showNextSteps(field.id), [getService, field.id], ); - const { results, pending, failed, mode } = useScreeningResults(); + const { results, pending, failed, mode, unansweredQuestions } = + useScreeningResults(); const benefits = Object.entries(results ?? {}); const complete = benefits.length > 0 && benefits.every(([, benefit]) => isDecided(benefit)); @@ -124,6 +126,7 @@ export function NextSteps({ field }: { field: NextStepsField }) { pending=${pending} failed=${failed} mode=${mode} + unansweredQuestions=${unansweredQuestions} /> `; } @@ -136,6 +139,7 @@ export function NextStepsBody({ failed, mode, forPrint = false, + unansweredQuestions, }: { field: NextStepsField; benefits: [string, BenefitResult][]; @@ -144,6 +148,7 @@ export function NextStepsBody({ failed: boolean; mode: "live" | "editor"; forPrint?: boolean; + unansweredQuestions?: UnansweredQuestions; }) { if (failed) return html`
@@ -186,6 +191,13 @@ export function NextStepsBody({ return html`

${benefit.name}

Still needs more information.

+ ${!!unansweredQuestions?.[id]?.length && + html` +

Find answers to these questions to continue:

+ + `}
`; if (hideDecided) return null; const unmet = steps.unmetRequirements; diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.test.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.test.ts index 0bf0e288..c3c5ec3e 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.test.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.test.ts @@ -96,7 +96,7 @@ it("prints current results and copied content with full URLs, without answers, a const { button, service, container } = await mount(); expect(button.disabled).toBe(true); service.setScreenerName("Local benefit screener"); - service.update(results, false); + service.update(results, false, false, { utility: ["Your date of birth"] }); await vi.waitFor(() => expect(button.disabled).toBe(false)); let root!: HTMLElement; let printing = false; @@ -115,6 +115,7 @@ it("prints current results and copied content with full URLs, without answers, a expect(root.textContent).toContain("Income limit"); expect(root.textContent).toContain("Ask about other help"); expect(root.textContent).toContain("Still needs more information"); + expect(root.textContent).toContain("Your date of birth"); expect(root.textContent).toContain( "https://example.org/apply?program=housing", ); diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.ts index 2a7bc7d9..17a9c500 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/printSummary/PrintSummary.ts @@ -111,6 +111,7 @@ export function PrintSummary() { failed=${false} mode="live" forPrint=${true} + unansweredQuestions=${current.unansweredQuestions} /> `, root, 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 a1307b2e..49854de9 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 @@ -67,7 +67,10 @@ describe.each(["published", "preview"])( document.body.replaceChildren(); }); - async function mount() { + 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); @@ -75,7 +78,7 @@ describe.each(["published", "preview"])( document.createElement("div"), ); const common = { - formData: () => ({ answer: "Keep this answer" }), + formData: () => data, hiddenQuestionPaths: () => [], submitForm: vi.fn(), results, @@ -86,9 +89,9 @@ describe.each(["published", "preview"])( render( () => mode === "published" ? ( - + ) : ( - schema} {...common} /> + formSchema} {...common} /> ), container, ), @@ -110,6 +113,91 @@ describe.each(["published", "preview"])( }; } + 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, + }, + }, + }); + 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, + }, + }, + }); + 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"); diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.test.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.test.ts index 588b7e16..56c87954 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.test.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.test.ts @@ -25,6 +25,18 @@ const decided: ScreenerResult = { }; describe("screening results service", () => { + it("publishes immutable question labels without storing the evaluated answers", () => { + const { service } = setup(); + const questions = { benefit: ["Annual income"] }; + service.update(decided, false, false, questions); + expect(service.getSnapshot().unansweredQuestions).toBe(questions); + expect(() => questions.benefit.push("Later edit")).toThrow(TypeError); + expect(service.getSnapshot().unansweredQuestions).toEqual({ + benefit: ["Annual income"], + }); + service.update(decided, false); + expect(service.getSnapshot().unansweredQuestions).toBeUndefined(); + }); it("keeps the screener name local to the form without notifying results subscribers", () => { const { service } = setup(); const other = setup().service; diff --git a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.ts b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.ts index bc35b2f6..eb04180e 100644 --- a/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.ts +++ b/builder-frontend/src/components/screenerEditor/formJsExtensions/screeningResults/screeningResults.ts @@ -1,5 +1,11 @@ -import { Accessor, createEffect } from "solid-js"; +import { Accessor, createEffect, createMemo, createSignal } from "solid-js"; import cloneDeep from "lodash/cloneDeep"; +import isEqual from "lodash/isEqual"; +import { + indexQuestions, + unansweredQuestions, + type UnansweredQuestions, +} from "@/utils/unansweredQuestions"; import type { BenefitDetail, BenefitResult, @@ -17,6 +23,8 @@ export interface ScreeningResultsSnapshot { /** True when the latest evaluation failed, until one succeeds. Pending stays true meanwhile. */ readonly failed: boolean; readonly mode: "live" | "editor"; + /** Question labels still needed for undecided benefits; contains no answers. */ + readonly unansweredQuestions?: UnansweredQuestions; } interface EventBus { @@ -89,10 +97,12 @@ export class ScreeningResultsService { return () => this.eventBus.off(SCREENING_RESULTS_CHANGED, listener); }; + /** Freezes `unansweredQuestions` in place: pass questions built for this form alone. */ update( results: ScreenerResult | undefined, pending: boolean, failed = false, + unansweredQuestions?: UnansweredQuestions, ): void { if (results !== this.liveSource) { this.liveSource = results; @@ -103,6 +113,8 @@ export class ScreeningResultsService { pending, failed, mode: "live", + unansweredQuestions: + unansweredQuestions && deepFreeze(unansweredQuestions), }); } @@ -120,7 +132,8 @@ export class ScreeningResultsService { next.results === this.snapshot.results && next.pending === this.snapshot.pending && next.failed === this.snapshot.failed && - next.mode === this.snapshot.mode + next.mode === this.snapshot.mode && + next.unansweredQuestions === this.snapshot.unansweredQuestions ) return; this.snapshot = Object.freeze(next); @@ -202,10 +215,30 @@ function deepFreeze(value: T): T { return value; } +/** Value paths, such as "people.1.age", of the fields and repeated sections a condition hides. */ +function hiddenAnswerPaths(form: { get(name: string): T }): Set { + const hidden = new Set(); + if (!form.get("formFieldRegistry").getForm()) return hidden; + const pathRegistry = form.get("pathRegistry"); + const { data } = form.get("form")._getState(); + // form-js asks for the path of each field it clears because a condition hides it. + form.get("conditionChecker").applyConditions(data, data, { + getFilterPath: (field: unknown, indexes: Record) => { + const path = pathRegistry.getValuePath(field, { indexes }); + hidden.add(path.join(".")); + return path; + }, + }); + return hidden; +} + /** Keeps a live form's service in step with its parent's results; call from the owning component. */ export function connectScreeningResults( form: { get(name: string): T }, live: { + schema: Accessor[0]>; + /** The normalized answers last sent for evaluation. */ + evaluatedAnswers: Accessor; results: Accessor; pending: Accessor; failed: Accessor; @@ -214,8 +247,29 @@ export function connectScreeningResults( }, ): void { const service = form.get("screeningResults"); + const questionIndex = createMemo(() => indexQuestions(live.schema())); + // Conditions are judged against the imported schema, so judge again after each import. + const [imports, setImports] = createSignal(0); + form + .get("eventBus") + .on("import.done", () => setImports((count) => count + 1)); + // Keep the same questions while their content is unchanged, so the service + // doesn't copy and republish them for every answer edit. + const questions = createMemo( + () => { + imports(); + return unansweredQuestions( + questionIndex(), + live.evaluatedAnswers(), + live.results(), + hiddenAnswerPaths(form), + ); + }, + undefined, + { equals: isEqual }, + ); createEffect(() => - service.update(live.results(), live.pending(), live.failed()), + service.update(live.results(), live.pending(), live.failed(), questions()), ); createEffect(() => service.setScreenerName(live.screenerName?.())); const { onNextStepsShownChange } = live; diff --git a/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx b/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx index d829d1b1..6405373e 100644 --- a/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx +++ b/builder-frontend/src/components/screenerEditor/preview/FormRenderer.tsx @@ -76,6 +76,8 @@ function FormRenderer({ additionalModules: [CustomFormFieldsModule, screeningResultsModule], }); connectScreeningResults(form, { + schema, + evaluatedAnswers: formData, results, screenerName, pending, diff --git a/builder-frontend/src/utils/arrayFieldData.ts b/builder-frontend/src/utils/arrayFieldData.ts index 19a9ec5d..46598889 100644 --- a/builder-frontend/src/utils/arrayFieldData.ts +++ b/builder-frontend/src/utils/arrayFieldData.ts @@ -2,15 +2,9 @@ import { CHECKLIST_WITH_NONE_TYPE, NONE_OF_THESE_VALUE, } from '@/components/screenerEditor/formJsExtensions/customFormFields/ChecklistWithNone'; +import { forEachKeyedField, type FormComponent } from '@/utils/formFields'; import { isUnsafeObjectKey } from '@/utils/unsafeObjectKeys'; -interface FormComponent { - type: string; - key?: string; - path?: string; - components?: FormComponent[]; -} - // Field types whose answers are arrays of selected options. const ARRAY_FIELD_TYPES = ['checklist', 'taglist', CHECKLIST_WITH_NONE_TYPE]; @@ -47,19 +41,10 @@ export function normalizeArrayFieldData( : Array.isArray(value) && value.length > 0 ? value : null; } - function visit(components: FormComponent[] | undefined, parentPath = '') { - for (const component of components ?? []) { - const prefix = [parentPath, component.path].filter(Boolean).join('.'); - - if (ARRAY_FIELD_TYPES.includes(component.type) && component.key) { - const path = [prefix, component.key].filter(Boolean).join('.'); - normalizeAtPath(result, path.split('.')); - } - - visit(component.components, prefix); + forEachKeyedField(schema?.components, (component, path) => { + if (ARRAY_FIELD_TYPES.includes(component.type ?? '')) { + normalizeAtPath(result, path.split('.')); } - } - - visit(schema?.components); + }); return result; } diff --git a/builder-frontend/src/utils/formFields.ts b/builder-frontend/src/utils/formFields.ts new file mode 100644 index 00000000..254ebeed --- /dev/null +++ b/builder-frontend/src/utils/formFields.ts @@ -0,0 +1,32 @@ +export interface FormComponent { + type?: string; + key?: string; + path?: string; + components?: FormComponent[]; +} + +/** Joins path parts, skipping empty ones, as form-js does for group paths and keys. */ +export const joinPath = (...parts: (string | undefined)[]) => + parts.filter(Boolean).join("."); + +/** + * Calls `visit` for each field with a key, passing the full path checks use to name + * its input (the paths of its groups and repeated sections, then its key) and the + * components containing it, outermost first. + */ +export function forEachKeyedField( + components: T[] | undefined, + visit: (field: T, path: string, ancestors: readonly T[]) => void, + parentPath = "", + ancestors: readonly T[] = [], +): void { + for (const component of components ?? []) { + const prefix = joinPath(parentPath, component.path); + if (component.key) + visit(component, joinPath(prefix, component.key), ancestors); + forEachKeyedField(component.components as T[] | undefined, visit, prefix, [ + ...ancestors, + component, + ]); + } +} diff --git a/builder-frontend/src/utils/questionVotes.test.ts b/builder-frontend/src/utils/questionVotes.test.ts index 8b72ad60..b8959943 100644 --- a/builder-frontend/src/utils/questionVotes.test.ts +++ b/builder-frontend/src/utils/questionVotes.test.ts @@ -100,4 +100,27 @@ describe("question votes", () => { expect(filtered.components[1].components).toEqual([]); expect(schema.components[1].components).toHaveLength(1); }); + + it("matches fields by their full path, including group paths", () => { + const schema = { + components: [ + { key: "age", type: "number" }, + { + type: "dynamiclist", + path: "people", + components: [{ key: "age", type: "number" }], + }, + ], + }; + + expect(hideQuestions(schema, ["age"]).components).toEqual([ + schema.components[1], + ]); + expect( + hideQuestions(schema, ["people.age"]).components[1].components, + ).toEqual([]); + expect(hideQuestions(schema, ["people.age"]).components[0]).toEqual( + schema.components[0], + ); + }); }); diff --git a/builder-frontend/src/utils/questionVotes.ts b/builder-frontend/src/utils/questionVotes.ts index 1a23e96a..596e76fd 100644 --- a/builder-frontend/src/utils/questionVotes.ts +++ b/builder-frontend/src/utils/questionVotes.ts @@ -1,4 +1,5 @@ import type { BenefitResult, ScreenerResult } from "@/types"; +import { joinPath } from "@/utils/formFields"; export function haveSameQuestionPaths( previous: readonly string[] | undefined, @@ -61,13 +62,24 @@ export function hideQuestions( ): any { const hidden = new Set(hiddenPaths); - const filterComponents = (components: any[] | undefined): any[] => + // Match the full path, as checks name inputs: a group's path prefixes its fields' keys. + const filterComponents = ( + components: any[] | undefined, + parentPath = "", + ): any[] => (components ?? []) - .filter((component) => !component.key || !hidden.has(component.key)) + .filter( + (component) => + !component.key || + !hidden.has(joinPath(parentPath, component.path, component.key)), + ) .map((component) => { const copy = { ...component }; if (Array.isArray(component.components)) { - copy.components = filterComponents(component.components); + copy.components = filterComponents( + component.components, + joinPath(parentPath, component.path), + ); } return copy; }); diff --git a/builder-frontend/src/utils/unansweredQuestions.test.ts b/builder-frontend/src/utils/unansweredQuestions.test.ts new file mode 100644 index 00000000..4a2659c9 --- /dev/null +++ b/builder-frontend/src/utils/unansweredQuestions.test.ts @@ -0,0 +1,250 @@ +import { expect, it } from "vitest"; +import { + indexQuestions, + unansweredQuestions as fromIndex, +} from "./unansweredQuestions"; +import { normalizeArrayFieldData } from "./arrayFieldData"; +import { + findFilledUnknownPaths, + restoreUnknownAnswers, +} from "./unknownAnswers"; +import type { ScreenerResult } from "@/types"; + +const unansweredQuestions = ( + schema: Parameters[0], + ...rest: [unknown, ScreenerResult | undefined] +) => fromIndex(indexQuestions(schema), ...rest); + +const schema = { + components: [ + { key: "custom.income", label: "Annual household income" }, + { key: "custom.resident", label: "Do you live here?" }, + { + key: "custom.programs", + type: "checklist_none", + label: "Current benefit programs", + }, + { + path: "client", + components: [ + { key: "birthdate", subtype: "date", dateLabel: "Your date of birth" }, + ], + }, + ], +}; +const check = (inputPaths: string[], result = "UNABLE_TO_DETERMINE") => + ({ inputPaths, result }) as any; +const results: ScreenerResult = { + housing: { + name: "Housing", + result: "UNABLE_TO_DETERMINE", + check_results: { + a: check([ + "custom.income", + "custom.resident", + "custom.programs", + "client.birthdate", + ]), + b: check(["custom.income"]), + decided: check(["not-needed"], "TRUE"), + }, + }, + decided: { + name: "Decided", + result: "FALSE", + check_results: { a: check(["custom.income"]) }, + }, +}; + +it("lists mapped unanswered questions only for unknown checks of undecided benefits", () => { + expect( + unansweredQuestions( + schema, + { + custom: { income: null, resident: false, programs: [] }, + client: { birthdate: "" }, + }, + results, + ), + ).toEqual({ + housing: ["Annual household income", "Your date of birth"], + }); + expect( + unansweredQuestions( + schema, + { + custom: { income: 0, resident: false, programs: [] }, + client: { birthdate: "1950-01-01" }, + }, + results, + ), + ).toEqual({}); +}); + +it("distinguishes unknown CRM prefill and untouched lists from explicit No and None", () => { + const prefill = { custom: { resident: null } }; + const initialized = { custom: { resident: false, programs: [] } }; + const normalized = normalizeArrayFieldData( + schema, + restoreUnknownAnswers( + initialized, + findFilledUnknownPaths(prefill, initialized), + ), + ); + expect(unansweredQuestions(schema, normalized, results).housing).toContain( + "Do you live here?", + ); + expect(unansweredQuestions(schema, normalized, results).housing).toContain( + "Current benefit programs", + ); + const explicit = normalizeArrayFieldData(schema, { + custom: { resident: false, programs: ["__bdt_none_of_these__"] }, + }); + expect(unansweredQuestions(schema, explicit, results).housing).not.toContain( + "Do you live here?", + ); + expect(unansweredQuestions(schema, explicit, results).housing).not.toContain( + "Current benefit programs", + ); +}); + +it("handles repeated sections and shared votes without exposing paths or values", () => { + const form = { + components: [ + { path: "people", components: [{ key: "age", label: "Age" }] }, + { key: "secret", label: "=secret" }, + { key: "templated", label: "Age of {{ client.name }}" }, + ], + }; + const result: ScreenerResult = { + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { + a: check(["people.age", "secret", "templated", "unbound.path"]), + b: check(["people.age"]), + }, + }, + }; + expect( + unansweredQuestions( + form, + { people: [{ age: 42 }, { age: null }], secret: null }, + result, + ), + ).toEqual({ benefit: ["Age"] }); + expect( + unansweredQuestions(form, { people: [{ age: 42 }], secret: null }, result), + ).toEqual({}); + expect(unansweredQuestions(form, { people: [] }, result)).toEqual({ + benefit: ["Age"], + }); +}); + +it("tells apart fields sharing a label and items of a repeated section", () => { + const form = { + components: [ + { + path: "client", + label: "You", + components: [{ key: "birthdate", label: "Date of birth" }], + }, + { + path: "spouse", + label: "Your spouse", + components: [{ key: "birthdate", label: "Date of birth" }], + }, + { + path: "people", + label: "Household member", + isRepeating: true, + components: [{ key: "age", label: "Age" }], + }, + ], + }; + const result: ScreenerResult = { + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { + a: check(["client.birthdate", "spouse.birthdate", "people.age"]), + }, + }, + }; + expect( + unansweredQuestions( + form, + { client: {}, spouse: {}, people: [{ age: 4 }, { age: null }, {}] }, + result, + ), + ).toEqual({ + benefit: [ + "Date of birth (You)", + "Date of birth (Your spouse)", + "Age (Household member #2)", + "Age (Household member #3)", + ], + }); + expect( + unansweredQuestions( + form, + { client: { birthdate: "1950-01-01" }, people: [{ age: null }] }, + result, + ), + ).toEqual({ benefit: ["Date of birth (Your spouse)", "Age"] }); +}); + +it("skips fields and repeated sections hidden by a condition", () => { + const form = { + components: [ + { + path: "spouse", + components: [{ key: "income", label: "Spouse income" }], + }, + { + path: "people", + label: "Household member", + isRepeating: true, + components: [{ key: "age", label: "Age" }], + }, + ], + }; + const result: ScreenerResult = { + benefit: { + name: "Benefit", + result: "UNABLE_TO_DETERMINE", + check_results: { a: check(["spouse.income", "people.age"]) }, + }, + }; + const answers = { people: [{ age: null }, { age: null }] }; + const ask = (hidden: string[]) => + fromIndex(indexQuestions(form), answers, result, new Set(hidden)).benefit; + expect(ask(["spouse.income", "people.0.age"])).toEqual([ + "Age (Household member #2)", + ]); + expect(ask(["spouse.income", "people"])).toBeUndefined(); +}); + +it("treats whitespace as answered, as the eligibility service receives it", () => { + expect( + unansweredQuestions( + schema, + { + custom: { income: " ", resident: false, programs: ["x"] }, + client: { birthdate: "1950-01-01" }, + }, + results, + ), + ).toEqual({}); +}); + +it("does not prompt for missing inputs in already decided checks", () => { + expect( + unansweredQuestions( + { components: [{ key: "not-needed", label: "Already decided" }] }, + {}, + results, + ), + ).toEqual({}); + expect(unansweredQuestions(schema, {}, undefined)).toEqual({}); +}); diff --git a/builder-frontend/src/utils/unansweredQuestions.ts b/builder-frontend/src/utils/unansweredQuestions.ts new file mode 100644 index 00000000..7884f99c --- /dev/null +++ b/builder-frontend/src/utils/unansweredQuestions.ts @@ -0,0 +1,150 @@ +import type { ScreenerResult } from "@/types"; +import { forEachKeyedField, type FormComponent } from "@/utils/formFields"; +import { isUnsafeObjectKey } from "@/utils/unsafeObjectKeys"; + +export type UnansweredQuestions = Readonly>; +interface Field extends FormComponent { + label?: string; + dateLabel?: string; + timeLabel?: string; + subtype?: string; + isRepeating?: boolean; +} +interface Question { + label: string; + // Labels of the field's groups, kept only to tell apart fields sharing a label. + groups: string[]; + // Labels of its repeated sections, outermost first, to number their items. + repeats: string[]; +} +// Which item of each repeated section, outermost first, holds an answer. +type Item = { index: number; count: number }; + +// Labels only: an expression or template label would evaluate answers into the prompt. +function staticLabel(label: unknown): string | undefined { + if (typeof label !== "string") return; + const text = label.trim(); + if (text && !text.startsWith("=") && !/{{[\s\S]*?}}/.test(text)) return text; +} + +type Answer = { value: unknown; items: Item[]; path: (string | number)[] }; + +// A repeated section may hold several answers at the same schema path. +function valuesAt( + value: unknown, + segments: string[], + items: Item[] = [], + path: (string | number)[] = [], +): Answer[] { + if (!segments.length) return [{ value, items, path }]; + if (Array.isArray(value)) + return value.length + ? value.flatMap((item, index) => + valuesAt( + item, + segments, + [...items, { index, count: value.length }], + [...path, index], + ), + ) + : [{ value: undefined, items, path: [...path, ...segments] }]; + const [key, ...rest] = segments; + if (!value || typeof value !== "object" || isUnsafeObjectKey(key)) + return [{ value: undefined, items, path: [...path, ...segments] }]; + return valuesAt( + Object.hasOwn(value, key) + ? (value as Record)[key] + : undefined, + rest, + items, + [...path, key], + ); +} + +/** A form's question labels by input path; build once per schema. */ +export type QuestionIndex = ReadonlyMap; + +export function indexQuestions(schema: { + components?: Field[]; +}): QuestionIndex { + const questionsAt = new Map(); + const labelPaths = new Map>(); + forEachKeyedField(schema.components, (field, path, ancestors) => { + const label = staticLabel( + field.label || + (field.subtype === "time" ? field.timeLabel : field.dateLabel), + ); + if (!label) return; + labelPaths.set(label, (labelPaths.get(label) ?? new Set()).add(path)); + questionsAt.set(path, [ + ...(questionsAt.get(path) ?? []), + { + label, + groups: ancestors + .filter((group) => !group.isRepeating) + .flatMap((group) => staticLabel(group.label) ?? []), + repeats: ancestors + .filter((group) => group.isRepeating) + .map((group) => staticLabel(group.label) ?? "Entry"), + }, + ]); + }); + // Name a field's groups only when another field shares its label. + for (const questions of questionsAt.values()) + for (const question of questions) + if (labelPaths.get(question.label)!.size === 1) question.groups = []; + return questionsAt; +} + +// Number a repeated section's items only when it has more than one. +function describe(question: Question, items: Item[]): string { + const context = [ + ...items.flatMap(({ index, count }, depth) => + count > 1 && question.repeats[depth] + ? [`${question.repeats[depth]} #${index + 1}`] + : [], + ), + ...question.groups, + ]; + return context.length + ? `${question.label} (${context.join(", ")})` + : question.label; +} + +/** + * Labels only: never expose answers, technical paths, or evaluated label templates. + * `hiddenAnswerPaths` are value paths, such as "people.1.age", of fields or repeated + * sections hidden by a condition: no one can answer them, so they're never listed. + */ +export function unansweredQuestions( + questionsAt: QuestionIndex, + evaluatedAnswers: unknown, + results: ScreenerResult | undefined, + hiddenAnswerPaths: ReadonlySet = new Set(), +): UnansweredQuestions { + const isHidden = (path: (string | number)[]) => + path.some((_, end) => + hiddenAnswerPaths.has(path.slice(0, end + 1).join(".")), + ); + return Object.fromEntries( + Object.entries(results ?? {}).flatMap(([id, benefit]) => { + if (benefit.result !== "UNABLE_TO_DETERMINE") return []; + const paths = new Set( + Object.values(benefit.check_results ?? {}) + .filter((check) => check.result === "UNABLE_TO_DETERMINE") + .flatMap((check) => check.inputPaths ?? []), + ); + const questions = new Set(); + for (const path of paths) + for (const answer of valuesAt(evaluatedAnswers, path.split("."))) + // Match what the eligibility service receives: whitespace is sent as typed. + if ( + (answer.value == null || answer.value === "") && + !isHidden(answer.path) + ) + for (const question of questionsAt.get(path) ?? []) + questions.add(describe(question, answer.items)); + return questions.size ? [[id, [...questions]]] : []; + }), + ); +} diff --git a/e2e/tests/nextStepsPublic.spec.ts b/e2e/tests/nextStepsPublic.spec.ts index 03a50e33..1276954d 100644 --- a/e2e/tests/nextStepsPublic.spec.ts +++ b/e2e/tests/nextStepsPublic.spec.ts @@ -30,10 +30,10 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { label: "Household income", }, { - id: "done", - type: "checkbox", - key: "done", - label: "Answer remaining question", + id: "household-size", + type: "number", + key: "householdSize", + label: "Number of people in your household", }, { id: "print", type: "print_summary" }, { @@ -76,8 +76,19 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { }, food: { name: "Food assistance", - result: answers.done ? "TRUE" : "UNABLE_TO_DETERMINE", - check_results: {}, + result: + answers.householdSize == null ? "UNABLE_TO_DETERMINE" : "TRUE", + check_results: { + size: { + name: "Household size", + result: + answers.householdSize == null + ? "UNABLE_TO_DETERMINE" + : "TRUE", + inputPaths: ["householdSize"], + parameters: {}, + }, + }, }, }, }); @@ -105,20 +116,45 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { page.getByRole("link", { name: "Apply for this benefit" }), ).toHaveCount(0); } - await page.getByLabel("Answer remaining question", { exact: true }).check(); + const nextSteps = page.getByRole("region", { + name: "Your next steps", + exact: true, + }); + await expect( + nextSteps.getByText("Number of people in your household", { + exact: true, + }), + ).toBeVisible(); + await page.evaluate(() => { + window.print = () => { + (window as any).partialPrint = + document.querySelector(".bdt-print-root")!.textContent; + window.dispatchEvent(new Event("afterprint")); + }; + }); + await page.getByRole("button", { name: "Print / Save as PDF" }).click(); + const partialPrint = await page.evaluate( + () => (window as any).partialPrint, + ); + expect(partialPrint).toContain("Number of people in your household"); + expect(partialPrint).not.toContain("Household income"); + await page + .getByLabel("Number of people in your household", { exact: true }) + .fill("2"); await expect( page.getByRole("heading", { name: "Screening complete — your next steps", exact: true, }), ).toBeVisible(); - const next = page.getByRole("region", { - name: "Your next steps", - exact: true, - }); - await expect(next.locator("strong")).toHaveText("photo ID"); await expect( - next.getByRole("link", { name: "Help", exact: true }), + nextSteps.getByText("Find answers to these questions to continue:", { + exact: true, + }), + ).toHaveCount(0); + await expect(nextSteps.locator("strong")).toHaveText("photo ID"); + await expect( + nextSteps.getByRole("link", { name: "Help", exact: true }), ).toHaveAttribute("target", "_blank"); await expect( page.getByText("Screening complete. All benefits", { exact: false }), @@ -132,7 +168,9 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { (window as any).printed = { text: root.textContent, summaryDisplay: getComputedStyle(root).display, - otherDisplays: Array.from(document.body.children).filter(el => el !== root).map(el => getComputedStyle(el).display), + otherDisplays: Array.from(document.body.children) + .filter((el) => el !== root) + .map((el) => getComputedStyle(el).display), }; }; }); @@ -144,14 +182,18 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { expect(printed.text).toContain("https://example.org/help"); expect(printed.text).not.toContain("Household income"); expect(printed.summaryDisplay).toBe("block"); - expect(printed.otherDisplays.every((display: string) => display === "none")).toBe(true); + expect( + printed.otherDisplays.every((display: string) => display === "none"), + ).toBe(true); // Like mobile browsers, this print() returns before printing ends, so the tree stays // until the print media query stops matching. await expect(page.locator(".bdt-print-root")).toHaveCount(1); await page.emulateMedia({ media: "screen" }); await expect(page.locator(".bdt-print-root")).toHaveCount(0); await income.fill("2000"); - await expect(page.getByRole("button", { name: "Print / Save as PDF" })).toBeDisabled(); + await expect( + page.getByRole("button", { name: "Print / Save as PDF" }), + ).toBeDisabled(); await expect( page.getByText("Updating your next steps…", { exact: true }), ).toBeVisible(); @@ -159,12 +201,14 @@ for (const showWhen of ["whenDecided", "whenComplete"]) { page.getByRole("link", { name: "Apply for this benefit" }), ).toHaveCount(0); await expect( - next.getByText("Requirements not met", { exact: true }), + nextSteps.getByText("Requirements not met", { exact: true }), ).toBeVisible(); - await expect(next.getByRole("listitem")).toHaveText( + await expect(nextSteps.getByRole("listitem")).toHaveText( "Income must be below $1,000", ); - await expect(next.getByText("Ask about other assistance.")).toBeVisible(); + await expect( + nextSteps.getByText("Ask about other assistance."), + ).toBeVisible(); fail = true; await income.fill("600"); await expect(