@aehrc/smart-forms-renderer 0.30.2 → 0.31.0

package/src/utils/initialise.ts

@@ -26,7 +26,7 @@ import type {
   QuestionnaireResponseItem,
   QuestionnaireResponseItemAnswer
 } from 'fhir/r4';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import type { Tabs } from '../interfaces/tab.interface';
 import { assignPopulatedAnswersToEnableWhen } from './enableWhen';
 import type { CalculatedExpression } from '../interfaces/calculatedExpression.interface';
@@ -34,7 +34,7 @@ import { evaluateInitialCalculatedExpressions } from './calculatedExpression';
 import { createQuestionnaireResponseItemMap } from './questionnaireResponseStoreUtils/updatableResponseItems';
 
 /**
- * Initialise a conformant questionnaireResponse from a given questionnaire
+ * Initialise a questionnaireResponse from a given questionnaire
  * optionally takes in an existing questionnaireResponse to be initialised
  *
  * @author Sean Fong

package/src/utils/manageForm.ts

@@ -0,0 +1,110 @@
+import type { Questionnaire, QuestionnaireResponse } from 'fhir/r4';
+import { questionnaireResponseStore, questionnaireStore, smartConfigStore } from '../stores';
+import { initialiseQuestionnaireResponse } from './initialise';
+import { removeEmptyAnswers } from './removeEmptyAnswers';
+import { readEncounter, readPatient, readUser } from '../api/smartClient';
+import type Client from 'fhirclient/lib/Client';
+
+/**
+ * Build the form with an initial Questionnaire and an optional filled QuestionnaireResponse.
+ * If a QuestionnaireResponse is not provided, an empty QuestionnaireResponse is set as the initial QuestionnaireResponse.
+ * There are other optional properties such as applying readOnly, providing a terminology server url and additional variables.
+ *
+ * @param questionnaire - Questionnaire to be rendered
+ * @param questionnaireResponse - Pre-populated/draft/loaded QuestionnaireResponse to be rendered (optional)
+ * @param readOnly - Applies read-only mode to all items in the form view
+ * @param terminologyServerUrl - Terminology server url to fetch terminology. If not provided, the default terminology server will be used. (optional)
+ * @param additionalVariables - Additional key-value pair of SDC variables `Record<name, variable extension>` for testing (optional)
+ *
+ * @author Sean Fong
+ */
+export async function buildForm(
+  questionnaire: Questionnaire,
+  questionnaireResponse?: QuestionnaireResponse,
+  readOnly?: boolean,
+  terminologyServerUrl?: string,
+  additionalVariables?: Record<string, object>
+): Promise<void> {
+  // QR is set to undefined here to prevent it from being initialised twice. This is defined like that for backward compatibility purposes.
+  await questionnaireStore
+    .getState()
+    .buildSourceQuestionnaire(questionnaire, undefined, additionalVariables, terminologyServerUrl);
+
+  const initialisedQuestionnaireResponse = initialiseQuestionnaireResponse(
+    questionnaire,
+    questionnaireResponse
+  );
+  questionnaireResponseStore.getState().buildSourceResponse(initialisedQuestionnaireResponse);
+  questionnaireStore.getState().updatePopulatedProperties(initialisedQuestionnaireResponse);
+
+  if (readOnly) {
+    questionnaireStore.getState().setFormAsReadOnly(readOnly);
+  }
+}
+
+/**
+ * Destroy the form to clean up the questionnaire and questionnaireResponse stores.
+ *
+ * @author Sean Fong
+ */
+export function destroyForm(): void {
+  questionnaireStore.getState().destroySourceQuestionnaire();
+  questionnaireResponseStore.getState().destroySourceResponse();
+}
+
+/**
+ * Initialise the FHIRClient object to make further FHIR calls in the renderer.
+ * Note that this does not provide pre-population capabilities.
+ *
+ * @param fhirClient - FHIRClient object to perform further FHIR calls. At the moment it's only used in answerExpressions
+ *
+ * @author Sean Fong
+ */
+export async function initialiseFhirClient(fhirClient: Client): Promise<void> {
+  smartConfigStore.getState().setClient(fhirClient);
+  const patientPromise = readPatient(fhirClient);
+  const userPromise = readUser(fhirClient);
+  const encounterPromise = readEncounter(fhirClient);
+
+  const [patient, user, encounter] = await Promise.all([
+    patientPromise,
+    userPromise,
+    encounterPromise
+  ]);
+  smartConfigStore.getState().setPatient(patient);
+  smartConfigStore.getState().setUser(user);
+  smartConfigStore.getState().setEncounter(encounter);
+}
+
+/**
+ * Get the filled QuestionnaireResponse at its current state.
+ * If no changes have been made to the form, the initial QuestionnaireResponse is returned.
+ *
+ * @author Sean Fong
+ */
+export function getResponse(): QuestionnaireResponse {
+  return questionnaireResponseStore.getState().updatableResponse;
+}
+
+/**
+ * Remove all hidden answers from the filled QuestionnaireResponse.
+ * This takes into account enableWhens, enableWhenExpressions, items without item.answer, empty item.answer arrays and empty strings.
+ *
+ * @author Sean Fong
+ */
+export function removeEmptyAnswersFromResponse(
+  questionnaire: Questionnaire,
+  questionnaireResponse: QuestionnaireResponse
+): QuestionnaireResponse {
+  const enableWhenIsActivated = questionnaireStore.getState().enableWhenIsActivated;
+  const enableWhenItems = questionnaireStore.getState().enableWhenItems;
+  const enableWhenExpressions = questionnaireStore.getState().enableWhenExpressions;
+
+  return removeEmptyAnswers({
+    questionnaire,
+    questionnaireResponse,
+    enableWhenIsActivated,
+    enableWhenItems,
+    enableWhenExpressions
+  });
+}

package/src/utils/qItem.ts

@@ -19,7 +19,7 @@ import type { Extension, Questionnaire, QuestionnaireItem } from 'fhir/r4';
 import { getChoiceControlType } from './choice';
 import { ChoiceItemControl, OpenChoiceItemControl } from '../interfaces/choice.enum';
 import { getOpenChoiceControlType } from './openChoice';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 
 interface isHiddenByEnableWhensParams {
   linkId: string;

package/src/utils/questionnaireStoreUtils/extractOtherExtensions.ts

@@ -31,7 +31,7 @@ import type {
   EnableWhenSingleExpression,
   EnableWhenSingleItemProperties,
   EnableWhenSingleLinkedItem
-} from '../../interfaces';
+} from '../../interfaces/enableWhen.interface';
 import type { AnswerExpression } from '../../interfaces/answerExpression.interface';
 import type { ValueSetPromise } from '../../interfaces/valueSet.interface';
 import { getTerminologyServerUrl, getValueSetPromise } from '../valueSet';

package/src/utils/removeEmptyAnswers.ts

@@ -21,7 +21,7 @@ import type {
   QuestionnaireResponse,
   QuestionnaireResponseItem
 } from 'fhir/r4';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import { isHiddenByEnableWhen } from './qItem';
 
 interface removeEmptyAnswersParams {

package/src/utils/repopulateIntoResponse.ts

@@ -7,6 +7,23 @@ import type {
 import type { ItemToRepopulate } from './repopulateItems';
 import { getQrItemsIndex, mapQItemsIndex } from './mapItem';
 import { isSpecificItemControl } from './itemControl';
+import { questionnaireResponseStore, questionnaireStore } from '../stores';
+
+/**
+ * Re-populate checked items in the re-population dialog into the current QuestionnaireResponse
+ *
+ * @author Sean Fong
+ */
+export function repopulateResponse(checkedItemsToRepopulate: Record<string, ItemToRepopulate>) {
+  const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
+  const updatableResponse = questionnaireResponseStore.getState().updatableResponse;
+
+  return repopulateItemsIntoResponse(
+    sourceQuestionnaire,
+    updatableResponse,
+    checkedItemsToRepopulate
+  );
+}
 
 export function repopulateItemsIntoResponse(
   questionnaire: Questionnaire,

package/src/utils/repopulateItems.ts

@@ -26,9 +26,22 @@ import _isEqual from 'lodash/isEqual';
 import { containsTabs, isTabContainer } from './tabs';
 import { getShortText, isSpecificItemControl } from './itemControl';
 import { getQrItemsIndex, mapQItemsIndex } from './mapItem';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import { isHiddenByEnableWhen } from './qItem';
+import { questionnaireResponseStore, questionnaireStore } from '../stores';
 
+/**
+ * ItemToRepopulate interface
+ *
+ * @property qItem - The QuestionnaireItem to repopulate
+ * @property heading - The heading of the group to repopulate
+ * @property newQRItem - The new QuestionnaireResponseItem to replace the old one
+ * @property oldQRItem - The old QuestionnaireResponseItem to be replaced
+ * @property newQRItems - The new QuestionnaireResponseItems to replace the old ones
+ * @property oldQRItems - The old QuestionnaireResponseItems to be replaced
+ *
+ * @author Sean Fong
+ */
 export interface ItemToRepopulate {
   qItem: QuestionnaireItem | null;
   heading: string | null;
@@ -52,6 +65,30 @@ interface getItemsToRepopulateParams {
   enableWhenExpressions: EnableWhenExpressions;
 }
 
+/**
+ * Compare latest data from the server with the current QuestionnaireResponse and decide items to re-populate
+ *
+ * @author Sean Fong
+ */
+export function generateItemsToRepopulate(populatedResponse: QuestionnaireResponse) {
+  const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
+  const tabs = questionnaireStore.getState().tabs;
+  const updatableResponse = questionnaireResponseStore.getState().updatableResponse;
+  const enableWhenIsActivated = questionnaireStore.getState().enableWhenIsActivated;
+  const enableWhenItems = questionnaireStore.getState().enableWhenItems;
+  const enableWhenExpressions = questionnaireStore.getState().enableWhenExpressions;
+
+  return getItemsToRepopulate({
+    sourceQuestionnaire,
+    tabs,
+    populatedResponse,
+    updatableResponse,
+    enableWhenIsActivated,
+    enableWhenItems,
+    enableWhenExpressions
+  });
+}
+
 export function getItemsToRepopulate(
   params: getItemsToRepopulateParams
 ): Record<string, ItemToRepopulate> {

package/src/utils/tabs.ts

@@ -16,7 +16,7 @@
  */
 
 import type { Tabs } from '../interfaces/tab.interface';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import type { Coding, QuestionnaireItem } from 'fhir/r4';
 import { isSpecificItemControl } from './itemControl';
 import { isHiddenByEnableWhen } from './qItem';
@@ -106,7 +106,7 @@ export function isTab(item: QuestionnaireItem) {
 }
 
 /**
- * Create a <linkId, {isComplete: boolean}> key-value pair for all tabbed items in a qItem array
+ * Create a `Record<linkId, {isComplete: boolean}>` key-value pair for all tabbed items in a qItem array
  *
  * @author Sean Fong
  */

package/src/utils/validateQuestionnaire.ts

@@ -25,7 +25,7 @@ import type {
   QuestionnaireResponseItemAnswer
 } from 'fhir/r4';
 import { getQrItemsIndex, mapQItemsIndex } from './mapItem';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import { isHiddenByEnableWhen } from './qItem';
 import {
   getDecimalPrecision,
@@ -39,6 +39,7 @@ import { structuredDataCapture } from 'fhir-sdc-helpers';
 import type { RegexValidation } from '../interfaces/regex.interface';
 import { parseDecimalStringToFloat } from './parseInputs';
 import dayjs from 'dayjs';
+import { questionnaireStore } from '../stores';
 
 export enum ValidationResult {
   unknown = 'unknown', // Unknown validation result
@@ -85,9 +86,6 @@ export enum ValidationResult {
 interface ValidateQuestionnaireParams {
   questionnaire: Questionnaire;
   questionnaireResponse: QuestionnaireResponse;
-  enableWhenIsActivated: boolean;
-  enableWhenItems: EnableWhenItems;
-  enableWhenExpressions: EnableWhenExpressions;
 }
 
 /**
@@ -99,23 +97,20 @@ interface ValidateQuestionnaireParams {
 export function validateQuestionnaire(
   params: ValidateQuestionnaireParams
 ): Record<string, OperationOutcome> {
-  const {
-    questionnaire,
-    questionnaireResponse,
-    enableWhenIsActivated,
-    enableWhenItems,
-    enableWhenExpressions
-  } = params;
+  const { questionnaire, questionnaireResponse } = params;
 
-  if (
-    !questionnaire.item ||
-    questionnaire.item.length === 0 ||
-    !questionnaireResponse.item ||
-    questionnaireResponse.item.length === 0
-  ) {
+  const enableWhenIsActivated = questionnaireStore.getState().enableWhenIsActivated;
+  const enableWhenItems = questionnaireStore.getState().enableWhenItems;
+  const enableWhenExpressions = questionnaireStore.getState().enableWhenExpressions;
+
+  if (!questionnaire.item || questionnaire.item.length === 0) {
     return {};
   }
 
+  if (!questionnaireResponse.item || questionnaireResponse.item.length === 0) {
+    questionnaireResponse.item = [];
+  }
+
   const qItemsIndexMap = mapQItemsIndex(questionnaire);
   const topLevelQRItemsByIndex = getQrItemsIndex(
     questionnaire.item,

package/vite.config.ts

@@ -26,7 +26,7 @@ export default defineConfig({
   },
   build: {
     commonjsOptions: {
-      include: [/node_modules/, '@aehrc/sdc-populate']
+      include: ['@aehrc/sdc-populate']
     }
   },
   resolve: { preserveSymlinks: true }

package/src/hooks/useInitialiseRenderer.ts

@@ -1,114 +0,0 @@
-/*
- * Copyright 2024 Commonwealth Scientific and Industrial Research
- * Organisation (CSIRO) ABN 41 687 119 230.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import type { Questionnaire, QuestionnaireResponse } from 'fhir/r4';
-import { useLayoutEffect, useState } from 'react';
-import { initialiseQuestionnaireResponse } from '../utils';
-import type Client from 'fhirclient/lib/Client';
-import { readEncounter, readPatient, readUser } from '../api/smartClient';
-import {
-  useQuestionnaireResponseStore,
-  useQuestionnaireStore,
-  useSmartConfigStore,
-  useTerminologyServerStore
-} from '../stores';
-
-function useInitialiseRenderer(
-  questionnaire: Questionnaire,
-  questionnaireResponse?: QuestionnaireResponse,
-  additionalVariables?: Record<string, object>,
-  terminologyServerUrl?: string,
-  fhirClient?: Client,
-  readOnly?: boolean
-): boolean {
-  const buildSourceQuestionnaire = useQuestionnaireStore.use.buildSourceQuestionnaire();
-  const updatePopulatedProperties = useQuestionnaireStore.use.updatePopulatedProperties();
-  const buildSourceResponse = useQuestionnaireResponseStore.use.buildSourceResponse();
-  const setUpdatableResponseAsPopulated =
-    useQuestionnaireResponseStore.use.setUpdatableResponseAsPopulated();
-
-  const setTerminologyServerUrl = useTerminologyServerStore.use.setUrl();
-  const resetTerminologyServerUrl = useTerminologyServerStore.use.resetUrl();
-  const setSmartClient = useSmartConfigStore.use.setClient();
-  const setPatient = useSmartConfigStore.use.setPatient();
-  const setUser = useSmartConfigStore.use.setUser();
-  const setEncounter = useSmartConfigStore.use.setEncounter();
-
-  const [loading, setLoading] = useState(true);
-
-  useLayoutEffect(() => {
-    setLoading(true);
-    // set fhirClient if provided
-    if (fhirClient) {
-      setSmartClient(fhirClient);
-      readPatient(fhirClient).then((patient) => {
-        setPatient(patient);
-      });
-      readUser(fhirClient).then((user) => {
-        setUser(user);
-      });
-      readEncounter(fhirClient).then((encounter) => {
-        setEncounter(encounter);
-      });
-    }
-
-    // set terminology server url if provided, otherwise reset it back to ontoserver
-    if (terminologyServerUrl) {
-      setTerminologyServerUrl(terminologyServerUrl);
-    } else {
-      resetTerminologyServerUrl();
-    }
-
-    // initialise form including enableWhen, enableWhenExpressions, calculatedExpressions, initialExpressions, answerExpressions, cache answerValueSets
-    buildSourceQuestionnaire(
-      questionnaire,
-      questionnaireResponse,
-      additionalVariables,
-      terminologyServerUrl,
-      readOnly
-    ).then(() => {
-      buildSourceResponse(initialiseQuestionnaireResponse(questionnaire));
-
-      if (questionnaireResponse) {
-        const updatedResponse = updatePopulatedProperties(questionnaireResponse);
-        setUpdatableResponseAsPopulated(updatedResponse);
-      }
-      setLoading(false);
-    });
-  }, [
-    questionnaire,
-    questionnaireResponse,
-    buildSourceQuestionnaire,
-    buildSourceResponse,
-    setUpdatableResponseAsPopulated,
-    updatePopulatedProperties,
-    additionalVariables,
-    fhirClient,
-    setSmartClient,
-    setPatient,
-    setUser,
-    setEncounter,
-    terminologyServerUrl,
-    setTerminologyServerUrl,
-    resetTerminologyServerUrl,
-    readOnly
-  ]);
-
-  return loading;
-}
-
-export default useInitialiseRenderer;