@olaboot/esm-form-engine-lib 4.1.0

package/src/types/domain.ts

@@ -0,0 +1,237 @@
+import { type UploadedFile, 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;
+  diagnoses?: Array<Diagnosis>;
+}
+
+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 FHIRObsResource {
+  resourceType: string;
+  id: string;
+  category: Array<{
+    coding: Array<{
+      system: string;
+      code: string;
+      display: string;
+    }>;
+  }>;
+  code: {
+    coding: Array<{
+      code: string;
+      display: string;
+    }>;
+    text: string;
+  };
+  encounter?: {
+    reference: string;
+    type: string;
+  };
+  effectiveDateTime: string;
+  issued: string;
+  valueBoolean?: boolean;
+  valueString?: string;
+  valueDateTime?: string;
+  valueQuantity?: {
+    value: number;
+    unit: string;
+    system: string;
+    code: string;
+  };
+  valueCodeableConcept?: {
+    coding: [
+      {
+        code: string;
+        display: string;
+      },
+    ];
+    text: string;
+  };
+  referenceRange: Array<{
+    low?: {
+      value: number;
+    };
+    high?: {
+      value: number;
+    };
+    type: {
+      coding: Array<{
+        system: string;
+        code: string;
+      }>;
+    };
+  }>;
+  hasMember?: Array<{
+    reference: 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 extends UploadedFile {
+  uuid?: string;
+  voided?: boolean;
+}
+
+export interface AttachmentFieldValue extends Attachment {
+  formFieldNamespace: string;
+  formFieldPath: 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 ProgramsFetchResponse {
+  results: Array<PatientProgram>;
+}
+
+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 PatientDeathPayload {
+  dead: boolean;
+  causeOfDeath: string;
+  deathDate: string;
+}
+
+export interface PatientIdentifier {
+  uuid?: string;
+  identifier: string;
+  identifierType?: string;
+  location?: string;
+  preferred?: boolean;
+}
+
+export interface PersonAttribute {
+  uuid?: string;
+  value: string;
+  attributeType: string;
+}
+
+export interface DiagnosisPayload {
+  patient: string;
+  condition: null;
+  diagnosis: {
+    coded: string;
+  };
+  certainty: string;
+  rank: number;
+  formFieldNamespace?: string;
+  formFieldPath?: string;
+  uuid?: string;
+  encounter?: string;
+}
+
+export interface Diagnosis {
+  encounter: string;
+  patient: string;
+  diagnosis: {
+    coded: {
+      uuid: string;
+    };
+  };
+  certainty: string;
+  rank: number;
+  display: string;
+  voided: boolean;
+  uuid: string;
+  formFieldNamespace?: string;
+  formFieldPath?: string;
+}

package/src/types/index.ts

@@ -0,0 +1,153 @@
+import { type Visit, 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: Visit;
+  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>): Promise<Array<T>>;
+
+  /**
+   * Fetches a single item from the data source based on its UUID.
+   * This is used for value binding with previously selected values.
+   */
+  fetchSingleItem(uuid: string): Promise<T | null>;
+
+  /**
+   * 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.
+   * Adds default values to questions based on the preFilledQuestions object.
+   */
+  transform: (form: FormSchema, preFilledQuestions?: PreFilledQuestions) => FormSchema;
+}
+
+export interface PostSubmissionAction {
+  applyAction(
+    formSession: {
+      patient: fhir.Patient;
+      encounters: Array<OpenmrsEncounter>;
+      sessionMode: SessionMode;
+    },
+    config?: Record<string, any>,
+    enabled?: string,
+  ): void;
+}
+
+export interface FormFieldInputProps<TValue = any> {
+  value: TValue;
+  field: FormField;
+  errors: ValidationResult[];
+  warnings: ValidationResult[];
+  /**
+   * Callback function to handle changes to the field value in the React Hook Form context.
+   *
+   * @param value - The new value of the field.
+   */
+  setFieldValue: (value: TValue) => 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 type PreFilledQuestions = Record<string, string | number | Date | boolean | Array<string>>;
+
+export * from './schema';
+export * from './domain';

package/src/types/schema.ts

@@ -0,0 +1,259 @@
+import { type OpenmrsResource } from '@openmrs/esm-framework';
+import { type OpenmrsEncounter } from './domain';
+
+export interface FormSchema {
+  name: string;
+  pages: Array<FormPage>;
+  processor: string;
+  uuid: string;
+  referencedForms: Array<ReferencedForm>;
+  encounterType: string;
+  encounter?: string | OpenmrsEncounter;
+  allowUnspecifiedAll?: boolean;
+  defaultPage?: string;
+  readonly?: string | boolean;
+  inlineRendering?: 'single-line' | 'multiline' | 'automatic';
+  markdown?: any;
+  postSubmissionActions?: Array<{ actionId: string; enabled?: string; config?: Record<string, any> }>;
+  formOptions?: {
+    usePreviousValueDisabled: boolean;
+  };
+  version?: string;
+  translations?: Record<string, string>;
+  meta?: {
+    programs?: {
+      hasProgramFields?: boolean;
+      [anythingElse: string]: any;
+    };
+  };
+}
+
+export interface FormPage {
+  label: string;
+  isHidden?: boolean;
+  hide?: HideProps;
+  sections: Array<FormSection>;
+  isSubform?: boolean;
+  inlineRendering?: 'single-line' | 'multiline' | 'automatic';
+  readonly?: string | boolean;
+  subform?: {
+    name?: string;
+    package?: string;
+    behaviours?: Array<any>;
+    form: Omit<FormSchema, 'postSubmissionActions'>;
+  };
+  id?: string;
+}
+
+export interface FormSection {
+  hide?: HideProps;
+  label: string;
+  isExpanded: string;
+  isHidden?: boolean;
+  isParentHidden?: boolean;
+  questions: Array<FormField>;
+  inlineRendering?: 'single-line' | 'multiline' | 'automatic';
+  readonly?: string | boolean;
+  reference?: FormReference;
+}
+
+export interface FormField {
+  label?: string;
+  type: string;
+  questionOptions: FormQuestionOptions;
+  datePickerFormat?: 'both' | 'calendar' | 'timer';
+  id: string;
+  questions?: Array<FormField>;
+  value?: any;
+  hide?: HideProps;
+  isHidden?: boolean;
+  isParentHidden?: boolean;
+  fieldDependents?: Set<string>;
+  pageDependents?: Set<string>;
+  sectionDependents?: Set<string>;
+  isRequired?: boolean;
+  required?: string | boolean | RequiredFieldProps;
+  unspecified?: boolean;
+  isDisabled?: boolean;
+  disabled?: boolean | Omit<DisableProps, 'isDisabled'>;
+  readonly?: string | boolean;
+  isReadonly?: boolean;
+  inlineRendering?: 'single-line' | 'multiline' | 'automatic';
+  validators?: Array<Record<string, any>>;
+  behaviours?: Array<Record<string, any>>;
+  questionInfo?: string;
+  historicalExpression?: string;
+  constrainMaxWidth?: boolean;
+  hideSteppers?: boolean;
+  /** @deprecated */
+  inlineMultiCheckbox?: boolean;
+  meta?: QuestionMetaProps;
+}
+
+export interface HideProps {
+  hideWhenExpression: string;
+}
+
+export interface DisableProps {
+  disableWhenExpression?: string;
+  isDisabled?: boolean;
+}
+
+export interface RequiredFieldProps {
+  type: string;
+  message?: string;
+  referenceQuestionId: string;
+  referenceQuestionAnswers: Array<string>;
+}
+
+export interface RepeatOptions {
+  addText?: string;
+  limit?: string;
+  limitExpression?: string;
+}
+
+export interface QuestionMetaProps {
+  concept?: OpenmrsResource;
+  initialValue?: {
+    omrsObject: OpenmrsResource | Array<OpenmrsResource>;
+    refinedValue?: string | number | Date | Array<string | number>;
+  };
+  submission?: {
+    voidedValue?: any;
+    newValue?: any;
+    unspecified?: boolean;
+    errors?: any[];
+    warnings?: any[];
+  };
+  repeat?: {
+    isClone?: boolean;
+    wasDeleted?: boolean;
+  };
+  groupId?: string;
+  pageId?: string;
+  [anythingElse: string]: any;
+}
+
+export interface FormQuestionOptions {
+  extensionId?: string;
+  extensionSlotName?: string;
+  rendering: RenderType;
+  concept?: string;
+  /**
+   * max and min are used to validate number field values
+   */
+  max?: string;
+  min?: string;
+  /**
+   * specifies the increment or decrement step for number field values
+   */
+  step?: number;
+  /**
+   * @description
+   * Indicates whether the field is transient.
+   * - Transient fields are ignored on form submission.
+   * - If set to __true__, the field is omitted from the O3 Form in `embedded-view` mode.
+   * @default false
+   */
+  isTransient?: boolean;
+  /**
+   * maxLength and maxLength are used to validate text field length
+   */
+  maxLength?: string;
+  minLength?: string;
+  showDate?: string;
+  shownDateOptions?: { validators?: Array<Record<string, any>>; hide?: { hideWhenExpression: string } };
+  answers?: Array<QuestionAnswerOption>;
+  weeksList?: string;
+  locationTag?: string;
+  disallowDecimals?: boolean;
+  rows?: number;
+  toggleOptions?: { labelTrue: string; labelFalse: string };
+  repeatOptions?: RepeatOptions;
+  defaultValue?: any;
+  calculate?: {
+    calculateExpression: string;
+  };
+  isDateTime?: { labelTrue: boolean; labelFalse: boolean };
+  enablePreviousValue?: boolean;
+  allowedFileTypes?: Array<string>;
+  allowMultiple?: boolean;
+  datasource?: { name: string; config?: Record<string, any> };
+  /**
+   * Determines if the ui-select-extended rendering is searchable
+   */
+  isSearchable?: boolean;
+  /**
+   * Determines if the checkbox rendering is searchable
+   */
+  isCheckboxSearchable?: boolean;
+  workspaceName?: string;
+  workspaceProps?: Record<string, any>;
+  buttonLabel?: string;
+  identifierType?: string;
+  attributeType?: string;
+  orderSettingUuid?: string;
+  orderType?: string;
+  selectableOrders?: Array<Record<any, any>>;
+  programUuid?: string;
+  workflowUuid?: string;
+  showComment?: boolean;
+  comment?: string;
+  orientation?: 'vertical' | 'horizontal';
+  shownCommentOptions?: { validators?: Array<Record<string, any>>; hide?: { hideWhenExpression: string } };
+  diagnosis?: {
+    rank?: number;
+    isConfirmed?: boolean;
+    conceptClasses?: Array<string>;
+    conceptSet?: string;
+  };
+}
+
+export interface QuestionAnswerOption {
+  hide?: HideProps;
+  disable?: DisableProps;
+  label?: string;
+  concept?: string;
+  [key: string]: any;
+}
+
+export type RenderType =
+  | 'checkbox'
+  | 'checkbox-searchable'
+  | 'content-switcher'
+  | 'date'
+  | 'datetime'
+  | 'drug'
+  | 'encounter-location'
+  | 'encounter-provider'
+  | 'encounter-role'
+  | 'fixed-value'
+  | 'file'
+  | 'group'
+  | 'number'
+  | 'problem'
+  | 'radio'
+  | 'repeating'
+  | 'select'
+  | 'text'
+  | 'textarea'
+  | 'toggle'
+  | 'ui-select-extended'
+  | 'workspace-launcher'
+  | 'markdown'
+  | 'extension-widget'
+  | 'select-concept-answers';
+
+export interface FormReference {
+  form: string;
+  page: string;
+  section: string;
+  excludeQuestions?: Array<string>;
+}
+
+export interface ReferencedForm {
+  formName: string;
+  alias: string;
+}
+
+export type FormExpanded = boolean | undefined;

package/src/typings.d.ts

@@ -0,0 +1,9 @@
+import type { i18n } from 'i18next';
+
+declare global {
+  interface Window {
+    openmrsBase: string;
+    spaBase: string;
+    formEnginei18next: i18n;
+  }
+}

package/src/utils/boolean-utils.ts

@@ -0,0 +1,25 @@
+/**
+ * Evaluates whether a value is truthy. This should be used when a string value is expected to parsed into a boolean ie.
+ * ```bash
+ *  'false' => false
+ *  'true' => true
+ * ```
+ */
+export function isTrue(value: string | boolean): boolean {
+  if (typeof value == 'boolean') {
+    return value;
+  }
+  if (typeof value == 'string') {
+    return value == 'true';
+  }
+  // TODO: throw an exception?
+  return !!value;
+}
+
+/**
+ * Checks whether a string is a UUID
+ */
+export function isUuid(value: string): boolean {
+  const uuidRegex = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+  return uuidRegex.test(value);
+}