@openmrs/esm-form-engine-lib 2.1.0-pre.1362

package/src/processors/encounter/encounter-processor-helper.ts

@@ -0,0 +1,320 @@
+import {
+  type PatientProgram,
+  type FormField,
+  type OpenmrsEncounter,
+  type OpenmrsObs,
+  type PatientIdentifier,
+  type PatientProgramPayload,
+  type FormProcessorContextProps,
+} from '../../types';
+import { saveAttachment, savePatientIdentifier, saveProgramEnrollment } from '../../api';
+import { hasRendering, hasSubmission } from '../../utils/common-utils';
+import dayjs from 'dayjs';
+import { voidObs, constructObs, assignedObsIds } from '../../adapters/obs-adapter';
+import { type FormContextProps } from '../../provider/form-provider';
+import { ConceptTrue } from '../../constants';
+import { DefaultValueValidator } from '../../validators/default-value-validator';
+import { cloneRepeatField } from '../../components/repeat/helpers';
+import { assignedOrderIds } from '../../adapters/orders-adapter';
+
+export function prepareEncounter(
+  context: FormContextProps,
+  encounterDate: Date,
+  encounterRole: string,
+  encounterProvider: string,
+  location: string,
+) {
+  const { patient, formJson, domainObjectValue: encounter, formFields, visit } = context;
+  const obsForSubmission = [];
+  prepareObs(obsForSubmission, formFields);
+  const ordersForSubmission = prepareOrders(formFields);
+  let encounterForSubmission: OpenmrsEncounter = {};
+
+  if (encounter) {
+    Object.assign(encounterForSubmission, encounter);
+    // update encounter providers
+    const hasCurrentProvider =
+      encounterForSubmission.encounterProviders.findIndex(
+        (encProvider) => encProvider.provider.uuid == encounterProvider,
+      ) !== -1;
+    if (!hasCurrentProvider) {
+      encounterForSubmission.encounterProviders = [
+        ...encounterForSubmission.encounterProviders,
+        {
+          provider: encounterProvider,
+          encounterRole,
+        },
+      ];
+    }
+    // TODO: Question: Should we be editing the location, form and visit here?
+    encounterForSubmission.encounterDatetime = encounterDate;
+    encounterForSubmission.location = location;
+    encounterForSubmission.form = {
+      uuid: formJson.uuid,
+    };
+    if (visit) {
+      encounterForSubmission.visit = visit.uuid;
+    }
+    encounterForSubmission.obs = obsForSubmission;
+    encounterForSubmission.orders = ordersForSubmission;
+  } else {
+    encounterForSubmission = {
+      patient: patient.id,
+      encounterDatetime: encounterDate,
+      location: location,
+      encounterType: formJson.encounterType,
+      encounterProviders: [
+        {
+          provider: encounterProvider,
+          encounterRole,
+        },
+      ],
+      obs: obsForSubmission,
+      form: {
+        uuid: formJson.uuid,
+      },
+      visit: visit?.uuid,
+      orders: ordersForSubmission,
+    };
+  }
+  return encounterForSubmission;
+}
+
+export function preparePatientIdentifiers(fields: FormField[], encounterLocation: string): PatientIdentifier[] {
+  return fields
+    .filter((field) => field.type === 'patientIdentifier' && hasSubmission(field))
+    .map((field) => field.meta.submission.newValue);
+}
+
+export function savePatientIdentifiers(patient: fhir.Patient, identifiers: PatientIdentifier[]) {
+  return identifiers.map((patientIdentifier) => {
+    return savePatientIdentifier(patientIdentifier, patient.id);
+  });
+}
+
+export function preparePatientPrograms(
+  fields: FormField[],
+  patient: fhir.Patient,
+  currentPatientPrograms: Array<PatientProgram>,
+): Array<PatientProgramPayload> {
+  const programStateFields = fields.filter((field) => field.type === 'programState' && hasSubmission(field));
+  const programMap = new Map<string, PatientProgramPayload>();
+  programStateFields.forEach((field) => {
+    const programUuid = field.questionOptions.programUuid;
+    const newState = field.meta.submission.newValue;
+    const existingProgramEnrollment = currentPatientPrograms.find((program) => program.program.uuid === programUuid);
+
+    if (existingProgramEnrollment) {
+      if (programMap.has(programUuid)) {
+        programMap.get(programUuid).states.push(newState);
+      } else {
+        programMap.set(programUuid, {
+          uuid: existingProgramEnrollment.uuid,
+          states: [newState],
+        });
+      }
+    } else {
+      if (programMap.has(programUuid)) {
+        programMap.get(programUuid).states.push(newState);
+      } else {
+        programMap.set(programUuid, {
+          patient: patient.id,
+          program: programUuid,
+          states: [newState],
+          dateEnrolled: dayjs().format(),
+        });
+      }
+    }
+  });
+  return Array.from(programMap.values());
+}
+
+export function savePatientPrograms(patientPrograms: PatientProgramPayload[]) {
+  const ac = new AbortController();
+  return Promise.all(patientPrograms.map((programPayload) => saveProgramEnrollment(programPayload, ac)));
+}
+
+export function saveAttachments(fields: FormField[], encounter: OpenmrsEncounter, abortController: AbortController) {
+  const complexFields = fields?.filter((field) => field?.questionOptions.rendering === 'file' && hasSubmission(field));
+
+  if (!complexFields?.length) return [];
+
+  return complexFields.map((field) => {
+    const patientUuid = typeof encounter?.patient === 'string' ? encounter?.patient : encounter?.patient?.uuid;
+    return saveAttachment(
+      patientUuid,
+      field,
+      field?.questionOptions.concept,
+      new Date().toISOString(),
+      encounter?.uuid,
+      abortController,
+    );
+  });
+}
+
+export function getMutableSessionProps(context: FormContextProps) {
+  const {
+    formFields,
+    location,
+    currentProvider,
+    sessionDate,
+    customDependencies,
+    domainObjectValue: encounter,
+  } = context;
+  const { defaultEncounterRole } = customDependencies;
+  const encounterRole =
+    formFields.find((field) => field.type === 'encounterRole')?.meta.submission?.newValue || defaultEncounterRole?.uuid;
+  const encounterProvider =
+    formFields.find((field) => field.type === 'encounterProvider')?.meta.submission?.newValue || currentProvider.uuid;
+  const encounterDate =
+    formFields.find((field) => field.type === 'encounterDatetime')?.meta.submission?.newValue ||
+    encounter?.encounterDatetime ||
+    sessionDate;
+  const encounterLocation =
+    formFields.find((field) => field.type === 'encounterLocation')?.meta.submission?.newValue ||
+    encounter?.location?.uuid ||
+    location.uuid;
+  return {
+    encounterRole: encounterRole as string,
+    encounterProvider: encounterProvider as string,
+    encounterDate: encounterDate as Date,
+    encounterLocation: encounterLocation as string,
+  };
+}
+
+// Helpers
+
+function prepareObs(obsForSubmission: OpenmrsObs[], fields: FormField[]) {
+  fields
+    .filter((field) => hasSubmittableObs(field))
+    .forEach((field) => {
+      if ((field.isHidden || field.isParentHidden) && field.meta.previousValue) {
+        const valuesArray = Array.isArray(field.meta.previousValue)
+          ? field.meta.previousValue
+          : [field.meta.previousValue];
+        addObsToList(
+          obsForSubmission,
+          valuesArray.map((obs) => voidObs(obs)),
+        );
+        return;
+      }
+      if (field.type == 'obsGroup') {
+        if (field.meta.submission?.voidedValue) {
+          addObsToList(obsForSubmission, field.meta.submission.voidedValue);
+          return;
+        }
+        const obsGroup = constructObs(field, null);
+        if (field.meta.previousValue) {
+          obsGroup.uuid = field.meta.previousValue.uuid;
+        }
+        field.questions.forEach((groupedField) => {
+          if (hasSubmission(groupedField)) {
+            addObsToList(obsGroup.groupMembers, groupedField.meta.submission.newValue);
+            addObsToList(obsGroup.groupMembers, groupedField.meta.submission.voidedValue);
+          }
+        });
+        if (obsGroup.groupMembers.length || obsGroup.voided) {
+          addObsToList(obsForSubmission, obsGroup);
+        }
+      }
+      if (hasSubmission(field)) {
+        addObsToList(obsForSubmission, field.meta.submission.newValue);
+        addObsToList(obsForSubmission, field.meta.submission.voidedValue);
+      }
+    });
+}
+
+function prepareOrders(fields: FormField[]) {
+  return fields
+    .filter((field) => field.type === 'testOrder' && hasSubmission(field))
+    .flatMap((field) => [field.meta.submission.newValue, field.meta.submission.voidedValue])
+    .filter((o) => o);
+}
+
+function addObsToList(obsList: Array<Partial<OpenmrsObs>>, obs: Partial<OpenmrsObs>) {
+  if (!obs) {
+    return;
+  }
+  if (Array.isArray(obs)) {
+    obsList.push(...obs);
+  } else {
+    obsList.push(obs);
+  }
+}
+
+function hasSubmittableObs(field: FormField) {
+  const {
+    questionOptions: { isTransient },
+    type,
+  } = field;
+
+  if (isTransient || !['obs', 'obsGroup'].includes(type) || hasRendering(field, 'file') || field.meta.groupId) {
+    return false;
+  }
+  if ((field.isHidden || field.isParentHidden) && field.meta.previousValue) {
+    return true;
+  }
+  return !field.isHidden && !field.isParentHidden && (type === 'obsGroup' || hasSubmission(field));
+}
+
+export function inferInitialValueFromDefaultFieldValue(field: FormField) {
+  if (field.questionOptions.rendering == 'toggle' && typeof field.questionOptions.defaultValue != 'boolean') {
+    return field.questionOptions.defaultValue == ConceptTrue;
+  }
+  // validate default value
+  if (!DefaultValueValidator.validate(field, field.questionOptions.defaultValue).length) {
+    return field.questionOptions.defaultValue;
+  }
+}
+
+export async function hydrateRepeatField(
+  field: FormField,
+  encounter: OpenmrsEncounter,
+  initialValues: Record<string, any>,
+  context: FormProcessorContextProps,
+): Promise<FormField[]> {
+  let counter = 1;
+  const { formFieldAdapters } = context;
+  const unMappedGroups = encounter.obs.filter(
+    (obs) =>
+      obs.concept.uuid === field.questionOptions.concept &&
+      obs.uuid != field.meta.previousValue?.uuid &&
+      !assignedObsIds.includes(obs.uuid),
+  );
+  const unMappedOrders = encounter.orders.filter((order) => {
+    const availableOrderables = field.questionOptions.answers?.map((answer) => answer.concept) || [];
+    return availableOrderables.includes(order.concept?.uuid) && !assignedOrderIds.includes(order.uuid);
+  });
+  if (field.type === 'testOrder') {
+    return Promise.all(
+      unMappedOrders
+        .filter((order) => !order.voided)
+        .map(async (order) => {
+          const clone = cloneRepeatField(field, order, counter++);
+          initialValues[clone.id] = await formFieldAdapters[field.type].getInitialValue(
+            clone,
+            { orders: [order] } as any,
+            context,
+          );
+          return clone;
+        }),
+    );
+  }
+  // handle obs groups
+  return Promise.all(
+    unMappedGroups.map(async (group) => {
+      const clone = cloneRepeatField(field, group, counter++);
+      await Promise.all(
+        clone.questions.map(async (childField) => {
+          initialValues[childField.id] = await formFieldAdapters[field.type].getInitialValue(
+            childField,
+            { obs: [group] } as any,
+            context,
+          );
+        }),
+      );
+      assignedObsIds.push(group.uuid);
+      return [clone, ...clone.questions];
+    }),
+  ).then((results) => results.flat());
+}

package/src/processors/form-processor.ts

@@ -0,0 +1,41 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+import { type FormContextProps } from '../provider/form-provider';
+import { type ValueAndDisplay, type FormField, type FormSchema } from '../types';
+import { type FormProcessorContextProps } from '../types';
+
+export type FormProcessorConstructor = new (...args: ConstructorParameters<typeof FormProcessor>) => FormProcessor;
+
+export type GetCustomHooksResponse = {
+  useCustomHooks: (context: Partial<FormProcessorContextProps>) => {
+    data: any;
+    isLoading: boolean;
+    error: any;
+    updateContext: (setContext: React.Dispatch<React.SetStateAction<FormProcessorContextProps>>) => void;
+  };
+};
+
+export abstract class FormProcessor {
+  formJson: FormSchema;
+  domainObjectValue: OpenmrsResource;
+
+  constructor(formJson: FormSchema) {
+    this.formJson = formJson;
+  }
+
+  getDomainObject() {
+    return this.domainObjectValue;
+  }
+
+  async loadDependencies(
+    context: Partial<FormProcessorContextProps>,
+    setContext: React.Dispatch<React.SetStateAction<FormProcessorContextProps>>,
+  ): Promise<Record<string, any>> {
+    return Promise.resolve({});
+  }
+
+  abstract getHistoricalValue(field: FormField, context: FormContextProps): Promise<ValueAndDisplay>;
+  abstract processSubmission(context: FormContextProps, abortController: AbortController): Promise<OpenmrsResource>;
+  abstract getInitialValues(context: FormProcessorContextProps): Promise<Record<string, any>>;
+  abstract getCustomHooks(): GetCustomHooksResponse;
+  abstract prepareFormSchema(schema: FormSchema): FormSchema;
+}

package/src/provider/form-factory-helper.ts

@@ -0,0 +1,100 @@
+import { type OpenmrsResource, showSnackbar } from '@openmrs/esm-framework';
+import { type FormContextProps } from './form-provider';
+import { extractErrorMessagesFromResponse } from '../utils/error-utils';
+import { evaluatePostSubmissionExpression } from '../utils/post-submission-action-helper';
+import { type PostSubmissionActionMeta } from '../hooks/usePostSubmissionActions';
+import { type TFunction } from 'react-i18next';
+import { type SessionMode } from '../types';
+
+export function validateForm(context: FormContextProps) {
+  const {
+    formFields,
+    formFieldValidators,
+    patient,
+    sessionMode,
+    addInvalidField,
+    methods: { getValues, trigger },
+  } = context;
+  const values = getValues();
+  const errors = formFields
+    .flatMap((field) =>
+      field.validators?.flatMap((validatorConfig) => {
+        const validator = formFieldValidators[validatorConfig.type];
+        if (validator) {
+          const validationResults = validator.validate(field, values[field.id], {
+            fields: formFields,
+            values,
+            expressionContext: {
+              patient,
+              mode: sessionMode,
+            },
+            ...validatorConfig,
+          });
+          const errors = validationResults.filter((result) => result.resultType === 'error');
+          if (errors.length) {
+            field.meta.submission = { ...field.meta.submission, errors };
+            trigger(field.id);
+            addInvalidField(field);
+          }
+          return errors;
+        }
+      }),
+    )
+    .filter((error) => Boolean(error));
+  return errors.length === 0;
+}
+
+export async function processPostSubmissionActions(
+  postSubmissionHandlers: PostSubmissionActionMeta[],
+  submissionResults: OpenmrsResource[],
+  patient: fhir.Patient,
+  sessionMode: SessionMode,
+  t: TFunction,
+) {
+  return Promise.all(
+    postSubmissionHandlers.map(async ({ postAction, config, actionId, enabled }) => {
+      try {
+        const encounterData = [];
+        if (submissionResults) {
+          submissionResults.forEach((result) => {
+            if (result?.data) {
+              encounterData.push(result.data);
+            }
+            if (result?.uuid) {
+              encounterData.push(result);
+            }
+          });
+
+          if (encounterData.length) {
+            const isActionEnabled = enabled ? evaluatePostSubmissionExpression(enabled, encounterData) : true;
+            if (isActionEnabled) {
+              await postAction.applyAction(
+                {
+                  patient,
+                  sessionMode,
+                  encounters: encounterData,
+                },
+                config,
+              );
+            }
+          } else {
+            throw new Error('No encounter data to process post submission action');
+          }
+        } else {
+          throw new Error('No handlers available to process post submission action');
+        }
+      } catch (error) {
+        const errorMessages = extractErrorMessagesFromResponse(error);
+        showSnackbar({
+          title: t(
+            'errorDescriptionTitle',
+            actionId ? actionId.replace(/([a-z])([A-Z])/g, '$1 $2') : 'Post Submission Error',
+          ),
+          subtitle: t('errorDescription', '{{errors}}', { errors: errorMessages.join(', ') }),
+          kind: 'error',
+          isLowContrast: false,
+        });
+      }
+    }),
+  );
+}

package/src/provider/form-factory-provider.tsx

@@ -0,0 +1,169 @@
+import React, { createContext, useCallback, useContext, useEffect, useRef } from 'react';
+import { type FormField, type FormSchema, type SessionMode } from '../types';
+import { EncounterFormProcessor } from '../processors/encounter/encounter-form-processor';
+import {
+  type LayoutType,
+  useLayoutType,
+  type OpenmrsResource,
+  showSnackbar,
+  showToast,
+  type ToastDescriptor,
+} from '@openmrs/esm-framework';
+import { type FormProcessorConstructor } from '../processors/form-processor';
+import { type FormContextProps } from './form-provider';
+import { processPostSubmissionActions, validateForm } from './form-factory-helper';
+import { useTranslation } from 'react-i18next';
+import { usePostSubmissionActions } from '../hooks/usePostSubmissionActions';
+import { reportError } from '../utils/error-utils';
+
+interface FormFactoryProviderContextProps {
+  patient: fhir.Patient;
+  sessionMode: SessionMode;
+  sessionDate: Date;
+  formJson: FormSchema;
+  formProcessors: Record<string, FormProcessorConstructor>;
+  layoutType: LayoutType;
+  workspaceLayout: 'minimized' | 'maximized';
+  visit: OpenmrsResource;
+  location: OpenmrsResource;
+  provider: OpenmrsResource;
+  registerForm: (formId: string, context: FormContextProps) => void;
+  setCurrentPage: (page: string) => void;
+  handleConfirmQuestionDeletion?: (question: Readonly<FormField>) => Promise<void>;
+}
+
+interface FormFactoryProviderProps {
+  patient: fhir.Patient;
+  sessionMode: SessionMode;
+  sessionDate: Date;
+  formJson: FormSchema;
+  workspaceLayout: 'minimized' | 'maximized';
+  location: OpenmrsResource;
+  provider: OpenmrsResource;
+  visit: OpenmrsResource;
+  children: React.ReactNode;
+  formSubmissionProps: {
+    isSubmitting: boolean;
+    setIsSubmitting: (isSubmitting: boolean) => void;
+    onSubmit: (data: any) => void;
+    onError: (error: any) => void;
+    handleClose: () => void;
+  };
+  setCurrentPage: (page: string) => void;
+  handleConfirmQuestionDeletion?: (question: Readonly<FormField>) => Promise<void>;
+}
+
+const FormFactoryProviderContext = createContext<FormFactoryProviderContextProps | undefined>(undefined);
+
+export const FormFactoryProvider: React.FC<FormFactoryProviderProps> = ({
+  patient,
+  sessionMode,
+  sessionDate,
+  formJson,
+  workspaceLayout,
+  location,
+  provider,
+  visit,
+  children,
+  formSubmissionProps,
+  setCurrentPage,
+  handleConfirmQuestionDeletion,
+}) => {
+  const { t } = useTranslation();
+  const rootForm = useRef<FormContextProps>();
+  const subForms = useRef<Record<string, FormContextProps>>({});
+  const layoutType = useLayoutType();
+  const { isSubmitting, setIsSubmitting, onSubmit, onError, handleClose } = formSubmissionProps;
+  const postSubmissionHandlers = usePostSubmissionActions(formJson.postSubmissionActions);
+
+  const abortController = new AbortController();
+
+  const registerForm = useCallback((formId: string, context: FormContextProps) => {
+    if (!rootForm.current) {
+      rootForm.current = context;
+    } else {
+      subForms.current[formId] = context;
+    }
+  }, []);
+
+  // TODO: Manage and load processors from the registry
+  const formProcessors = useRef<Record<string, FormProcessorConstructor>>({
+    EncounterFormProcessor: EncounterFormProcessor,
+  });
+
+  useEffect(() => {
+    if (isSubmitting) {
+      // TODO: find a dynamic way of managing the form processing order
+      const forms = [rootForm.current, ...Object.values(subForms.current)];
+      // validate all forms
+      const isValid = forms.every((formContext) => validateForm(formContext));
+      if (isValid) {
+        Promise.all(forms.map((formContext) => formContext.processor.processSubmission(formContext, abortController)))
+          .then(async (results) => {
+            formSubmissionProps.setIsSubmitting(false);
+            if (sessionMode === 'edit') {
+              showSnackbar({
+                title: t('updatedRecord', 'Record updated'),
+                subtitle: t('updatedRecordDescription', 'The patient encounter was updated'),
+                kind: 'success',
+                isLowContrast: true,
+              });
+            } else {
+              showSnackbar({
+                title: t('createdRecord', 'Record created'),
+                subtitle: t('createdRecordDescription', 'A new encounter was created'),
+                kind: 'success',
+                isLowContrast: true,
+              });
+            }
+            if (postSubmissionHandlers) {
+              await processPostSubmissionActions(postSubmissionHandlers, results, patient, sessionMode, t);
+            }
+            if (onSubmit) {
+              onSubmit(results);
+            } else {
+              handleClose();
+            }
+          })
+          .catch((toastErrorObject: ToastDescriptor) => {
+            setIsSubmitting(false);
+            showToast(toastErrorObject);
+          });
+      } else {
+        setIsSubmitting(false);
+      }
+    }
+    return () => {
+      abortController.abort();
+    };
+  }, [isSubmitting]);
+
+  return (
+    <FormFactoryProviderContext.Provider
+      value={{
+        patient,
+        sessionMode,
+        sessionDate,
+        formJson,
+        formProcessors: formProcessors.current,
+        layoutType,
+        workspaceLayout,
+        visit,
+        location,
+        provider,
+        registerForm,
+        setCurrentPage,
+        handleConfirmQuestionDeletion,
+      }}>
+      {formProcessors.current && children}
+    </FormFactoryProviderContext.Provider>
+  );
+};
+
+export const useFormFactory = () => {
+  const context = useContext(FormFactoryProviderContext);
+  if (!context) {
+    throw new Error('useFormFactoryContext must be used within a FormFactoryProvider');
+  }
+  return context;
+};

package/src/provider/form-provider.tsx

@@ -0,0 +1,37 @@
+import React, { type ReactNode } from 'react';
+import { type UseFormReturn } from 'react-hook-form';
+import { type FormProcessorContextProps } from '../types';
+import { type FormSchema, type FormField } from '../types/schema';
+
+export interface FormContextProps extends FormProcessorContextProps {
+  methods: UseFormReturn<any>;
+  workspaceLayout: 'minimized' | 'maximized';
+  isSubmitting?: boolean;
+  getFormField?: (field: string) => FormField;
+  addFormField?: (field: FormField) => void;
+  updateFormField?: (field: FormField) => void;
+  removeFormField?: (fieldId: string) => void;
+  addInvalidField?: (field: FormField) => void;
+  removeInvalidField?: (fieldId: string) => void;
+  setInvalidFields?: (fields: FormField[]) => void;
+  setForm?: (formJson: FormSchema) => void;
+}
+
+export interface FormProviderProps extends FormContextProps {
+  children: ReactNode;
+}
+
+export const FormContext = React.createContext<FormContextProps | undefined>(undefined);
+
+export const FormProvider = ({ methods, children, ...contextProps }: FormProviderProps) => {
+  return <FormContext.Provider value={{ ...contextProps, methods }}>{children}</FormContext.Provider>;
+};
+
+export const useFormProviderContext = () => {
+  const context = React.useContext(FormContext);
+  if (!context) {
+    throw new Error('FormProviderContext must be used within a FormProviderContext');
+  }
+
+  return context;
+};

package/src/registry/inbuilt-components/InbuiltPostSubmissionActions.ts

@@ -0,0 +1,9 @@
+import { type PostSubmissionAction } from '../../types';
+import { type ComponentRegistration } from '../registry';
+
+export const inbuiltPostSubmissionActions: Array<ComponentRegistration<PostSubmissionAction>> = [
+  {
+    name: 'ProgramEnrollmentSubmissionAction',
+    load: () => import('../../post-submission-actions/program-enrollment-action'),
+  },
+];