From f010d40f6a38945d2a408b8728a15cca69f9b649 Mon Sep 17 00:00:00 2001
From: Preston Cabe
Date: Thu, 22 Oct 2026 17:56:19 -0400
Subject: [PATCH 01/16] Add configurable next steps form component
---
builder-frontend/README.md | 19 ++
.../src/components/screener/Screener.tsx | 11 +-
.../FormEditorView.bindings.test.tsx | 126 ++++++++++-
.../screenerEditor/FormEditorView.tsx | 190 ++++++++++++-----
.../NextStepsContentModal.test.tsx | 66 ++++++
.../screenerEditor/NextStepsContentModal.tsx | 132 ++++++++++++
.../customFormFields/index.js | 2 +
.../nextSteps/NextSteps.test.ts | 195 ++++++++++++++++++
.../formJsExtensions/nextSteps/NextSteps.ts | 151 ++++++++++++++
.../formJsExtensions/nextSteps/content.ts | 34 +++
.../nextSteps/editorModule.ts | 89 ++++++++
.../formJsExtensions/nextSteps/nextSteps.css | 54 +++++
.../screenerEditor/preview/Preview.tsx | 5 +-
.../shared/screeningCompletionFlow.test.tsx | 18 +-
e2e/playwright.config.ts | 4 +-
e2e/tests/nextSteps.spec.ts | 99 +++++++++
e2e/tests/nextStepsPublic.spec.ts | 154 ++++++++++++++
17 files changed, 1280 insertions(+), 69 deletions(-)
create mode 100644 builder-frontend/src/components/screenerEditor/NextStepsContentModal.test.tsx
create mode 100644 builder-frontend/src/components/screenerEditor/NextStepsContentModal.tsx
create mode 100644 builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.test.ts
create mode 100644 builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/NextSteps.ts
create mode 100644 builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/content.ts
create mode 100644 builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/editorModule.ts
create mode 100644 builder-frontend/src/components/screenerEditor/formJsExtensions/nextSteps/nextSteps.css
create mode 100644 e2e/tests/nextSteps.spec.ts
create mode 100644 e2e/tests/nextStepsPublic.spec.ts
diff --git a/builder-frontend/README.md b/builder-frontend/README.md
index 3736d590..ab24b44f 100644
--- a/builder-frontend/README.md
+++ b/builder-frontend/README.md
@@ -57,3 +57,22 @@ The hook uses the viewer's `FormContext`, shared by both field renderers. The
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.
+
+## Next steps component
+
+Analysts can place **Next steps** from the presentation palette. Its `next_steps`
+schema field stores `benefitContent`, a map from benefit ID to the `NextSteps`
+shape, and `showWhen`: `whenDecided` (default) or `whenComplete`. Content is copied
+when the field is inserted. The properties panel opens a modal to edit the copy
+or reset an individual benefit from its source. New benefits need content added
+to existing components; removed benefits are ignored when displaying results.
+
+Editor startup loads the benefit sources before enabling insertion. Failed
+loads show a retry action and preserve saved component content. Content edits
+change the form draft and require saving the form. Publish snapshots that schema;
+viewers do not fetch the working benefit content.
+
+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.
diff --git a/builder-frontend/src/components/screener/Screener.tsx b/builder-frontend/src/components/screener/Screener.tsx
index b1053fc0..d0de6a86 100644
--- a/builder-frontend/src/components/screener/Screener.tsx
+++ b/builder-frontend/src/components/screener/Screener.tsx
@@ -19,6 +19,7 @@ import {
import HiddenQuestionsNotice from "@/components/shared/HiddenQuestionsNotice";
import ScreeningComplete from "@/components/shared/ScreeningComplete";
+import { hasNextSteps } from "@/components/screenerEditor/formJsExtensions/nextSteps/content";
import type { PublishedScreener, ScreenerResult } from "@/types";
import {
@@ -161,10 +162,12 @@ export default function Screener() {
change an answer to try again.
-
+
+
+ unneededQuestionPaths().length}
showAllQuestions={showAllQuestions}
diff --git a/builder-frontend/src/components/screenerEditor/FormEditorView.bindings.test.tsx b/builder-frontend/src/components/screenerEditor/FormEditorView.bindings.test.tsx
index 6ee02841..ad29d18a 100644
--- a/builder-frontend/src/components/screenerEditor/FormEditorView.bindings.test.tsx
+++ b/builder-frontend/src/components/screenerEditor/FormEditorView.bindings.test.tsx
@@ -2,6 +2,7 @@
import { createSignal } from "solid-js";
import { render } from "solid-js/web";
+import { act } from "preact/test-utils";
import { afterEach, beforeEach, expect, it, vi } from "vitest";
import { extractFormPaths } from "@/utils/formSchemaUtils";
@@ -27,6 +28,13 @@ vi.mock("@/api/screener", () => ({
saveFormSchema: vi.fn(),
fetchFormPaths: vi.fn(),
}));
+vi.mock("@/api/benefit", () => ({
+ fetchScreenerBenefit: vi.fn(async (_screenerId, id) => ({
+ id,
+ name: id,
+ checks: [],
+ })),
+}));
import {
draftFormSchema,
@@ -34,9 +42,11 @@ import {
fetchFormPaths,
} from "@/api/screener";
import FormEditorView from "./FormEditorView";
+import { fetchScreenerBenefit } from "@/api/benefit";
let dispose: (() => void) | undefined;
beforeEach(() => {
+ editor.instance = undefined;
vi.stubGlobal(
"IntersectionObserver",
class {
@@ -46,11 +56,68 @@ beforeEach(() => {
},
);
});
-afterEach(() => {
+afterEach(async () => {
+ await act(async () => {});
dispose?.();
document.body.replaceChildren();
vi.clearAllMocks();
- vi.unstubAllGlobals();
+});
+// form-js has deferred Preact effects; keep the DOM shim for this file's environment.
+
+it("preserves saved component content after a failed source load and retry", async () => {
+ vi.mocked(fetchFormPaths).mockResolvedValue({ paths: [] });
+ const benefit = {
+ id: "housing",
+ name: "Housing",
+ description: "",
+ checks: [],
+ nextSteps: { eligible: { body: "New source instructions" } },
+ };
+ vi.mocked(fetchScreenerBenefit)
+ .mockRejectedValueOnce(new Error("Offline"))
+ .mockResolvedValueOnce(benefit);
+ const [schema, setSchema] = createSignal({
+ id: "form",
+ type: "default",
+ schemaVersion: 18,
+ components: [
+ {
+ id: "next",
+ type: "next_steps",
+ benefitContent: { housing: { eligible: { body: "Published copy" } } },
+ },
+ ],
+ });
+ const container = document.body.appendChild(document.createElement("div"));
+ dispose = render(
+ () => (
+ [benefit]}
+ />
+ ),
+ container,
+ );
+ await vi.waitFor(() =>
+ expect(container.querySelector('[role="alert"]')?.textContent).toContain(
+ "could not be loaded",
+ ),
+ );
+ expect(
+ editor.instance.saveSchema().components[0].benefitContent.housing.eligible
+ .body,
+ ).toBe("Published copy");
+ Array.from(container.querySelectorAll("button"))
+ .find((button) => button.textContent === "Try again")!
+ .click();
+ await vi.waitFor(() =>
+ expect(container.querySelector('[role="alert"]')).toBeNull(),
+ );
+ expect(
+ editor.instance.saveSchema().components[0].benefitContent.housing.eligible
+ .body,
+ ).toBe("Published copy");
});
it("keeps every required binding after the actual editor finishes importing and saving a draft", async () => {
@@ -164,7 +231,7 @@ it("provides reactive editor samples keyed to the screener's benefits", async ()
container,
);
await vi.waitFor(() =>
- expect(editor.instance.get("screeningResults").getSnapshot().mode).toBe(
+ expect(editor.instance?.get("screeningResults").getSnapshot().mode).toBe(
"editor",
),
);
@@ -176,3 +243,56 @@ it("provides reactive editor samples keyed to the screener's benefits", async ()
expect(service.getSnapshot().results.housing).toBeUndefined();
expect(editor.instance.saveSchema()).toEqual(saved);
});
+
+it("copies next steps only on insertion, keeps them out of answers, and preserves imports and undo/redo", async () => {
+ vi.mocked(fetchFormPaths).mockResolvedValue({ paths: [] });
+ const source = {
+ id: "housing",
+ name: "Housing",
+ description: "",
+ checks: [],
+ nextSteps: { eligible: { body: "Original benefit instructions" } },
+ };
+ vi.mocked(fetchScreenerBenefit).mockResolvedValue(source);
+ const [schema, setSchema] = createSignal();
+ const container = document.body.appendChild(document.createElement("div"));
+ dispose = render(
+ () => (
+ [source]}
+ />
+ ),
+ container,
+ );
+ await vi.waitFor(() => expect(editor.instance).toBeDefined());
+ const model = editor.instance.get("modeling");
+ const registry = editor.instance.get("formFieldRegistry");
+ const field = model.addFormField(
+ { type: "next_steps" },
+ registry.getAll()[0],
+ 0,
+ );
+ expect(field.benefitContent.housing).toEqual(source.nextSteps);
+ expect(field.key).toBeUndefined();
+ await new Promise((resolve) => setTimeout(resolve, 0));
+ expect(field.key).toBeUndefined();
+ expect(extractFormPaths(editor.instance.saveSchema())).toEqual([]);
+ source.nextSteps.eligible.body = "Updated benefit instructions";
+ expect(field.benefitContent.housing.eligible.body).toBe(
+ "Original benefit instructions",
+ );
+ editor.instance.get("commandStack").undo();
+ expect(registry.get(field.id)).toBeUndefined();
+ editor.instance.get("commandStack").redo();
+ expect(registry.get(field.id).benefitContent.housing.eligible.body).toBe(
+ "Original benefit instructions",
+ );
+ const saved = editor.instance.saveSchema();
+ await editor.instance.importSchema(saved);
+ expect(
+ editor.instance.saveSchema().components[0].benefitContent.housing.eligible
+ .body,
+ ).toBe("Original benefit instructions");
+});
diff --git a/builder-frontend/src/components/screenerEditor/FormEditorView.tsx b/builder-frontend/src/components/screenerEditor/FormEditorView.tsx
index 6c55adb2..849831ff 100644
--- a/builder-frontend/src/components/screenerEditor/FormEditorView.tsx
+++ b/builder-frontend/src/components/screenerEditor/FormEditorView.tsx
@@ -9,6 +9,8 @@ import {
Show,
Switch,
Accessor,
+ getOwner,
+ runWithOwner,
} from "solid-js";
import { useParams } from "@solidjs/router";
@@ -33,6 +35,10 @@ import {
} from "../../api/screener";
import { extractFormPaths } from "../../utils/formSchemaUtils";
import Loading from "../Loading";
+import { fetchScreenerBenefit } from "@/api/benefit";
+import NextStepsContentModal from "./NextStepsContentModal";
+import { nextStepsEditorModule } from "./formJsExtensions/nextSteps/editorModule";
+import { NEXT_STEPS_TYPE } from "./formJsExtensions/nextSteps/content";
import "@bpmn-io/form-js/dist/assets/form-js.css";
import "@bpmn-io/form-js-editor/dist/assets/form-js-editor.css";
@@ -46,6 +52,24 @@ function FormEditorView({ formSchema, setFormSchema, benefits = () => [] }) {
let disposed = false;
let importingDraft = false;
const params = useParams();
+ const editorOwner = getOwner();
+ const [editorReady, setEditorReady] = createSignal(false);
+ const [contentField, setContentField] = createSignal();
+ const [benefitSources, { refetch: reloadBenefitSources }] = createResource(
+ () => [params.screenerId, benefits()] as const,
+ async ([screenerId, details]) => {
+ const loaded = await Promise.allSettled(
+ details.map((benefit) => fetchScreenerBenefit(screenerId, benefit.id)),
+ );
+ return {
+ failed: loaded.some((result) => result.status === "rejected"),
+ benefits: loaded.flatMap((result) =>
+ result.status === "fulfilled" ? [result.value] : [],
+ ),
+ };
+ },
+ );
+ const benefitContentError = () => benefitSources()?.failed ?? false;
// Fetch form paths from backend (replaces local transformation logic)
const [formPaths] = createResource(
@@ -69,73 +93,86 @@ function FormEditorView({ formSchema, setFormSchema, benefits = () => [] }) {
};
onMount(() => {
- formEditor = new FormEditor({
- container,
- additionalModules: [
- // FilterFormComponentsModule,
- CustomFormFieldsModule,
- screeningResultsModule,
- pathOptionsModule,
- customKeyModule,
- ],
- });
- const screeningResults =
- formEditor.get("screeningResults");
- createEffect(() => screeningResults.showEditorSamples(benefits()));
+ // Finish loading benefit content before insertion can copy it. Existing schema
+ // content is never refreshed from these sources automatically.
+ createEffect(() => {
+ if (benefitSources.loading || formEditor) return;
+ runWithOwner(editorOwner, () => {
+ formEditor = new FormEditor({
+ container,
+ additionalModules: [
+ // FilterFormComponentsModule,
+ CustomFormFieldsModule,
+ screeningResultsModule,
+ pathOptionsModule,
+ customKeyModule,
+ nextStepsEditorModule({
+ benefits: () => benefitSources()?.benefits ?? [],
+ open: (field) => setContentField(field),
+ }),
+ ],
+ });
+ const screeningResults =
+ formEditor.get("screeningResults");
+ createEffect(() => screeningResults.showEditorSamples(benefits()));
- if (formSchema()) {
- formEditor.importSchema(formSchema()).catch((err) => {
- console.error("Failed to load schema", err);
- });
- } else {
- formEditor.importSchema(emptySchema).catch((err) => {
- console.error("Failed to load schema", err);
- });
- }
+ if (formSchema()) {
+ formEditor.importSchema(formSchema()).catch((err) => {
+ console.error("Failed to load schema", err);
+ });
+ } else {
+ formEditor.importSchema(emptySchema).catch((err) => {
+ console.error("Failed to load schema", err);
+ });
+ }
- formEditor.on("changed", (e) => {
- if (importingDraft) return;
- setIsUnsaved(true);
- setFormSchema(e.schema);
- });
+ formEditor.on("changed", (e) => {
+ if (importingDraft) return;
+ setIsUnsaved(true);
+ setFormSchema(e.schema);
+ });
- // Set default key to field ID when a new form field is added
- const eventBus = formEditor.get("eventBus") as any;
- const modeling = formEditor.get("modeling") as any;
- eventBus.on("formField.add", (event: { formField: any }) => {
- const field = event.formField;
+ // Set default key to field ID when a new form field is added
+ const eventBus = formEditor.get("eventBus") as any;
+ const modeling = formEditor.get("modeling") as any;
+ eventBus.on("formField.add", (event: { formField: any }) => {
+ const field = event.formField;
- // Imports also emit formField.add; keep the keys of imported fields.
- // Skip group components as they don't use keys
- if (
- !importingDraft &&
- field &&
- field.id &&
- field.type !== "group" &&
- field.type !== "default"
- ) {
- // Use setTimeout to ensure the field is fully added before modifying
- setTimeout(() => {
- if (!disposed) {
- modeling.editFormField(field, "key", field.id);
+ // Imports also emit formField.add; keep the keys of imported fields.
+ // Skip group components as they don't use keys
+ if (
+ !importingDraft &&
+ field &&
+ field.id &&
+ field.type !== NEXT_STEPS_TYPE &&
+ field.type !== "group" &&
+ field.type !== "default"
+ ) {
+ // Use setTimeout to ensure the field is fully added before modifying
+ setTimeout(() => {
+ if (!disposed) {
+ modeling.editFormField(field, "key", field.id);
+ }
+ }, 0);
}
- }, 0);
- }
+ });
+ setEditorReady(true);
+ });
});
+ });
- onCleanup(() => {
- disposed = true;
- if (formEditor) {
- formEditor.destroy();
- formEditor = null;
- clearTimeout(timeoutId);
- }
- });
+ onCleanup(() => {
+ disposed = true;
+ if (formEditor) {
+ formEditor.destroy();
+ formEditor = null;
+ clearTimeout(timeoutId);
+ }
});
// Update path options when form paths load from backend
createEffect(() => {
- if (!formEditor || formPaths.loading) return;
+ if (!editorReady() || formPaths.loading) return;
const currentFormPaths: FormPath[] = formPaths() || [];
const pathOptionsService = formEditor.get(
@@ -241,6 +278,39 @@ function FormEditorView({ formSchema, setFormSchema, benefits = () => [] }) {
return (
<>
+
+
+
+
+
+ Some benefit content could not be loaded. Existing component content
+ is preserved.{" "}
+
+