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

package/src/transformers/default-schema-transformer.test.ts

@@ -0,0 +1,155 @@
+import { DefaultFormSchemaTransformer } from './default-schema-transformer';
+import testForm from '__mocks__/forms/afe-forms/test-schema-transformer-form.json';
+
+const expectedTransformedSchema = {
+  name: 'AFE form with aliased questions',
+  readonly: false,
+  pages: [
+    {
+      label: 'Page 1',
+      readonly: false,
+      sections: [
+        {
+          label: 'Section 1',
+          isExpanded: true,
+          questions: [
+            {
+              label: 'Multi Checkbox',
+              type: 'obs',
+              required: true,
+              id: 'dem_multi_checkbox',
+              questionOptions: {
+                rendering: 'checkbox',
+              },
+              validators: [
+                {
+                  type: 'form_field',
+                },
+                {
+                  type: 'default_value',
+                },
+              ],
+              meta: {
+                submission: null,
+              },
+            },
+            {
+              label: 'Numeric',
+              id: 'dem_numeric',
+              type: 'obs',
+              required: false,
+              questionOptions: {
+                rendering: 'number',
+              },
+              validators: [
+                {
+                  type: 'form_field',
+                },
+                {
+                  type: 'default_value',
+                },
+              ],
+              meta: {
+                submission: null,
+              },
+            },
+            {
+              label: 'Encounter Provider',
+              id: 'dem_encounter_provider',
+              type: 'encounterProvider',
+              required: false,
+              questionOptions: {
+                rendering: 'encounter-provider',
+              },
+              validators: [
+                {
+                  type: 'form_field',
+                },
+                {
+                  type: 'default_value',
+                },
+              ],
+              meta: {
+                submission: null,
+              },
+            },
+            {
+              id: 'dem_encounter_location',
+              type: 'obsGroup',
+              required: false,
+              questionOptions: {
+                rendering: 'group',
+              },
+              questions: [
+                {
+                  label: 'Encounter Location',
+                  type: 'encounterLocation',
+                  required: false,
+                  questionOptions: {
+                    rendering: 'encounter-location',
+                  },
+                  validators: [
+                    {
+                      type: 'form_field',
+                    },
+                    {
+                      type: 'default_value',
+                    },
+                  ],
+                  meta: {
+                    submission: null,
+                  },
+                },
+              ],
+              meta: {
+                submission: null,
+              },
+            },
+            {
+              id: 'labOrder',
+              type: 'testOrder',
+              label: 'Add Lab Order',
+              required: true,
+              questionOptions: {
+                rendering: 'repeating',
+                concept: 'f1742346-cf43-4a17-8c98-720e3f487fc0',
+                orderType: 'testorder',
+                orderSettingUuid: 'INPATIENT',
+                repeatOptions: {
+                  limit: 2,
+                },
+                answers: [
+                  {
+                    concept: '30e2da8f-34ca-4c93-94c8-d429f22d381c',
+                    label: 'Option 1',
+                  },
+                  {
+                    concept: '143264AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
+                    label: 'Option 2',
+                  },
+                ],
+              },
+              validators: [
+                {
+                  type: 'form_field',
+                },
+                {
+                  type: 'default_value',
+                },
+              ],
+              meta: {
+                submission: null,
+              },
+            },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe('Default form schema transformer', () => {
+  it('should transform AFE schema to be compatible with RFE', () => {
+    expect(DefaultFormSchemaTransformer.transform(testForm as any)).toEqual(expectedTransformedSchema);
+  });
+});

package/src/transformers/default-schema-transformer.ts

@@ -0,0 +1,239 @@
+import { type FormField, type FormSchemaTransformer, type FormSchema } from '../types';
+import { isTrue } from '../utils/boolean-utils';
+import { hasRendering } from '../utils/common-utils';
+
+export const DefaultFormSchemaTransformer: FormSchemaTransformer = {
+  transform: (form: FormSchema) => {
+    parseBooleanTokenIfPresent(form, 'readonly');
+    form.pages.forEach((page) => {
+      parseBooleanTokenIfPresent(page, 'readonly');
+      if (page.sections) {
+        page.sections.forEach((section) => {
+          section.questions = handleQuestionsWithDateOptions(section.questions);
+          section.questions = handleQuestionsWithObsComments(section.questions);
+          parseBooleanTokenIfPresent(section, 'readonly');
+          parseBooleanTokenIfPresent(section, 'isExpanded');
+          section?.questions?.forEach((question, index) => handleQuestion(question, form));
+        });
+      }
+    });
+    if (form.meta?.programs) {
+      handleProgramMetaTags(form);
+    }
+    return form;
+  },
+};
+
+function handleQuestion(question: FormField, form: FormSchema) {
+  if (question.type === 'programState') {
+    const formMeta = form.meta ?? {};
+    formMeta.programs = formMeta.programs
+      ? { ...formMeta.programs, hasProgramFields: true }
+      : { hasProgramFields: true };
+    form.meta = formMeta;
+  }
+  try {
+    sanitizeQuestion(question);
+    setFieldValidators(question);
+    transformByType(question);
+    transformByRendering(question);
+    if (question?.questions?.length) {
+      question.questions.forEach((question) => handleQuestion(question, form));
+    }
+  } catch (error) {
+    console.error(error);
+  }
+}
+
+function handleQuestionsWithDateOptions(sectionQuestions: Array<FormField>): Array<FormField> {
+  const augmentedQuestions: Array<FormField> = [];
+
+  sectionQuestions?.forEach((question) => {
+    augmentedQuestions.push(question);
+    if (question.type !== 'inlineDate' && isTrue(question.questionOptions?.showDate)) {
+      const inlinedDate: FormField = {
+        id: `${question.id}_inline_date`,
+        label: `Date for ${question.label}`,
+        type: 'inlineDate',
+        questionOptions: {
+          rendering: 'date',
+          isTransient: true,
+        },
+        validators: question.questionOptions.shownDateOptions?.validators,
+        disabled: { disableWhenExpression: `isEmpty(${question.id})` },
+        hide: question.questionOptions.shownDateOptions?.hide || question.hide,
+        meta: {
+          targetField: question.id,
+          previousValue: question.meta?.previousValue?.obsDatetime,
+        },
+      };
+
+      augmentedQuestions.push(inlinedDate);
+    }
+  });
+
+  return augmentedQuestions;
+}
+
+function sanitizeQuestion(question: FormField) {
+  parseBooleanTokenIfPresent(question, 'readonly');
+  parseBooleanTokenIfPresent(question, 'required');
+  parseBooleanTokenIfPresent(question, 'unspecified');
+  parseBooleanTokenIfPresent(question.questionOptions, 'disallowDecimals');
+  parseBooleanTokenIfPresent(question.questionOptions, 'isSearchable');
+  parseBooleanTokenIfPresent(question.questionOptions, 'isTransient');
+  parseBooleanTokenIfPresent(question.questionOptions, 'enablePreviousValue');
+  parseBooleanTokenIfPresent(question.questionOptions, 'allowMultiple');
+  if (!question.meta) {
+    question.meta = {
+      submission: null,
+    };
+  }
+}
+
+function parseBooleanTokenIfPresent(node: any, token: any) {
+  if (node && typeof node[token] === 'string') {
+    const trimmed = node[token].trim().toLowerCase();
+    if (trimmed === 'true' || trimmed === 'false') {
+      node[token] = trimmed === 'true';
+    }
+  }
+
+  return node;
+}
+
+function setFieldValidators(question: FormField) {
+  if (hasRendering(question, 'group')) {
+    return;
+  }
+  question.validators = question.validators || [];
+  if (question.validators.findIndex((v) => v.type === 'form_field') < 0) {
+    question.validators.push({ type: 'form_field' });
+  }
+  if (question.validators.findIndex((v) => v.type === 'default_value') < 0) {
+    question.validators.push({ type: 'default_value' });
+  }
+}
+
+function transformByType(question: FormField) {
+  switch (question.type) {
+    case 'encounterProvider':
+      question.questionOptions.rendering = 'encounter-provider';
+      break;
+    case 'encounterLocation':
+      question.questionOptions.rendering = 'encounter-location';
+      break;
+    case 'encounterRole':
+      question.questionOptions.rendering = 'encounter-role';
+      break;
+    case 'encounterDatetime':
+      question.questionOptions.rendering = hasRendering(question, 'ui-select-extended')
+        ? 'date'
+        : question.questionOptions.rendering;
+      break;
+  }
+}
+
+function transformByRendering(question: FormField) {
+  switch (question.questionOptions.rendering as any) {
+    case 'multiCheckbox':
+      question.questionOptions.rendering = 'checkbox';
+      break;
+    case 'numeric':
+      question.questionOptions.rendering = 'number';
+      break;
+    case 'select-concept-answers':
+      handleSelectConceptAnswers(question);
+      break;
+    case 'repeating':
+    case 'group':
+      handleLabOrders(question);
+      break;
+    case 'date':
+      question.datePickerFormat = question.datePickerFormat ?? 'calendar';
+      break;
+    case 'datetime':
+      question.datePickerFormat = question.datePickerFormat ?? 'both';
+      break;
+    case 'workspace-launcher':
+      question.type = 'control';
+      break;
+    case 'markdown':
+      question.type = 'control';
+      break;
+  }
+  return question;
+}
+
+function handleLabOrders(question: FormField) {
+  if (hasRendering(question, 'group') && question.questions?.length) {
+    question.questions.forEach(handleLabOrders);
+  }
+  if (question.type === 'testOrder' && question.questionOptions.selectableOrders?.length) {
+    question.questionOptions.answers = question.questionOptions.selectableOrders || [];
+    delete question.questionOptions.selectableOrders;
+  }
+}
+
+function handleSelectConceptAnswers(question: FormField) {
+  if (!question.questionOptions.datasource?.config) {
+    question.questionOptions.datasource = {
+      name: 'select_concept_answers_datasource',
+      config: {
+        concept: question.questionOptions.concept,
+      },
+    };
+  }
+}
+
+function handleProgramMetaTags(form: FormSchema) {
+  if (form.meta.programs.isEnrollment || form.meta.programs.discontinuationDateQuestionId) {
+    const config = {
+      programUuid: form.meta.programs.uuid,
+    };
+
+    if (form.meta.programs.isEnrollment) {
+      config['enrollmentDate'] = '';
+    } else {
+      config['completionDate'] = form.meta.programs.discontinuationDateQuestionId;
+    }
+
+    form.postSubmissionActions = [
+      {
+        actionId: 'ProgramEnrollmentSubmissionAction',
+        enabled: 'true',
+        config,
+      },
+    ];
+  }
+}
+
+function handleQuestionsWithObsComments(sectionQuestions: Array<FormField>): Array<FormField> {
+  const augmentedQuestions: Array<FormField> = [];
+
+  sectionQuestions?.forEach((question) => {
+    augmentedQuestions.push(question);
+    if (question.type !== 'obsComment' && isTrue(question.questionOptions?.showComment)) {
+      const obsComment: FormField = {
+        id: `${question.id}_obs_comment`,
+        label: `Comment for ${question.label}`,
+        type: 'obsComment',
+        questionOptions: {
+          rendering: 'text',
+          isTransient: true,
+        },
+        validators: question.questionOptions.shownCommentOptions?.validators,
+        disabled: { disableWhenExpression: `isEmpty(${question.id})` },
+        hide: question.questionOptions.shownCommentOptions?.hide || question.hide,
+        meta: {
+          targetField: question.id,
+          previousValue: question.meta?.previousValue?.comment,
+        },
+      };
+
+      augmentedQuestions.push(obsComment);
+    }
+  });
+
+  return augmentedQuestions;
+}

package/src/types/domain.ts

@@ -0,0 +1,129 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+
+export interface OpenmrsEncounter {
+  uuid?: string;
+  encounterDatetime?: string | Date;
+  patient?: OpenmrsResource | string;
+  location?: OpenmrsResource | string;
+  encounterType?: OpenmrsResource | string;
+  obs?: Array<OpenmrsObs>;
+  orders?: Array<OpenmrsResource>;
+  voided?: boolean;
+  visit?: OpenmrsResource | string;
+  encounterProviders?: Array<Record<string, any>>;
+  form?: OpenmrsFormResource;
+}
+
+export interface OpenmrsObs extends OpenmrsResource {
+  concept: any;
+  obsDatetime: string | Date;
+  obsGroup: OpenmrsObs;
+  groupMembers: Array<OpenmrsObs>;
+  comment: string;
+  location: OpenmrsResource;
+  order: OpenmrsResource;
+  encounter: OpenmrsResource;
+  voided: boolean;
+  value: any;
+  formFieldPath: string;
+  formFieldNamespace: string;
+  status: string;
+  interpretation: string;
+}
+
+export interface OpenmrsForm {
+  uuid: string;
+  name: string;
+  encounterType: OpenmrsResource;
+  version: string;
+  description: string;
+  published: boolean;
+  retired: boolean;
+  resources: Array<OpenmrsFormResource>;
+}
+
+export interface OpenmrsFormResource extends OpenmrsResource {
+  dataType?: string;
+  valueReference?: string;
+}
+
+export interface Attachment {
+  id: string;
+  src: string;
+  title: string;
+  description: string;
+  dateTime: string;
+  bytesMimeType: string;
+  bytesContentFamily: string;
+}
+
+export interface AttachmentResponse {
+  bytesContentFamily: string;
+  bytesMimeType: string;
+  comment: string;
+  dateTime: string;
+  uuid: string;
+}
+
+export interface Order {
+  concept: string;
+  orderer: string;
+  uuid?: string;
+  formFieldPath?: string;
+  type?: string;
+  action?: string;
+  urgency?: string;
+  dateActivated?: string;
+  careSetting?: string;
+  groupMembers?: Order[];
+  encounter?: string;
+  patient?: string;
+  orderNumber?: string;
+  voided?: boolean;
+}
+
+export interface ProgramState {
+  name?: string;
+  startDate?: string;
+  uuid?: string;
+  concept: OpenmrsResource;
+  programWorkflow: OpenmrsResource;
+}
+
+export interface ProgramWorkflowState {
+  state: ProgramState;
+  endDate?: string;
+  startDate?: string;
+}
+
+export interface PatientProgram extends OpenmrsResource {
+  patient?: OpenmrsResource;
+  program?: OpenmrsResource;
+  dateEnrolled?: string;
+  dateCompleted?: string;
+  location?: OpenmrsResource;
+  states?: Array<ProgramWorkflowState>;
+}
+
+export interface PatientProgramPayload {
+  program?: string;
+  uuid?: string;
+  display?: string;
+  patient?: string;
+  dateEnrolled?: string;
+  dateCompleted?: string;
+  location?: string;
+  states?: Array<{
+    state?: string;
+    startDate?: string;
+    endDate?: string;
+  }>;
+}
+
+export interface PatientIdentifier {
+  uuid?: string;
+  identifier: string;
+  identifierType?: string;
+  location?: string;
+  preferred?: boolean;
+}

package/src/types/index.ts

@@ -0,0 +1,130 @@
+import { type LayoutType, type OpenmrsResource } from '@openmrs/esm-framework';
+import { type FormProcessor } from '../processors/form-processor';
+import { type FormContextProps } from '../provider/form-provider';
+import { type FormField, type FormSchema } from './schema';
+import { type OpenmrsEncounter } from './domain';
+
+export type SessionMode = 'edit' | 'enter' | 'view' | 'embedded-view';
+
+export interface FormProcessorContextProps {
+  patient: fhir.Patient;
+  formJson: FormSchema;
+  visit: OpenmrsResource;
+  sessionMode: SessionMode;
+  sessionDate: Date;
+  location: OpenmrsResource;
+  currentProvider: OpenmrsResource;
+  layoutType: LayoutType;
+  domainObjectValue?: OpenmrsResource;
+  previousDomainObjectValue?: OpenmrsResource;
+  processor: FormProcessor;
+  formFields?: FormField[];
+  formFieldAdapters?: Record<string, FormFieldValueAdapter>;
+  formFieldValidators?: Record<string, FormFieldValidator>;
+  customDependencies?: Record<string, any>;
+}
+
+export interface ValueAndDisplay {
+  value: any;
+  display: string;
+}
+
+/**
+ * Interface for adapting form field values between primitive and composite formats.
+ */
+export interface FormFieldValueAdapter {
+  /**
+   * Adapts a field value from its primitive form to a composite form for backend submission.
+   */
+  transformFieldValue: (field: FormField, value: any, context: FormContextProps) => any;
+  /**
+   * Extracts the primitive value of a field from an Openmrs object.
+   * @param field - The form field whose value is to be extracted.
+   * @param sourceObject - The Openmrs object to extract the value from eg. patient, encounter etc.
+   */
+  getInitialValue: (
+    field: FormField,
+    sourceObject: OpenmrsResource,
+    context: FormProcessorContextProps,
+  ) => Promise<any> | any;
+  /**
+   * Very similar to `getInitialValue`, but used to extract "previous" values.
+   */
+  getPreviousValue: (
+    field: FormField,
+    sourceObject: OpenmrsResource,
+    context: FormProcessorContextProps,
+  ) => Promise<ValueAndDisplay> | ValueAndDisplay;
+  /**
+   * Extracts the display value from a composite object.
+   */
+  getDisplayValue: (field: FormField, value: any) => any;
+  /**
+   * Tears down the adapter.
+   */
+  tearDown: () => void;
+}
+
+export interface DataSource<T> {
+  /**
+   * Fetches arbitrary data from a data source
+   */
+  fetchData(searchTerm?: string, config?: Record<string, any>, uuid?: string): Promise<Array<T>>;
+  /**
+   * Maps a data source item to an object with a uuid and display property
+   */
+  toUuidAndDisplay(item: T): OpenmrsResource;
+}
+
+export interface ControlTemplate {
+  name: string;
+  datasource: DataSourceParameters;
+}
+
+export interface DataSourceParameters {
+  name: string;
+  config?: Record<string, any>;
+}
+
+/**
+ * A form schema transformer is used to bridge the gap caused by different variations of form schemas
+ * in the OpenMRS JSON schema-based form-entry world. It fine-tunes custom schemas to be compliant
+ * with the React Form Engine.
+ */
+export interface FormSchemaTransformer {
+  /**
+   * Transforms the raw schema to be compatible with the React Form Engine.
+   */
+  transform: (form: FormSchema) => FormSchema;
+}
+
+export interface PostSubmissionAction {
+  applyAction(
+    formSession: {
+      patient: fhir.Patient;
+      encounters: Array<OpenmrsEncounter>;
+      sessionMode: SessionMode;
+    },
+    config?: Record<string, any>,
+    enabled?: string,
+  ): void;
+}
+
+/**
+ * Field validator
+ */
+export interface FormFieldValidator {
+  /**
+   * Validates a field and returns validation errors
+   */
+  validate(field: FormField, value?: any, config?: any): Array<ValidationResult>;
+}
+
+export interface ValidationResult {
+  resultType: 'warning' | 'error';
+  errCode?: string;
+  message: string;
+}
+
+export * from './schema';
+export * from './domain';