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

package/src/hooks/useFormJson.tsx

@@ -0,0 +1,237 @@
+import { useEffect, useState } from 'react';
+import { type FormSchemaTransformer, type FormSchema, type FormSection, type ReferencedForm } from '../types';
+import { isTrue } from '../utils/boolean-utils';
+import { applyFormIntent } from '../utils/forms-loader';
+import { fetchOpenMRSForm, fetchClobData } from '../api';
+import { getRegisteredFormSchemaTransformers } from '../registry/registry';
+import { moduleName } from '../globals';
+
+export function useFormJson(formUuid: string, rawFormJson: any, encounterUuid: string, formSessionIntent: string) {
+  const [formJson, setFormJson] = useState<FormSchema>(null);
+  const [error, setError] = useState(validateFormsArgs(formUuid, rawFormJson));
+  useEffect(() => {
+    const setFormJsonWithTranslations = (formJson: FormSchema) => {
+      if (formJson?.translations) {
+        const language = window.i18next.language;
+        window.i18next.addResourceBundle(language, moduleName, formJson.translations, true, true);
+      }
+      setFormJson(formJson);
+    };
+    loadFormJson(formUuid, rawFormJson, formSessionIntent)
+      .then((formJson) => {
+        setFormJsonWithTranslations({ ...formJson, encounter: encounterUuid });
+      })
+      .catch((error) => {
+        console.error(error);
+        setError(new Error('Error loading form JSON: ' + error.message));
+      });
+  }, [formSessionIntent, formUuid, rawFormJson, encounterUuid]);
+
+  return {
+    formJson,
+    isLoading: !formJson,
+    formError: error,
+  };
+}
+
+/**
+ * Fetches a form JSON schema from OpenMRS and recursively fetches its subForms if they available.
+ *
+ * If `rawFormJson` is provided, it will be used as the raw form JSON object. Otherwise, the form JSON will be fetched from OpenMRS using the `formIdentifier` parameter.
+ *
+ * @param rawFormJson The raw form JSON object to be used if `formIdentifier` is not provided.
+ * @param formIdentifier The UUID or name of the form to be fetched from OpenMRS if `rawFormJson` is not provided.
+ * @param formSessionIntent An optional parameter that represents the current intent.
+ * @returns A well-built form object that might include subForms.
+ */
+export async function loadFormJson(
+  formIdentifier: string,
+  rawFormJson?: FormSchema,
+  formSessionIntent?: string,
+): Promise<FormSchema> {
+  const openmrsFormResponse = await fetchOpenMRSForm(formIdentifier);
+  const clobDataResponse = await fetchClobData(openmrsFormResponse);
+  const transformers = await getRegisteredFormSchemaTransformers();
+  const formJson: FormSchema = clobDataResponse
+    ? { ...clobDataResponse, uuid: openmrsFormResponse.uuid }
+    : parseFormJson(rawFormJson);
+
+  // Sub forms
+  const subFormRefs = extractSubFormRefs(formJson);
+  const subForms = await loadSubForms(subFormRefs, formSessionIntent);
+  updateFormJsonWithSubForms(formJson, subForms);
+
+  // Form components
+  const formComponentsRefs = getReferencedForms(formJson);
+  const resolvedFormComponents = await loadFormComponents(formComponentsRefs);
+  const formNameToAliasMap = formComponentsRefs.reduce((acc, form) => {
+    acc[form.formName] = form.alias;
+    return acc;
+  }, {});
+
+  const formComponents = mapFormComponents(resolvedFormComponents);
+  updateFormJsonWithComponents(formJson, formComponents, formNameToAliasMap);
+  return refineFormJson(formJson, transformers, formSessionIntent);
+}
+
+function extractSubFormRefs(formJson: FormSchema): string[] {
+  return formJson.pages
+    .filter((page) => page.isSubform && !page.subform.form && page.subform?.name)
+    .map((page) => page.subform?.name);
+}
+
+async function loadSubForms(subFormRefs: string[], formSessionIntent?: string): Promise<FormSchema[]> {
+  return Promise.all(subFormRefs.map((subForm) => loadFormJson(subForm, null, formSessionIntent)));
+}
+
+function updateFormJsonWithSubForms(formJson: FormSchema, subForms: FormSchema[]): void {
+  subForms.forEach((subForm) => {
+    const matchingPage = formJson.pages.find((page) => page.subform?.name === subForm.name);
+    if (matchingPage) {
+      matchingPage.subform.form = subForm;
+    }
+  });
+}
+
+function validateFormsArgs(formUuid: string, rawFormJson: any): Error {
+  if (!formUuid && !rawFormJson) {
+    return new Error('InvalidArgumentsErr: Neither formUuid nor formJson was provided');
+  }
+  if (formUuid && rawFormJson) {
+    return new Error('InvalidArgumentsErr: Both formUuid and formJson cannot be provided at the same time.');
+  }
+}
+
+/**
+ * Refines the input form JSON object by parsing it, removing inline sub forms, applying form schema transformers, setting the encounter type, and applying form intents if provided.
+ * @param {any} formJson - The input form JSON object or string.
+ * @param {string} [formSessionIntent] - The optional form session intent.
+ * @returns {FormSchema} - The refined form JSON object of type FormSchema.
+ */
+function refineFormJson(
+  formJson: any,
+  schemaTransformers: FormSchemaTransformer[] = [],
+  formSessionIntent?: string,
+): FormSchema {
+  removeInlineSubForms(formJson, formSessionIntent);
+  // apply form schema transformers
+  schemaTransformers.reduce((draftForm, transformer) => transformer.transform(draftForm), formJson);
+  setEncounterType(formJson);
+  return applyFormIntent(formSessionIntent, formJson);
+}
+
+/**
+ * Parses the input form JSON and returns a deep copy of the object.
+ * @param {any} formJson - The input form JSON object or string.
+ * @returns {FormSchema} - The parsed form JSON object of type FormSchema.
+ */
+function parseFormJson(formJson: any): FormSchema {
+  return typeof formJson === 'string' ? JSON.parse(formJson) : JSON.parse(JSON.stringify(formJson));
+}
+
+/**
+ * Removes inline sub forms from the form JSON and replaces them with their pages if the encounter type matches.
+ * @param {FormSchema} formJson - The input form JSON object of type FormSchema.
+ * @param {string} formSessionIntent - The form session intent.
+ */
+function removeInlineSubForms(formJson: FormSchema, formSessionIntent: string): void {
+  for (let i = formJson.pages.length - 1; i >= 0; i--) {
+    const page = formJson.pages[i];
+    if (
+      isTrue(page.isSubform) &&
+      !isTrue(page.isHidden) &&
+      page.subform?.form?.encounterType === formJson.encounterType
+    ) {
+      const nonSubformPages = page.subform.form.pages.filter((page) => !isTrue(page.isSubform));
+      formJson.pages.splice(i, 1, ...refineFormJson(page.subform.form, [], formSessionIntent).pages);
+    }
+  }
+}
+
+/**
+ * Sets the encounter type for the form JSON if it's provided through the `encounter` attribute.
+ * @param {FormSchema} formJson - The input form JSON object of type FormSchema.
+ */
+function setEncounterType(formJson: FormSchema): void {
+  if (formJson.encounter && typeof formJson.encounter === 'string' && !formJson.encounterType) {
+    formJson.encounterType = formJson.encounter;
+    delete formJson.encounter;
+  }
+}
+
+/**
+ * Functions to support reusable Form Components
+ */
+function getReferencedForms(formJson: FormSchema): Array<ReferencedForm> {
+  const referencedForms: Array<any> = formJson?.referencedForms;
+  if (!referencedForms) {
+    return [];
+  }
+  return referencedForms;
+}
+
+async function loadFormComponents(formComponentRefs: Array<ReferencedForm>): Promise<FormSchema[]> {
+  return Promise.all(formComponentRefs.map((formComponent) => loadFormJson(formComponent.formName, null, null)));
+}
+
+function mapFormComponents(formComponents: Array<FormSchema>): Map<string, FormSchema> {
+  const formComponentsMap: Map<string, FormSchema> = new Map();
+
+  formComponents.forEach((formComponent) => {
+    formComponentsMap.set(formComponent.name, formComponent);
+  });
+
+  return formComponentsMap;
+}
+
+function updateFormJsonWithComponents(
+  formJson: FormSchema,
+  formComponents: Map<string, FormSchema>,
+  formNameToAliasMap: Record<string, string>,
+): void {
+  formComponents.forEach((component, targetFormName) => {
+    //loop through pages and search sections for reference key
+    formJson.pages.forEach((page) => {
+      if (page.sections) {
+        page.sections.forEach((section) => {
+          if (
+            section.reference &&
+            (section.reference.form === targetFormName || section.reference.form === formNameToAliasMap[targetFormName])
+          ) {
+            // resolve referenced component section
+            let resolvedFormSection = getReferencedFormSection(section, component);
+            // add resulting referenced component section to section
+            Object.assign(section, resolvedFormSection);
+          }
+        });
+      }
+    });
+  });
+}
+
+function getReferencedFormSection(formSection: FormSection, formComponent: FormSchema): FormSection {
+  let referencedFormSection: FormSection;
+
+  // search for component page and section reference from component
+  let matchingComponentPage = formComponent.pages.filter((page) => page.label === formSection.reference.page);
+  if (matchingComponentPage.length > 0) {
+    let matchingComponentSection = matchingComponentPage[0].sections.filter(
+      (componentSection) => componentSection.label === formSection.reference.section,
+    );
+    if (matchingComponentSection.length > 0) {
+      referencedFormSection = matchingComponentSection[0];
+    }
+  }
+
+  return filterExcludedQuestions(referencedFormSection, formSection.reference);
+}
+
+function filterExcludedQuestions(formSection: FormSection, reference: any): FormSection {
+  if (reference?.excludeQuestions) {
+    const excludeQuestions = reference.excludeQuestions;
+    formSection.questions = formSection.questions.filter((question) => {
+      return !excludeQuestions.includes(question.id);
+    });
+  }
+  return formSection;
+}

package/src/hooks/useFormStateHelpers.ts

@@ -0,0 +1,50 @@
+import { type Dispatch, useCallback } from 'react';
+import { type FormSchema, type FormField } from '../types';
+import { type Action } from '../components/renderer/form/state';
+
+export function useFormStateHelpers(dispatch: Dispatch<Action>, formFields: FormField[]) {
+  const addFormField = useCallback((field: FormField) => {
+    dispatch({ type: 'ADD_FORM_FIELD', value: field });
+  }, []);
+  const updateFormField = useCallback((field: FormField) => {
+    dispatch({ type: 'UPDATE_FORM_FIELD', value: field });
+  }, []);
+
+  const getFormField = useCallback(
+    (fieldId: string) => {
+      return formFields.find((field) => field.id === fieldId);
+    },
+    [formFields.length],
+  );
+
+  const removeFormField = useCallback((fieldId: string) => {
+    dispatch({ type: 'REMOVE_FORM_FIELD', value: fieldId });
+  }, []);
+
+  const setInvalidFields = useCallback((fields: FormField[]) => {
+    dispatch({ type: 'SET_INVALID_FIELDS', value: fields });
+  }, []);
+
+  const addInvalidField = useCallback((field: FormField) => {
+    dispatch({ type: 'ADD_INVALID_FIELD', value: field });
+  }, []);
+
+  const removeInvalidField = useCallback((fieldId: string) => {
+    dispatch({ type: 'REMOVE_INVALID_FIELD', value: fieldId });
+  }, []);
+
+  const setForm = useCallback((formJson: FormSchema) => {
+    dispatch({ type: 'SET_FORM_JSON', value: formJson });
+  }, []);
+
+  return {
+    addFormField,
+    updateFormField,
+    getFormField,
+    removeFormField,
+    setInvalidFields,
+    addInvalidField,
+    removeInvalidField,
+    setForm,
+  };
+}

package/src/hooks/useFormsConfig.tsx

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+import get from 'lodash-es/get';
+import { getConfig } from '@openmrs/esm-framework';
+import { ConceptTrue, ConceptFalse } from '../constants';
+
+export interface FormsConfig {
+  conceptTrue: string;
+  conceptFalse: string;
+}
+const defaultOptions: FormsConfig = {
+  conceptTrue: ConceptTrue,
+  conceptFalse: ConceptFalse,
+};
+
+export function useFormsConfig(moduleName: string, configPath: string) {
+  const [config, setConfig] = useState<FormsConfig>(defaultOptions);
+
+  useEffect(() => {
+    if (moduleName && configPath) {
+      getConfig(moduleName).then((c) => {
+        setConfig({ config, ...get(c, configPath, config) });
+      });
+    }
+  }, [moduleName, configPath, config]);
+
+  return config;
+}

package/src/hooks/useInitialValues.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react';
+import { type FormProcessorContextProps } from '../types';
+import { type FormProcessor } from '../processors/form-processor';
+
+const useInitialValues = (
+  formProcessor: FormProcessor,
+  isLoadingContextDependencies: boolean,
+  context: FormProcessorContextProps,
+) => {
+  const [isLoadingInitialValues, setIsLoadingInitialValues] = useState(true);
+  const [initialValues, setInitialValues] = useState({});
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    if (
+      formProcessor &&
+      !isLoadingContextDependencies &&
+      context.formFields?.length &&
+      Object.keys(context.formFieldAdapters).length &&
+      !Object.keys(initialValues).length
+    ) {
+      formProcessor
+        .getInitialValues(context)
+        .then((values) => {
+          setInitialValues(values);
+          setIsLoadingInitialValues(false);
+        })
+        .catch((error) => {
+          console.error(error);
+          setError(error);
+        });
+    }
+  }, [formProcessor, isLoadingContextDependencies, context]);
+
+  return { isLoadingInitialValues, initialValues, error };
+};
+
+export default useInitialValues;

package/src/hooks/usePatientData.tsx

@@ -0,0 +1,32 @@
+import { usePatient } from '@openmrs/esm-framework';
+
+function calculateAge(birthDate: Date): number {
+  const today = new Date();
+  const yearsDiff = today.getFullYear() - birthDate.getFullYear();
+  if (
+    today.getMonth() < birthDate.getMonth() ||
+    (today.getMonth() === birthDate.getMonth() && today.getDate() < birthDate.getDate())
+  ) {
+    // subtract one year if the current date is before the birth date this year
+    return yearsDiff - 1;
+  } else {
+    return yearsDiff;
+  }
+}
+
+const patientGenderMap = {
+  female: 'F',
+  male: 'M',
+  other: 'O',
+  unknown: 'U',
+};
+
+export const usePatientData = (patientUuid) => {
+  const { patient, isLoading: isLoadingPatient, error: patientError } = usePatient(patientUuid);
+  if (patient && !isLoadingPatient) {
+    // This is to support backward compatibility with the AMPATH JSON format
+    patient['age'] = calculateAge(new Date(patient?.birthDate));
+    patient['sex'] = patientGenderMap[patient.gender] ?? 'U';
+  }
+  return { patient, isLoadingPatient, patientError };
+};

package/src/hooks/usePatientPrograms.ts

@@ -0,0 +1,32 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { useEffect, useState } from 'react';
+import { type FormSchema, type PatientProgram } from '../types';
+const customRepresentation = `custom:(uuid,display,program:(uuid,name,allWorkflows),dateEnrolled,dateCompleted,location:(uuid,display),states:(startDate,endDate,state:(uuid,name,retired,concept:(uuid),programWorkflow:(uuid)))`;
+
+export const usePatientPrograms = (patientUuid: string, formJson: FormSchema) => {
+  const [patientPrograms, setPatientPrograms] = useState<Array<PatientProgram>>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    if (formJson.meta?.programs?.hasProgramFields) {
+      openmrsFetch(`${restBaseUrl}/programenrollment?patient=${patientUuid}&v=${customRepresentation}`)
+        .then((response) => {
+          setPatientPrograms(response.data.results.filter((enrollment) => enrollment.dateCompleted === null));
+          setIsLoading(false);
+        })
+        .catch((error) => {
+          setError(error);
+          setIsLoading(false);
+        });
+    } else {
+      setIsLoading(false);
+    }
+  }, [formJson]);
+
+  return {
+    patientPrograms,
+    error,
+    isLoading,
+  };
+};

package/src/hooks/usePostSubmissionActions.test.tsx

@@ -0,0 +1,42 @@
+import { renderHook, act } from '@testing-library/react';
+import { usePostSubmissionActions } from './usePostSubmissionActions';
+
+// Mock the getRegisteredPostSubmissionAction function
+jest.mock('../registry/registry', () => ({
+  getRegisteredPostSubmissionAction: jest.fn(),
+}));
+
+describe('usePostSubmissionActions', () => {
+  // Mock the actual post-submission action function
+  const mockPostAction = jest.fn();
+
+  // Sample action references
+  const actionRefs = [
+    { actionId: 'action1', config: { param1: 'value1' } },
+    { actionId: 'action2', config: { param2: 'value2' } },
+  ];
+
+  // Set up the mock implementation for getRegisteredPostSubmissionAction
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.spyOn(global.console, 'error').mockImplementation(() => {});
+    jest.requireMock('../registry/registry').getRegisteredPostSubmissionAction.mockImplementation((actionId) => {
+      if (actionId === 'action1') {
+        return Promise.resolve(mockPostAction);
+      }
+      return Promise.resolve(null);
+    });
+  });
+
+  it('should fetch post-submission actions and return them', async () => {
+    const { result } = renderHook(() => usePostSubmissionActions(actionRefs));
+
+    // Wait for the effect to complete
+    await act(async () => {});
+
+    expect(result.current).toEqual([
+      { postAction: mockPostAction, config: { param1: 'value1' }, actionId: 'action1' },
+      { postAction: null, config: { param2: 'value2' }, actionId: 'action2' },
+    ]);
+  });
+});

package/src/hooks/usePostSubmissionActions.ts

@@ -0,0 +1,31 @@
+import { useEffect, useState } from 'react';
+import { getRegisteredPostSubmissionAction } from '../registry/registry';
+import { type PostSubmissionAction } from '../types';
+
+export interface PostSubmissionActionMeta {
+  postAction: PostSubmissionAction;
+  actionId: string;
+  config: Record<string, any>;
+  enabled?: string;
+}
+
+export function usePostSubmissionActions(
+  actionRefs: Array<{ actionId: string; enabled?: string; config?: Record<string, any> }>,
+): Array<PostSubmissionActionMeta> {
+  const [actions, setActions] = useState<Array<PostSubmissionActionMeta>>([]);
+
+  useEffect(() => {
+    const actionArray: Array<PostSubmissionActionMeta> = [];
+    if (actionRefs?.length) {
+      actionRefs.map((ref) => {
+        const actionId = typeof ref === 'string' ? ref : ref.actionId;
+        getRegisteredPostSubmissionAction(actionId)?.then((action) =>
+          actionArray.push({ postAction: action, config: ref.config, actionId: actionId, enabled: ref.enabled }),
+        );
+      });
+    }
+    setActions(actionArray);
+  }, [actionRefs]);
+
+  return actions;
+}

package/src/hooks/useProcessorDependencies.ts

@@ -0,0 +1,30 @@
+import { useState, useEffect } from 'react';
+import { type FormProcessorContextProps } from '../types';
+import { type FormProcessor } from '../processors/form-processor';
+
+const useProcessorDependencies = (
+  formProcessor: FormProcessor,
+  context: Partial<FormProcessorContextProps>,
+  setContext: (context: FormProcessorContextProps) => void,
+) => {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState('');
+  const { loadDependencies } = formProcessor;
+
+  useEffect(() => {
+    if (loadDependencies) {
+      setIsLoading(true);
+      loadDependencies(context, setContext)
+        .then((results) => {
+          setIsLoading(false);
+        })
+        .catch((error) => {
+          setError(error);
+        });
+    }
+  }, []);
+
+  return { isLoading, error };
+};
+
+export default useProcessorDependencies;

package/src/hooks/useRestMaxResultsCount.ts

@@ -0,0 +1,5 @@
+import useSystemSetting from './useSystemSetting';
+
+export default function useRestMaxResultsCount() {
+  return useSystemSetting('webservices.rest.maxResultsDefault');
+}

package/src/hooks/useSystemSetting.ts

@@ -0,0 +1,36 @@
+import { openmrsFetch, restBaseUrl, showSnackbar } from '@openmrs/esm-framework';
+import { useEffect } from 'react';
+import { useTranslation } from 'react-i18next';
+import useSWRImmutable from 'swr/immutable';
+
+export interface SystemSetting {
+  uuid: string;
+  property: string;
+  value: string;
+}
+
+export default function useSystemSetting(setting: string) {
+  const { t } = useTranslation();
+  const apiUrl = `${restBaseUrl}/systemsetting/${setting}?v=custom:(value)`;
+  const { data, error, isLoading } = useSWRImmutable<{ data: SystemSetting }, Error>(apiUrl, openmrsFetch);
+
+  useEffect(() => {
+    if (error) {
+      showSnackbar({
+        title: t('error', 'Error'),
+        subtitle: error?.message,
+        kind: 'error',
+        isLowContrast: false,
+      });
+    }
+  }, [error]);
+
+  return {
+    systemSetting: data?.data,
+    error: error,
+    isLoading: isLoading,
+    isValueUuid:
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(data?.data?.value) ||
+      /^[0-9a-f]{36}$/i.test(data?.data?.value),
+  };
+}

package/src/hooks/useWorkspaceLayout.ts

@@ -0,0 +1,29 @@
+import { useLayoutEffect, useState } from 'react';
+
+/**
+ * This hook evaluates the layout of the current workspace based on the width of the container element
+ */
+export function useWorkspaceLayout(rootRef): 'minimized' | 'maximized' {
+  const [layout, setLayout] = useState<'minimized' | 'maximized'>('minimized');
+  const TABLET_MAX = 1023;
+  useLayoutEffect(() => {
+    const handleResize = () => {
+      const containerWidth = rootRef.current?.parentElement?.offsetWidth;
+      containerWidth && setLayout(containerWidth > TABLET_MAX ? 'maximized' : 'minimized');
+    };
+    handleResize();
+    const resizeObserver = new ResizeObserver((entries) => {
+      handleResize();
+    });
+
+    if (rootRef.current) {
+      resizeObserver.observe(rootRef.current?.parentElement);
+    }
+
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, [rootRef]);
+
+  return layout;
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from './types';
+export * from './utils/forms-loader';
+export * from './registry/registry';
+export * from './constants';
+export * from './utils/boolean-utils';
+export * from './validators/form-validator';
+export * from './utils/form-helper';
+export * from './form-context';
+export * from './components/value/view/field-value-view.component';
+export * from './components/previous-value-review/previous-value-review.component';
+export * from './hooks/useFormJson';
+export { default as FormEngine } from './form-engine.component';

package/src/lifecycle.ts

@@ -0,0 +1,33 @@
+import setupFormEngineLibI18n from './setupI18n';
+import { type FormFieldValueAdapter } from './types';
+
+const formFieldAdapters = new Set<FormFieldValueAdapter>();
+
+export function registerFormFieldAdaptersForCleanUp(formFieldAdaptersMap: Record<string, FormFieldValueAdapter>) {
+  if (formFieldAdaptersMap) {
+    Object.values(formFieldAdaptersMap).forEach((adapter) => {
+      formFieldAdapters.add(adapter);
+    });
+  }
+}
+/**
+ * Invoked on mounting the "FormEngine" component
+ */
+export function init() {
+  // Setting up the i18n for the form engine library
+  setupFormEngineLibI18n();
+}
+
+/**
+ * Invoked on unmounting the "FormEngine" component
+ */
+export function teardown() {
+  formFieldAdapters.forEach((adapter) => {
+    try {
+      adapter.tearDown();
+    } catch (error) {
+      // pass
+    }
+  });
+  formFieldAdapters.clear();
+}