@olaboot/esm-form-engine-lib 4.1.0

package/dist/post-submission-actions/program-enrollment-action.js

@@ -0,0 +1,105 @@
+import dayjs from "dayjs";
+import { showSnackbar, translateFrom } from "@openmrs/esm-framework";
+import { getPatientEnrolledPrograms, saveProgramEnrollment } from "../api/index.js";
+import { formEngineAppName } from "../globals.js";
+import { extractErrorMessagesFromResponse } from "../utils/error-utils.js";
+export const ProgramEnrollmentSubmissionAction = {
+    applyAction: async function({ patient, encounters, sessionMode }, config) {
+        const encounter = encounters[0];
+        const encounterLocation = encounter.location['uuid'];
+        const t = (key, defaultValue, options)=>translateFrom(formEngineAppName, key, defaultValue, options);
+        const programUuid = config.programUuid;
+        if (sessionMode === 'view') {
+            return;
+        }
+        if (!programUuid) {
+            throw new Error('Program UUID not configured');
+        }
+        const enrollmentDate = encounter.obs?.find((item)=>item.formFieldPath.includes(config.enrollmentDate || null))?.value;
+        const completionDate = encounter.obs?.find((item)=>item.formFieldPath.includes(config.completionDate || null))?.value;
+        const abortController = new AbortController();
+        let payload = {
+            patient: patient.id,
+            program: programUuid,
+            dateEnrolled: enrollmentDate ?? dayjs().format(),
+            location: encounterLocation
+        };
+        const patientPrograms = await getPatientEnrolledPrograms(patient.id);
+        const existingProgramEnrollment = patientPrograms?.results.find((enrollment)=>enrollment.program.uuid === programUuid && !enrollment.dateCompleted);
+        if (config.completionDate) {
+            if (!completionDate) {
+                throw new Error('Completion date was not found in the encounter');
+            }
+            if (existingProgramEnrollment) {
+                payload = {
+                    uuid: existingProgramEnrollment.uuid,
+                    dateCompleted: updateTimeToNow(completionDate)
+                };
+            } else {
+                showSnackbar({
+                    title: t('enrollmentDiscontinuationNotAllowed', 'Enrollment discontinuation not allowed'),
+                    subtitle: t('cannotDiscontinueEnrollment', 'Cannot discontinue an enrollment that does not exist'),
+                    kind: 'error',
+                    isLowContrast: false
+                });
+                return;
+            }
+        }
+        if (existingProgramEnrollment) {
+            if (!existingProgramEnrollment.dateCompleted && !completionDate) {
+                // The patient is already enrolled in the program and there is no completion date provided.
+                if (sessionMode === 'enter') {
+                    showSnackbar({
+                        title: t('enrollmentNotAllowed', 'Enrollment not allowed'),
+                        subtitle: t('alreadyEnrolledDescription', 'This patient is already enrolled in the selected program and cannot be enrolled again.'),
+                        kind: 'error',
+                        isLowContrast: false
+                    });
+                }
+                return;
+            } else if (existingProgramEnrollment.dateCompleted) {
+                // The enrollment has already been completed
+                if (sessionMode === 'enter') {
+                    showSnackbar({
+                        title: t('enrollmentAlreadyDiscontinued', 'Enrollment already discontinued'),
+                        subtitle: t('alreadyDiscontinuedDescription', 'This patient is already enrolled in the selected program and has already been discontinued.'),
+                        kind: 'error',
+                        isLowContrast: false
+                    });
+                }
+                return;
+            }
+        }
+        saveProgramEnrollment(payload, abortController).then((response)=>{
+            showSnackbar({
+                kind: 'success',
+                title: getSnackTitle(t, response),
+                isLowContrast: true
+            });
+        }, (err)=>{
+            showSnackbar({
+                title: t('errorSavingEnrollment', 'Error saving enrollment'),
+                subtitle: extractErrorMessagesFromResponse(err).join(', '),
+                kind: 'error',
+                isLowContrast: false
+            });
+        });
+    }
+};
+function getSnackTitle(t, response) {
+    if (response.data.dateCompleted) {
+        return t('enrollmentDiscontinued', "The patient's program enrollment has been successfully discontinued.");
+    }
+    return t('enrolledToProgram', 'The patient has been successfully enrolled in the program.');
+}
+function updateTimeToNow(dateString) {
+    // Check if the input date string has the time set to midnight (00:00:00.000+0000)
+    if (!dateString.endsWith('T00:00:00.000+0000')) {
+        return dateString;
+    }
+    const now = dayjs();
+    const originalDate = dayjs(dateString);
+    const updatedDate = originalDate.hour(now.hour()).minute(now.minute()).second(now.second()).millisecond(now.millisecond());
+    return updatedDate.format();
+}
+export default ProgramEnrollmentSubmissionAction;

package/dist/processors/encounter/encounter-form-processor.d.ts

@@ -0,0 +1,26 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+import { type FormField, type FormProcessorContextProps, type FormSchema, type ValueAndDisplay } from '../../types';
+import { FormProcessor } from '../form-processor';
+import { type FormContextProps } from '../../provider/form-provider';
+declare function useCustomHooks(context: Partial<FormProcessorContextProps>): {
+    data: {
+        encounter: import("../../types").OpenmrsEncounter;
+        patientPrograms: import("../../types").PatientProgram[];
+        encounterRole: OpenmrsResource;
+    };
+    isLoading: boolean;
+    error: any;
+    updateContext: (setContext: React.Dispatch<React.SetStateAction<FormProcessorContextProps>>) => void;
+};
+export declare class EncounterFormProcessor extends FormProcessor {
+    prepareFormSchema(schema: FormSchema): FormSchema;
+    processSubmission(context: FormContextProps, abortController: AbortController): Promise<any>;
+    getCustomHooks(): {
+        useCustomHooks: typeof useCustomHooks;
+    };
+    getInitialValues(context: FormProcessorContextProps): Promise<{}>;
+    loadDependencies(context: FormContextProps, setContext: React.Dispatch<React.SetStateAction<FormProcessorContextProps>>): Promise<FormContextProps>;
+    getHistoricalValue(field: FormField, context: FormContextProps): Promise<ValueAndDisplay>;
+}
+export {};
+//# sourceMappingURL=encounter-form-processor.d.ts.map

package/dist/processors/encounter/encounter-form-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encounter-form-processor.d.ts","sourceRoot":"","sources":["../../../src/processors/encounter/encounter-form-processor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,eAAe,EAA+B,MAAM,wBAAwB,CAAC;AAc3F,OAAO,EACL,KAAK,SAAS,EAEd,KAAK,yBAAyB,EAC9B,KAAK,UAAU,EAEf,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKlD,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAOrE,iBAAS,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,yBAAyB,CAAC;;;;;;;;gCAcnC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,yBAAyB,CAAC,CAAC;EAe9F;AAkBD,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,iBAAiB,CAAC,MAAM,EAAE,UAAU;IAuC9B,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe;IAiInF,cAAc;;;IAIR,gBAAgB,CAAC,OAAO,EAAE,yBAAyB;IAsFnD,gBAAgB,CACpB,OAAO,EAAE,gBAAgB,EACzB,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,cAAc,CAAC,yBAAyB,CAAC,CAAC;IAavE,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;CA0BhG"}

package/dist/processors/encounter/encounter-form-processor.js

@@ -0,0 +1,376 @@
+import { useEffect, useState } from "react";
+import { showSnackbar, translateFrom } from "@openmrs/esm-framework";
+import { getMutableSessionProps, hydrateRepeatField, inferInitialValueFromDefaultFieldValue, prepareEncounter, preparePatientIdentifiers, preparePatientPrograms, preparePersonAttributes, saveAttachments, savePatientIdentifiers, savePatientPrograms, savePersonAttributes } from "./encounter-processor-helper.js";
+import { evaluateAsyncExpression } from "../../utils/expression-runner.js";
+import { extractErrorMessagesFromResponse } from "../../utils/error-utils.js";
+import { extractObsValueAndDisplay } from "../../utils/form-helper.js";
+import { FormProcessor } from "../form-processor.js";
+import { getPreviousEncounter, saveEncounter } from "../../api/index.js";
+import { hasRendering } from "../../utils/common-utils.js";
+import { isEmpty } from "../../validators/form-validator.js";
+import { formEngineAppName } from "../../globals.js";
+import { useEncounter } from "../../hooks/useEncounter.js";
+import { useEncounterRole } from "../../hooks/useEncounterRole.js";
+import { usePatientPrograms } from "../../hooks/usePatientPrograms.js";
+function useCustomHooks(context) {
+    const [isLoading, setIsLoading] = useState(true);
+    const { encounter, isLoading: isLoadingEncounter } = useEncounter(context.formJson);
+    const { encounterRole, isLoading: isLoadingEncounterRole } = useEncounterRole();
+    const { isLoadingPatientPrograms, patientPrograms } = usePatientPrograms(context.patient?.id, context.formJson);
+    useEffect(()=>{
+        setIsLoading(isLoadingPatientPrograms || isLoadingEncounter || isLoadingEncounterRole);
+    }, [
+        isLoadingPatientPrograms,
+        isLoadingEncounter,
+        isLoadingEncounterRole
+    ]);
+    return {
+        data: {
+            encounter,
+            patientPrograms,
+            encounterRole
+        },
+        isLoading,
+        error: null,
+        updateContext: (setContext)=>{
+            setContext((context)=>{
+                context.processor.domainObjectValue = encounter;
+                return {
+                    ...context,
+                    domainObjectValue: encounter,
+                    customDependencies: {
+                        ...context.customDependencies,
+                        patientPrograms: patientPrograms,
+                        defaultEncounterRole: encounterRole
+                    }
+                };
+            });
+        }
+    };
+}
+const emptyValues = {
+    checkbox: [],
+    toggle: false,
+    text: ''
+};
+const contextInitializableTypes = [
+    'encounterProvider',
+    'encounterDatetime',
+    'encounterLocation',
+    'patientIdentifier',
+    'encounterRole',
+    'programState',
+    'personAttribute'
+];
+export class EncounterFormProcessor extends FormProcessor {
+    prepareFormSchema(schema) {
+        const allFieldIds = new Set();
+        schema.pages.forEach((page)=>{
+            page.sections.forEach((section)=>{
+                section.questions.forEach((question)=>{
+                    prepareFormField(question, section, page, schema);
+                });
+            });
+        });
+        function prepareFormField(field, section, page, schema) {
+            // Collect field ID
+            if (field.id) {
+                allFieldIds.add(field.id);
+            }
+            // inherit inlineRendering and readonly from parent section and page if not set
+            field.inlineRendering = field.inlineRendering ?? section.inlineRendering ?? page.inlineRendering ?? schema.inlineRendering;
+            field.readonly = field.readonly ?? section.readonly ?? page.readonly ?? schema.readonly;
+            if (field.questionOptions?.rendering == 'fixed-value' && !field.meta.fixedValue) {
+                field.meta.fixedValue = field.value;
+                delete field.value;
+            }
+            if (field.questionOptions?.rendering == 'group' || field.type === 'obsGroup') {
+                field.questions?.forEach((child)=>{
+                    child.readonly = child.readonly ?? field.readonly;
+                    return prepareFormField(child, section, page, schema);
+                });
+            }
+        }
+        // Validate calculate expressions for common mistakes
+        validateCalculateExpressions(schema, allFieldIds);
+        return schema;
+    }
+    async processSubmission(context, abortController) {
+        const { encounterRole, encounterProvider, encounterDate, encounterLocation } = getMutableSessionProps(context);
+        const t = (key, defaultValue, options)=>translateFrom(formEngineAppName, key, defaultValue, options);
+        const patientIdentifiers = preparePatientIdentifiers(context.formFields, encounterLocation);
+        const encounter = prepareEncounter(context, encounterDate, encounterRole, encounterProvider, encounterLocation);
+        // save patient identifiers
+        try {
+            await Promise.all(savePatientIdentifiers(context.patient, patientIdentifiers));
+            if (patientIdentifiers?.length) {
+                showSnackbar({
+                    title: t('patientIdentifiersSaved', 'Patient identifier(s) saved successfully'),
+                    kind: 'success',
+                    isLowContrast: true
+                });
+            }
+        } catch (error) {
+            const errorMessages = extractErrorMessagesFromResponse(error);
+            return Promise.reject({
+                title: t('errorSavingPatientIdentifiers', 'Error saving patient identifiers'),
+                subtitle: errorMessages.join(', '),
+                kind: 'error',
+                isLowContrast: false
+            });
+        }
+        // save person attributes
+        try {
+            const personAttributes = preparePersonAttributes(context.formFields);
+            await Promise.all(savePersonAttributes(context.patient, personAttributes));
+            if (personAttributes?.length) {
+                showSnackbar({
+                    title: t('personAttributesSaved', 'Person attribute(s) saved successfully'),
+                    kind: 'success',
+                    isLowContrast: true
+                });
+            }
+        } catch (error) {
+            const errorMessages = extractErrorMessagesFromResponse(error);
+            return Promise.reject({
+                title: t('errorSavingPersonAttributes', 'Error saving person attributes'),
+                description: errorMessages.join(', '),
+                kind: 'error',
+                critical: true
+            });
+        }
+        // save patient programs
+        try {
+            const programs = preparePatientPrograms(context.formFields, context.patient, context.customDependencies.patientPrograms);
+            const savedPrograms = await await savePatientPrograms(programs);
+            if (savedPrograms?.length) {
+                showSnackbar({
+                    title: t('patientProgramsSaved', 'Patient program(s) saved successfully'),
+                    kind: 'success',
+                    isLowContrast: true
+                });
+            }
+        } catch (error) {
+            const errorMessages = extractErrorMessagesFromResponse(error);
+            return Promise.reject({
+                title: t('errorSavingPatientPrograms', 'Error saving patient program(s)'),
+                subtitle: errorMessages.join(', '),
+                kind: 'error',
+                isLowContrast: false
+            });
+        }
+        // save encounter
+        try {
+            const { data: savedEncounter } = await saveEncounter(abortController, encounter, encounter.uuid);
+            const savedOrders = savedEncounter.orders.map((order)=>order.orderNumber);
+            const savedDiagnoses = savedEncounter.diagnoses.map((diagnosis)=>diagnosis.display);
+            if (savedOrders.length) {
+                showSnackbar({
+                    title: t('ordersSaved', 'Order(s) saved successfully'),
+                    subtitle: savedOrders.join(', '),
+                    kind: 'success',
+                    isLowContrast: true
+                });
+            }
+            // handle diagnoses
+            if (savedDiagnoses.length) {
+                showSnackbar({
+                    title: t('diagnosisSaved', 'Diagnosis(es) saved successfully'),
+                    subtitle: savedDiagnoses.join(', '),
+                    kind: 'success',
+                    isLowContrast: true
+                });
+            }
+            // handle attachments
+            try {
+                const attachmentsResponse = await saveAttachments(context.formFields, savedEncounter, abortController);
+                if (attachmentsResponse?.length) {
+                    showSnackbar({
+                        title: t('attachmentsSaved', 'Attachment(s) saved successfully'),
+                        kind: 'success',
+                        isLowContrast: true
+                    });
+                }
+            } catch (error) {
+                console.error('Error saving attachments', error);
+                const errorMessages = extractErrorMessagesFromResponse(error);
+                return Promise.reject({
+                    title: t('errorSavingAttachments', 'Error saving attachment(s)'),
+                    subtitle: errorMessages.join(', '),
+                    kind: 'error',
+                    isLowContrast: false
+                });
+            }
+            return savedEncounter;
+        } catch (error) {
+            console.error('Error saving encounter', error);
+            const errorMessages = extractErrorMessagesFromResponse(error);
+            return Promise.reject({
+                title: t('errorSavingEncounter', 'Error saving encounter'),
+                subtitle: errorMessages.join(', '),
+                kind: 'error',
+                isLowContrast: false
+            });
+        }
+    }
+    getCustomHooks() {
+        return {
+            useCustomHooks
+        };
+    }
+    async getInitialValues(context) {
+        const { domainObjectValue: encounter, formFields, formFieldAdapters } = context;
+        const initialValues = {};
+        const repeatableFields = [];
+        if (encounter) {
+            await Promise.all(formFields.map(async (field)=>{
+                const adapter = formFieldAdapters[field.type];
+                if (field.meta.initialValue?.omrsObject && !isEmpty(field.meta.initialValue.refinedValue)) {
+                    initialValues[field.id] = field.meta.initialValue.refinedValue;
+                    return;
+                }
+                if (adapter) {
+                    if (hasRendering(field, 'repeating') && !field.meta?.repeat?.isClone) {
+                        repeatableFields.push(field);
+                    }
+                    let value = null;
+                    try {
+                        value = await adapter.getInitialValue(field, encounter, context);
+                        field.meta.initialValue.refinedValue = value;
+                    } catch (error) {
+                        console.error(error);
+                    }
+                    if (field.type === 'obsGroup') {
+                        return;
+                    }
+                    if (!isEmpty(value)) {
+                        initialValues[field.id] = value;
+                    } else if (!isEmpty(field.questionOptions.defaultValue)) {
+                        initialValues[field.id] = inferInitialValueFromDefaultFieldValue(field);
+                    } else {
+                        initialValues[field.id] = emptyValues[field.questionOptions.rendering] ?? '';
+                    }
+                    if (field.questionOptions.calculate?.calculateExpression) {
+                        try {
+                            await evaluateCalculateExpression(field, initialValues, context);
+                        } catch (error) {
+                            console.error(error);
+                        }
+                    }
+                } else {
+                    console.warn(`No adapter found for field type ${field.type}`);
+                }
+            }));
+            const flattenedRepeatableFields = await Promise.all(repeatableFields.flatMap((field)=>hydrateRepeatField(field, encounter, initialValues, context))).then((results)=>results.flat());
+            formFields.push(...flattenedRepeatableFields);
+        } else {
+            const filteredFields = formFields.filter((field)=>field.questionOptions.rendering !== 'group' && field.type !== 'obsGroup');
+            const fieldsWithCalculateExpressions = [];
+            await Promise.all(filteredFields.map(async (field)=>{
+                const adapter = formFieldAdapters[field.type];
+                initialValues[field.id] = emptyValues[field.questionOptions.rendering] ?? null;
+                if (isEmpty(initialValues[field.id]) && contextInitializableTypes.includes(field.type)) {
+                    try {
+                        initialValues[field.id] = await adapter.getInitialValue(field, null, context);
+                    } catch (error) {
+                        console.error(error);
+                    }
+                }
+                if (field.questionOptions.defaultValue) {
+                    initialValues[field.id] = inferInitialValueFromDefaultFieldValue(field);
+                }
+                if (field.questionOptions.calculate?.calculateExpression) {
+                    fieldsWithCalculateExpressions.push(field);
+                }
+            }));
+            await Promise.all(fieldsWithCalculateExpressions.map(async (field)=>{
+                try {
+                    await evaluateCalculateExpression(field, initialValues, context);
+                } catch (error) {
+                    console.error(error);
+                }
+            }));
+        }
+        return initialValues;
+    }
+    async loadDependencies(context, setContext) {
+        const { patient, formJson } = context;
+        const encounter = await getPreviousEncounter(patient?.id, formJson.encounterType);
+        setContext((context)=>{
+            return {
+                ...context,
+                previousDomainObjectValue: encounter
+            };
+        });
+        return context;
+    }
+    async getHistoricalValue(field, context) {
+        const { formFields, sessionMode, patient, methods: { getValues }, formFieldAdapters, previousDomainObjectValue, visit } = context;
+        const node = {
+            value: field,
+            type: 'field'
+        };
+        const adapter = formFieldAdapters[field.type];
+        if (field.historicalExpression) {
+            const value = await evaluateAsyncExpression(field.historicalExpression, node, formFields, getValues(), {
+                mode: sessionMode,
+                patient: patient,
+                previousEncounter: previousDomainObjectValue,
+                visit
+            });
+            return value ? extractObsValueAndDisplay(field, value) : null;
+        }
+        if (previousDomainObjectValue && field.questionOptions.enablePreviousValue) {
+            return await adapter.getPreviousValue(field, previousDomainObjectValue, context);
+        }
+        return null;
+    }
+}
+async function evaluateCalculateExpression(field, values, formContext) {
+    const { formFields, sessionMode, patient, visit } = formContext;
+    const expression = field.questionOptions.calculate.calculateExpression;
+    const node = {
+        value: field,
+        type: 'field'
+    };
+    const context = {
+        mode: sessionMode,
+        patient: patient,
+        visit
+    };
+    const value = await evaluateAsyncExpression(expression, node, formFields, values, context);
+    if (!isEmpty(value)) {
+        values[field.id] = value;
+    }
+}
+/**
+ * Validates calculate expressions to warn about common mistakes.
+ * Specifically, checks if string literals in expressions match field IDs,
+ * which usually indicates the user should use bare variable references instead.
+ *
+ * For example: calcEDD('lmp') should be calcEDD(lmp)
+ */ function validateCalculateExpressions(schema, allFieldIds) {
+    const stringLiteralPattern = /(['"])([a-zA-Z_][a-zA-Z0-9_]*)\1/g;
+    function checkExpression(expression, fieldId) {
+        for (const match of expression.matchAll(stringLiteralPattern)){
+            const quotedValue = match[2];
+            if (allFieldIds.has(quotedValue)) {
+                console.error(`The calculateExpression for the field '${fieldId}' incorrectly quotes the field ID '${quotedValue}' as a string. ` + `Field IDs must be referenced as variables without quotes to access their values. ` + `Remove the quotes: use ${quotedValue} instead of '${quotedValue}'.`);
+            }
+        }
+    }
+    function processField(field) {
+        if (field.questionOptions?.calculate?.calculateExpression) {
+            checkExpression(field.questionOptions.calculate.calculateExpression, field.id);
+        }
+        // Process nested questions (for obsGroups)
+        if (field.questions) {
+            field.questions.forEach(processField);
+        }
+    }
+    schema.pages.forEach((page)=>{
+        page.sections.forEach((section)=>{
+            section.questions.forEach(processField);
+        });
+    });
+}