@olaboot/esm-form-engine-lib 4.1.0

package/src/components/sidebar/useCurrentActivePage.ts

@@ -0,0 +1,137 @@
+import { useState, useEffect, useCallback, useRef } from 'react';
+import { type FormPage } from '../../types';
+import { scrollIntoView } from '../../utils/form-helper';
+
+interface UseCurrentActivePageProps {
+  pages: FormPage[];
+  defaultPage: string;
+  activePages: string[];
+  evaluatedPagesVisibility: boolean;
+}
+
+interface UseCurrentActivePageResult {
+  currentActivePage: string | null;
+  requestPage: (pageId: string) => void;
+}
+
+/**
+ * Hook to manage the currently active page in a form sidebar.
+ *
+ * This implementation includes a locking mechanism to handle a specific limitation with Waypoint:
+ * When dealing with short forms where multiple pages are visible in the viewport simultaneously,
+ * Waypoint's initial visibility detection can be unpredictable. It might:
+ * 1. Report pages in a different order than their DOM position
+ * 2. Miss reporting some visible pages in the first few renders
+ * 3. Report visibility events before our desired initial scroll position is established
+ *
+ * The locking mechanism (isInitialPhaseRef) prevents these early Waypoint events from
+ * overriding our intended initial page selection. Without this lock:
+ * - The form might initially select the first page
+ * - But then immediately jump to a different page due to Waypoint's visibility events
+ * - This creates a jarring user experience where the form appears to "jump" during initialization
+ *
+ * The lock is released either:
+ * 1. Automatically after a timeout (allowing for initial render and scroll stabilization)
+ * 2. Immediately when the user explicitly interacts with the form
+ */
+export const useCurrentActivePage = ({
+  pages,
+  defaultPage,
+  activePages,
+  evaluatedPagesVisibility,
+}: UseCurrentActivePageProps): UseCurrentActivePageResult => {
+  const [currentActivePage, setCurrentActivePage] = useState<string | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+  const [requestedPage, setRequestedPage] = useState<string | null>(null);
+  const isInitialPhaseRef = useRef(true);
+
+  // Initialize the active page
+  useEffect(() => {
+    if (isInitialized || !evaluatedPagesVisibility) return;
+
+    const initializePage = () => {
+      // Try to find and set the default page
+      const defaultPageObject = pages.find(({ label }) => label === defaultPage);
+
+      if (defaultPageObject && !defaultPageObject.isHidden) {
+        setCurrentActivePage(defaultPageObject.id);
+        scrollIntoView(defaultPageObject.id);
+      } else {
+        // Fall back to first visible page
+        const firstVisiblePage = pages.find((page) => !page.isHidden);
+        if (firstVisiblePage) {
+          setCurrentActivePage(firstVisiblePage.id);
+        }
+      }
+    };
+
+    initializePage();
+    setIsInitialized(true);
+  }, [pages, defaultPage, evaluatedPagesVisibility, isInitialized]);
+
+  useEffect(() => {
+    let initialLockTimeout = null;
+    // Lock out Waypoint updates for 200ms to allow for:
+    // 1. Initial render completion
+    // 2. Scroll position establishment
+    // 3. Waypoint to complete its initial visibility detection
+    if (isInitialized) {
+      initialLockTimeout = setTimeout(() => {
+        isInitialPhaseRef.current = false;
+      }, 200);
+    }
+
+    // Cleanup
+    return () => {
+      if (initialLockTimeout) {
+        clearTimeout(initialLockTimeout);
+      }
+    };
+  }, [isInitialized]);
+
+  // Handle active pages updates from viewport visibility
+  useEffect(() => {
+    if (isInitialPhaseRef.current) return;
+
+    let clearRequestTimeout: NodeJS.Timeout | null = null;
+
+    // If there's a requested page and it's visible, keep it active
+    if (requestedPage && activePages.includes(requestedPage)) {
+      setCurrentActivePage(requestedPage);
+      clearRequestTimeout = setTimeout(() => {
+        setRequestedPage(null);
+      }, 100);
+      return;
+    }
+
+    // If there's no requested page, use the topmost visible page
+    if (!requestedPage && activePages.length > 0) {
+      const topVisiblePage = activePages.reduce((top, current) => {
+        const topIndex = pages.findIndex((page) => page.id === top);
+        const currentIndex = pages.findIndex((page) => page.id === current);
+        return topIndex < currentIndex ? top : current;
+      });
+
+      setCurrentActivePage(topVisiblePage);
+    }
+
+    return () => {
+      if (clearRequestTimeout) {
+        clearTimeout(clearRequestTimeout);
+      }
+    };
+  }, [activePages, requestedPage, pages]);
+
+  // Handle page requests
+  const requestPage = useCallback((pageId: string) => {
+    isInitialPhaseRef.current = false; // Release the lock on explicit user interaction
+    setRequestedPage(pageId);
+    setCurrentActivePage(pageId);
+    scrollIntoView(pageId);
+  }, []);
+
+  return {
+    currentActivePage,
+    requestPage,
+  };
+};

package/src/components/sidebar/usePageObserver.ts

@@ -0,0 +1,45 @@
+import { useState, useEffect } from 'react';
+import { type FormPage } from '../../types';
+import { pageObserver } from './page-observer';
+
+interface PageObserverState {
+  pages: FormPage[];
+  pagesWithErrors: string[];
+  activePages: string[];
+  evaluatedPagesVisibility: boolean;
+  hasMultiplePages: boolean | null;
+}
+
+export const usePageObserver = () => {
+  const [state, setState] = useState<PageObserverState>({
+    pages: [],
+    pagesWithErrors: [],
+    activePages: [],
+    evaluatedPagesVisibility: false,
+    hasMultiplePages: null,
+  });
+
+  useEffect(() => {
+    const subscriptions = [
+      pageObserver.getScrollablePagesObservable().subscribe((pages) => {
+        setState((prev) => ({ ...prev, pages, hasMultiplePages: pages.length > 1 }));
+      }),
+
+      pageObserver.getPagesWithErrorsObservable().subscribe((errors) => {
+        setState((prev) => ({ ...prev, pagesWithErrors: Array.from(errors) }));
+      }),
+
+      pageObserver.getActivePagesObservable().subscribe((activePages) => {
+        setState((prev) => ({ ...prev, activePages: Array.from(activePages) }));
+      }),
+
+      pageObserver.getEvaluatedPagesVisibilityObservable().subscribe((evaluated) => {
+        setState((prev) => ({ ...prev, evaluatedPagesVisibility: evaluated }));
+      }),
+    ];
+
+    return () => subscriptions.forEach((sub) => sub.unsubscribe());
+  }, []);
+
+  return state;
+};

package/src/components/value/value.component.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import styles from './value.scss';
+import { useTranslation } from 'react-i18next';
+
+export const ValueEmpty = () => {
+  const { t } = useTranslation();
+
+  return (
+    <div>
+      <span className={styles.empty}>({t('blank', 'Blank')})</span>
+    </div>
+  );
+};
+
+export const ValueDisplay = ({ value }) => {
+  if (Array.isArray(value)) {
+    return <ListDisplay valueArray={value} />;
+  }
+  return <div className={styles.value}>{value}</div>;
+};
+
+const ListDisplay = ({ valueArray }) => {
+  return (
+    <ul>
+      {valueArray.map((item) => (
+        <li className={styles.item}>{item}</li>
+      ))}
+    </ul>
+  );
+};

package/src/components/value/value.scss

@@ -0,0 +1,17 @@
+@use '@carbon/colors';
+
+.value {
+  font-size: 0.875rem;
+  font-weight: 500;
+  color: colors.$gray-60;
+}
+
+.empty {
+  @extend .value;
+  color: colors.$gray-30;
+}
+
+.item {
+  @extend .value;
+  margin-bottom: 0.5rem;
+}

package/src/components/value/view/field-value-view.component.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { isEmpty } from '../../../validators/form-validator';
+import LabelField from '../../label/label.component';
+import { ValueDisplay, ValueEmpty } from '../value.component';
+import styles from './field-value-view.scss';
+
+interface FieldValueViewProps {
+  isInline: boolean;
+  label: string;
+  value: any;
+  conceptName: string;
+}
+
+const FieldValueView: React.FC<FieldValueViewProps> = ({ label, conceptName, value, isInline }) => (
+  <>
+    {isInline ? (
+      <div className={styles.inlineFlexRow}>
+        <div className={styles.inlineFlexColumn}>
+          <LabelField value={label} tooltipText={conceptName} />
+        </div>
+        <div className={styles.inlineFlexColumn}>
+          {isEmpty(value) ? <ValueEmpty /> : <ValueDisplay value={value} />}
+        </div>
+      </div>
+    ) : (
+      <div className={styles.readonly}>
+        <div className={styles.formField}>
+          <LabelField value={label} tooltipText={conceptName} />
+          <div className={styles.value}>{isEmpty(value) ? <ValueEmpty /> : <ValueDisplay value={value} />}</div>
+        </div>
+      </div>
+    )}
+  </>
+);
+
+export default FieldValueView;

package/src/components/value/view/field-value-view.scss

@@ -0,0 +1,31 @@
+@use '@carbon/colors';
+
+.formField {
+  margin-top: 10px;
+}
+
+.formField > div > div > label {
+  color: colors.$gray-70;
+}
+
+.readonly {
+  border-bottom: 0.5px colors.$gray-30;
+  border-style: solid;
+}
+
+.readonly > div {
+  padding-bottom: 7px !important;
+}
+
+.value {
+  color: colors.$gray-70;
+}
+
+.inlineFlexRow {
+  display: flex;
+  flex-wrap: wrap;
+}
+
+.inlineFlexColumn {
+  width: 300px;
+}

package/src/constants.ts

@@ -0,0 +1,14 @@
+export const ConceptTrue = 'cf82933b-3f3f-45e7-a5ab-5d31aaee3da3';
+export const ConceptFalse = '488b58ff-64f5-4f8a-8979-fa79940b1594';
+export const UnspecifiedValue = 'VALUE_UNSPECIFIED';
+export const encounterRepresentation =
+  'custom:(uuid,encounterDatetime,encounterType:(uuid,name,description),location:(uuid,name),' +
+  'patient:(uuid,display),encounterProviders:(uuid,provider:(uuid,name),encounterRole:(uuid,name)),' +
+  'orders:(uuid,display,concept:(uuid,display),voided),' +
+  'diagnoses:(uuid,certainty,condition,formFieldPath,formFieldNamespace,display,rank,voided,diagnosis:(coded:(uuid,display))),' +
+  'obs:(uuid,obsDatetime,comment,voided,groupMembers,formFieldNamespace,formFieldPath,concept:(uuid,name:(uuid,name)),value:(uuid,name:(uuid,name),' +
+  'names:(uuid,conceptNameType,name))))';
+export const FormsStore = 'forms-engine-store';
+export const PatientChartWorkspaceHeaderSlot = 'patient-chart-workspace-header-slot';
+export const codedTypes = ['radio', 'checkbox', 'select', 'content-switcher'];
+export const NullSelectOption = 'OPTION_NULL';

package/src/datasources/concept-data-source.ts

@@ -0,0 +1,42 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { BaseOpenMRSDataSource } from './data-source';
+import { isEmpty } from '../validators/form-validator';
+
+export class ConceptDataSource extends BaseOpenMRSDataSource {
+  constructor() {
+    super(`${restBaseUrl}/concept?v=custom:(uuid,display,conceptClass:(uuid,display))`);
+  }
+
+  fetchData(searchTerm: string, config?: Record<string, any>): Promise<any[]> {
+    if (isEmpty(config?.class) && isEmpty(config?.concept) && !config?.useSetMembersByConcept && isEmpty(searchTerm)) {
+      return Promise.resolve([]);
+    }
+
+    let searchUrl = `${restBaseUrl}/concept?name=&searchType=fuzzy&v=custom:(uuid,display,conceptClass:(uuid,display))`;
+    if (config?.class) {
+      if (typeof config.class == 'string') {
+        const urlParts = searchUrl.split('searchType=fuzzy');
+        searchUrl = `${urlParts[0]}searchType=fuzzy&class=${config.class}&${urlParts[1]}`;
+      } else {
+        return openmrsFetch(searchTerm ? `${searchUrl}&q=${searchTerm}` : searchUrl).then(({ data }) => {
+          return data.results.filter(
+            (concept) => concept.conceptClass && config.class.includes(concept.conceptClass.uuid),
+          );
+        });
+      }
+    }
+
+    if (config?.concept && config?.useSetMembersByConcept) {
+      let urlParts = searchUrl.split('?name=&searchType=fuzzy&v=');
+      searchUrl = `${urlParts[0]}/${config.concept}?v=custom:(uuid,setMembers:(uuid,display))`;
+      return openmrsFetch(searchTerm ? `${searchUrl}&q=${searchTerm}` : searchUrl).then(({ data }) => {
+        // return the setMembers from the retrieved concept object
+        return data['setMembers'];
+      });
+    }
+
+    return openmrsFetch(searchTerm ? `${searchUrl}&q=${searchTerm}` : searchUrl).then(({ data }) => {
+      return data.results;
+    });
+  }
+}

package/src/datasources/data-source.ts

@@ -0,0 +1,34 @@
+import { openmrsFetch, type OpenmrsResource } from '@openmrs/esm-framework';
+import { type DataSource } from '../types';
+
+export class BaseOpenMRSDataSource implements DataSource<OpenmrsResource> {
+  url: string;
+
+  constructor(url: string) {
+    this.url = url;
+  }
+
+  fetchData(searchTerm: string): Promise<any[]> {
+    return openmrsFetch(searchTerm ? `${this.url}&q=${searchTerm}` : this.url).then(({ data }) => {
+      return data.results;
+    });
+  }
+
+  fetchSingleItem(uuid: string): Promise<OpenmrsResource | null> {
+    let apiUrl = this.url;
+    if (apiUrl.includes('?')) {
+      const urlParts = apiUrl.split('?');
+      apiUrl = `${urlParts[0]}/${uuid}?${urlParts[1]}`;
+    } else {
+      apiUrl = `${apiUrl}/${uuid}`;
+    }
+    return openmrsFetch(apiUrl).then(({ data }) => data);
+  }
+
+  toUuidAndDisplay(data: OpenmrsResource): OpenmrsResource {
+    if (typeof data.uuid === 'undefined' || typeof data.display === 'undefined') {
+      throw new Error("'uuid' or 'display' not found in the OpenMRS object.");
+    }
+    return data;
+  }
+}

package/src/datasources/encounter-role-datasource.ts

@@ -0,0 +1,15 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { BaseOpenMRSDataSource } from './data-source';
+
+export class EncounterRoleDataSource extends BaseOpenMRSDataSource {
+  constructor() {
+    super(null);
+  }
+
+  async fetchData(searchTerm: string, config?: Record<string, any>): Promise<any[]> {
+    const rep = 'v=custom:(uuid,display,name)';
+    const url = `${restBaseUrl}/encounterrole?${rep}`;
+    const { data } = await openmrsFetch(searchTerm ? `${url}&q=${searchTerm}` : url);
+    return data?.results;
+  }
+}

package/src/datasources/historical-data-source.ts

@@ -0,0 +1,11 @@
+export class HistoricalDataSourceService {
+  dataSourceMap: Record<string, any> = {};
+
+  putObject(key: string, value: any) {
+    this.dataSourceMap[key] = value;
+  }
+
+  getObject(key: string) {
+    return this.dataSourceMap[key];
+  }
+}

package/src/datasources/location-data-source.ts

@@ -0,0 +1,27 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { BaseOpenMRSDataSource } from './data-source';
+
+export class LocationDataSource extends BaseOpenMRSDataSource {
+  constructor() {
+    super(`${restBaseUrl}/location?v=custom:(uuid,display)`);
+  }
+
+  fetchData(searchTerm: string, config?: Record<string, any>, uuid?: string): Promise<any[]> {
+    let apiUrl = this.url;
+    const urlParts = apiUrl.split('?');
+    if (config?.tag) {
+      apiUrl = `${urlParts[0]}?tag=${config.tag}&${urlParts[1]}`;
+    }
+    //overwrite url if there's a uuid value, meaning we are in edit mode
+    if (uuid) {
+      apiUrl = `${urlParts[0]}/${uuid}?${urlParts[1]}`;
+    }
+
+    return openmrsFetch(searchTerm ? `${apiUrl}&q=${searchTerm}` : apiUrl).then(({ data }) => {
+      if (data.results) {
+        return data.results;
+      }
+      return data;
+    });
+  }
+}

package/src/datasources/provider-datasource.ts

@@ -0,0 +1,15 @@
+import { openmrsFetch, restBaseUrl } from '@openmrs/esm-framework';
+import { BaseOpenMRSDataSource } from './data-source';
+
+export class ProviderDataSource extends BaseOpenMRSDataSource {
+  constructor() {
+    super(null);
+  }
+
+  async fetchData(searchTerm: string, config?: Record<string, any>): Promise<any[]> {
+    const rep = 'v=custom:(uuid,display)';
+    const url = `${restBaseUrl}/provider?${rep}`;
+    const { data } = await openmrsFetch(searchTerm ? `${url}&q=${searchTerm}` : url);
+    return data?.results;
+  }
+}

package/src/datasources/select-concept-answers-datasource.ts

@@ -0,0 +1,25 @@
+import { openmrsFetch, type OpenmrsResource, restBaseUrl } from '@openmrs/esm-framework';
+import { BaseOpenMRSDataSource } from './data-source';
+
+export class SelectConceptAnswersDatasource extends BaseOpenMRSDataSource {
+  constructor() {
+    super(
+      `${restBaseUrl}/concept/:conceptUuid?v=custom:(uuid,display,setMembers:(uuid,display),answers:(uuid,display))`,
+    );
+  }
+
+  fetchSingleItem(uuid: string): Promise<OpenmrsResource | null> {
+    return openmrsFetch(this.buildUrl(uuid)).then(({ data }) => data);
+  }
+
+  fetchData(searchTerm: string, config?: Record<string, any>): Promise<any[]> {
+    const apiUrl = this.buildUrl(config.referencedValue || config.concept);
+    return openmrsFetch(apiUrl).then(({ data }) => {
+      return data['setMembers'].length ? data['setMembers'] : data['answers'];
+    });
+  }
+
+  private buildUrl(conceptUuid: string): string {
+    return this.url.replace(':conceptUuid', conceptUuid);
+  }
+}

package/src/declarations.d.ts

@@ -0,0 +1,2 @@
+declare module '*.css';
+declare module '*.scss';

package/src/external-function-context.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { FormField } from './types';
+
+export type ExternalFunctionContextProps = {
+  handleConfirmQuestionDeletion: (question: Readonly<FormField>) => Promise<void>;
+};
+
+export const ExternalFunctionContext = React.createContext<ExternalFunctionContextProps | undefined>(undefined);