@olaboot/esm-form-engine-lib 4.1.0

package/src/form-engine.component.tsx

@@ -0,0 +1,222 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import classNames from 'classnames';
+import { Button, ButtonSet, InlineLoading } from '@carbon/react';
+import { I18nextProvider, useTranslation } from 'react-i18next';
+import { useSession, type Visit } from '@openmrs/esm-framework';
+import { FormFactoryProvider } from './provider/form-factory-provider';
+import { init, teardown } from './lifecycle';
+import { isEmpty, useFormJson } from '.';
+import { formEngineAppName } from './globals';
+import { reportError } from './utils/error-utils';
+import { useFormCollapse } from './hooks/useFormCollapse';
+import { useFormWorkspaceSize } from './hooks/useFormWorkspaceSize';
+import { usePageObserver } from './components/sidebar/usePageObserver';
+import { usePatientData } from './hooks/usePatientData';
+import type { FormField, FormSchema, SessionMode, PreFilledQuestions } from './types';
+import FormProcessorFactory from './components/processor-factory/form-processor-factory.component';
+import Loader from './components/loaders/loader.component';
+import MarkdownWrapper from './components/inputs/markdown/markdown-wrapper.component';
+import PatientBanner from './components/patient-banner/patient-banner.component';
+import Sidebar from './components/sidebar/sidebar.component';
+import styles from './form-engine.scss';
+
+interface FormEngineProps {
+  patientUUID: string;
+  formUUID?: string;
+  formJson?: FormSchema;
+  encounterUUID?: string;
+  visit?: Visit;
+  formSessionIntent?: string;
+  mode?: SessionMode;
+  onSubmit?: (data: any) => void;
+  onCancel?: () => void;
+  handleClose?: () => void;
+  handleConfirmQuestionDeletion?: (question: Readonly<FormField>) => Promise<void>;
+  markFormAsDirty?: (isDirty: boolean) => void;
+  hideControls?: boolean;
+  hidePatientBanner?: boolean;
+  preFilledQuestions?: PreFilledQuestions;
+}
+
+const FormEngine = ({
+  formJson,
+  patientUUID,
+  formUUID,
+  encounterUUID,
+  visit,
+  formSessionIntent,
+  mode,
+  onSubmit,
+  onCancel,
+  handleClose,
+  handleConfirmQuestionDeletion,
+  markFormAsDirty,
+  hideControls = false,
+  hidePatientBanner = false,
+  preFilledQuestions,
+}: FormEngineProps) => {
+  const { t } = useTranslation();
+  const session = useSession();
+  const ref = useRef(null);
+  const sessionDate = useMemo(() => {
+    return new Date();
+  }, []);
+  const workspaceSize = useFormWorkspaceSize(ref);
+  const { patient, isLoadingPatient } = usePatientData(patientUUID);
+  const [isLoadingDependencies, setIsLoadingDependencies] = useState(false);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isFormDirty, setIsFormDirty] = useState(false);
+  const sessionMode = !isEmpty(mode) ? mode : !isEmpty(encounterUUID) ? 'edit' : 'enter';
+  const { isFormExpanded, hideFormCollapseToggle } = useFormCollapse(sessionMode);
+  const { hasMultiplePages } = usePageObserver();
+
+  const {
+    formJson: refinedFormJson,
+    isLoading: isLoadingFormJson,
+    formError,
+  } = useFormJson(formUUID, formJson, encounterUUID, formSessionIntent, preFilledQuestions);
+
+  const showPatientBanner = useMemo(() => {
+    if (hidePatientBanner) {
+      return false;
+    }
+    return patient && workspaceSize === 'ultra-wide' && mode !== 'embedded-view';
+  }, [patient, mode, workspaceSize, hidePatientBanner]);
+
+  const isFormWorkspaceTooNarrow = useMemo(() => ['narrow'].includes(workspaceSize), [workspaceSize]);
+
+  const showBottomButtonSet = useMemo(() => {
+    if (mode === 'embedded-view' || isLoadingDependencies || hasMultiplePages === null) {
+      return false;
+    }
+
+    return isFormWorkspaceTooNarrow || !hasMultiplePages;
+  }, [mode, isFormWorkspaceTooNarrow, isLoadingDependencies, hasMultiplePages]);
+
+  const showSidebar = useMemo(() => {
+    if (mode === 'embedded-view' || isLoadingDependencies || hasMultiplePages === null) {
+      return false;
+    }
+
+    return !isFormWorkspaceTooNarrow && hasMultiplePages;
+  }, [isFormWorkspaceTooNarrow, isLoadingDependencies, hasMultiplePages]);
+
+  useEffect(() => {
+    reportError(formError, t('errorLoadingFormSchema', 'Error loading form schema'));
+  }, [formError]);
+
+  useEffect(() => {
+    init();
+    return () => {
+      teardown();
+    };
+  }, []);
+
+  useEffect(() => {
+    markFormAsDirty?.(isFormDirty);
+  }, [isFormDirty]);
+
+  const handleSubmit = useCallback((e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault();
+    setIsSubmitting(true);
+  }, []);
+
+  return (
+    <form ref={ref} noValidate className={classNames('cds--form', styles.form)} onSubmit={handleSubmit}>
+      {isLoadingPatient || isLoadingFormJson ? (
+        <Loader />
+      ) : (
+        <FormFactoryProvider
+          patient={patient}
+          patientUUID={patientUUID}
+          sessionMode={sessionMode}
+          sessionDate={sessionDate}
+          formJson={refinedFormJson}
+          workspaceLayout={workspaceSize === 'ultra-wide' ? 'maximized' : 'minimized'}
+          location={session?.sessionLocation}
+          provider={session?.currentProvider}
+          visit={visit}
+          handleConfirmQuestionDeletion={handleConfirmQuestionDeletion}
+          isFormExpanded={isFormExpanded}
+          formSubmissionProps={{
+            isSubmitting,
+            setIsSubmitting,
+            onSubmit,
+            onError: () => {},
+            handleClose: () => {},
+          }}
+          hideFormCollapseToggle={hideFormCollapseToggle}
+          setIsFormDirty={setIsFormDirty}>
+          <div className={styles.formContainer}>
+            {isLoadingDependencies && (
+              <div className={styles.linearActivity}>
+                <div className={styles.indeterminate}></div>
+              </div>
+            )}
+            <div className={styles.formContent}>
+              {showSidebar && (
+                <Sidebar
+                  isFormSubmitting={isSubmitting}
+                  sessionMode={mode}
+                  defaultPage={refinedFormJson.defaultPage}
+                  onCancel={onCancel}
+                  handleClose={handleClose}
+                  hideFormCollapseToggle={hideFormCollapseToggle}
+                  hideControls={hideControls}
+                />
+              )}
+              <div className={styles.formContentInner}>
+                {showPatientBanner && <PatientBanner patient={patient} hideActionsOverflow />}
+                {refinedFormJson.markdown && (
+                  <div className={styles.markdownContainer}>
+                    <MarkdownWrapper markdown={refinedFormJson.markdown} />
+                  </div>
+                )}
+                <div className={styles.formBody}>
+                  <FormProcessorFactory
+                    formJson={refinedFormJson}
+                    setIsLoadingFormDependencies={setIsLoadingDependencies}
+                  />
+                </div>
+                {showBottomButtonSet && !hideControls && (
+                  <ButtonSet className={styles.minifiedButtons}>
+                    <Button
+                      kind="secondary"
+                      onClick={() => {
+                        onCancel && onCancel();
+                        handleClose && handleClose();
+                        hideFormCollapseToggle();
+                      }}>
+                      {mode === 'view' ? t('close', 'Close') : t('cancel', 'Cancel')}
+                    </Button>
+                    <Button
+                      className={styles.saveButton}
+                      disabled={isLoadingDependencies || isSubmitting || mode === 'view'}
+                      kind="primary"
+                      type="submit">
+                      {isSubmitting ? (
+                        <InlineLoading description={t('submitting', 'Submitting') + '...'} />
+                      ) : (
+                        <span>{`${t('save', 'Save')}`}</span>
+                      )}
+                    </Button>
+                  </ButtonSet>
+                )}
+              </div>
+            </div>
+          </div>
+        </FormFactoryProvider>
+      )}
+    </form>
+  );
+};
+
+function I18FormEngine(props: FormEngineProps) {
+  return (
+    <I18nextProvider i18n={window.i18next} defaultNS={formEngineAppName}>
+      <FormEngine {...props} />
+    </I18nextProvider>
+  );
+}
+
+export default I18FormEngine;

package/src/form-engine.scss

@@ -0,0 +1,148 @@
+@use '@carbon/layout';
+
+// replaces .formEngine
+.form {
+  height: 100%;
+  overflow: hidden;
+  flex-grow: 1;
+}
+
+// replaces .container
+.formContainer {
+  display: flex;
+  height: 100%;
+  overflow-y: hidden;
+  flex-direction: column;
+}
+
+// replaces .body
+.formContent {
+  display: flex;
+  flex-direction: row;
+  height: 100%;
+}
+
+// replaces .content
+.formContentInner {
+  height: var(--desktop-workspace-window-height);
+  margin: 0;
+  flex-basis: 65%;
+  flex-grow: 1;
+  flex-shrink: 1;
+  display: flex;
+  position: relative;
+  overflow-y: hidden;
+  flex-direction: column;
+  justify-content: space-between;
+}
+
+// replaces .contentBody
+.formBody {
+  overflow-y: auto;
+  width: inherit;
+  position: relative;
+  flex-grow: 1;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-start;
+}
+
+.minifiedButtons {
+  button {
+    height: 4rem;
+    display: flex;
+    align-content: flex-start;
+    align-items: baseline;
+    min-width: 50%;
+  }
+}
+
+.markdownContainer {
+  padding: 1rem;
+}
+
+.loader {
+  @extend .formContent;
+  height: 1rem;
+}
+
+:global(.omrs-breakpoint-lt-desktop) {
+  .formContentInner {
+    height: var(--tablet-workspace-window-height);
+  }
+
+  .minifiedButtons {
+    border-top: 1px solid #ededed;
+    padding: 1.5rem 1rem;
+    background-color: white;
+  }
+}
+
+.linearActivity {
+  overflow: hidden;
+  width: 100%;
+  height: 4px;
+  background-color: var(--brand-03);
+  margin-top: 0px;
+}
+
+.determinate {
+  position: relative;
+  max-width: 100%;
+  height: 100%;
+  -webkit-transition: width 500ms ease-out 1s;
+  -moz-transition: width 500ms ease-out 1s;
+  -o-transition: width 500ms ease-out 1s;
+  transition: width 500ms ease-out 1s;
+  background-color: var(--brand-02);
+}
+
+.indeterminate {
+  position: relative;
+  width: 100%;
+  height: 100%;
+}
+
+.indeterminate:before {
+  content: '';
+  position: absolute;
+  height: 100%;
+  background-color: var(--brand-02);
+  animation: indeterminate_first 2.5s infinite ease-out;
+}
+
+.indeterminate:after {
+  content: '';
+  position: absolute;
+  height: 100%;
+  background-color: var(--brand-01);
+  animation: indeterminate_second 2.5s infinite ease-in;
+}
+
+@keyframes indeterminate_first {
+  0% {
+    left: -100%;
+    width: 100%;
+  }
+  100% {
+    left: 100%;
+    width: 10%;
+  }
+}
+
+@keyframes indeterminate_second {
+  0% {
+    left: -150%;
+    width: 100%;
+  }
+  100% {
+    left: 100%;
+    width: 10%;
+  }
+}
+
+.saveButton {
+  &:global(.cds--inline-loading) {
+    min-height: layout.$spacing-05;
+  }
+}

package/src/globals.ts

@@ -0,0 +1,2 @@
+export const moduleName = '@openmrs/esm-form-engine-lib';
+export const formEngineAppName = '@openmrs/esm-form-engine-app';

package/src/hooks/useConcepts.ts

@@ -0,0 +1,58 @@
+import { useMemo } from 'react';
+import useSWR from 'swr';
+import { type Concept, type FetchResponse, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+
+const conceptRepresentation =
+  'custom:(uuid,display,conceptClass:(uuid,display),answers:(uuid,display),conceptMappings:(conceptReferenceTerm:(conceptSource:(name),code)))';
+
+type ConceptRepresentation = Pick<Concept, 'uuid' | 'display'> & {
+  conceptClass: Pick<Concept['conceptClass'], 'uuid' | 'display'>;
+  answers: Array<{
+    uuid: string;
+    display: string;
+  }>;
+  conceptMappings: Array<{
+    conceptReferenceTerm: {
+      conceptSource: {
+        name: string;
+      };
+      code: string;
+    };
+  }>;
+};
+
+type ConceptFetchResponse = FetchResponse<{ [reference: string]: ConceptRepresentation }>;
+
+export function useConcepts(references: Array<string>): {
+  concepts: Array<ConceptRepresentation> | undefined;
+  isLoading: boolean;
+  error: Error | undefined;
+} {
+  const { data, error, isLoading } = useSWR<ConceptFetchResponse, Error>(
+    [`${restBaseUrl}/conceptreferences?v=${conceptRepresentation}`, references],
+    ([url, refs]) =>
+      openmrsFetch(url, {
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: {
+          references: refs,
+        },
+        method: 'POST',
+      }),
+    {
+      revalidateIfStale: false,
+      revalidateOnFocus: false,
+      revalidateOnReconnect: false,
+      shouldRetryOnError: false,
+    },
+  );
+
+  const concepts = useMemo(() => (data?.data ? Object.values(data.data) : undefined), [data]);
+
+  return {
+    concepts,
+    isLoading,
+    error,
+  };
+}

package/src/hooks/useDataSourceDependentValue.ts

@@ -0,0 +1,16 @@
+import { useWatch } from 'react-hook-form';
+import { type FormField } from '../types';
+import { useFormProviderContext } from '../provider/form-provider';
+
+const useDataSourceDependentValue = (field: FormField) => {
+  const dependentField = field.questionOptions['config']?.referencedField;
+  const {
+    methods: { control },
+  } = useFormProviderContext();
+
+  const dependentValue = useWatch({ control, name: dependentField, exact: true, disabled: !dependentField });
+
+  return dependentValue;
+};
+
+export default useDataSourceDependentValue;

package/src/hooks/useEncounter.ts

@@ -0,0 +1,40 @@
+import { useEffect, useState } from 'react';
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { type FormSchema, type OpenmrsEncounter } from '../types';
+import { encounterRepresentation } from '../constants';
+import { isEmpty } from '../validators/form-validator';
+import isString from 'lodash-es/isString';
+
+export function useEncounter(formJson: FormSchema) {
+  const [encounter, setEncounter] = useState<OpenmrsEncounter>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    const abortController = new AbortController();
+
+    if (!isEmpty(formJson.encounter) && isString(formJson.encounter)) {
+      openmrsFetch(`${restBaseUrl}/encounter/${formJson.encounter}?v=${encounterRepresentation}`, {
+        signal: abortController.signal,
+      })
+        .then((response) => {
+          setEncounter(response.data);
+          setIsLoading(false);
+        })
+        .catch((error) => {
+          setError(error);
+        });
+    } else if (!isEmpty(formJson.encounter)) {
+      setEncounter(formJson.encounter as OpenmrsEncounter);
+      setIsLoading(false);
+    } else {
+      setIsLoading(false);
+    }
+
+    return () => {
+      abortController.abort();
+    };
+  }, [formJson.encounter]);
+
+  return { encounter: encounter, error, isLoading };
+}

package/src/hooks/useEncounterRole.ts

@@ -0,0 +1,15 @@
+import useSWRImmutable from 'swr/immutable';
+import { type OpenmrsResource, openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+
+export function useEncounterRole() {
+  const { data, error, isLoading } = useSWRImmutable<{ data: { results: Array<OpenmrsResource> } }, Error>(
+    `${restBaseUrl}/encounterrole?v=custom:(uuid,display,name)`,
+    openmrsFetch,
+  );
+  const clinicalEncounterRole = data?.data.results.find((encounterRole) => encounterRole.name === 'Clinician');
+
+  if (clinicalEncounterRole) {
+    return { encounterRole: clinicalEncounterRole, error, isLoading };
+  }
+  return { encounterRole: data?.data.results[0], error, isLoading };
+}

package/src/hooks/useEvaluateFormFieldExpressions.ts

@@ -0,0 +1,152 @@
+import { useEffect, useMemo, useState } from 'react';
+import { type FormProcessorContextProps } from '../types';
+import { type FormNode, evaluateExpression } from '../utils/expression-runner';
+import { evalConditionalRequired, evaluateConditionalAnswered, evaluateHide } from '../utils/form-helper';
+import { isTrue } from '../utils/boolean-utils';
+import { isEmpty } from '../validators/form-validator';
+import { type QuestionAnswerOption } from '../types/schema';
+import { updateFormSectionReferences } from '../utils/common-utils';
+
+export const useEvaluateFormFieldExpressions = (
+  formValues: Record<string, any>,
+  factoryContext: FormProcessorContextProps,
+) => {
+  const { formFields, patient, sessionMode, visit } = factoryContext;
+  const [evaluatedFormJson, setEvaluatedFormJson] = useState(factoryContext.formJson);
+  const [evaluatedPagesVisibility, setEvaluatedPagesVisibility] = useState(false);
+
+  const evaluatedFields = useMemo(() => {
+    return formFields?.map((field) => {
+      const fieldNode: FormNode = { value: field, type: 'field' };
+      const runnerContext = {
+        patient,
+        mode: sessionMode,
+        visit,
+      };
+      // evaluate hide
+      if (field.hide?.hideWhenExpression) {
+        const isHidden = evaluateExpression(
+          field.hide.hideWhenExpression,
+          fieldNode,
+          formFields,
+          formValues,
+          runnerContext,
+        );
+        field.isHidden = isHidden;
+        if (Array.isArray(field.questions)) {
+          field.questions.forEach((question) => {
+            question.isHidden = isHidden;
+          });
+        }
+      } else {
+        field.isHidden = false;
+      }
+      // evaluate required
+      if (typeof field.required === 'object' && field.required.type === 'conditionalRequired') {
+        field.isRequired = evalConditionalRequired(field, formFields, formValues);
+      } else {
+        field.isRequired = isTrue(field.required as string);
+      }
+      // evaluate disabled
+      if (typeof field.disabled === 'object' && field.disabled.disableWhenExpression) {
+        field.isDisabled = evaluateExpression(
+          field.disabled.disableWhenExpression,
+          fieldNode,
+          formFields,
+          formValues,
+          runnerContext,
+        );
+      } else {
+        field.isDisabled = isTrue(field.disabled as string);
+      }
+      // evaluate conditional answered
+      if (field.validators?.some((validator) => validator.type === 'conditionalAnswered')) {
+        evaluateConditionalAnswered(field, formFields);
+      }
+      // evaluate conditional hide for answers
+      field.questionOptions.answers
+        ?.filter((answer) => !isEmpty(answer.hide?.hideWhenExpression))
+        .forEach((answer) => {
+          answer.isHidden = evaluateExpression(
+            answer.hide.hideWhenExpression,
+            fieldNode,
+            formFields,
+            formValues,
+            runnerContext,
+          );
+        });
+      // evaluate conditional disable for answers
+      field.questionOptions.answers
+        ?.filter((answer: QuestionAnswerOption) => !isEmpty(answer.disable?.disableWhenExpression))
+        .forEach((answer: QuestionAnswerOption) => {
+          answer.disable.isDisabled = evaluateExpression(
+            answer.disable?.disableWhenExpression,
+            fieldNode,
+            formFields,
+            formValues,
+            runnerContext,
+          );
+        });
+      // evaluate readonly
+      if (typeof field.readonly == 'string' && isNotBooleanString(field.readonly)) {
+        field.meta.readonlyExpression = field.readonly;
+        field.readonly = evaluateExpression(field.readonly, fieldNode, formFields, formValues, runnerContext);
+      }
+      // evaluate repeat limit
+      const limitExpression = field.questionOptions.repeatOptions?.limitExpression;
+      if (field.questionOptions.rendering === 'repeating' && !isEmpty(limitExpression)) {
+        field.questionOptions.repeatOptions.limit = evaluateExpression(
+          limitExpression,
+          fieldNode,
+          formFields,
+          formValues,
+          runnerContext,
+        );
+      }
+      return field;
+    });
+  }, [formValues, formFields, patient, sessionMode]);
+
+  useEffect(() => {
+    factoryContext.formJson?.pages?.forEach((page) => {
+      if (page.hide) {
+        evaluateHide(
+          { value: page, type: 'page' },
+          formFields,
+          formValues,
+          sessionMode,
+          patient,
+          evaluateExpression,
+          null,
+        );
+      } else {
+        page.isHidden = false;
+      }
+      page?.sections?.forEach((section) => {
+        if (section.hide) {
+          evaluateHide(
+            { value: section, type: 'section' },
+            formFields,
+            formValues,
+            sessionMode,
+            patient,
+            evaluateExpression,
+            null,
+          );
+        } else {
+          section.isHidden = false;
+        }
+      });
+    });
+    setEvaluatedFormJson(updateFormSectionReferences(factoryContext.formJson));
+    setEvaluatedPagesVisibility(true);
+  }, [factoryContext.formJson, formFields]);
+
+  return { evaluatedFormJson, evaluatedFields, evaluatedPagesVisibility };
+};
+
+// helpers
+
+function isNotBooleanString(str: string) {
+  return str !== 'true' && str !== 'false';
+}