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

package/src/utils/form-helper.test.ts

@@ -0,0 +1,482 @@
+import {
+  findConceptByReference,
+  evaluateConditionalAnswered,
+  evaluateFieldReadonlyProp,
+  parseToLocalDateTime,
+  evaluateDisabled,
+} from './form-helper';
+import { DefaultValueValidator } from '../validators/default-value-validator';
+import { type LayoutType } from '@openmrs/esm-framework';
+import { ConceptTrue } from '../constants';
+import { type FormField, type OpenmrsEncounter, type SessionMode } from '../types';
+import { type EncounterContext } from '../form-context';
+
+jest.mock('../validators/default-value-validator');
+
+describe('Form Engine Helper', () => {
+  describe('findConceptByReference', () => {
+    const concepts = [
+      {
+        uuid: '3cd6f600-26fe-102b-80cb-0017a47871b2',
+        display: 'Yes',
+        conceptMappings: [
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'SNOMED CT',
+              },
+              code: '373066001',
+            },
+          },
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'PIH',
+              },
+              code: 'YES',
+            },
+          },
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'CIEL',
+              },
+              code: '1065',
+            },
+          },
+        ],
+      },
+      {
+        uuid: '3cd6f86c-26fe-102b-80cb-0017a47871b2',
+        display: 'No',
+        conceptMappings: [
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'PIH',
+              },
+              code: 'NO',
+            },
+          },
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'CIEL',
+              },
+              code: '1066',
+            },
+          },
+          {
+            conceptReferenceTerm: {
+              conceptSource: {
+                name: 'SNOMED CT',
+              },
+              code: '373067005',
+            },
+          },
+        ],
+      },
+    ];
+
+    it('should find concept by mapping', () => {
+      expect(findConceptByReference('CIEL:1066', concepts).uuid).toBe('3cd6f86c-26fe-102b-80cb-0017a47871b2');
+    });
+    it('should find concept by uuid', () => {
+      expect(findConceptByReference('3cd6f86c-26fe-102b-80cb-0017a47871b2', concepts).uuid).toBe(
+        '3cd6f86c-26fe-102b-80cb-0017a47871b2',
+      );
+    });
+    it('should return undefined if no match', () => {
+      expect(findConceptByReference('CIEL:9999', concepts)).toBeUndefined();
+    });
+    it('should return undefined if null input', () => {
+      expect(findConceptByReference(null, concepts)).toBeUndefined();
+    });
+  });
+
+  // describe('inferInitialValueFromDefaultFieldValue', () => {
+  //   const mockHandleFieldSubmission = jest.fn();
+  //   const mockHandler = {
+  //     handleFieldSubmission: mockHandleFieldSubmission,
+  //     getInitialValue: function (
+  //       encounter: OpenmrsEncounter,
+  //       field: FormField,
+  //       allFormFields?: FormField[],
+  //       context?: EncounterContext,
+  //     ): {} {
+  //       throw new Error('Function not implemented.');
+  //     },
+  //     getDisplayValue: function (field: FormField, value: any) {
+  //       throw new Error('Function not implemented.');
+  //     },
+  //   };
+
+  //   const sampleContext: EncounterContext = {
+  //     patient: {
+  //       id: '833db896-c1f0-11eb-8529-0242ac130003',
+  //     },
+  //     encounter: {
+  //       uuid: '773455da-3ec4-453c-b565-7c1fe35426be',
+  //       encounterProviders: [],
+  //       obs: [],
+  //     },
+  //     location: {},
+  //     sessionMode: 'edit',
+  //     encounterDate: new Date(),
+  //     setEncounterDate: jest.fn(),
+  //     encounterProvider: '',
+  //     setEncounterProvider: jest.fn(),
+  //     setEncounterLocation: jest.fn(),
+  //     encounterRole: '',
+  //     setEncounterRole: jest.fn(),
+  //   };
+
+  //   beforeEach(() => {
+  //     jest.clearAllMocks();
+  //   });
+
+  //   it('should return true if rendering is toggle and default value is ConceptTrue', () => {
+  //     const sampleField: FormField = {
+  //       label: 'Sample Toggle Field',
+  //       type: 'obs',
+  //       questionOptions: { rendering: 'toggle', defaultValue: ConceptTrue },
+  //       id: 'toggle-field',
+  //     };
+
+  //     const result = inferInitialValueFromDefaultFieldValue(sampleField, sampleContext, mockHandler);
+
+  //     expect(result).toBe(true);
+  //   });
+
+  //   it('should validate default value and handle field submission if valid', () => {
+  //     const sampleField: FormField = {
+  //       label: 'Sample Field',
+  //       type: 'obs',
+  //       questionOptions: { rendering: 'text', defaultValue: 'valid-value' },
+  //       id: 'text-field',
+  //     };
+
+  //     (DefaultValueValidator.validate as jest.Mock).mockReturnValue([]);
+
+  //     const result = inferInitialValueFromDefaultFieldValue(sampleField, sampleContext, mockHandler);
+
+  //     expect(DefaultValueValidator.validate).toHaveBeenCalledWith(sampleField, 'valid-value');
+  //     expect(mockHandleFieldSubmission).toHaveBeenCalledWith(sampleField, 'valid-value', sampleContext);
+  //     expect(result).toBe('valid-value');
+  //   });
+
+  //   it('should not handle field submission if default value is invalid', () => {
+  //     const sampleField: FormField = {
+  //       label: 'Sample Field',
+  //       type: 'obs',
+  //       questionOptions: { rendering: 'text', defaultValue: 'invalid-value' },
+  //       id: 'text-field',
+  //     };
+
+  //     (DefaultValueValidator.validate as jest.Mock).mockReturnValue(['Error: Invalid value']);
+
+  //     const result = inferInitialValueFromDefaultFieldValue(sampleField, sampleContext, mockHandler);
+
+  //     expect(DefaultValueValidator.validate).toHaveBeenCalledWith(sampleField, 'invalid-value');
+  //     expect(mockHandleFieldSubmission).not.toHaveBeenCalled();
+  //     expect(result).toBeUndefined();
+  //   });
+  // });
+
+  // describe('isInlineView', () => {
+  //   it('should return true if sessionMode is embedded-view', () => {
+  //     const result = isInlineView('single-line', 'desktop' as LayoutType, 'maximized', 'embedded-view' as SessionMode);
+  //     expect(result).toBe(true);
+  //   });
+
+  //   it('should return true if renderingType is automatic, workspaceLayout is maximized, and layoutType ends with desktop', () => {
+  //     const result = isInlineView('automatic', 'large-desktop' as LayoutType, 'maximized', 'edit' as SessionMode);
+  //     expect(result).toBe(true);
+  //   });
+
+  //   it('should return false if renderingType is automatic, workspaceLayout is maximized, but layoutType does not end with desktop', () => {
+  //     const result = isInlineView('automatic', 'tablet' as LayoutType, 'maximized', 'edit' as SessionMode);
+  //     expect(result).toBe(false);
+  //   });
+
+  //   it('should return true if renderingType is single-line', () => {
+  //     const result = isInlineView('single-line', 'desktop' as LayoutType, 'minimized', 'edit' as SessionMode);
+  //     expect(result).toBe(true);
+  //   });
+
+  //   it('should return false if renderingType is multiline', () => {
+  //     const result = isInlineView('multiline', 'desktop' as LayoutType, 'maximized', 'edit' as SessionMode);
+  //     expect(result).toBe(false);
+  //   });
+
+  //   it('should return false if renderingType is automatic and workspaceLayout is minimized', () => {
+  //     const result = isInlineView('automatic', 'large-desktop' as LayoutType, 'minimized', 'edit' as SessionMode);
+  //     expect(result).toBe(false);
+  //   });
+
+  //   it('should return false if renderingType is automatic and layoutType does not end with desktop', () => {
+  //     const result = isInlineView('automatic', 'mobile' as LayoutType, 'maximized', 'edit' as SessionMode);
+  //     expect(result).toBe(false);
+  //   });
+
+  //   it('should return false if renderingType is multiline and sessionMode is not embedded-view', () => {
+  //     const result = isInlineView('multiline', 'desktop' as LayoutType, 'maximized', 'edit' as SessionMode);
+  //     expect(result).toBe(false);
+  //   });
+  // });
+
+  // describe('evaluateConditionalAnswered', () => {
+  //   it('should add field id to referencedField.fieldDependants when referenced field is found', () => {
+  //     const field: FormField = {
+  //       label: 'Field with Validator',
+  //       type: 'obs',
+  //       questionOptions: {
+  //         rendering: 'number',
+  //       },
+  //       id: 'field-1',
+  //       validators: [
+  //         {
+  //           type: 'conditionalAnswered',
+  //           referenceQuestionId: 'field-2',
+  //         },
+  //       ],
+  //     };
+
+  //     const referencedField: FormField = {
+  //       label: 'Referenced Field',
+  //       type: 'obs',
+  //       questionOptions: {
+  //         rendering: 'number',
+  //       },
+  //       id: 'field-2',
+  //     };
+
+  //     const allFields: FormField[] = [field, referencedField];
+
+  //     evaluateConditionalAnswered(field, allFields);
+
+  //     expect(referencedField.fieldDependants).toEqual(new Set(['field-1']));
+  //   });
+
+  //   it('should not add field id to referencedField.fieldDependants when referenced field is not found', () => {
+  //     const field: FormField = {
+  //       label: 'Field with Validator',
+  //       type: 'obs',
+  //       questionOptions: {
+  //         rendering: 'number',
+  //       },
+  //       id: 'field-1',
+  //       validators: [
+  //         {
+  //           type: 'conditionalAnswered',
+  //           referenceQuestionId: 'field-2',
+  //         },
+  //       ],
+  //     };
+
+  //     const allFields: FormField[] = [field];
+
+  //     evaluateConditionalAnswered(field, allFields);
+
+  //     // Since referenced field is not in allFields, nothing should be added
+  //     allFields.forEach((field) => {
+  //       expect(field.fieldDependants).toBeUndefined();
+  //     });
+  //   });
+
+  //   it('should not overwrite existing fieldDependants', () => {
+  //     const field: FormField = {
+  //       label: 'Field with Validator',
+  //       type: 'obs',
+  //       questionOptions: {
+  //         rendering: 'number',
+  //       },
+  //       id: 'field-1',
+  //       validators: [
+  //         {
+  //           type: 'conditionalAnswered',
+  //           referenceQuestionId: 'field-2',
+  //         },
+  //       ],
+  //     };
+
+  //     const referencedField: FormField = {
+  //       label: 'Referenced Field',
+  //       type: 'obs',
+  //       questionOptions: {
+  //         rendering: 'number',
+  //       },
+  //       id: 'field-2',
+  //       fieldDependants: new Set(['field-3']),
+  //     };
+
+  //     const allFields: FormField[] = [field, referencedField];
+
+  //     evaluateConditionalAnswered(field, allFields);
+
+  //     expect(referencedField.fieldDependants).toEqual(new Set(['field-3', 'field-1']));
+  //   });
+  // });
+
+  describe('evaluateFieldReadonlyProp', () => {
+    it('should not change field.readonly if it is not empty', () => {
+      const field: FormField = {
+        label: 'Test Field',
+        type: 'obs',
+        questionOptions: {
+          rendering: 'number',
+        },
+        id: 'field-1',
+        readonly: true,
+      };
+
+      evaluateFieldReadonlyProp(field, false, false, false);
+
+      expect(field.readonly).toBe(true);
+    });
+
+    it('should set field.readonly to true if sectionReadonly is not empty', () => {
+      const field: FormField = {
+        label: 'Test Field',
+        type: 'obs',
+        questionOptions: {
+          rendering: 'number',
+        },
+        id: 'field-1',
+        readonly: '',
+      };
+
+      evaluateFieldReadonlyProp(field, 'some value', false, false);
+
+      expect(field.readonly).toBe(true);
+    });
+
+    it('should set field.readonly to true if pageReadonly is not empty', () => {
+      const field: FormField = {
+        label: 'Test Field',
+        type: 'obs',
+        questionOptions: {
+          rendering: 'number',
+        },
+        id: 'field-1',
+        readonly: '',
+      };
+
+      evaluateFieldReadonlyProp(field, false, 'some value', false);
+
+      expect(field.readonly).toBe(true);
+    });
+
+    it('should set field.readonly to true if formReadonly is true', () => {
+      const field: FormField = {
+        label: 'Test Field',
+        type: 'obs',
+        questionOptions: {
+          rendering: 'number',
+        },
+        id: 'field-1',
+        readonly: '',
+      };
+
+      evaluateFieldReadonlyProp(field, false, false, true);
+
+      expect(field.readonly).toBe(true);
+    });
+  });
+
+  describe('parseToLocalDateTime', () => {
+    it('should parse valid date string with time correctly', () => {
+      const dateString = '2023-06-27T14:30:00';
+      const expectedDate = new Date(2023, 5, 27, 14, 30, 0);
+      const parsedDate = parseToLocalDateTime(dateString);
+
+      expect(parsedDate).toEqual(expectedDate);
+    });
+
+    it('should parse valid date string without time correctly', () => {
+      const dateString = '2023-06-27';
+      const expectedDate = new Date(2023, 5, 27);
+      const parsedDate = parseToLocalDateTime(dateString);
+
+      // Set hours, minutes, and seconds to 0 since the input doesn't contain time
+      expectedDate.setHours(0, 0, 0, 0);
+
+      expect(parsedDate).toEqual(expectedDate);
+    });
+
+    it('should handle invalid date string format gracefully', () => {
+      const dateString = 'invalid-date-string';
+      const parsedDate = parseToLocalDateTime(dateString);
+
+      // Check if the parsedDate is an Invalid Date
+      expect(isNaN(parsedDate.getTime())).toBe(true);
+    });
+  });
+
+  describe('evaluateDisabled', () => {
+    let mockExpressionRunnerFn;
+    let node;
+    let allFields;
+    let allValues;
+    let sessionMode;
+    let patient;
+
+    beforeEach(() => {
+      mockExpressionRunnerFn = jest.fn();
+      node = { value: { disabled: { disableWhenExpression: '' } } };
+      allFields = [{ id: 'field1', value: 'value1' }];
+      allValues = { field1: 'value1' };
+      sessionMode = 'edit';
+      patient = { id: 'patient1', name: 'John Doe' };
+    });
+
+    test('returns true when disableWhenExpression evaluates to true', () => {
+      mockExpressionRunnerFn.mockReturnValue(true);
+      const result = evaluateDisabled(node, allFields, allValues, sessionMode, patient, mockExpressionRunnerFn);
+      expect(result).toBe(true);
+      expect(mockExpressionRunnerFn).toHaveBeenCalledWith(
+        node.value.disabled.disableWhenExpression,
+        node,
+        allFields,
+        allValues,
+        { mode: sessionMode, patient },
+      );
+    });
+
+    test('returns false when disableWhenExpression evaluates to false', () => {
+      mockExpressionRunnerFn.mockReturnValue(false);
+      const result = evaluateDisabled(node, allFields, allValues, sessionMode, patient, mockExpressionRunnerFn);
+      expect(result).toBe(false);
+      expect(mockExpressionRunnerFn).toHaveBeenCalledWith(
+        node.value.disabled.disableWhenExpression,
+        node,
+        allFields,
+        allValues,
+        { mode: sessionMode, patient },
+      );
+    });
+
+    test('works with different sessionMode values', () => {
+      sessionMode = 'view';
+      mockExpressionRunnerFn.mockReturnValue(true);
+      const result = evaluateDisabled(node, allFields, allValues, sessionMode, patient, mockExpressionRunnerFn);
+      expect(result).toBe(true);
+      expect(mockExpressionRunnerFn).toHaveBeenCalledWith(
+        node.value.disabled.disableWhenExpression,
+        node,
+        allFields,
+        allValues,
+        { mode: sessionMode, patient },
+      );
+    });
+
+    test('throws if the expression causes an error', () => {
+      mockExpressionRunnerFn.mockImplementation(() => {
+        throw new Error('Invalid expression');
+      });
+      expect(() => evaluateDisabled(node, allFields, allValues, sessionMode, patient, mockExpressionRunnerFn)).toThrow(
+        'Invalid expression',
+      );
+    });
+  });
+});

package/src/utils/form-helper.ts

@@ -0,0 +1,210 @@
+import dayjs from 'dayjs';
+import { type LayoutType } from '@openmrs/esm-framework';
+import { type FormField, type FormPage, type FormSection, type SessionMode } from '../types';
+import { isEmpty } from '../validators/form-validator';
+import { getRegisteredControl } from '../registry/registry';
+
+export function shouldUseInlineLayout(
+  renderingType: 'single-line' | 'multiline' | 'automatic',
+  layoutType: LayoutType,
+  workspaceLayout: 'minimized' | 'maximized',
+  sessionMode: SessionMode,
+): boolean {
+  if (sessionMode == 'embedded-view') {
+    return true;
+  }
+  if (renderingType == 'automatic') {
+    return workspaceLayout == 'maximized' && layoutType.endsWith('desktop');
+  }
+  return renderingType == 'single-line';
+}
+
+export function evaluateConditionalAnswered(field: FormField, allFields: FormField[]) {
+  const referencedFieldId = field.validators.find(
+    (validator) => validator.type === 'conditionalAnswered',
+  ).referenceQuestionId;
+  const referencedField = allFields.find((field) => field.id == referencedFieldId);
+  if (referencedField) {
+    (referencedField.fieldDependents || (referencedField.fieldDependents = new Set())).add(field.id);
+  }
+}
+
+export function evaluateFieldReadonlyProp(
+  field: FormField,
+  sectionReadonly: string | boolean,
+  pageReadonly: string | boolean,
+  formReadonly: string | boolean,
+) {
+  if (!isEmpty(field.readonly)) {
+    return;
+  }
+  field.readonly = !isEmpty(sectionReadonly) || !isEmpty(pageReadonly) || formReadonly;
+}
+
+export function findPagesWithErrors(pages: Set<FormPage>, errorFields: FormField[]): string[] {
+  let pagesWithErrors: string[] = [];
+  let allFormPages = [...pages];
+  if (errorFields?.length) {
+    //Find pages each of the errors belong to
+    errorFields.forEach((field) => {
+      allFormPages.forEach((page) => {
+        let errorPage = page.sections.find((section) => section.questions.find((question) => question === field));
+        if (errorPage && !pagesWithErrors.includes(page.label)) {
+          pagesWithErrors.push(page.label);
+        }
+      });
+    });
+  }
+  return pagesWithErrors;
+}
+
+export function parseToLocalDateTime(dateString: string): Date {
+  const dateObj = dayjs(dateString).toDate();
+  try {
+    const localTimeTokens = dateString.split('T')[1].split(':');
+    dateObj.setHours(parseInt(localTimeTokens[0]), parseInt(localTimeTokens[1]), 0);
+  } catch (e) {
+    console.error(e);
+  }
+  return dateObj;
+}
+
+export function evalConditionalRequired(field: FormField, allFields: FormField[], formValues: Record<string, any>) {
+  if (typeof field.required !== 'object') {
+    return false;
+  }
+  const { referenceQuestionAnswers, referenceQuestionId } = field.required;
+  const referencedField = allFields.find((field) => field.id == referenceQuestionId);
+  if (referencedField) {
+    (referencedField.fieldDependents || (referencedField.fieldDependents = new Set())).add(field.id);
+    return referenceQuestionAnswers?.includes(formValues[referenceQuestionId]);
+  }
+  return false;
+}
+
+export function evaluateDisabled(
+  node,
+  allFields: FormField[],
+  allValues: Record<string, any>,
+  sessionMode: SessionMode,
+  patient: fhir.Patient,
+  expressionRunnerFn,
+) {
+  const { value } = node;
+  const isDisabled = expressionRunnerFn(value['disabled']?.disableWhenExpression, node, allFields, allValues, {
+    mode: sessionMode,
+    patient,
+  });
+  return isDisabled;
+}
+
+export function evaluateHide(
+  node,
+  allFields: FormField[],
+  allValues: Record<string, any>,
+  sessionMode: SessionMode,
+  patient: fhir.Patient,
+  expressionRunnerFn,
+) {
+  const { value, type } = node;
+  const isHidden = expressionRunnerFn(value['hide']?.hideWhenExpression, node, allFields, allValues, {
+    mode: sessionMode,
+    patient,
+  });
+  node.value.isHidden = isHidden;
+  if (type == 'field' && node.value?.questions?.length) {
+    node.value?.questions.forEach((question) => {
+      question.isParentHidden = isHidden;
+    });
+  }
+  // cascade visibility
+  if (type == 'page') {
+    value['sections'].forEach((section) => {
+      section.isParentHidden = isHidden;
+      cascadeVisibilityToChildFields(isHidden, section, allFields);
+    });
+  }
+  if (type == 'section') {
+    cascadeVisibilityToChildFields(isHidden, value, allFields);
+  }
+}
+
+function cascadeVisibilityToChildFields(visibility: boolean, section: FormSection, allFields: Array<FormField>) {
+  const candidateIds = section.questions.map((q) => q.id);
+  allFields
+    .filter((field) => candidateIds.includes(field.id))
+    .forEach((field) => {
+      field.isParentHidden = visibility;
+      if (field.questionOptions.rendering == 'group') {
+        field.questions.forEach((member) => {
+          member.isParentHidden = visibility;
+        });
+      }
+    });
+}
+
+/**
+ * Given a reference to a concept (either the uuid, or the source and reference term, ie "CIEL:1234") and a set of concepts, return matching concept, if any
+ *
+ * @param reference a uuid or source/term mapping, ie "3cd6f86c-26fe-102b-80cb-0017a47871b2" or "CIEL:1234"
+ * @param concepts
+ */
+export function findConceptByReference(reference: string, concepts) {
+  if (reference?.includes(':')) {
+    // handle mapping
+    const [source, code] = reference.split(':');
+
+    return concepts?.find((concept) => {
+      return concept?.conceptMappings?.find((mapping) => {
+        return (
+          mapping?.conceptReferenceTerm?.conceptSource?.name.toUpperCase() === source.toUpperCase() &&
+          mapping?.conceptReferenceTerm?.code.toUpperCase() === code.toUpperCase()
+        );
+      });
+    });
+  } else {
+    // handle uuid
+    return concepts?.find((concept) => {
+      return concept.uuid === reference;
+    });
+  }
+}
+
+/**
+ * Retrieves the appropriate field control for a question, considering missing concepts.
+ * If the question is of type 'obs' and has a missing concept, it falls back to a disabled text input.
+ * Otherwise, it retrieves the registered control based on the rendering specified in the question.
+ * @param question - The FormField representing the question.
+ * @returns The field control to be used for rendering the question.
+ */
+export function getFieldControlWithFallback(question: FormField) {
+  // Check if the question has a missing concept
+  if (hasMissingConcept(question)) {
+    // If so, render a disabled text input
+    question.disabled = true;
+    question.isDisabled = true;
+    return getRegisteredControl('text');
+  }
+
+  // Retrieve the registered control based on the specified rendering
+  return getRegisteredControl(question.questionOptions.rendering);
+}
+
+export function hasMissingConcept(question: FormField) {
+  return (
+    question.type == 'obs' && !question.questionOptions.concept && question.questionOptions.rendering !== 'fixed-value'
+  );
+}
+
+export function scrollIntoView(viewId: string, shouldFocus: boolean = false) {
+  const currentElement = document.getElementById(viewId);
+  currentElement?.scrollIntoView({
+    behavior: 'smooth',
+    block: 'center',
+    inline: 'center',
+  });
+
+  if (shouldFocus) {
+    currentElement?.focus();
+  }
+}

package/src/utils/form-page-utils.ts

@@ -0,0 +1,13 @@
+import { type FormExpanded, type FormSection } from '../types';
+import { isTrue } from './boolean-utils';
+
+export function isSectionExpanded(section: FormSection, isFormExpanded: FormExpanded): FormExpanded {
+  if (isFormExpanded !== undefined) {
+    return isFormExpanded;
+  }
+
+  if (section?.isExpanded !== undefined && section?.isExpanded !== null) {
+    return isTrue(section.isExpanded);
+  }
+  return true;
+}