@olaboot/esm-form-engine-lib 4.1.0

package/src/utils/common-utils.ts

@@ -0,0 +1,108 @@
+import dayjs from 'dayjs';
+import { type FormSchema, type FormField, type OpenmrsObs, type RenderType } from '../types';
+import { isEmpty } from '../validators/form-validator';
+import { formatDate, type FormatDateOptions } from '@openmrs/esm-framework';
+
+export function flattenObsList(obsList: OpenmrsObs[]): OpenmrsObs[] {
+  const flattenedList: OpenmrsObs[] = [];
+
+  function flatten(obs: OpenmrsObs): void {
+    flattenedList.push(obs);
+    if (obs.groupMembers?.length) {
+      obs.groupMembers.forEach((groupMember) => {
+        flatten(groupMember);
+      });
+    }
+  }
+  obsList.forEach((obs) => {
+    flatten(obs);
+  });
+
+  return flattenedList;
+}
+
+export function hasRendering(field: FormField, rendering: RenderType) {
+  return field.questionOptions.rendering === rendering;
+}
+
+export function clearSubmission(field: FormField) {
+  if (!field.meta?.submission) {
+    field.meta = { ...(field.meta || {}), submission: {} };
+  }
+  field.meta.submission = {
+    ...field.meta.submission,
+    voidedValue: null,
+    newValue: null,
+  };
+}
+
+export function gracefullySetSubmission(field: FormField, newValue: any, voidedValue: any) {
+  if (!field.meta?.submission) {
+    field.meta = { ...(field.meta || {}), submission: {} };
+  }
+  if (!isEmpty(newValue)) {
+    field.meta.submission.newValue = newValue;
+  }
+  if (!isEmpty(voidedValue)) {
+    field.meta.submission.voidedValue = voidedValue;
+  }
+  return field.meta.submission.newValue;
+}
+
+export function hasSubmission(field: FormField) {
+  return !!field.meta.submission?.newValue || !!field.meta.submission?.voidedValue;
+}
+
+export function isViewMode(sessionMode: string) {
+  return sessionMode === 'view' || sessionMode === 'embedded-view';
+}
+
+export function parseToLocalDateTime(dateString: string): Date {
+  const dateObj = dayjs(dateString).toDate();
+  if (isNaN(dateObj.getTime())) {
+    return new Date(NaN);
+  }
+
+  try {
+    const timePart = dateString.split('T')[1];
+    if (timePart) {
+      const localTimeTokens = timePart.split(':');
+      dateObj.setHours(parseInt(localTimeTokens[0]), parseInt(localTimeTokens[1]), 0);
+    }
+  } catch (e) {
+    console.error(e);
+  }
+  return dateObj;
+}
+
+export function formatDateAsDisplayString(field: FormField, date: Date) {
+  const options: Partial<FormatDateOptions> = { noToday: true };
+  if (field.datePickerFormat === 'calendar') {
+    options.time = false;
+  } else {
+    options.time = true;
+  }
+  return formatDate(date, options);
+}
+
+/**
+ * Creates a new copy of `formJson` with updated references at the page and section levels.
+ * This ensures React re-renders properly by providing new references for nested arrays.
+ */
+export function updateFormSectionReferences(formJson: FormSchema) {
+  formJson.pages = formJson.pages.map((page) => {
+    page.sections = Array.from(page.sections);
+    return page;
+  });
+  return { ...formJson };
+}
+
+/**
+ * Converts a px value to a rem value
+ * @param px - The px value to convert
+ * @param fontSize - The font size to use for the conversion
+ * @returns The rem value
+ */
+export function pxToRem(px: number, fontSize: number = 16) {
+  return px / fontSize;
+}

package/src/utils/error-utils.ts

@@ -0,0 +1,37 @@
+import { showSnackbar } from '@openmrs/esm-framework';
+
+export function reportError(error: Error, title: string): void {
+  if (error) {
+    const errorMessage = extractErrorMessagesFromResponse(error).join(', ');
+    console.error(error);
+    showSnackbar({
+      subtitle: errorMessage,
+      title: title,
+      kind: 'error',
+      isLowContrast: false,
+    });
+  }
+}
+
+/**
+ * Extracts error messages from a given error response object.
+ * If fieldErrors are present, it extracts the error messages from each field.
+ * Otherwise, it returns the top-level error message.
+ *
+ * @param {object} errorObject - The error response object.
+ * @returns {string[]} An array of error messages.
+ */
+export function extractErrorMessagesFromResponse(errorObject) {
+  const fieldErrors = errorObject?.responseBody?.error?.fieldErrors;
+  const globalErrors = errorObject?.responseBody?.error?.globalErrors;
+
+  if ((!fieldErrors || Object.keys(fieldErrors).length === 0) && !globalErrors) {
+    return [errorObject?.responseBody?.error?.message ?? errorObject?.message];
+  }
+
+  if (globalErrors?.length) {
+    return globalErrors.flatMap((error) => error.message);
+  } else {
+    return Object.values(fieldErrors).flatMap((errors: Array<Error>) => errors.map((error) => error.message));
+  }
+}

package/src/utils/expression-runner.ts

@@ -0,0 +1,172 @@
+import { getRegisteredExpressionHelpers } from '../registry/registry';
+import { isEmpty } from 'lodash-es';
+import { type OpenmrsEncounter, type FormField, type FormPage, type FormSection } from '../types';
+import { CommonExpressionHelpers, registerDependency, simpleHash } from './common-expression-helpers';
+import { HistoricalDataSourceService } from '../datasources/historical-data-source';
+import {
+  compile,
+  type DefaultEvaluateReturnType,
+  evaluateAsType,
+  evaluateAsTypeAsync,
+  extractVariableNames,
+  type VariablesMap,
+  type Visit,
+} from '@openmrs/esm-framework';
+
+export interface FormNode {
+  value: FormPage | FormSection | FormField;
+  type: 'field' | 'page' | 'section';
+}
+
+export interface ExpressionContext {
+  mode: 'enter' | 'edit' | 'view' | 'embedded-view';
+  myValue?: any;
+  patient: any;
+  previousEncounter?: OpenmrsEncounter;
+  visit?: Visit;
+}
+
+export type EvaluateReturnType = DefaultEvaluateReturnType | Record<string, any>;
+
+export const astCache = new Map();
+
+function typePredicate(result: unknown): result is EvaluateReturnType {
+  return (
+    typeof result === 'string' ||
+    typeof result === 'number' ||
+    typeof result === 'boolean' ||
+    typeof result === 'undefined' ||
+    typeof result === 'object' || // Support for arbitrary objects
+    result === null ||
+    result === undefined
+  );
+}
+
+export function evaluateExpression(
+  expression: string,
+  node: FormNode,
+  fields: Array<FormField>,
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): any {
+  if (!expression?.trim()) {
+    return null;
+  }
+  const compiledExpression = getExpressionAst(expression);
+  // track dependencies
+  trackFieldDependencies(compiledExpression, node, fields);
+  try {
+    return evaluateAsType(compiledExpression, getEvaluationContext(node, fields, fieldValues, context), typePredicate);
+  } catch (error) {
+    console.error(`Error: ${error} \n\n failing expression: ${expression}`);
+  }
+  return null;
+}
+
+export async function evaluateAsyncExpression(
+  expression: string,
+  node: FormNode,
+  fields: Array<FormField>,
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): Promise<any> {
+  if (!expression?.trim()) {
+    return null;
+  }
+
+  const compiledExpression = getExpressionAst(expression);
+  // track dependencies
+  trackFieldDependencies(compiledExpression, node, fields);
+  try {
+    return evaluateAsTypeAsync(
+      compiledExpression,
+      getEvaluationContext(node, fields, fieldValues, context),
+      typePredicate,
+    );
+  } catch (error) {
+    console.error(`Error: ${error} \n\n failing expression: ${expression}`);
+  }
+  return null;
+}
+
+function getEvaluationContext(
+  node: FormNode,
+  formFields: FormField[],
+  fieldValues: Record<string, any>,
+  context: ExpressionContext,
+): VariablesMap {
+  let { myValue, patient } = context;
+  const { sex, age } = patient ?? {};
+
+  if (node.type === 'field' && myValue === undefined && node.value) {
+    myValue = fieldValues[node.value['id']];
+  }
+
+  const HD = new HistoricalDataSourceService();
+  HD.putObject('prevEnc', {
+    value: context.previousEncounter || { obs: [] },
+    getValue(concept) {
+      return this.value.obs.find((obs) => obs.concept.uuid == concept);
+    },
+  });
+
+  const visit: Visit = context?.visit ?? ({} as Visit);
+  const visitType = visit?.visitType || { uuid: '' };
+  const visitTypeUuid = visitType.uuid ?? '';
+
+  const _ = {
+    isEmpty,
+  };
+
+  return {
+    ...new CommonExpressionHelpers(node, patient, formFields, fieldValues),
+    ...getRegisteredExpressionHelpers(),
+    ...context,
+    ...fieldValues,
+    patient,
+    myValue,
+    sex,
+    age,
+    HD,
+    visit,
+    visitType,
+    visitTypeUuid,
+    _,
+  };
+}
+
+/**
+ * Compiles an expression into an abstract syntax tree (AST) and caches the result.
+ * @param expression - The expression to compile.
+ * @returns The abstract syntax tree (AST) of the compiled expression.
+ */
+function getExpressionAst(expression: string): ReturnType<typeof compile> {
+  const hash = simpleHash(expression);
+  if (astCache.has(hash)) {
+    return astCache.get(hash);
+  }
+  const ast = compile(expression);
+  astCache.set(hash, ast);
+  return ast;
+}
+
+/**
+ * Extracts all referenced fields in the expression and registers them as dependencies.
+ * @param expression - The expression to track dependencies for.
+ * @param fieldNode - The node representing the field.
+ * @param allFields - The list of all fields in the form.
+ */
+export function trackFieldDependencies(
+  expression: ReturnType<typeof compile>,
+  fieldNode: FormNode,
+  allFields: FormField[],
+) {
+  const variables = extractVariableNames(expression);
+
+  for (const variable of variables) {
+    const field = allFields.find((field) => field.id === variable);
+    if (field) {
+      registerDependency(fieldNode, field);
+    }
+  }
+}

package/src/utils/form-helper.ts

@@ -0,0 +1,283 @@
+import { type LayoutType } from '@openmrs/esm-framework';
+import type { FormField, FormPage, FormSection, SessionMode, FHIRObsResource, RenderType, FormSchema } from '../types';
+import { isEmpty } from '../validators/form-validator';
+import { parseToLocalDateTime } from './common-utils';
+import dayjs from 'dayjs';
+import { ConceptFalse, ConceptTrue } from '../constants';
+
+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 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,
+  updateFormFieldFn: (field: FormField) => void | null,
+) {
+  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, updateFormFieldFn);
+    });
+  }
+  if (type == 'section') {
+    cascadeVisibilityToChildFields(isHidden, value, allFields, updateFormFieldFn);
+  }
+}
+
+function cascadeVisibilityToChildFields(
+  visibility: boolean,
+  section: FormSection,
+  allFields: Array<FormField>,
+  updateFormFieldFn: (field: FormField) => void,
+) {
+  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;
+        });
+      }
+      updateFormFieldFn?.(field);
+    });
+}
+
+/**
+ * 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;
+    });
+  }
+}
+
+export function scrollIntoView(viewId: string, shouldFocus: boolean = false) {
+  const currentElement = document.getElementById(viewId);
+  currentElement?.scrollIntoView({
+    behavior: 'smooth',
+    block: 'start',
+    inline: 'center',
+  });
+
+  if (shouldFocus) {
+    currentElement?.focus();
+  }
+}
+
+export const extractObsValueAndDisplay = (field: FormField, obs: any) => {
+  const rendering = field.questionOptions.rendering;
+  if (typeof obs !== 'object') {
+    return { value: obs, display: obs };
+  }
+  const omrsObs = obs.resourceType === 'Observation' ? mapFHIRObsToOpenMRS(obs, rendering) : obs;
+  if (!omrsObs) {
+    return { value: null, display: null };
+  }
+  if (typeof omrsObs.value === 'string' || typeof omrsObs.value === 'number') {
+    if (rendering === 'date' || rendering === 'datetime') {
+      const dateObj = parseToLocalDateTime(`${omrsObs.value}`);
+      return { value: dateObj, display: dayjs(dateObj).format('YYYY-MM-DD HH:mm') };
+    }
+    return { value: omrsObs.value, display: omrsObs.value };
+  } else if (['toggle', 'checkbox'].includes(rendering)) {
+    return {
+      value: omrsObs.value?.uuid,
+      display: omrsObs.value?.name?.name,
+    };
+  } else {
+    return {
+      value: omrsObs.value?.uuid,
+      display: field.questionOptions.answers?.find((option) => option.concept === omrsObs.value?.uuid)?.label,
+    };
+  }
+};
+
+/**
+ * Checks if a given form page has visible content.
+ *
+ * A page is considered to have visible content if:
+ * - The page itself is not hidden.
+ * - At least one section within the page is visible.
+ * - At least one question within each section is visible.
+ */
+export function isPageContentVisible(page: FormPage) {
+  if (page.isHidden) {
+    return false;
+  }
+  return (
+    page.sections?.some((section) => {
+      return !section.isHidden && section.questions?.some((question) => !question.isHidden);
+    }) ?? false
+  );
+}
+
+function mapFHIRObsToOpenMRS(fhirObs: FHIRObsResource, rendering: RenderType) {
+  try {
+    return {
+      obsDatetime: fhirObs.effectiveDateTime,
+      uuid: fhirObs.id,
+      concept: {
+        uuid: fhirObs.code.coding[0]?.code,
+        display: fhirObs.code.coding[0]?.display,
+      },
+      value: extractFHIRObsValue(fhirObs, rendering),
+    };
+  } catch (error) {
+    console.error('Error converting FHIR Obs to OpenMRS modelling', error);
+    return null;
+  }
+}
+
+function extractFHIRObsValue(fhirObs: FHIRObsResource, rendering: RenderType) {
+  switch (rendering) {
+    case 'toggle':
+      return fhirObs.valueBoolean ? { uuid: ConceptTrue } : { uuid: ConceptFalse };
+
+    case 'date':
+    case 'datetime':
+      return fhirObs.valueDateTime;
+
+    case 'number':
+      return fhirObs.valueQuantity?.value ?? null;
+
+    case 'radio':
+    case 'checkbox':
+    case 'select':
+    case 'content-switcher':
+      return fhirObs.valueCodeableConcept?.coding[0]
+        ? {
+            uuid: fhirObs.valueCodeableConcept?.coding[0].code,
+            name: { name: fhirObs.valueCodeableConcept?.coding[0].display },
+          }
+        : null;
+
+    default:
+      return fhirObs.valueString;
+  }
+}
+
+/**
+ * Find formField section
+ * @param formJson FormSchema
+ * @param field FormField
+ */
+export function findFieldSection(formJson: FormSchema, field: FormField) {
+  let page = formJson.pages.find((page) => field.meta.pageId === page.id);
+  return page.sections.find((section) => section.questions.find((question) => question.id === field.id));
+}

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;
+}