@olaboot/esm-form-engine-lib 4.1.0

package/src/components/renderer/field/form-field-renderer.component.tsx

@@ -0,0 +1,291 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { ToastNotification } from '@carbon/react';
+import { Controller, useWatch } from 'react-hook-form';
+import { useTranslation } from 'react-i18next';
+import { ErrorBoundary } from 'react-error-boundary';
+import { useConfig } from '@openmrs/esm-framework';
+import {
+  type FormField,
+  type FormFieldInputProps,
+  type FormFieldValueAdapter,
+  type RenderType,
+  type ValidationResult,
+  type ValueAndDisplay,
+} from '../../../types';
+import { getFieldControlWithFallback, getRegisteredControl } from '../../../registry/registry';
+import { handleFieldLogic, validateFieldValue } from './fieldLogic';
+import { hasRendering } from '../../../utils/common-utils';
+import { isEmpty } from '../../../validators/form-validator';
+import { isTrue } from '../../../utils/boolean-utils';
+import { useFormProviderContext } from '../../../provider/form-provider';
+import PreviousValueReview from '../../previous-value-review/previous-value-review.component';
+import UnspecifiedField from '../../inputs/unspecified/unspecified.component';
+import { shouldRenderField } from './fieldRenderUtils';
+import styles from './form-field-renderer.scss';
+
+export interface FormFieldRendererProps {
+  fieldId: string;
+  valueAdapter: FormFieldValueAdapter;
+  repeatOptions?: {
+    targetRendering: RenderType;
+  };
+}
+
+export const FormFieldRenderer = ({ fieldId, valueAdapter, repeatOptions }: FormFieldRendererProps) => {
+  const [inputComponentWrapper, setInputComponentWrapper] = useState<{
+    value: React.ComponentType<FormFieldInputProps>;
+  }>(null);
+  const [errors, setErrors] = useState<ValidationResult[]>([]);
+  const [warnings, setWarnings] = useState<ValidationResult[]>([]);
+  const [historicalValue, setHistoricalValue] = useState<ValueAndDisplay>(null);
+  const context = useFormProviderContext();
+
+  // Try to get config from external module, fallback to default if not available
+  let hideUnansweredQuestionsInReadonlyForms = false;
+  try {
+    const config = useConfig({
+      externalModuleName: '@openmrs/esm-form-engine-app',
+    });
+    hideUnansweredQuestionsInReadonlyForms = config?.hideUnansweredQuestionsInReadonlyForms ?? false;
+  } catch (error) {
+    // If external module config is not available, use default value
+    console.warn(
+      'Failed to load @openmrs/esm-form engine-app config - using hideUnansweredQuestionsInReadonlyForms=false (empty fields will be visible in readonly mode): ',
+      error,
+    );
+  }
+
+  const {
+    methods: { control, getValues, getFieldState },
+    patient,
+    sessionMode,
+    formFields,
+    formFieldValidators,
+    addInvalidField,
+    removeInvalidField,
+    updateFormField,
+  } = context;
+
+  const fieldValue = useWatch({ control, name: fieldId, exact: true });
+  const noop = () => {};
+
+  const field = useMemo(() => formFields.find((field) => field.id === fieldId), [fieldId, formFields]);
+
+  useEffect(() => {
+    if (hasRendering(field, 'repeating') && repeatOptions?.targetRendering) {
+      getRegisteredControl(repeatOptions.targetRendering).then((component) => {
+        if (component) {
+          setInputComponentWrapper({ value: component });
+        }
+      });
+    } else {
+      getFieldControlWithFallback(field).then((component) => {
+        if (component) {
+          setInputComponentWrapper({ value: component });
+        }
+      });
+    }
+    if (sessionMode === 'enter' && (field.historicalExpression || context.previousDomainObjectValue)) {
+      try {
+        context.processor.getHistoricalValue(field, context).then((value) => {
+          setHistoricalValue(value);
+        });
+      } catch (error) {
+        console.error(error);
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    const { isDirty, isTouched } = getFieldState(field.id);
+    const { submission, unspecified } = field.meta;
+    const { calculate, defaultValue } = field.questionOptions;
+    if (
+      !isEmpty(fieldValue) &&
+      !submission?.newValue &&
+      !isDirty &&
+      !unspecified &&
+      (calculate?.calculateExpression || defaultValue)
+    ) {
+      valueAdapter.transformFieldValue(field, fieldValue, context);
+    }
+    if (isDirty || isTouched) {
+      onAfterChange(fieldValue);
+    }
+  }, [fieldValue]);
+
+  useEffect(() => {
+    if (field.meta.submission?.errors) {
+      setErrors(field.meta.submission.errors);
+    }
+    if (field.meta.submission?.warnings) {
+      setWarnings(field.meta.submission.warnings);
+    }
+    if (field.meta.submission?.unspecified) {
+      setErrors([]);
+      removeInvalidField(field.id);
+    }
+  }, [field.meta.submission]);
+
+  const onAfterChange = (value: any) => {
+    const { errors: validationErrors, warnings: validationWarnings } = validateFieldValue(
+      field,
+      value,
+      formFieldValidators,
+      {
+        formFields: formFields,
+        values: getValues(),
+        expressionContext: { patient, mode: sessionMode },
+      },
+    );
+
+    if (field.meta.submission) {
+      // clear stale submission validation results
+      field.meta.submission.errors = undefined;
+      field.meta.submission.warnings = undefined;
+    }
+
+    if (errors.length && !validationErrors.length) {
+      removeInvalidField(field.id);
+      setErrors([]);
+    } else if (validationErrors.length) {
+      setErrors(validationErrors);
+      addInvalidField(field);
+    }
+    if (!validationErrors.length) {
+      valueAdapter.transformFieldValue(field, value, context);
+    }
+    setWarnings(validationWarnings);
+    handleFieldLogic(field, context);
+    if (field.meta.groupId) {
+      const group = formFields.find((f) => f.id === field.meta.groupId);
+      if (group) {
+        group.questions = group.questions.map((child) => {
+          if (child.id === field.id) {
+            return field;
+          }
+          return child;
+        });
+        updateFormField(group);
+      }
+    }
+  };
+
+  if (!inputComponentWrapper) {
+    return null;
+  }
+
+  const InputComponent = inputComponentWrapper.value;
+
+  if (!repeatOptions?.targetRendering && isGroupField(field.questionOptions.rendering)) {
+    return (
+      <InputComponent
+        key={field.id}
+        field={field}
+        value={null}
+        errors={errors}
+        warnings={warnings}
+        setFieldValue={null}
+      />
+    );
+  }
+
+  // In 'embedded-view' mode, empty fields are hidden if they are transient
+  // or if the config flag `hideUnansweredQuestionsInReadonlyForms` is enabled.
+  if (
+    !shouldRenderField(
+      sessionMode,
+      !!field.questionOptions.isTransient,
+      isEmpty(fieldValue),
+      hideUnansweredQuestionsInReadonlyForms,
+    )
+  ) {
+    return null;
+  }
+
+  return (
+    <ErrorBoundary FallbackComponent={ErrorFallback} onReset={noop}>
+      <Controller
+        control={control}
+        name={field.id}
+        render={({ field: { value, onChange, onBlur } }) => (
+          <div>
+            <InputComponent
+              key={`${field.id}-input-component`}
+              field={field}
+              value={value}
+              errors={errors}
+              warnings={warnings}
+              setFieldValue={(val) => {
+                onChange(val);
+                onAfterChange(val);
+                onBlur();
+              }}
+            />
+            {isUnspecifiedSupported(field) && (
+              <div className={styles.unspecifiedContainer}>
+                {field.unspecified && (
+                  <UnspecifiedField
+                    key={`${field.id}-unspecified`}
+                    field={field}
+                    setFieldValue={onChange}
+                    onAfterChange={onAfterChange}
+                    fieldValue={value}
+                  />
+                )}
+              </div>
+            )}
+            {historicalValue?.value && (
+              <div>
+                <PreviousValueReview
+                  key={`${field.id}-previous-value-review`}
+                  previousValue={historicalValue.value}
+                  displayText={historicalValue.display}
+                  onAfterChange={onAfterChange}
+                  field={field}
+                />
+              </div>
+            )}
+          </div>
+        )}
+      />
+    </ErrorBoundary>
+  );
+};
+
+export function ErrorFallback({ error }) {
+  const { t } = useTranslation();
+  return (
+    <ToastNotification
+      aria-label={t('closesNotification', 'Closes notification')}
+      caption=""
+      hideCloseButton
+      lowContrast
+      onClose={function noRefCheck() {}}
+      onCloseButtonClick={function noRefCheck() {}}
+      statusIconDescription={t('notification', 'Notification')}
+      subtitle={error.message}
+      title={t('errorRenderingField', 'Error rendering field')}
+    />
+  );
+}
+
+/**
+ * Determines whether a field can be unspecified
+ */
+export function isUnspecifiedSupported(question: FormField) {
+  const { rendering } = question.questionOptions;
+  return (
+    isTrue(question.unspecified) &&
+    rendering != 'toggle' &&
+    rendering != 'group' &&
+    rendering != 'repeating' &&
+    rendering != 'markdown' &&
+    rendering != 'extension-widget' &&
+    rendering != 'workspace-launcher'
+  );
+}
+
+export function isGroupField(rendering: RenderType) {
+  return rendering === 'group' || rendering === 'repeating';
+}

package/src/components/renderer/field/form-field-renderer.scss

@@ -0,0 +1,5 @@
+.unspecifiedContainer {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}

package/src/components/renderer/form/form-renderer.component.tsx

@@ -0,0 +1,123 @@
+import React, { useEffect, useMemo, useReducer } from 'react';
+import { useForm } from 'react-hook-form';
+import PageRenderer from '../page/page.renderer.component';
+import FormProcessorFactory from '../../processor-factory/form-processor-factory.component';
+import { formStateReducer, initialState } from './state';
+import { useEvaluateFormFieldExpressions } from '../../../hooks/useEvaluateFormFieldExpressions';
+import { useFormFactory } from '../../../provider/form-factory-provider';
+import { FormProvider, type FormContextProps } from '../../../provider/form-provider';
+import { type FormProcessorContextProps } from '../../../types';
+import { useFormStateHelpers } from '../../../hooks/useFormStateHelpers';
+import { pageObserver } from '../../sidebar/page-observer';
+import { isPageContentVisible } from '../../../utils/form-helper';
+
+export type FormRendererProps = {
+  processorContext: FormProcessorContextProps;
+  initialValues: Record<string, any>;
+  isSubForm: boolean;
+  setIsLoadingFormDependencies: (isLoading: boolean) => void;
+};
+
+export const FormRenderer = ({
+  processorContext,
+  initialValues,
+  isSubForm,
+  setIsLoadingFormDependencies,
+}: FormRendererProps) => {
+  const { evaluatedFields, evaluatedFormJson, evaluatedPagesVisibility } = useEvaluateFormFieldExpressions(
+    initialValues,
+    processorContext,
+  );
+  const { registerForm, setIsFormDirty, workspaceLayout, isFormExpanded } = useFormFactory();
+  const methods = useForm({
+    defaultValues: initialValues,
+    mode: 'onChange',
+    reValidateMode: 'onChange',
+    criteriaMode: 'all',
+  });
+
+  const {
+    formState: { isDirty },
+  } = methods;
+
+  const [{ formFields, invalidFields, formJson, deletedFields }, dispatch] = useReducer(formStateReducer, {
+    ...initialState,
+    formFields: evaluatedFields,
+    formJson: evaluatedFormJson,
+  });
+
+  const {
+    addFormField,
+    updateFormField,
+    getFormField,
+    removeFormField,
+    setInvalidFields,
+    addInvalidField,
+    removeInvalidField,
+    setForm,
+    setDeletedFields,
+  } = useFormStateHelpers(dispatch, formFields);
+
+  useEffect(() => {
+    const scrollablePages = formJson.pages.filter((page) => !page.isSubform).map((page) => page);
+    pageObserver.updateScrollablePages(scrollablePages);
+  }, [formJson.pages]);
+
+  useEffect(() => {
+    pageObserver.setEvaluatedPagesVisibility(evaluatedPagesVisibility);
+  }, [evaluatedPagesVisibility]);
+
+  useEffect(() => {
+    pageObserver.updatePagesWithErrors(invalidFields.map((field) => field.meta.pageId));
+  }, [invalidFields]);
+
+  const context: FormContextProps = useMemo(() => {
+    return {
+      ...processorContext,
+      workspaceLayout,
+      methods,
+      formFields,
+      formJson,
+      invalidFields,
+      deletedFields,
+      addFormField,
+      updateFormField,
+      getFormField,
+      removeFormField,
+      setInvalidFields,
+      addInvalidField,
+      removeInvalidField,
+      setForm,
+      setDeletedFields,
+    };
+  }, [processorContext, workspaceLayout, methods, formFields, formJson, invalidFields, deletedFields]);
+
+  useEffect(() => {
+    registerForm(formJson.name, isSubForm, context);
+  }, [formJson.name, isSubForm, context]);
+
+  useEffect(() => {
+    setIsFormDirty(isDirty);
+  }, [isDirty]);
+
+  return (
+    <FormProvider {...context}>
+      {formJson.pages.map((page) => {
+        if (!page.isSubform && !isPageContentVisible(page)) {
+          return null;
+        }
+        if (page.isSubform && page.subform?.form) {
+          return (
+            <FormProcessorFactory
+              key={page.subform.form.uuid}
+              formJson={page.subform.form}
+              isSubForm={true}
+              setIsLoadingFormDependencies={setIsLoadingFormDependencies}
+            />
+          );
+        }
+        return <PageRenderer key={page.label} page={page} isFormExpanded={isFormExpanded} />;
+      })}
+    </FormProvider>
+  );
+};

package/src/components/renderer/form/state.ts

@@ -0,0 +1,59 @@
+import { type FormField, type FormSchema } from '../../../types';
+
+type FormState = {
+  formFields: FormField[];
+  invalidFields: FormField[];
+  formJson: FormSchema;
+  deletedFields: FormField[];
+};
+
+type Action =
+  | { type: 'SET_FORM_FIELDS'; value: FormField[] }
+  | { type: 'ADD_FORM_FIELD'; value: FormField }
+  | { type: 'UPDATE_FORM_FIELD'; value: FormField }
+  | { type: 'REMOVE_FORM_FIELD'; value: string }
+  | { type: 'SET_INVALID_FIELDS'; value: FormField[] }
+  | { type: 'ADD_INVALID_FIELD'; value: FormField }
+  | { type: 'REMOVE_INVALID_FIELD'; value: string }
+  | { type: 'CLEAR_INVALID_FIELDS' }
+  | { type: 'SET_FORM_JSON'; value: any }
+  | { type: 'SET_DELETED_FIELDS'; value: FormField[] };
+
+const initialState: FormState = {
+  formFields: [],
+  invalidFields: [],
+  formJson: null,
+  deletedFields: [],
+};
+
+const formStateReducer = (state: FormState, action: Action): FormState => {
+  switch (action.type) {
+    case 'SET_FORM_FIELDS':
+      return { ...state, formFields: action.value };
+    case 'ADD_FORM_FIELD':
+      return { ...state, formFields: [...state.formFields, action.value] };
+    case 'UPDATE_FORM_FIELD':
+      return {
+        ...state,
+        formFields: state.formFields.map((field) => (field.id === action.value.id ? action.value : field)),
+      };
+    case 'REMOVE_FORM_FIELD':
+      return { ...state, formFields: state.formFields.filter((field) => field.id !== action.value) };
+    case 'SET_INVALID_FIELDS':
+      return { ...state, invalidFields: action.value };
+    case 'ADD_INVALID_FIELD':
+      return { ...state, invalidFields: [...state.invalidFields, action.value] };
+    case 'REMOVE_INVALID_FIELD':
+      return { ...state, invalidFields: state.invalidFields.filter((field) => field.id !== action.value) };
+    case 'CLEAR_INVALID_FIELDS':
+      return { ...state, invalidFields: [] };
+    case 'SET_FORM_JSON':
+      return { ...state, formJson: action.value };
+    case 'SET_DELETED_FIELDS':
+      return { ...state, deletedFields: action.value };
+    default:
+      return state;
+  }
+};
+
+export { formStateReducer, initialState, FormState, Action };

package/src/components/renderer/page/page.renderer.component.tsx

@@ -0,0 +1,120 @@
+import React, { useEffect, useMemo, useState } from 'react';
+import { type FormSection, type FormPage } from '../../../types';
+import { isTrue } from '../../../utils/boolean-utils';
+import { useTranslation } from 'react-i18next';
+import { SectionRenderer } from '../section/section-renderer.component';
+import { Waypoint } from 'react-waypoint';
+import styles from './page.renderer.scss';
+import { Accordion, AccordionItem } from '@carbon/react';
+import { ChevronDownIcon, ChevronUpIcon } from '@openmrs/esm-framework';
+import classNames from 'classnames';
+import { pageObserver } from '../../sidebar/page-observer';
+
+interface PageRendererProps {
+  page: FormPage;
+  isFormExpanded: boolean;
+}
+
+interface CollapsibleSectionContainerProps {
+  section: FormSection;
+  sectionIndex: number;
+  visibleSections: FormSection[];
+  isFormExpanded: boolean;
+}
+
+function PageRenderer({ page, isFormExpanded }: PageRendererProps) {
+  const { t } = useTranslation();
+  const [isCollapsed, setIsCollapsed] = useState(false);
+
+  const visibleSections = useMemo(
+    () =>
+      page.sections.filter((section) => {
+        const hasVisibleQuestions = section.questions.some((question) => !isTrue(question.isHidden));
+        return !isTrue(section.isHidden) && hasVisibleQuestions;
+      }),
+    [page.sections],
+  );
+
+  const toggleCollapse = () => setIsCollapsed(!isCollapsed);
+
+  useEffect(() => {
+    setIsCollapsed(!isFormExpanded);
+
+    return () => {
+      pageObserver.removeInactivePage(page.id);
+    };
+  }, [isFormExpanded]);
+
+  return (
+    <div>
+      <Waypoint
+        key={page.id}
+        onEnter={() => pageObserver.addActivePage(page.id)}
+        onLeave={() => pageObserver.removeInactivePage(page.id)}
+        topOffset="40%"
+        bottomOffset="40%">
+        <div id={page.id} className={styles.pageContent}>
+          <div className={styles.pageHeader} onClick={toggleCollapse}>
+            <p className={styles.pageTitle}>
+              {t(page.label)}
+              <span className={styles.collapseIconWrapper}>
+                {isCollapsed ? (
+                  <ChevronDownIcon className={styles.collapseIcon} aria-label="Expand" />
+                ) : (
+                  <ChevronUpIcon className={styles.collapseIcon} aria-label="Collapse" />
+                )}
+              </span>
+            </p>
+          </div>
+          <div
+            className={classNames({
+              [styles.hiddenAccordion]: isCollapsed,
+              [styles.accordionContainer]: !isCollapsed,
+            })}>
+            <Accordion>
+              {visibleSections.map((section, index) => (
+                <CollapsibleSectionContainer
+                  key={`section-${section.label}`}
+                  section={section}
+                  sectionIndex={index}
+                  visibleSections={visibleSections}
+                  isFormExpanded={isFormExpanded}
+                />
+              ))}
+            </Accordion>
+          </div>
+        </div>
+      </Waypoint>
+    </div>
+  );
+}
+
+function CollapsibleSectionContainer({
+  section,
+  sectionIndex,
+  visibleSections,
+  isFormExpanded,
+}: CollapsibleSectionContainerProps) {
+  const { t } = useTranslation();
+  const [isSectionOpen, setIsSectionOpen] = useState(isFormExpanded);
+
+  useEffect(() => {
+    setIsSectionOpen(isFormExpanded);
+  }, [isFormExpanded]);
+
+  return (
+    <AccordionItem
+      title={t(section.label)}
+      open={isSectionOpen}
+      className={classNames(styles.sectionContainer, {
+        [styles.firstSection]: sectionIndex === 0,
+        [styles.lastSection]: sectionIndex === visibleSections.length - 1,
+      })}>
+      <div className={styles.formSection}>
+        <SectionRenderer section={section} />
+      </div>
+    </AccordionItem>
+  );
+}
+
+export default PageRenderer;

package/src/components/renderer/page/page.renderer.scss

@@ -0,0 +1,74 @@
+@use '@carbon/colors';
+@use '@carbon/type';
+@use '@carbon/layout';
+
+.pageContent:last-child > hr {
+  display: none;
+}
+
+.pageHeader {
+  cursor: pointer;
+  transition: background-color 0.1s;
+  border-radius: 1px;
+  padding: 0.5rem 1rem;
+  border-top: 1px solid colors.$gray-20;
+  border-bottom: 1px solid colors.$gray-20;
+  &:hover {
+    background-color: colors.$gray-20;
+  }
+}
+
+.pageTitle {
+  font-size: 1.25rem;
+  font-weight: 600;
+  line-height: 1.4;
+  color: colors.$gray-100;
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin: 0;
+}
+
+.collapseIcon {
+  fill: colors.$gray-70;
+  width: 1rem;
+  height: 1rem;
+}
+
+.sectionContainer > div {
+  background-color: colors.$gray-10;
+}
+
+.sectionContainer :global(.cds--accordion__content) {
+  padding-right: layout.$spacing-05;
+}
+
+.accordionContainer {
+  width: 95%;
+}
+
+.firstSection {
+  border-top: none;
+}
+
+.lastSection {
+  border-bottom: none !important;
+}
+
+.formSection {
+  flex: 1 1 65%;
+}
+
+.hiddenAccordion {
+  display: none;
+}
+
+.formSection > div > fieldset {
+  margin-bottom: 0 !important;
+}
+
+// TODO: try removing this when upgrading @carbon/react. Added at 1.37
+:global(.cds--accordion__wrapper) {
+  max-block-size: unset !important;
+}

package/src/components/renderer/section/section-renderer.component.tsx

@@ -0,0 +1,25 @@
+import React, { useMemo } from 'react';
+import { type FormSection } from '../../../types';
+import { useFormProviderContext } from '../../../provider/form-provider';
+import { FormFieldRenderer } from '../field/form-field-renderer.component';
+import styles from './section-renderer.scss';
+
+export const SectionRenderer = ({ section }: { section: FormSection }) => {
+  const { formFieldAdapters } = useFormProviderContext();
+  const sectionId = useMemo(() => section.label.replace(/\s/g, ''), [section.label]);
+  return (
+    <div className={styles.section}>
+      {section.questions.map((question) =>
+        formFieldAdapters[question.type] ? (
+          <div key={`${sectionId}-${question.id}`} className={styles.sectionBody}>
+            <FormFieldRenderer
+              key={question.id}
+              fieldId={question.id}
+              valueAdapter={formFieldAdapters[question.type]}
+            />
+          </div>
+        ) : null,
+      )}
+    </div>
+  );
+};