@fogpipe/forma-react 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fogpipe/forma-react",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Headless React form renderer for Forma specifications",
   "type": "module",
   "main": "./dist/index.js",
@@ -30,7 +30,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@fogpipe/forma-core": "^0.8.2"
+    "@fogpipe/forma-core": "^0.9.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"

package/src/__tests__/diabetes-trial-flow.test.ts

@@ -0,0 +1,776 @@
+/**
+ * Tests for the diabetes clinical trial enrollment form wizard flow
+ *
+ * This test suite documents expected wizard behavior for a complex multi-page
+ * form with conditional page visibility based on computed eligibility fields.
+ *
+ * The form has:
+ * - 10 pages with conditional visibility
+ * - Complex computed field dependency chains for eligibility determination
+ * - Conditional signature flows (participant vs LAR, optional witness)
+ */
+
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useForma } from "../useForma.js";
+import type { Forma } from "@fogpipe/forma-core";
+
+// Simplified version of the diabetes trial spec for focused testing
+function createDiabetesTrialSpec(): Forma {
+  return {
+    version: "1.0",
+    meta: {
+      id: "diabetes-trial-enrollment",
+      title: "Diabetes Medication Clinical Trial Enrollment Form",
+    },
+    schema: {
+      type: "object",
+      properties: {
+        // Study info (pre-filled)
+        studyName: { type: "string" },
+        protocolNumber: { type: "string" },
+        // Participant info
+        screeningId: { type: "string" },
+        participantInitials: { type: "string" },
+        dateOfBirth: { type: "string", format: "date" },
+        // Inclusion criteria
+        inclusionAge: { type: "boolean" },
+        inclusionDiagnosis: { type: "boolean" },
+        inclusionVisits: { type: "boolean" },
+        inclusionConsent: { type: "boolean" },
+        // Exclusion criteria
+        exclusionPregnant: { type: "boolean" },
+        exclusionAllergy: { type: "boolean" },
+        exclusionRecentStudy: { type: "boolean" },
+        exclusionKidney: { type: "boolean" },
+        exclusionSglt2: { type: "boolean" },
+        // Ineligibility
+        ineligibilityReason: { type: "string" },
+        ineligibilityNotes: { type: "string" },
+        // Consents
+        consentPurpose: { type: "boolean" },
+        consentProcedures: { type: "boolean" },
+        consentRisks: { type: "boolean" },
+        consentBenefits: { type: "boolean" },
+        consentVoluntary: { type: "boolean" },
+        consentDataHandling: { type: "boolean" },
+        // Optional consents
+        optionalSamples: { type: "boolean" },
+        optionalContact: { type: "boolean" },
+        optionalGenetic: { type: "boolean" },
+        // Signatures
+        signingOnBehalf: { type: "boolean" },
+        participantSignatureName: { type: "string" },
+        participantSignatureDateTime: { type: "string" },
+        larName: { type: "string" },
+        larRelationship: { type: "string" },
+        larSignatureDateTime: { type: "string" },
+        researcherName: { type: "string" },
+        researcherConfirm: { type: "boolean" },
+        researcherSignatureDateTime: { type: "string" },
+        witnessRequired: { type: "boolean" },
+        witnessName: { type: "string" },
+        witnessSignatureDateTime: { type: "string" },
+        // Enrollment
+        enrollmentDate: { type: "string" },
+        randomizationNumber: { type: "string" },
+        treatmentGroup: { type: "string" },
+      },
+    },
+    fields: {
+      studyName: { type: "text", label: "Study Name", enabledWhen: "false" },
+      protocolNumber: { type: "text", label: "Protocol Number", enabledWhen: "false" },
+      screeningId: { type: "text", label: "Screening ID" },
+      participantInitials: { type: "text", label: "Participant Initials" },
+      dateOfBirth: { type: "date", label: "Date of Birth" },
+      inclusionAge: { type: "boolean", label: "Age between 18-65 years" },
+      inclusionDiagnosis: { type: "boolean", label: "Confirmed Type 2 diabetes diagnosis" },
+      inclusionVisits: { type: "boolean", label: "Willing to attend all study visits" },
+      inclusionConsent: { type: "boolean", label: "Can give informed consent" },
+      exclusionPregnant: { type: "boolean", label: "Pregnant or planning to become pregnant" },
+      exclusionAllergy: { type: "boolean", label: "Allergy to metformin or similar drugs" },
+      exclusionRecentStudy: { type: "boolean", label: "Participated in another drug study in last 30 days" },
+      exclusionKidney: { type: "boolean", label: "History of severe kidney disease" },
+      exclusionSglt2: { type: "boolean", label: "Currently taking SGLT2 inhibitors" },
+      ineligibilityReason: { type: "textarea", label: "Ineligibility Reason", enabledWhen: "false" },
+      ineligibilityNotes: { type: "textarea", label: "Additional Notes" },
+      consentPurpose: { type: "boolean", label: "I have read and understand the study purpose" },
+      consentProcedures: { type: "boolean", label: "I understand the procedures I will undergo" },
+      consentRisks: { type: "boolean", label: "I understand the risks involved" },
+      consentBenefits: { type: "boolean", label: "I understand the potential benefits" },
+      consentVoluntary: { type: "boolean", label: "I understand participation is voluntary" },
+      consentDataHandling: { type: "boolean", label: "I understand how my data will be handled" },
+      optionalSamples: { type: "boolean", label: "I consent to storing blood samples" },
+      optionalContact: { type: "boolean", label: "I consent to being contacted about other studies" },
+      optionalGenetic: { type: "boolean", label: "I consent to genetic analysis" },
+      signingOnBehalf: { type: "boolean", label: "Is someone signing on behalf of the participant?" },
+      participantSignatureName: {
+        type: "text",
+        label: "Participant Signature Name",
+        visibleWhen: "signingOnBehalf = false",
+        requiredWhen: "signingOnBehalf = false",
+      },
+      participantSignatureDateTime: {
+        type: "datetime",
+        label: "Participant Signature Date and Time",
+        visibleWhen: "signingOnBehalf = false",
+        requiredWhen: "signingOnBehalf = false",
+      },
+      larName: {
+        type: "text",
+        label: "Legally Authorized Representative Name",
+        visibleWhen: "signingOnBehalf = true",
+        requiredWhen: "signingOnBehalf = true",
+      },
+      larRelationship: {
+        type: "text",
+        label: "Relationship to Participant",
+        visibleWhen: "signingOnBehalf = true",
+        requiredWhen: "signingOnBehalf = true",
+      },
+      larSignatureDateTime: {
+        type: "datetime",
+        label: "Representative Signature Date and Time",
+        visibleWhen: "signingOnBehalf = true",
+        requiredWhen: "signingOnBehalf = true",
+      },
+      researcherName: { type: "text", label: "Researcher Name" },
+      researcherConfirm: { type: "boolean", label: "I confirm I have properly explained the study" },
+      researcherSignatureDateTime: { type: "datetime", label: "Researcher Signature Date and Time" },
+      witnessRequired: { type: "boolean", label: "Is a witness signature required?" },
+      witnessName: {
+        type: "text",
+        label: "Witness Name",
+        visibleWhen: "witnessRequired = true",
+        requiredWhen: "witnessRequired = true",
+      },
+      witnessSignatureDateTime: {
+        type: "datetime",
+        label: "Witness Signature Date and Time",
+        visibleWhen: "witnessRequired = true",
+        requiredWhen: "witnessRequired = true",
+      },
+      enrollmentDate: { type: "date", label: "Enrollment Date" },
+      randomizationNumber: { type: "text", label: "Randomization Number" },
+      treatmentGroup: {
+        type: "select",
+        label: "Treatment Group",
+        options: [
+          { value: "group-a", label: "Group A - Active Treatment" },
+          { value: "group-b", label: "Group B - Placebo" },
+          { value: "group-c", label: "Group C - Active Comparator" },
+        ],
+      },
+    },
+    fieldOrder: [
+      "studyName", "protocolNumber",
+      "screeningId", "participantInitials", "dateOfBirth",
+      "inclusionAge", "inclusionDiagnosis", "inclusionVisits", "inclusionConsent",
+      "exclusionPregnant", "exclusionAllergy", "exclusionRecentStudy", "exclusionKidney", "exclusionSglt2",
+      "ineligibilityReason", "ineligibilityNotes",
+      "consentPurpose", "consentProcedures", "consentRisks", "consentBenefits", "consentVoluntary", "consentDataHandling",
+      "optionalSamples", "optionalContact", "optionalGenetic",
+      "signingOnBehalf", "participantSignatureName", "participantSignatureDateTime",
+      "larName", "larRelationship", "larSignatureDateTime",
+      "researcherName", "researcherConfirm", "researcherSignatureDateTime",
+      "witnessRequired", "witnessName", "witnessSignatureDateTime",
+      "enrollmentDate", "randomizationNumber", "treatmentGroup",
+    ],
+    computed: {
+      // Inclusion checks
+      allInclusionAnswered: {
+        expression: "(inclusionAge = true or inclusionAge = false) and (inclusionDiagnosis = true or inclusionDiagnosis = false) and (inclusionVisits = true or inclusionVisits = false) and (inclusionConsent = true or inclusionConsent = false)",
+      },
+      allInclusionMet: {
+        expression: "inclusionAge = true and inclusionDiagnosis = true and inclusionVisits = true and inclusionConsent = true",
+      },
+      // Exclusion checks
+      allExclusionAnswered: {
+        expression: "(exclusionPregnant = true or exclusionPregnant = false) and (exclusionAllergy = true or exclusionAllergy = false) and (exclusionRecentStudy = true or exclusionRecentStudy = false) and (exclusionKidney = true or exclusionKidney = false) and (exclusionSglt2 = true or exclusionSglt2 = false)",
+      },
+      anyExclusionMet: {
+        expression: "exclusionPregnant = true or exclusionAllergy = true or exclusionRecentStudy = true or exclusionKidney = true or exclusionSglt2 = true",
+      },
+      // Eligibility determination
+      eligibilityDetermined: {
+        expression: "computed.allInclusionAnswered = true and computed.allExclusionAnswered = true",
+      },
+      eligible: {
+        expression: "computed.eligibilityDetermined = true and computed.allInclusionMet = true and computed.anyExclusionMet = false",
+      },
+      ineligible: {
+        expression: "computed.eligibilityDetermined = true and (computed.allInclusionMet = false or computed.anyExclusionMet = true)",
+      },
+      // Consent checks
+      allMainConsentsSigned: {
+        expression: "consentPurpose = true and consentProcedures = true and consentRisks = true and consentBenefits = true and consentVoluntary = true and consentDataHandling = true",
+      },
+      // Signature checks - using null-safe patterns
+      hasParticipantSignature: {
+        expression: "signingOnBehalf != true and participantSignatureName != null and participantSignatureDateTime != null",
+      },
+      hasLarSignature: {
+        expression: "signingOnBehalf = true and larName != null and larRelationship != null and larSignatureDateTime != null",
+      },
+      hasValidSignature: {
+        expression: "computed.hasParticipantSignature = true or computed.hasLarSignature = true",
+      },
+      hasResearcherSignature: {
+        expression: "researcherName != null and researcherConfirm = true and researcherSignatureDateTime != null",
+      },
+      hasWitnessSignature: {
+        expression: "witnessRequired != true or (witnessName != null and witnessSignatureDateTime != null)",
+      },
+      allSignaturesComplete: {
+        expression: "computed.hasValidSignature = true and computed.hasResearcherSignature = true and computed.hasWitnessSignature = true",
+      },
+      // Final enrollment gate
+      canEnroll: {
+        expression: "computed.eligible = true and computed.allMainConsentsSigned = true and computed.allSignaturesComplete = true",
+      },
+    },
+    pages: [
+      {
+        id: "study-information",
+        title: "Study Information",
+        fields: ["studyName", "protocolNumber"],
+      },
+      {
+        id: "participant-information",
+        title: "Participant Information",
+        fields: ["screeningId", "participantInitials", "dateOfBirth"],
+      },
+      {
+        id: "inclusion-criteria",
+        title: "Eligibility Screening - Inclusion Criteria",
+        fields: ["inclusionAge", "inclusionDiagnosis", "inclusionVisits", "inclusionConsent"],
+      },
+      {
+        id: "exclusion-criteria",
+        title: "Eligibility Screening - Exclusion Criteria",
+        fields: ["exclusionPregnant", "exclusionAllergy", "exclusionRecentStudy", "exclusionKidney", "exclusionSglt2"],
+      },
+      {
+        id: "ineligibility-documentation",
+        title: "Ineligibility Documentation",
+        fields: ["ineligibilityReason", "ineligibilityNotes"],
+        visibleWhen: "computed.ineligible = true",
+      },
+      {
+        id: "main-consents",
+        title: "Informed Consent - Main Consents",
+        fields: ["consentPurpose", "consentProcedures", "consentRisks", "consentBenefits", "consentVoluntary", "consentDataHandling"],
+        visibleWhen: "computed.eligible = true",
+      },
+      {
+        id: "optional-consents",
+        title: "Optional Consents",
+        fields: ["optionalSamples", "optionalContact", "optionalGenetic"],
+        visibleWhen: "computed.eligible = true",
+      },
+      {
+        id: "participant-signature",
+        title: "Participant Signature",
+        fields: ["signingOnBehalf", "participantSignatureName", "participantSignatureDateTime", "larName", "larRelationship", "larSignatureDateTime"],
+        visibleWhen: "computed.eligible = true and computed.allMainConsentsSigned = true",
+      },
+      {
+        id: "researcher-witness-signatures",
+        title: "Researcher and Witness Signatures",
+        fields: ["researcherName", "researcherConfirm", "researcherSignatureDateTime", "witnessRequired", "witnessName", "witnessSignatureDateTime"],
+        visibleWhen: "computed.eligible = true and computed.allMainConsentsSigned = true and computed.hasValidSignature = true",
+      },
+      {
+        id: "enrollment-details",
+        title: "Enrollment Details",
+        fields: ["enrollmentDate", "randomizationNumber", "treatmentGroup"],
+        visibleWhen: "computed.canEnroll = true",
+      },
+    ],
+  };
+}
+
+describe("diabetes trial enrollment wizard", () => {
+  describe("initial page visibility", () => {
+    it("should show first 4 pages unconditionally", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      const pages = result.current.wizard?.pages;
+      expect(pages).toHaveLength(10);
+
+      // First 4 pages always visible
+      expect(pages?.[0].id).toBe("study-information");
+      expect(pages?.[0].visible).toBe(true);
+
+      expect(pages?.[1].id).toBe("participant-information");
+      expect(pages?.[1].visible).toBe(true);
+
+      expect(pages?.[2].id).toBe("inclusion-criteria");
+      expect(pages?.[2].visible).toBe(true);
+
+      expect(pages?.[3].id).toBe("exclusion-criteria");
+      expect(pages?.[3].visible).toBe(true);
+    });
+
+    it("should hide conditional pages initially", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      const pages = result.current.wizard?.pages;
+
+      // Conditional pages hidden initially
+      expect(pages?.[4].id).toBe("ineligibility-documentation");
+      expect(pages?.[4].visible).toBe(false);
+
+      expect(pages?.[5].id).toBe("main-consents");
+      expect(pages?.[5].visible).toBe(false);
+
+      expect(pages?.[6].id).toBe("optional-consents");
+      expect(pages?.[6].visible).toBe(false);
+
+      expect(pages?.[7].id).toBe("participant-signature");
+      expect(pages?.[7].visible).toBe(false);
+
+      expect(pages?.[8].id).toBe("researcher-witness-signatures");
+      expect(pages?.[8].visible).toBe(false);
+
+      expect(pages?.[9].id).toBe("enrollment-details");
+      expect(pages?.[9].visible).toBe(false);
+    });
+  });
+
+  describe("eligibility determination", () => {
+    it("should determine eligibility only after all criteria answered", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Initially not determined
+      expect(result.current.computed?.eligibilityDetermined).toBeFalsy();
+
+      // Fill inclusion criteria
+      act(() => {
+        result.current.setFieldValue("inclusionAge", true);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+      });
+
+      // Still not determined - exclusion not answered
+      expect(result.current.computed?.eligibilityDetermined).toBeFalsy();
+
+      // Fill exclusion criteria
+      act(() => {
+        result.current.setFieldValue("exclusionPregnant", false);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      // Now determined
+      expect(result.current.computed?.eligibilityDetermined).toBe(true);
+    });
+
+    it("should mark eligible when all inclusion met and no exclusion met", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Fill all criteria - eligible scenario
+      act(() => {
+        // All inclusion = true
+        result.current.setFieldValue("inclusionAge", true);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+        // All exclusion = false
+        result.current.setFieldValue("exclusionPregnant", false);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      expect(result.current.computed?.eligible).toBe(true);
+      expect(result.current.computed?.ineligible).toBe(false);
+    });
+
+    it("should mark ineligible when any inclusion criterion is false", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        // One inclusion = false
+        result.current.setFieldValue("inclusionAge", false);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+        // All exclusion = false
+        result.current.setFieldValue("exclusionPregnant", false);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      expect(result.current.computed?.eligible).toBe(false);
+      expect(result.current.computed?.ineligible).toBe(true);
+    });
+
+    it("should mark ineligible when any exclusion criterion is true", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        // All inclusion = true
+        result.current.setFieldValue("inclusionAge", true);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+        // One exclusion = true (pregnant)
+        result.current.setFieldValue("exclusionPregnant", true);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      expect(result.current.computed?.eligible).toBe(false);
+      expect(result.current.computed?.ineligible).toBe(true);
+    });
+  });
+
+  describe("eligible flow - page visibility", () => {
+    function setupEligibleParticipant(setFieldValue: (field: string, value: unknown) => void) {
+      // All inclusion = true
+      setFieldValue("inclusionAge", true);
+      setFieldValue("inclusionDiagnosis", true);
+      setFieldValue("inclusionVisits", true);
+      setFieldValue("inclusionConsent", true);
+      // All exclusion = false
+      setFieldValue("exclusionPregnant", false);
+      setFieldValue("exclusionAllergy", false);
+      setFieldValue("exclusionRecentStudy", false);
+      setFieldValue("exclusionKidney", false);
+      setFieldValue("exclusionSglt2", false);
+    }
+
+    it("should show consent pages after eligibility confirmed", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupEligibleParticipant(result.current.setFieldValue);
+      });
+
+      const pages = result.current.wizard?.pages;
+      expect(pages?.[5].id).toBe("main-consents");
+      expect(pages?.[5].visible).toBe(true);
+
+      expect(pages?.[6].id).toBe("optional-consents");
+      expect(pages?.[6].visible).toBe(true);
+    });
+
+    it("should show participant signature page after consents signed", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupEligibleParticipant(result.current.setFieldValue);
+      });
+
+      // Signature page not yet visible
+      expect(result.current.wizard?.pages?.[7].visible).toBe(false);
+
+      // Sign all main consents
+      act(() => {
+        result.current.setFieldValue("consentPurpose", true);
+        result.current.setFieldValue("consentProcedures", true);
+        result.current.setFieldValue("consentRisks", true);
+        result.current.setFieldValue("consentBenefits", true);
+        result.current.setFieldValue("consentVoluntary", true);
+        result.current.setFieldValue("consentDataHandling", true);
+      });
+
+      expect(result.current.computed?.allMainConsentsSigned).toBe(true);
+      expect(result.current.wizard?.pages?.[7].visible).toBe(true);
+    });
+
+    it("should show researcher signature page after valid participant signature", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupEligibleParticipant(result.current.setFieldValue);
+        // Sign consents
+        result.current.setFieldValue("consentPurpose", true);
+        result.current.setFieldValue("consentProcedures", true);
+        result.current.setFieldValue("consentRisks", true);
+        result.current.setFieldValue("consentBenefits", true);
+        result.current.setFieldValue("consentVoluntary", true);
+        result.current.setFieldValue("consentDataHandling", true);
+      });
+
+      // Researcher signature page not yet visible
+      expect(result.current.wizard?.pages?.[8].visible).toBe(false);
+
+      // Provide participant signature (not signing on behalf)
+      act(() => {
+        result.current.setFieldValue("signingOnBehalf", false);
+        result.current.setFieldValue("participantSignatureName", "John Doe");
+        result.current.setFieldValue("participantSignatureDateTime", "2024-01-15T10:00:00");
+      });
+
+      expect(result.current.computed?.hasValidSignature).toBe(true);
+      expect(result.current.wizard?.pages?.[8].visible).toBe(true);
+    });
+
+    it("should show enrollment page only after all signatures complete", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupEligibleParticipant(result.current.setFieldValue);
+        // Sign consents
+        result.current.setFieldValue("consentPurpose", true);
+        result.current.setFieldValue("consentProcedures", true);
+        result.current.setFieldValue("consentRisks", true);
+        result.current.setFieldValue("consentBenefits", true);
+        result.current.setFieldValue("consentVoluntary", true);
+        result.current.setFieldValue("consentDataHandling", true);
+        // Participant signature
+        result.current.setFieldValue("signingOnBehalf", false);
+        result.current.setFieldValue("participantSignatureName", "John Doe");
+        result.current.setFieldValue("participantSignatureDateTime", "2024-01-15T10:00:00");
+      });
+
+      // Enrollment page not yet visible
+      expect(result.current.wizard?.pages?.[9].visible).toBe(false);
+
+      // Add researcher signature
+      act(() => {
+        result.current.setFieldValue("researcherName", "Dr. Smith");
+        result.current.setFieldValue("researcherConfirm", true);
+        result.current.setFieldValue("researcherSignatureDateTime", "2024-01-15T10:30:00");
+        result.current.setFieldValue("witnessRequired", false);
+      });
+
+      expect(result.current.computed?.canEnroll).toBe(true);
+      expect(result.current.wizard?.pages?.[9].visible).toBe(true);
+    });
+  });
+
+  describe("ineligible flow - page visibility", () => {
+    it("should show ineligibility documentation when participant is ineligible", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        // One inclusion = false (not eligible)
+        result.current.setFieldValue("inclusionAge", false);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+        // All exclusion answered
+        result.current.setFieldValue("exclusionPregnant", false);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      const pages = result.current.wizard?.pages;
+
+      // Ineligibility page visible
+      expect(pages?.[4].id).toBe("ineligibility-documentation");
+      expect(pages?.[4].visible).toBe(true);
+
+      // Consent pages hidden
+      expect(pages?.[5].visible).toBe(false);
+      expect(pages?.[6].visible).toBe(false);
+    });
+
+    it("should hide eligible-only pages when ineligible", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        // All inclusion = true
+        result.current.setFieldValue("inclusionAge", true);
+        result.current.setFieldValue("inclusionDiagnosis", true);
+        result.current.setFieldValue("inclusionVisits", true);
+        result.current.setFieldValue("inclusionConsent", true);
+        // One exclusion = true (pregnant - ineligible)
+        result.current.setFieldValue("exclusionPregnant", true);
+        result.current.setFieldValue("exclusionAllergy", false);
+        result.current.setFieldValue("exclusionRecentStudy", false);
+        result.current.setFieldValue("exclusionKidney", false);
+        result.current.setFieldValue("exclusionSglt2", false);
+      });
+
+      const pages = result.current.wizard?.pages;
+
+      // Ineligibility visible
+      expect(pages?.[4].visible).toBe(true);
+
+      // All eligible-only pages hidden
+      expect(pages?.[5].visible).toBe(false); // main-consents
+      expect(pages?.[6].visible).toBe(false); // optional-consents
+      expect(pages?.[7].visible).toBe(false); // participant-signature
+      expect(pages?.[8].visible).toBe(false); // researcher-witness-signatures
+      expect(pages?.[9].visible).toBe(false); // enrollment-details
+    });
+  });
+
+  describe("signature flow variations", () => {
+    function setupReadyForSignature(setFieldValue: (field: string, value: unknown) => void) {
+      // Eligible
+      setFieldValue("inclusionAge", true);
+      setFieldValue("inclusionDiagnosis", true);
+      setFieldValue("inclusionVisits", true);
+      setFieldValue("inclusionConsent", true);
+      setFieldValue("exclusionPregnant", false);
+      setFieldValue("exclusionAllergy", false);
+      setFieldValue("exclusionRecentStudy", false);
+      setFieldValue("exclusionKidney", false);
+      setFieldValue("exclusionSglt2", false);
+      // Consents signed
+      setFieldValue("consentPurpose", true);
+      setFieldValue("consentProcedures", true);
+      setFieldValue("consentRisks", true);
+      setFieldValue("consentBenefits", true);
+      setFieldValue("consentVoluntary", true);
+      setFieldValue("consentDataHandling", true);
+    }
+
+    it("should show participant fields when not signing on behalf", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupReadyForSignature(result.current.setFieldValue);
+        result.current.setFieldValue("signingOnBehalf", false);
+      });
+
+      // Participant fields visible
+      expect(result.current.visibility.participantSignatureName).toBe(true);
+      expect(result.current.visibility.participantSignatureDateTime).toBe(true);
+
+      // LAR fields hidden
+      expect(result.current.visibility.larName).toBe(false);
+      expect(result.current.visibility.larRelationship).toBe(false);
+      expect(result.current.visibility.larSignatureDateTime).toBe(false);
+    });
+
+    it("should show LAR fields when signing on behalf", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupReadyForSignature(result.current.setFieldValue);
+        result.current.setFieldValue("signingOnBehalf", true);
+      });
+
+      // LAR fields visible
+      expect(result.current.visibility.larName).toBe(true);
+      expect(result.current.visibility.larRelationship).toBe(true);
+      expect(result.current.visibility.larSignatureDateTime).toBe(true);
+
+      // Participant fields hidden
+      expect(result.current.visibility.participantSignatureName).toBe(false);
+      expect(result.current.visibility.participantSignatureDateTime).toBe(false);
+    });
+
+    it("should show witness fields when witness required", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupReadyForSignature(result.current.setFieldValue);
+        result.current.setFieldValue("witnessRequired", true);
+      });
+
+      expect(result.current.visibility.witnessName).toBe(true);
+      expect(result.current.visibility.witnessSignatureDateTime).toBe(true);
+    });
+
+    it("should hide witness fields when witness not required", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupReadyForSignature(result.current.setFieldValue);
+        result.current.setFieldValue("witnessRequired", false);
+      });
+
+      expect(result.current.visibility.witnessName).toBe(false);
+      expect(result.current.visibility.witnessSignatureDateTime).toBe(false);
+    });
+
+    it("should accept LAR signature as valid signature", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      act(() => {
+        setupReadyForSignature(result.current.setFieldValue);
+        result.current.setFieldValue("signingOnBehalf", true);
+        result.current.setFieldValue("larName", "Jane Doe");
+        result.current.setFieldValue("larRelationship", "Spouse");
+        result.current.setFieldValue("larSignatureDateTime", "2024-01-15T10:00:00");
+      });
+
+      expect(result.current.computed?.hasLarSignature).toBe(true);
+      expect(result.current.computed?.hasValidSignature).toBe(true);
+    });
+  });
+
+  describe("wizard navigation", () => {
+    it("should navigate through visible pages correctly", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Start on page 0
+      expect(result.current.wizard?.currentPageIndex).toBe(0);
+      expect(result.current.wizard?.currentPage?.id).toBe("study-information");
+
+      // Navigate forward
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+      expect(result.current.wizard?.currentPageIndex).toBe(1);
+      expect(result.current.wizard?.currentPage?.id).toBe("participant-information");
+
+      // Continue to inclusion
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+      expect(result.current.wizard?.currentPage?.id).toBe("inclusion-criteria");
+
+      // Continue to exclusion
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+      expect(result.current.wizard?.currentPage?.id).toBe("exclusion-criteria");
+    });
+
+    it("should skip hidden pages during navigation", () => {
+      const spec = createDiabetesTrialSpec();
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Go to exclusion page (index 3)
+      act(() => {
+        result.current.wizard?.goToPage(3);
+      });
+      expect(result.current.wizard?.currentPage?.id).toBe("exclusion-criteria");
+
+      // Without eligibility determined, next visible page count is limited
+      // The visible pages should be: study-info (0), participant-info (1), inclusion (2), exclusion (3)
+      // Pages 4-9 are conditional and hidden
+      const visiblePages = result.current.wizard?.pages.filter(p => p.visible);
+      expect(visiblePages?.length).toBe(4);
+
+      // Should be on last visible page
+      expect(result.current.wizard?.isLastPage).toBe(true);
+    });
+  });
+});

package/src/__tests__/null-handling.test.ts

@@ -0,0 +1,436 @@
+/**
+ * Tests documenting FEEL null handling behavior in visibility expressions
+ *
+ * These tests document the behavior where FEEL expressions that evaluate to `null`
+ * (due to undefined field references) are silently converted to `false` by
+ * the forma-core engine. This can cause unexpected behavior where pages and fields
+ * become invisible not because the condition is false, but because it couldn't
+ * be evaluated.
+ *
+ * Root cause: forma-core's evaluateBoolean() converts null to false without warning.
+ */
+
+import { describe, it, expect } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+import { useForma } from "../useForma.js";
+import { createTestSpec } from "./test-utils.js";
+
+describe("FEEL null handling in visibility expressions", () => {
+  describe("boolean field null checks", () => {
+    it("should treat undefined boolean as not matching '= true'", () => {
+      const spec = createTestSpec({
+        fields: {
+          accepted: { type: "boolean", label: "Accept terms" },
+          details: {
+            type: "text",
+            label: "Details",
+            visibleWhen: "accepted = true",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Field is undefined initially
+      expect(result.current.data.accepted).toBeUndefined();
+
+      // The visibility expression "accepted = true" evaluates to null when accepted is undefined
+      // forma-core converts this null to false, so the field is hidden
+      // This happens to be the "correct" behavior by accident
+      expect(result.current.visibility.details).toBe(false);
+
+      // When user explicitly sets to true, field becomes visible
+      act(() => {
+        result.current.setFieldValue("accepted", true);
+      });
+      expect(result.current.visibility.details).toBe(true);
+    });
+
+    it("should treat undefined boolean as not matching '= false'", () => {
+      const spec = createTestSpec({
+        fields: {
+          signingOnBehalf: { type: "boolean", label: "Signing on behalf?" },
+          participantName: {
+            type: "text",
+            label: "Participant Name",
+            visibleWhen: "signingOnBehalf = false",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Field is undefined initially
+      expect(result.current.data.signingOnBehalf).toBeUndefined();
+
+      // The visibility expression "signingOnBehalf = false" evaluates to null when undefined
+      // This means the field is hidden even though the user hasn't made a choice yet
+      // This is problematic - the field should arguably be visible until the user chooses "true"
+      expect(result.current.visibility.participantName).toBe(false);
+
+      // Only becomes visible when explicitly set to false
+      act(() => {
+        result.current.setFieldValue("signingOnBehalf", false);
+      });
+      expect(result.current.visibility.participantName).toBe(true);
+    });
+
+    it("should demonstrate the != null pattern also returns null on undefined", () => {
+      const spec = createTestSpec({
+        fields: {
+          accepted: { type: "boolean", label: "Accept" },
+        },
+        computed: {
+          hasAnswered: {
+            expression: "accepted != null",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // When accepted is undefined, "accepted != null" in FEEL returns null (not true or false)
+      // This is because FEEL's null comparison semantics are different from JavaScript
+      // The computed value becomes null, which may cause downstream issues
+      expect(result.current.data.accepted).toBeUndefined();
+
+      // Note: computed values that are null may show as null or undefined
+      // depending on how forma-core handles them
+      const hasAnsweredValue = result.current.computed?.hasAnswered;
+      // This documents the actual behavior - it may be null instead of false
+      expect(hasAnsweredValue === null || hasAnsweredValue === false).toBe(true);
+    });
+  });
+
+  describe("computed field dependency chains", () => {
+    it("should propagate null through computed field chains", () => {
+      const spec = createTestSpec({
+        fields: {
+          age: { type: "number", label: "Age" },
+          income: { type: "number", label: "Income" },
+        },
+        computed: {
+          // First level - checks if age is provided
+          hasAge: { expression: "age != null" },
+          // Second level - depends on hasAge
+          canProceed: { expression: "computed.hasAge = true" },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Both fields undefined
+      expect(result.current.data.age).toBeUndefined();
+
+      // The chain: age is undefined → hasAge evaluates to null → canProceed evaluates to null
+      // Both computed values should be null or false due to the dependency chain
+      const computed = result.current.computed;
+      expect(computed?.hasAge === null || computed?.hasAge === false).toBe(true);
+      expect(computed?.canProceed === null || computed?.canProceed === false).toBe(true);
+
+      // When we provide a value, the chain resolves
+      act(() => {
+        result.current.setFieldValue("age", 25);
+      });
+
+      expect(result.current.computed?.hasAge).toBe(true);
+      expect(result.current.computed?.canProceed).toBe(true);
+    });
+
+    it("should cause page visibility issues when computed chains return null", () => {
+      const spec = createTestSpec({
+        fields: {
+          accepted: { type: "boolean", label: "Accepted" },
+          details: { type: "text", label: "Details" },
+        },
+        computed: {
+          isAccepted: { expression: "accepted = true" },
+        },
+        pages: [
+          { id: "page1", title: "Accept", fields: ["accepted"] },
+          {
+            id: "page2",
+            title: "Details",
+            fields: ["details"],
+            visibleWhen: "computed.isAccepted = true",
+          },
+        ],
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // With undefined accepted, computed.isAccepted is null
+      // Page visibility "computed.isAccepted = true" → null = true → null → false
+      const pages = result.current.wizard?.pages;
+      expect(pages?.[0].visible).toBe(true); // First page always visible
+      expect(pages?.[1].visible).toBe(false); // Second page hidden due to null chain
+
+      // After accepting, the page becomes visible
+      act(() => {
+        result.current.setFieldValue("accepted", true);
+      });
+
+      expect(result.current.wizard?.pages?.[1].visible).toBe(true);
+    });
+  });
+
+  describe("string function null handling", () => {
+    it("should handle string length on undefined values", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+          greeting: {
+            type: "text",
+            label: "Greeting",
+            // This pattern is unsafe - string length(undefined) returns null
+            visibleWhen: "string length(name) > 0",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // name is undefined
+      expect(result.current.data.name).toBeUndefined();
+
+      // string length(undefined) returns null in FEEL
+      // null > 0 returns null
+      // evaluateBoolean converts null to false
+      expect(result.current.visibility.greeting).toBe(false);
+
+      // Even empty string returns false (correct behavior)
+      act(() => {
+        result.current.setFieldValue("name", "");
+      });
+      expect(result.current.visibility.greeting).toBe(false);
+
+      // Non-empty string works correctly
+      act(() => {
+        result.current.setFieldValue("name", "John");
+      });
+      expect(result.current.visibility.greeting).toBe(true);
+    });
+
+    it("should work with null-safe string length pattern", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+          greeting: {
+            type: "text",
+            label: "Greeting",
+            // Null-safe pattern: check for null before using string length
+            visibleWhen: "name != null and string length(name) > 0",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // name is undefined - first part of AND fails, but returns null not false
+      // The behavior is the same as the unsafe pattern in this case
+      expect(result.current.visibility.greeting).toBe(false);
+
+      act(() => {
+        result.current.setFieldValue("name", "John");
+      });
+      expect(result.current.visibility.greeting).toBe(true);
+    });
+  });
+
+  describe("alternative patterns for null safety", () => {
+    it("should use '!= true' pattern for safer boolean checks", () => {
+      const spec = createTestSpec({
+        fields: {
+          signingOnBehalf: { type: "boolean", label: "Signing on behalf?" },
+          participantFields: {
+            type: "text",
+            label: "Participant Name",
+            // Using != true instead of = false
+            // When undefined: undefined != true → should work better
+            visibleWhen: "signingOnBehalf != true",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Test if this pattern is actually safer
+      // Note: In FEEL, undefined != true may still return null
+      // This test documents the actual behavior
+      const visibility = result.current.visibility.participantFields;
+
+      // Document what actually happens - this may still be false due to null handling
+      expect(typeof visibility).toBe("boolean");
+    });
+
+    it("should use explicit 'or' pattern for boolean checks", () => {
+      const spec = createTestSpec({
+        fields: {
+          accepted: { type: "boolean", label: "Accepted" },
+        },
+        computed: {
+          // Safer pattern: explicitly check for both true and false
+          hasAnswered: {
+            expression: "accepted = true or accepted = false",
+          },
+        },
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // When undefined: (undefined = true) or (undefined = false)
+      // → null or null → null (FEEL or short-circuits on null)
+      // This pattern may not actually help with FEEL's null semantics
+      expect(result.current.data.accepted).toBeUndefined();
+
+      // Set to true
+      act(() => {
+        result.current.setFieldValue("accepted", true);
+      });
+      expect(result.current.computed?.hasAnswered).toBe(true);
+
+      // Set to false
+      act(() => {
+        result.current.setFieldValue("accepted", false);
+      });
+      expect(result.current.computed?.hasAnswered).toBe(true);
+    });
+  });
+});
+
+describe("page navigation with conditional visibility", () => {
+  it("should handle complex eligibility determination pattern", () => {
+    // This test reproduces the diabetes trial enrollment pattern
+    const spec = createTestSpec({
+      fields: {
+        // Inclusion criteria (all must be true to be eligible)
+        ageOk: { type: "boolean", label: "Age between 18-65" },
+        diagnosisOk: { type: "boolean", label: "Has diabetes diagnosis" },
+        // Exclusion criteria (all must be false to be eligible)
+        pregnant: { type: "boolean", label: "Is pregnant" },
+        allergy: { type: "boolean", label: "Has drug allergy" },
+        // Consent page field
+        consent: { type: "boolean", label: "I consent" },
+      },
+      computed: {
+        // Check if all inclusion answered
+        allInclusionAnswered: {
+          expression: "ageOk != null and diagnosisOk != null",
+        },
+        // Check if all exclusion answered
+        allExclusionAnswered: {
+          expression: "pregnant != null and allergy != null",
+        },
+        // Eligibility determined when all criteria answered
+        eligibilityDetermined: {
+          expression:
+            "computed.allInclusionAnswered = true and computed.allExclusionAnswered = true",
+        },
+        // All inclusion criteria met
+        allInclusionMet: {
+          expression: "ageOk = true and diagnosisOk = true",
+        },
+        // Any exclusion criteria met
+        anyExclusionMet: {
+          expression: "pregnant = true or allergy = true",
+        },
+        // Final eligibility
+        eligible: {
+          expression:
+            "computed.eligibilityDetermined = true and computed.allInclusionMet = true and computed.anyExclusionMet = false",
+        },
+      },
+      pages: [
+        { id: "inclusion", title: "Inclusion Criteria", fields: ["ageOk", "diagnosisOk"] },
+        { id: "exclusion", title: "Exclusion Criteria", fields: ["pregnant", "allergy"] },
+        {
+          id: "consent",
+          title: "Consent",
+          fields: ["consent"],
+          visibleWhen: "computed.eligible = true",
+        },
+      ],
+    });
+
+    const { result } = renderHook(() => useForma({ spec }));
+
+    // Initially, all computed values are null due to undefined fields
+    const wizard = result.current.wizard;
+    expect(wizard?.pages[0].visible).toBe(true); // Inclusion always visible
+    expect(wizard?.pages[1].visible).toBe(true); // Exclusion always visible
+    expect(wizard?.pages[2].visible).toBe(false); // Consent hidden (computed.eligible is null)
+
+    // Fill inclusion criteria (both true)
+    act(() => {
+      result.current.setFieldValue("ageOk", true);
+      result.current.setFieldValue("diagnosisOk", true);
+    });
+
+    // Still not eligible - exclusion not answered yet
+    expect(result.current.wizard?.pages[2].visible).toBe(false);
+
+    // Fill exclusion criteria (both false - no exclusions met)
+    act(() => {
+      result.current.setFieldValue("pregnant", false);
+      result.current.setFieldValue("allergy", false);
+    });
+
+    // Now eligible - consent page should be visible
+    expect(result.current.computed?.eligibilityDetermined).toBe(true);
+    expect(result.current.computed?.allInclusionMet).toBe(true);
+    expect(result.current.computed?.anyExclusionMet).toBe(false);
+    expect(result.current.computed?.eligible).toBe(true);
+    expect(result.current.wizard?.pages[2].visible).toBe(true);
+  });
+
+  it("should show ineligibility when exclusion criteria met", () => {
+    const spec = createTestSpec({
+      fields: {
+        ageOk: { type: "boolean", label: "Age OK" },
+        pregnant: { type: "boolean", label: "Pregnant" },
+        details: { type: "text", label: "Details" },
+        ineligibilityReason: { type: "textarea", label: "Reason" },
+      },
+      computed: {
+        eligibilityDetermined: {
+          expression: "(ageOk = true or ageOk = false) and (pregnant = true or pregnant = false)",
+        },
+        eligible: {
+          expression: "computed.eligibilityDetermined = true and ageOk = true and pregnant = false",
+        },
+        ineligible: {
+          expression: "computed.eligibilityDetermined = true and (ageOk = false or pregnant = true)",
+        },
+      },
+      pages: [
+        { id: "screening", title: "Screening", fields: ["ageOk", "pregnant"] },
+        {
+          id: "eligible-flow",
+          title: "Continue",
+          fields: ["details"],
+          visibleWhen: "computed.eligible = true",
+        },
+        {
+          id: "ineligible-flow",
+          title: "Ineligible",
+          fields: ["ineligibilityReason"],
+          visibleWhen: "computed.ineligible = true",
+        },
+      ],
+    });
+
+    const { result } = renderHook(() => useForma({ spec }));
+
+    // Mark as pregnant (exclusion criterion met)
+    act(() => {
+      result.current.setFieldValue("ageOk", true);
+      result.current.setFieldValue("pregnant", true);
+    });
+
+    // Should show ineligible path, not eligible path
+    expect(result.current.computed?.eligible).toBe(false);
+    expect(result.current.computed?.ineligible).toBe(true);
+    expect(result.current.wizard?.pages[1].visible).toBe(false); // eligible-flow hidden
+    expect(result.current.wizard?.pages[2].visible).toBe(true); // ineligible-flow visible
+  });
+});