@olaboot/esm-form-engine-lib 4.1.0

package/src/adapters/person-attribute-adapter.ts

@@ -0,0 +1,45 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+import { type FormContextProps } from '../provider/form-provider';
+import { type FormField, type FormFieldValueAdapter, type FormProcessorContextProps } from '../types';
+import { clearSubmission } from '../utils/common-utils';
+import { isEmpty } from '../validators/form-validator';
+
+export const PersonAttributeAdapter: FormFieldValueAdapter = {
+  transformFieldValue: function (field: FormField, value: any, context: FormContextProps) {
+    clearSubmission(field);
+    if (field.meta.initialValue?.refinedValue === value || isEmpty(value)) {
+      return null;
+    }
+    field.meta.submission.newValue = {
+      value: value,
+      attributeType: field.questionOptions.attributeType,
+      uuid: (field.meta.initialValue?.omrsObject as OpenmrsResource)?.uuid,
+    };
+    return field.meta.submission.newValue;
+  },
+  getInitialValue: function (field: FormField, sourceObject: OpenmrsResource, context: FormProcessorContextProps) {
+    const latestAttribute = context.patient?.extension?.find(
+      (ext) => ext.url === `http://fhir.openmrs.org/ext/person-attribute/${field.questionOptions.attributeType}`,
+    );
+    field.meta = {
+      ...field.meta,
+      initialValue: {
+        omrsObject: latestAttribute as unknown as OpenmrsResource,
+        refinedValue: latestAttribute?.valueString || latestAttribute?.valueReference?.reference,
+      },
+    };
+    return field.meta.initialValue.refinedValue;
+  },
+  getPreviousValue: function (field: FormField, sourceObject: OpenmrsResource, context: FormProcessorContextProps) {
+    return null;
+  },
+  getDisplayValue: function (field: FormField, value: any) {
+    if (value?.display) {
+      return value.display;
+    }
+    return value;
+  },
+  tearDown: function (): void {
+    return;
+  },
+};

package/src/adapters/program-state-adapter.ts

@@ -0,0 +1,57 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+import { type FormContextProps } from '../provider/form-provider';
+import { type FormField, type FormProcessorContextProps, type FormFieldValueAdapter } from '../types';
+import dayjs from 'dayjs';
+import { clearSubmission } from '../utils/common-utils';
+import { isEmpty } from '../validators/form-validator';
+
+export const ProgramStateAdapter: FormFieldValueAdapter = {
+  transformFieldValue: function (field: FormField, value: any, context: FormContextProps) {
+    clearSubmission(field);
+    if ((field.meta?.initialValue?.omrsObject as OpenmrsResource)?.uuid === value || isEmpty(value)) {
+      return null;
+    }
+    field.meta.submission.newValue = {
+      state: value,
+      startDate: dayjs().format(),
+    };
+  },
+  getInitialValue: function (
+    field: FormField,
+    sourceObject: OpenmrsResource,
+    context: FormProcessorContextProps,
+  ): Promise<any> {
+    const program = context.customDependencies.patientPrograms?.find(
+      (program) => program.program.uuid === field.questionOptions.programUuid,
+    );
+    if (program?.states?.length > 0) {
+      const currentState = program.states
+        .filter((state) => !state.endDate)
+        .find((state) => state.state.programWorkflow?.uuid === field.questionOptions.workflowUuid)?.state;
+      field.meta = {
+        ...(field.meta || {}),
+        initialValue: {
+          omrsObject: currentState,
+        },
+      };
+      return currentState?.uuid;
+    }
+    return null;
+  },
+  getPreviousValue: function (
+    field: FormField,
+    sourceObject: OpenmrsResource,
+    context: FormProcessorContextProps,
+  ): Promise<any> {
+    return null;
+  },
+  getDisplayValue: function (field: FormField, value: any) {
+    if (value?.display) {
+      return value.display;
+    }
+    return value;
+  },
+  tearDown: function (): void {
+    return;
+  },
+};

package/src/api/index.ts

@@ -0,0 +1,224 @@
+import type { TFunction } from 'i18next';
+import { attachmentUrl, fhirBaseUrl, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { encounterRepresentation } from '../constants';
+import type {
+  AttachmentFieldValue,
+  FHIRObsResource,
+  OpenmrsForm,
+  PatientDeathPayload,
+  PatientIdentifier,
+  PatientProgramPayload,
+  PersonAttribute,
+} from '../types';
+import { isUuid } from '../utils/boolean-utils';
+
+export function saveEncounter(abortController: AbortController, payload, encounterUuid?: string) {
+  const url = encounterUuid
+    ? `${restBaseUrl}/encounter/${encounterUuid}?v=${encounterRepresentation}`
+    : `${restBaseUrl}/encounter?v=${encounterRepresentation}`;
+
+  return openmrsFetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+    body: payload,
+    signal: abortController.signal,
+  });
+}
+
+export async function createAttachment(patientUuid: string, encounterUUID: string, attachment: AttachmentFieldValue) {
+  const formData = new FormData();
+
+  formData.append('fileCaption', attachment.fileDescription);
+  formData.append('patient', patientUuid);
+
+  if (attachment.file) {
+    formData.append('file', attachment.file, attachment.fileName);
+  } else {
+    formData.append('file', new File([''], attachment.fileName), attachment.fileName);
+    formData.append('base64Content', attachment.base64Content);
+  }
+  formData.append('encounter', encounterUUID);
+  formData.append('formFieldNamespace', attachment.formFieldNamespace);
+  formData.append('formFieldPath', attachment.formFieldPath);
+
+  return openmrsFetch(`${attachmentUrl}`, {
+    method: 'POST',
+    body: formData,
+  });
+}
+
+export function getConcept(conceptUuid: string, v: string) {
+  return openmrsFetch(`${restBaseUrl}/concept/${conceptUuid}?v=${v}`).then(({ data }) => data.results);
+}
+
+export function getLocationsByTag(tag: string) {
+  return openmrsFetch(`${restBaseUrl}/location?tag=${tag}&v=custom:(uuid,display)`).then(({ data }) => data.results);
+}
+
+export function getAllLocations() {
+  return openmrsFetch<{ results }>(`${restBaseUrl}/location?v=custom:(uuid,display)`).then(({ data }) => data.results);
+}
+
+export async function getPreviousEncounter(patientUuid: string, encounterType: string) {
+  const query = `patient=${patientUuid}&_sort=-date&_count=1&type=${encounterType}`;
+  let response = await openmrsFetch(`${fhirBaseUrl}/Encounter?${query}`);
+  if (response?.data?.entry?.length) {
+    const latestEncounter = response.data.entry[0].resource.id;
+    response = await openmrsFetch(`${restBaseUrl}/encounter/${latestEncounter}?v=${encounterRepresentation}`);
+    return response.data;
+  }
+  return null;
+}
+
+export async function getLatestObs(
+  patientUuid: string,
+  conceptUuid: string,
+  encounterTypeUuid?: string,
+): Promise<FHIRObsResource> {
+  let params = `patient=${patientUuid}&code=${conceptUuid}${
+    encounterTypeUuid ? `&encounter.type=${encounterTypeUuid}` : ''
+  }`;
+  // the latest obs
+  params += '&_sort=-date&_count=1';
+  const { data } = await openmrsFetch(`${fhirBaseUrl}/Observation?${params}`);
+  return data.entry?.length ? data.entry[0].resource : null;
+}
+
+/**
+ * Fetches an OpenMRS form using either its name or UUID.
+ * @param {string} nameOrUUID - The form's name or UUID.
+ * @returns {Promise<OpenmrsForm | null>} - A Promise that resolves to the fetched OpenMRS form or null if not found.
+ */
+export async function fetchOpenMRSForm(nameOrUUID: string): Promise<OpenmrsForm | null> {
+  if (!nameOrUUID) {
+    return null;
+  }
+
+  const { url, isUUID } = isUuid(nameOrUUID)
+    ? { url: `${restBaseUrl}/form/${nameOrUUID}?v=full`, isUUID: true }
+    : { url: `${restBaseUrl}/form?q=${nameOrUUID}&v=full`, isUUID: false };
+
+  const { data: openmrsFormResponse } = await openmrsFetch(url);
+  if (isUUID) {
+    return openmrsFormResponse;
+  }
+
+  if (openmrsFormResponse.results?.length) {
+    const form = openmrsFormResponse.results.find((form) => form.retired === false);
+    if (form) {
+      return form;
+    }
+  }
+  throw new Error(`Form with ID "${nameOrUUID}" was not found`);
+}
+
+/**
+ * Fetches ClobData for a given OpenMRS form.
+ * @param {OpenmrsForm} form - The OpenMRS form object.
+ * @returns {Promise<any | null>} - A Promise that resolves to the fetched ClobData or null if not found.
+ */
+export async function fetchClobData(form: OpenmrsForm): Promise<any | null> {
+  if (!form) {
+    return null;
+  }
+
+  const jsonSchemaResource = form.resources?.find(({ name }) => name === 'JSON schema');
+  if (!jsonSchemaResource) {
+    return null;
+  }
+
+  const clobDataUrl = `${restBaseUrl}/clobdata/${jsonSchemaResource.valueReference}`;
+  const { data: clobDataResponse } = await openmrsFetch(clobDataUrl);
+
+  return clobDataResponse;
+}
+
+// Program Enrollment
+export function getPatientEnrolledPrograms(patientUuid: string) {
+  return openmrsFetch(
+    `${restBaseUrl}/programenrollment?patient=${patientUuid}&v=custom:(uuid,display,program:(uuid,name,allWorkflows),dateEnrolled,dateCompleted,location:(uuid,display),states:(state:(uuid,name,concept:(uuid),programWorkflow:(uuid)))`,
+  ).then(({ data }) => {
+    if (data) {
+      return data;
+    }
+    return null;
+  });
+}
+
+export function saveProgramEnrollment(payload: PatientProgramPayload, abortController: AbortController) {
+  if (!payload) {
+    throw new Error('Program enrollment cannot be created because no payload is supplied');
+  }
+  const url = payload.uuid ? `${restBaseUrl}/programenrollment/${payload.uuid}` : `${restBaseUrl}/programenrollment`;
+  return openmrsFetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: payload,
+    signal: abortController.signal,
+  });
+}
+
+export function savePatientIdentifier(patientIdentifier: PatientIdentifier, patientUuid: string) {
+  let url: string;
+
+  if (patientIdentifier.uuid) {
+    url = `${restBaseUrl}/patient/${patientUuid}/identifier/${patientIdentifier.uuid}`;
+  } else {
+    url = `${restBaseUrl}/patient/${patientUuid}/identifier`;
+  }
+
+  return openmrsFetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+    body: JSON.stringify(patientIdentifier),
+  });
+}
+
+export function savePersonAttribute(personAttribute: PersonAttribute, patientUuid: string) {
+  let url: string;
+
+  if (personAttribute.uuid) {
+    url = `${restBaseUrl}/person/${patientUuid}/attribute/${personAttribute.uuid}`;
+  } else {
+    url = `${restBaseUrl}/person/${patientUuid}/attribute`;
+  }
+
+  return openmrsFetch(url, {
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    method: 'POST',
+    body: personAttribute,
+  });
+}
+
+export function markPatientAsDeceased(
+  t: TFunction,
+  patientUUID: string,
+  payload: PatientDeathPayload,
+  abortController: AbortController,
+) {
+  if (!payload) {
+    throw new Error(
+      t(
+        'patientCannotBeMarkedAsDeceasedBecauseNoPayloadSupplied',
+        'Patient cannot be marked as deceased because no payload is supplied',
+      ),
+    );
+  }
+  const url = `${restBaseUrl}/person/${patientUUID}`;
+  return openmrsFetch(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: payload,
+    signal: abortController.signal,
+  });
+}

package/src/components/error/error-modal.component.tsx

@@ -0,0 +1,37 @@
+import React, { useMemo } from 'react';
+import { InlineNotification } from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+import { fieldRequiredErrCode, fieldOutOfBoundErrCode } from '../../validators/form-validator';
+import type { ValidationResult } from '../../types';
+import styles from './error.scss';
+
+const ErrorModal: React.FC<{ errors: ValidationResult[] }> = ({ errors }) => {
+  const { t } = useTranslation();
+
+  const errorMessage = useMemo(() => {
+    const errorMessages: { [key: string]: string } = {};
+
+    errors.forEach((error) => {
+      if (error?.errCode === fieldRequiredErrCode && !errorMessages[fieldRequiredErrCode]) {
+        errorMessages[fieldRequiredErrCode] = t('nullMandatoryField', 'Please fill the required fields');
+      } else if (error?.errCode === fieldOutOfBoundErrCode && !errorMessages[fieldOutOfBoundErrCode]) {
+        errorMessages[fieldOutOfBoundErrCode] = t('valuesOutOfBound', 'Some of the values are out of bounds');
+      }
+    });
+
+    return Object.values(errorMessages).join(', ');
+  }, [errors, t]);
+
+  return (
+    <InlineNotification
+      role="alert"
+      className={styles.inlineErrorMessage}
+      kind="error"
+      lowContrast={true}
+      title={t('fieldErrorDescriptionTitle', 'Validation Errors')}
+      subtitle={errorMessage}
+    />
+  );
+};
+
+export default ErrorModal;

package/src/components/error/error.scss

@@ -0,0 +1,4 @@
+
+.inlineErrorMessage {
+    margin: 0.75rem;
+}

package/src/components/extension/extension-parcel.component.tsx

@@ -0,0 +1,32 @@
+import React, { useEffect, useMemo } from 'react';
+import { BehaviorSubject } from 'rxjs';
+import { attach, ExtensionSlot } from '@openmrs/esm-framework';
+import { type FormFieldInputProps } from '../../types';
+import { useFormProviderContext } from '../../provider/form-provider';
+
+const ExtensionParcel: React.FC<FormFieldInputProps> = ({ field }) => {
+  const submissionNotifier = useMemo(() => new BehaviorSubject<{ isSubmitting: boolean }>({ isSubmitting: false }), []);
+  const { isSubmitting, patient } = useFormProviderContext();
+
+  const state = useMemo(() => ({ patientUuid: patient.id, submissionNotifier }), [patient.id, submissionNotifier]);
+
+  useEffect(() => {
+    if (field.questionOptions.extensionSlotName && field.questionOptions.extensionId) {
+      attach(field.questionOptions.extensionSlotName, field.questionOptions.extensionId);
+    }
+  }, []);
+
+  useEffect(() => {
+    submissionNotifier.next({ isSubmitting: isSubmitting });
+  }, [isSubmitting, submissionNotifier]);
+
+  return (
+    <>
+      {field.questionOptions.extensionSlotName && (
+        <ExtensionSlot name={field.questionOptions.extensionSlotName} state={state} />
+      )}
+    </>
+  );
+};
+
+export default ExtensionParcel;

package/src/components/field-label/field-label.component.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { Tooltip } from '@carbon/react';
+import { Information } from '@carbon/react/icons';
+import { useTranslation } from 'react-i18next';
+import { type FormField } from '../../types';
+import styles from './field-label.scss';
+
+interface FieldLabelProps {
+  field: FormField;
+  /**
+   * Custom label text to override the default field label.
+   */
+  customLabel?: string;
+}
+
+const TooltipWrapper: React.FC<{ field: FormField; children: React.ReactNode }> = ({ field, children }) => {
+  const { t } = useTranslation();
+  const hasTooltip = Boolean(field.questionInfo);
+
+  return hasTooltip ? (
+    <Tooltip autoAlign label={t(field.questionInfo)}>
+      <div>{children}</div>
+    </Tooltip>
+  ) : (
+    <>{children}</>
+  );
+};
+
+const FieldLabel: React.FC<FieldLabelProps> = ({ field, customLabel }) => {
+  const { t } = useTranslation();
+  const hasTooltip = Boolean(field.questionInfo);
+  const labelText = customLabel || t(field.label);
+  return (
+    <TooltipWrapper field={field}>
+      <div className={styles.questionLabel} data-testid={`${field.id}-label`}>
+        <span>{labelText}</span>
+        {field.isRequired && (
+          <span title={t('required', 'Required')} className={styles.required}>
+            *
+          </span>
+        )}
+        {hasTooltip && (
+          <Information
+            size={16}
+            aria-hidden="true"
+            className={styles.tooltipIcon}
+            data-testid={`${field.id}-information-icon`}
+          />
+        )}
+      </div>
+    </TooltipWrapper>
+  );
+};
+
+export default FieldLabel;

package/src/components/field-label/field-label.scss

@@ -0,0 +1,15 @@
+@use '@carbon/colors';
+
+.required {
+  color: colors.$red-60;
+  margin-left: 0.25rem;
+}
+
+.questionLabel {
+  display: flex;
+  align-items: center;
+}
+
+.tooltipIcon {
+  margin-left: 0.25rem;
+}

package/src/components/group/obs-group.component.tsx

@@ -0,0 +1,59 @@
+import React, { useMemo } from 'react';
+import classNames from 'classnames';
+import { type FormFieldInputProps } from '../../types';
+import styles from './obs-group.scss';
+import { ErrorFallback, FormFieldRenderer, isGroupField } from '../renderer/field/form-field-renderer.component';
+import { useFormProviderContext } from '../../provider/form-provider';
+import { FormGroup } from '@carbon/react';
+import { useTranslation } from 'react-i18next';
+
+export const ObsGroup: React.FC<FormFieldInputProps> = ({ field, ...restProps }) => {
+  const { t } = useTranslation();
+  const { formFieldAdapters, formFields } = useFormProviderContext();
+
+  const content = useMemo(
+    () =>
+      field.questions
+        .map((child) => formFields.find((field) => field.id === child.id))
+        .filter((child) => !child.isHidden)
+        .map((child, index) => {
+          const key = `${child.id}_${index}`;
+          if (child.id === field.id) {
+            return (
+              <ErrorFallback error={new Error('ObsGroup child has same id as parent question')}/>
+            );
+          }
+
+          if (child.type === 'obsGroup' && isGroupField(child.questionOptions.rendering)) {
+            return (
+              <div key={key} className={styles.nestedGroupContainer}>
+                <ObsGroup field={child} {...restProps} />
+              </div>
+            );
+          } else if (formFieldAdapters[child.type]) {
+            return (
+              <div className={classNames(styles.flexColumn)} key={key}>
+                <div className={styles.groupContainer}>
+                  <FormFieldRenderer fieldId={child.id} valueAdapter={formFieldAdapters[child.type]} />
+                </div>
+              </div>
+            );
+          }
+        }),
+    [field, formFields],
+  );
+
+  return (
+    <div className={styles.groupContainer}>
+      {content.length > 1 ? (
+        <FormGroup legendText={t(field.label)} className={styles.boldLegend}>
+          {content}
+        </FormGroup>
+      ) : (
+        content
+      )}
+    </div>
+  );
+};
+
+export default ObsGroup;

package/src/components/group/obs-group.scss

@@ -0,0 +1,16 @@
+.flexColumn {
+  display: flex;
+  flex-direction: column;
+}
+
+.flexFullWidth {
+  flex-basis: 100%;
+}
+
+.groupContainer {
+  margin: 0.5rem 0;
+}
+
+.boldLegend > legend {
+  font-weight: bolder;
+}

package/src/components/inputs/content-switcher/content-switcher.component.tsx

@@ -0,0 +1,81 @@
+import React, { useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import classNames from 'classnames';
+import { FormGroup, ContentSwitcher as CdsContentSwitcher, Switch } from '@carbon/react';
+import { shouldUseInlineLayout } from '../../../utils/form-helper';
+import { isTrue } from '../../../utils/boolean-utils';
+import { type FormFieldInputProps } from '../../../types';
+import FieldValueView from '../../value/view/field-value-view.component';
+import styles from './content-switcher.scss';
+import { useFormProviderContext } from '../../../provider/form-provider';
+import FieldLabel from '../../field-label/field-label.component';
+
+const ContentSwitcher: React.FC<FormFieldInputProps> = ({ field, value, errors, warnings, setFieldValue }) => {
+  const { t } = useTranslation();
+  const { layoutType, sessionMode, workspaceLayout, formFieldAdapters } = useFormProviderContext();
+
+  const handleChange = useCallback(
+    (value) => {
+      setFieldValue(value.name);
+    },
+    [setFieldValue],
+  );
+
+  const visibleAnswers = useMemo(
+    () => field.questionOptions.answers.filter((answer) => !answer.isHidden),
+    [field.questionOptions.answers],
+  );
+
+  const selectedIndex = useMemo(
+    () => visibleAnswers.findIndex((option) => option.concept == value),
+    [value, visibleAnswers],
+  );
+
+  const isInline = useMemo(() => {
+    if (['view', 'embedded-view'].includes(sessionMode) || isTrue(field.readonly)) {
+      return shouldUseInlineLayout(field.inlineRendering, layoutType, workspaceLayout, sessionMode);
+    }
+    return false;
+  }, [sessionMode, field.readonly, field.inlineRendering, layoutType, workspaceLayout]);
+
+  return sessionMode == 'view' || sessionMode == 'embedded-view' || isTrue(field.readonly) ? (
+    <div className={styles.formField}>
+      <FieldValueView
+        label={t(field.label)}
+        value={value ? formFieldAdapters[field.type].getDisplayValue(field, value) : value}
+        conceptName={field.meta?.concept?.display}
+        isInline={isInline}
+      />
+    </div>
+  ) : (
+    !field.isHidden && (
+      <FormGroup
+        legendText={
+          <div className={styles.boldedLegend}>
+            <FieldLabel field={field} />
+          </div>
+        }
+        className={classNames({
+          [styles.errorLegend]: errors.length > 0,
+          [styles.boldedLegend]: errors.length === 0,
+        })}>
+        <CdsContentSwitcher
+          onChange={handleChange}
+          selectedIndex={selectedIndex}
+          className={styles.selectedOption}
+          size="md">
+          {visibleAnswers.map((option, index) => (
+            <Switch
+              name={option.concept || option.value}
+              text={t(option.label)}
+              key={index}
+              disabled={field.isDisabled}
+            />
+          ))}
+        </CdsContentSwitcher>
+      </FormGroup>
+    )
+  );
+};
+
+export default ContentSwitcher;

package/src/components/inputs/content-switcher/content-switcher.scss

@@ -0,0 +1,55 @@
+@use '@carbon/colors';
+
+.formField {
+  margin-top: 0.625rem;
+}
+
+.formField > div > div > label {
+  color: colors.$gray-70;
+}
+
+.textContainer {
+  label {
+    font-size: 0.875rem !important;
+  }
+}
+
+.errorLegend legend,
+.errorLabel label {
+  color: colors.$red-60 !important;
+}
+
+.boldedLegend {
+  font-weight: 600;
+  color: black;
+}
+
+.selectedOption {
+  border-radius: 4px;
+  width: 15rem;
+
+  button {
+    background-color: colors.$gray-10;
+
+    &:before {
+      display: none !important;
+    }
+  }
+}
+
+.switchOverrides {
+  background-color: colors.$blue-10 !important;
+  border: 1px solid colors.$blue-60 !important;
+  color: colors.$blue-60 !important;
+  padding: 0 0 0 1rem;
+
+  button:focus {
+    border: none !important;
+  }
+}
+
+.sansSwitchOverrides {
+  border: solid 1px colors.$blue-30 !important;
+  background-color: colors.$gray-10 !important;
+  padding: 0 0 0 1rem;
+}