@aehrc/smart-forms-renderer 1.0.0-alpha.98 → 1.0.0

package/lib/stores/questionnaireStore.d.ts

@@ -1,17 +1,17 @@
 import type { Coding, Questionnaire, QuestionnaireItem, QuestionnaireResponse, QuestionnaireResponseItemAnswer } from 'fhir/r4';
-import type { Variables } from '../interfaces/variables.interface';
-import type { LaunchContext } from '../interfaces/populate.interface';
+import type { ComponentType } from 'react';
+import type { QItemOverrideComponentProps, SdcUiOverrideComponentProps } from '../interfaces';
+import type { AnswerExpression } from '../interfaces/answerExpression.interface';
+import type { AnswerOptionsToggleExpression } from '../interfaces/answerOptionsToggleExpression.interface';
 import type { CalculatedExpression } from '../interfaces/calculatedExpression.interface';
 import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
-import type { AnswerExpression } from '../interfaces/answerExpression.interface';
-import type { Tabs } from '../interfaces/tab.interface';
-import type { Pages } from '../interfaces/page.interface';
 import type { InitialExpression } from '../interfaces/initialExpression.interface';
-import type { QItemOverrideComponentProps, SdcUiOverrideComponentProps } from '../interfaces';
-import type { ComponentType } from 'react';
+import type { Pages } from '../interfaces/page.interface';
+import type { LaunchContext } from '../interfaces/populate.interface';
+import type { Tabs } from '../interfaces/tab.interface';
 import type { TargetConstraint } from '../interfaces/targetConstraint.interface';
 import type { ProcessedValueSet } from '../interfaces/valueSet.interface';
-import type { AnswerOptionsToggleExpression } from '../interfaces/answerOptionsToggleExpression.interface';
+import type { Variables } from '../interfaces/variables.interface';
 /**
  * QuestionnaireStore properties and methods
  * Properties can be accessed for fine-grain details.
@@ -26,6 +26,9 @@ import type { AnswerOptionsToggleExpression } from '../interfaces/answerOptionsT
  * @property currentPageIndex - Index of the current page
  * @property variables - Questionnaire variables object containing FHIRPath and x-fhir-query variables
  * @property launchContexts - Key-value pair of launch contexts `Record<launch context name, launch context properties>`
+ * @property initialExpressions - Key-value pair of initial expressions `Record<linkId, InitialExpression>`
+ * @property answerExpressions - Key-value pair of answer expressions `Record<linkId, answer expression properties>`
+ * @property calculatedExpressions - Key-value pair of calculated expressions `Record<linkId, array of calculated expression properties>`
  * @property targetConstraints - Key-value pair of target constraints `Record<target constraint key, target constraint properties>`
  * @property targetConstraintLinkIds - Key-value pair of linkIds against target constraint key(s) `Record<linkId, target constraint keys>`
  * @property answerOptionsToggleExpressions - Key-value pair of answer options toggle expressions `Record<linkId, array of answer options toggle expressions>`
@@ -33,13 +36,11 @@ import type { AnswerOptionsToggleExpression } from '../interfaces/answerOptionsT
  * @property enableWhenLinkedQuestions - Key-value pair of linked questions to enableWhen items `Record<linkId, linkIds of linked questions>`
  * @property enableWhenIsActivated - Flag to turn enableWhen checks on/off
  * @property enableWhenExpressions - EnableWhenExpressions object containing enableWhen expressions
- * @property calculatedExpressions - Key-value pair of calculated expressions `Record<linkId, array of calculated expression properties>`
- * @property answerExpressions - Key-value pair of answer expressions `Record<linkId, answer expression properties>`
  * @property processedValueSets - Key-value pair of (pre-)processed value set codings `Record<valueSetUrl, ProcessedValueSet>`
  * @property cachedValueSetCodings - Key-value pair of cached value set codings `Record<valueSetUrl, codings>`
  * @property fhirPathContext - Key-value pair of evaluated FHIRPath values `Record<variable name, evaluated value(s)>`
  * @property fhirPathTerminologyCache - Key-value pair of cached FHIRPath Terminology results `Record<cacheKey, cached terminology result>`
- * @property populatedContext - Key-value pair of one-off pre-populated FHIRPath values `Record<variable/launchContext/sourceQueries batch name, evaluated value(s)>`
+ * @property additionalContext - Key-value pair of additional/pre-populated FHIRPath values `Record<variable/launchContext/sourceQueries batch name, evaluated value(s)>`
  * @property qItemOverrideComponents - Key-value pair of React component overrides for Questionnaire Items via linkId `Record<linkId, React component>`
  * @property sdcUiOverrideComponents - Key-value pair of React component overrides for SDC UI Controls https://hl7.org/fhir/extensions/ValueSet-questionnaire-item-control.html `Record<SDC UI code, React component>`
  * @property focusedLinkId - LinkId of the currently focused item
@@ -50,14 +51,15 @@ import type { AnswerOptionsToggleExpression } from '../interfaces/answerOptionsT
  * @property switchPage - Used to switch the current page index
  * @property markTabAsComplete - Used to mark a tab index as complete
  * @property markPageAsComplete - Used to mark a page index as complete
+ * @property resetToFirstVisibleTab - Used to reset the current tab to the first visible tab
+ * @property resetToFirstVisiblePage - Used to reset the current page to the first visible page
  * @property updateEnableWhenItem - Used to update linked enableWhen items by updating a question with a new answer
  * @property mutateRepeatEnableWhenItems - Used to add or remove instances of repeating enableWhen items
  * @property toggleEnableWhenActivation - Used to toggle enableWhen checks on/off
- * @property updateExpressions - Used to update all SDC expressions based on the updated questionnaire response
+ * @property updateExpressions - Used to update all SDC expressions based on the updated questionnaire response, initialUpdate flag is to ensure formChangesHistory is not updated during the first update after form build
  * @property addCodingToCache - Used to add a coding to the cached value set codings
- * @property updatePopulatedProperties - Used to update all SDC expressions based on a pre-populated questionnaire response
  * @property onFocusLinkId - Used to set the focused linkId
- * @property setPopulatedContext - Used to set the populated contexts (launchContext, sourceQueries, x-fhir-query vars) for debugging purposes, and optionally add to the FHIRPath context
+ * @property setAdditionalContext - Optionally used to set additional context information for FHIRPath eval. Useful to pass pre-populated context into the renderer. If you are rebuilding the form on pre-populate, you don't need to use this. pass `additionalContext` directly into buildForm().
  * @property setFormAsReadOnly - Used to set the form as read-only
  *
  * @author Sean Fong
@@ -72,45 +74,46 @@ export interface QuestionnaireStoreType {
     currentPageIndex: number;
     variables: Variables;
     launchContexts: Record<string, LaunchContext>;
+    initialExpressions: Record<string, InitialExpression>;
+    answerExpressions: Record<string, AnswerExpression>;
+    calculatedExpressions: Record<string, CalculatedExpression[]>;
     targetConstraints: Record<string, TargetConstraint>;
     targetConstraintLinkIds: Record<string, string[]>;
-    answerOptionsToggleExpressions: Record<string, AnswerOptionsToggleExpression[]>;
     enableWhenItems: EnableWhenItems;
     enableWhenLinkedQuestions: Record<string, string[]>;
     enableWhenIsActivated: boolean;
     enableWhenExpressions: EnableWhenExpressions;
-    calculatedExpressions: Record<string, CalculatedExpression[]>;
-    initialExpressions: Record<string, InitialExpression>;
-    answerExpressions: Record<string, AnswerExpression>;
+    answerOptionsToggleExpressions: Record<string, AnswerOptionsToggleExpression[]>;
     processedValueSets: Record<string, ProcessedValueSet>;
     cachedValueSetCodings: Record<string, Coding[]>;
     fhirPathContext: Record<string, any>;
     fhirPathTerminologyCache: Record<string, any>;
-    populatedContext: Record<string, any>;
+    additionalContext: Record<string, any>;
     qItemOverrideComponents: Record<string, ComponentType<QItemOverrideComponentProps>>;
     sdcUiOverrideComponents: Record<string, ComponentType<SdcUiOverrideComponentProps>>;
     focusedLinkId: string;
     readOnly: boolean;
-    buildSourceQuestionnaire: (questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse, additionalVariables?: Record<string, any>, terminologyServerUrl?: string, readOnly?: boolean, qItemOverrideComponents?: Record<string, ComponentType<QItemOverrideComponentProps>>, sdcUiOverrideComponents?: Record<string, ComponentType<SdcUiOverrideComponentProps>>) => Promise<void>;
+    buildSourceQuestionnaire: (questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse, additionalContext?: Record<string, any>, terminologyServerUrl?: string, readOnly?: boolean, qItemOverrideComponents?: Record<string, ComponentType<QItemOverrideComponentProps>>, sdcUiOverrideComponents?: Record<string, ComponentType<SdcUiOverrideComponentProps>>) => Promise<void>;
     destroySourceQuestionnaire: () => void;
     switchTab: (newTabIndex: number) => void;
     switchPage: (newPageIndex: number) => void;
     markTabAsComplete: (tabLinkId: string) => void;
     markPageAsComplete: (pageLinkId: string) => void;
+    resetToFirstVisibleTab: () => void;
+    resetToFirstVisiblePage: () => void;
     updateEnableWhenItem: (linkId: string, newAnswer: QuestionnaireResponseItemAnswer[] | undefined, parentRepeatGroupIndex: number | null) => void;
     mutateRepeatEnableWhenItems: (parentRepeatGroupLinkId: string, parentRepeatGroupIndex: number, actionType: 'add' | 'remove') => void;
     toggleEnableWhenActivation: (isActivated: boolean) => void;
-    updateExpressions: (updatedResponse: QuestionnaireResponse) => Promise<void>;
+    updateExpressions: (updatedResponse: QuestionnaireResponse, isInitialUpdate: boolean) => Promise<void>;
     addCodingToCache: (valueSetUrl: string, codings: Coding[]) => void;
-    updatePopulatedProperties: (populatedResponse: QuestionnaireResponse, populatedContext?: Record<string, any>, persistTabIndex?: boolean) => Promise<QuestionnaireResponse>;
     onFocusLinkId: (linkId: string) => void;
-    setPopulatedContext: (newPopulatedContext: Record<string, any>, addToFhirPathContext?: boolean) => void;
+    setAdditionalContext: (additionalContext: Record<string, any>) => void;
     setFormAsReadOnly: (readOnly: boolean) => void;
 }
 /**
  * Questionnaire state management store which contains all properties and methods to manage the state of the questionnaire.
  * This is the vanilla version of the store which can be used in non-React environments.
- * @see QuestionnaireStoreType for available properties and methods.
+ * @see {@link QuestionnaireStoreType} for available properties and methods.
  *
  * @author Sean Fong
  */
@@ -118,8 +121,8 @@ export declare const questionnaireStore: import("zustand/vanilla").StoreApi<Ques
 /**
  * Questionnaire state management store which contains all properties and methods to manage the state of the questionnaire.
  * This is the React version of the store which can be used as React hooks in React functional components.
- * @see QuestionnaireStoreType for available properties and methods.
- * @see questionnaireStore for the vanilla store.
+ * @see {@link QuestionnaireStoreType} for available properties and methods.
+ * @see {@link questionnaireStore} for the vanilla store.
  *
  * @author Sean Fong
  */
@@ -134,39 +137,40 @@ export declare const useQuestionnaireStore: import("zustand/vanilla").StoreApi<Q
         currentPageIndex: () => number;
         variables: () => Variables;
         launchContexts: () => Record<string, LaunchContext>;
+        initialExpressions: () => Record<string, InitialExpression>;
+        answerExpressions: () => Record<string, AnswerExpression>;
+        calculatedExpressions: () => Record<string, CalculatedExpression[]>;
         targetConstraints: () => Record<string, TargetConstraint>;
         targetConstraintLinkIds: () => Record<string, string[]>;
-        answerOptionsToggleExpressions: () => Record<string, AnswerOptionsToggleExpression[]>;
         enableWhenItems: () => EnableWhenItems;
         enableWhenLinkedQuestions: () => Record<string, string[]>;
         enableWhenIsActivated: () => boolean;
         enableWhenExpressions: () => EnableWhenExpressions;
-        calculatedExpressions: () => Record<string, CalculatedExpression[]>;
-        initialExpressions: () => Record<string, InitialExpression>;
-        answerExpressions: () => Record<string, AnswerExpression>;
+        answerOptionsToggleExpressions: () => Record<string, AnswerOptionsToggleExpression[]>;
         processedValueSets: () => Record<string, ProcessedValueSet>;
         cachedValueSetCodings: () => Record<string, Coding[]>;
         fhirPathContext: () => Record<string, any>;
         fhirPathTerminologyCache: () => Record<string, any>;
-        populatedContext: () => Record<string, any>;
+        additionalContext: () => Record<string, any>;
         qItemOverrideComponents: () => Record<string, ComponentType<QItemOverrideComponentProps>>;
         sdcUiOverrideComponents: () => Record<string, ComponentType<SdcUiOverrideComponentProps>>;
         focusedLinkId: () => string;
         readOnly: () => boolean;
-        buildSourceQuestionnaire: () => (questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse, additionalVariables?: Record<string, any>, terminologyServerUrl?: string, readOnly?: boolean, qItemOverrideComponents?: Record<string, ComponentType<QItemOverrideComponentProps>>, sdcUiOverrideComponents?: Record<string, ComponentType<SdcUiOverrideComponentProps>>) => Promise<void>;
+        buildSourceQuestionnaire: () => (questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse, additionalContext?: Record<string, any>, terminologyServerUrl?: string, readOnly?: boolean, qItemOverrideComponents?: Record<string, ComponentType<QItemOverrideComponentProps>>, sdcUiOverrideComponents?: Record<string, ComponentType<SdcUiOverrideComponentProps>>) => Promise<void>;
         destroySourceQuestionnaire: () => () => void;
         switchTab: () => (newTabIndex: number) => void;
         switchPage: () => (newPageIndex: number) => void;
         markTabAsComplete: () => (tabLinkId: string) => void;
         markPageAsComplete: () => (pageLinkId: string) => void;
+        resetToFirstVisibleTab: () => () => void;
+        resetToFirstVisiblePage: () => () => void;
         updateEnableWhenItem: () => (linkId: string, newAnswer: QuestionnaireResponseItemAnswer[] | undefined, parentRepeatGroupIndex: number | null) => void;
         mutateRepeatEnableWhenItems: () => (parentRepeatGroupLinkId: string, parentRepeatGroupIndex: number, actionType: "add" | "remove") => void;
         toggleEnableWhenActivation: () => (isActivated: boolean) => void;
-        updateExpressions: () => (updatedResponse: QuestionnaireResponse) => Promise<void>;
+        updateExpressions: () => (updatedResponse: QuestionnaireResponse, isInitialUpdate: boolean) => Promise<void>;
         addCodingToCache: () => (valueSetUrl: string, codings: Coding[]) => void;
-        updatePopulatedProperties: () => (populatedResponse: QuestionnaireResponse, populatedContext?: Record<string, any>, persistTabIndex?: boolean) => Promise<QuestionnaireResponse>;
         onFocusLinkId: () => (linkId: string) => void;
-        setPopulatedContext: () => (newPopulatedContext: Record<string, any>, addToFhirPathContext?: boolean) => void;
+        setAdditionalContext: () => (additionalContext: Record<string, any>) => void;
         setFormAsReadOnly: () => (readOnly: boolean) => void;
     };
 };

package/lib/stores/questionnaireStore.js

@@ -14,34 +14,27 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
 import { createStore } from 'zustand/vanilla';
+import { processCalculatedExpressions } from '../utils/calculatedExpression';
+import { applyComputedUpdates } from '../utils/computedUpdates';
 import { mutateRepeatEnableWhenItemInstances, updateEnableWhenItemAnswer } from '../utils/enableWhen';
-import { evaluateUpdatedExpressions } from '../utils/fhirpath';
-import { evaluateInitialCalculatedExpressions, initialiseCalculatedExpressionValues } from '../utils/calculatedExpression';
-import { createQuestionnaireModel } from '../utils/questionnaireStoreUtils/createQuestionnaireModel';
-import { initialiseFormFromResponse } from '../utils/initialise';
 import { emptyQuestionnaire, emptyResponse } from '../utils/emptyResource';
-import { terminologyServerStore } from './terminologyServerStore';
-import { createSelectors } from './selector';
 import { mutateRepeatEnableWhenExpressionInstances } from '../utils/enableWhenExpression';
-import { questionnaireResponseStore } from './questionnaireResponseStore';
+import { evaluateOtherExpressions } from '../utils/fhirpath';
+import { initialiseFormFromResponse } from '../utils/initialise';
 import { createQuestionnaireResponseItemMap } from '../utils/questionnaireResponseStoreUtils/updatableResponseItems';
 import { insertCompleteAnswerOptionsIntoQuestionnaire } from '../utils/questionnaireStoreUtils/insertAnswerOptions';
 import { readTargetConstraintLocationLinkIds } from '../utils/targetConstraint';
-import { applyComputedUpdates } from '../utils/computedUpdates';
+import { questionnaireResponseStore } from './questionnaireResponseStore';
+import { createSelectors } from './selector';
+import { terminologyServerStore } from './terminologyServerStore';
+import { createQuestionnaireModel } from '../utils/questionnaireStoreUtils/createQuestionnaireModel';
+import { getFirstVisibleTab } from '../utils/tabs';
+import { getFirstVisiblePage } from '../utils/page';
 /**
  * Questionnaire state management store which contains all properties and methods to manage the state of the questionnaire.
  * This is the vanilla version of the store which can be used in non-React environments.
- * @see QuestionnaireStoreType for available properties and methods.
+ * @see {@link QuestionnaireStoreType} for available properties and methods.
  *
  * @author Sean Fong
  */
@@ -69,26 +62,22 @@ export const questionnaireStore = createStore()((set, get) => ({
     cachedValueSetCodings: {},
     fhirPathContext: {},
     fhirPathTerminologyCache: {},
-    populatedContext: {},
+    additionalContext: {},
     qItemOverrideComponents: {},
     sdcUiOverrideComponents: {},
     focusedLinkId: '',
     readOnly: false,
-    buildSourceQuestionnaire: (questionnaire_1, ...args_1) => __awaiter(void 0, [questionnaire_1, ...args_1], void 0, function* (questionnaire, questionnaireResponse = structuredClone(emptyResponse), additionalVariables = {}, terminologyServerUrl = terminologyServerStore.getState().url, readOnly = false, qItemOverrideComponents = {}, sdcUiOverrideComponents = {}) {
-        var _a, _b;
-        const questionnaireModel = yield createQuestionnaireModel(questionnaire, terminologyServerUrl);
+    buildSourceQuestionnaire: async (questionnaire, questionnaireResponse = structuredClone(emptyResponse), additionalContext = {}, terminologyServerUrl = terminologyServerStore.getState().url, readOnly = false, qItemOverrideComponents = {}, sdcUiOverrideComponents = {}) => {
+        const questionnaireModel = await createQuestionnaireModel(questionnaire, terminologyServerUrl);
         // Insert answerOptions with displays into questionnaire
         questionnaire = insertCompleteAnswerOptionsIntoQuestionnaire(questionnaire, questionnaireModel.answerOptions);
         // If existing fhirPathContext is empty, use the one from the questionnaire model
         // Mostly existing fhirPathContext will be empty, but in some cases it may not be e.g. after pre-population
-        let fhirPathContext = (_a = get().fhirPathContext) !== null && _a !== void 0 ? _a : questionnaireModel.fhirPathContext;
         // TODO reminder to have documentation when upgrading to 1.0.0 - 05/06/2025
         // TODO This is something new - the definition of additionalVariables is now <"name", "value">, which allows it to be injected into the renderer's fhirPathContext.
         // TODO as an example, populatedContext from a pre-pop module can now be inserted into the renderer for further use.
-        fhirPathContext = Object.assign(Object.assign({}, fhirPathContext), additionalVariables);
-        const fhirPathTerminologyCache = (_b = get().fhirPathTerminologyCache) !== null && _b !== void 0 ? _b : questionnaireModel.fhirPathTerminologyCache;
         // Initialise form with questionnaire response and properties in questionnaire model
-        const { initialTargetConstraints, initialEnableWhenItems, initialEnableWhenLinkedQuestions, initialEnableWhenExpressions, initialCalculatedExpressions, initialProcessedValueSets, initialAnswerOptionsToggleExpressions, firstVisibleTab, firstVisiblePage, updatedFhirPathContext, fhirPathTerminologyCache: updatedFhirPathTerminologyCache } = yield initialiseFormFromResponse({
+        const { initialTargetConstraints, initialEnableWhenItems, initialEnableWhenLinkedQuestions, initialEnableWhenExpressions, initialCalculatedExpressions, initialProcessedValueSets, initialAnswerOptionsToggleExpressions, firstVisibleTab, firstVisiblePage, updatedFhirPathContext, fhirPathTerminologyCache: updatedFhirPathTerminologyCache } = await initialiseFormFromResponse({
             sourceQuestionnaire: questionnaire,
             questionnaireResponse,
             targetConstraints: questionnaireModel.targetConstraints,
@@ -100,12 +89,13 @@ export const questionnaireStore = createStore()((set, get) => ({
             processedValueSets: questionnaireModel.processedValueSets,
             tabs: questionnaireModel.tabs,
             pages: questionnaireModel.pages,
-            fhirPathContext: fhirPathContext,
-            fhirPathTerminologyCache: fhirPathTerminologyCache,
+            fhirPathContext: questionnaireModel.fhirPathContext,
+            fhirPathTerminologyCache: questionnaireModel.fhirPathTerminologyCache,
             terminologyServerUrl: terminologyServerUrl
         });
         // Read target constraint locations
         const targetConstraintLinkIds = readTargetConstraintLocationLinkIds(questionnaire, initialTargetConstraints);
+        const finalFhirPathContext = { ...updatedFhirPathContext, ...additionalContext };
         set({
             sourceQuestionnaire: questionnaire,
             itemMap: questionnaireModel.itemMap,
@@ -127,13 +117,14 @@ export const questionnaireStore = createStore()((set, get) => ({
             answerExpressions: questionnaireModel.answerExpressions,
             processedValueSets: initialProcessedValueSets,
             cachedValueSetCodings: questionnaireModel.cachedValueSetCodings,
-            fhirPathContext: updatedFhirPathContext,
+            fhirPathContext: finalFhirPathContext,
             fhirPathTerminologyCache: updatedFhirPathTerminologyCache,
+            additionalContext: additionalContext,
             qItemOverrideComponents: qItemOverrideComponents,
             sdcUiOverrideComponents: sdcUiOverrideComponents,
             readOnly: readOnly
         });
-    }),
+    },
     destroySourceQuestionnaire: () => set({
         sourceQuestionnaire: structuredClone(emptyQuestionnaire),
         itemMap: {},
@@ -164,15 +155,39 @@ export const questionnaireStore = createStore()((set, get) => ({
     markTabAsComplete: (tabLinkId) => {
         const tabs = get().tabs;
         set(() => ({
-            tabs: Object.assign(Object.assign({}, tabs), { [tabLinkId]: Object.assign(Object.assign({}, tabs[tabLinkId]), { isComplete: !tabs[tabLinkId].isComplete }) })
+            tabs: {
+                ...tabs,
+                [tabLinkId]: { ...tabs[tabLinkId], isComplete: !tabs[tabLinkId].isComplete }
+            }
         }));
     },
     markPageAsComplete: (pageLinkId) => {
         const pages = get().pages;
         set(() => ({
-            pages: Object.assign(Object.assign({}, pages), { [pageLinkId]: Object.assign(Object.assign({}, pages[pageLinkId]), { isComplete: !pages[pageLinkId].isComplete }) })
+            pages: {
+                ...pages,
+                [pageLinkId]: { ...pages[pageLinkId], isComplete: !pages[pageLinkId].isComplete }
+            }
         }));
     },
+    resetToFirstVisibleTab: () => {
+        const tabs = get().tabs;
+        const enableWhenItems = get().enableWhenItems;
+        const enableWhenExpressions = get().enableWhenExpressions;
+        const firstVisibleTab = Object.keys(tabs).length > 0
+            ? getFirstVisibleTab(tabs, enableWhenItems, enableWhenExpressions)
+            : 0;
+        set(() => ({ currentTabIndex: firstVisibleTab }));
+    },
+    resetToFirstVisiblePage: () => {
+        const pages = get().pages;
+        const enableWhenItems = get().enableWhenItems;
+        const enableWhenExpressions = get().enableWhenExpressions;
+        const firstVisiblePage = Object.keys(pages).length > 0
+            ? getFirstVisiblePage(pages, enableWhenItems, enableWhenExpressions)
+            : 0;
+        set(() => ({ currentPageIndex: firstVisiblePage }));
+    },
     updateEnableWhenItem: (linkId, newAnswer, parentRepeatGroupIndex) => {
         const enableWhenLinkedQuestions = get().enableWhenLinkedQuestions;
         const enableWhenItems = get().enableWhenItems;
@@ -180,16 +195,18 @@ export const questionnaireStore = createStore()((set, get) => ({
             return;
         }
         const itemLinkedQuestions = enableWhenLinkedQuestions[linkId];
-        const updatedEnableWhenItems = updateEnableWhenItemAnswer(Object.assign({}, enableWhenItems), itemLinkedQuestions, linkId, newAnswer, parentRepeatGroupIndex);
+        const updatedEnableWhenItems = updateEnableWhenItemAnswer({ ...enableWhenItems }, itemLinkedQuestions, linkId, newAnswer, parentRepeatGroupIndex);
         set(() => ({
             enableWhenItems: updatedEnableWhenItems
         }));
     },
-    mutateRepeatEnableWhenItems: (parentRepeatGroupLinkId, parentRepeatGroupIndex, actionType) => __awaiter(void 0, void 0, void 0, function* () {
+    mutateRepeatEnableWhenItems: async (parentRepeatGroupLinkId, parentRepeatGroupIndex, actionType) => {
         const enableWhenItems = get().enableWhenItems;
         const enableWhenExpressions = get().enableWhenExpressions;
-        const updatedEnableWhenItems = mutateRepeatEnableWhenItemInstances(Object.assign({}, enableWhenItems), parentRepeatGroupLinkId, parentRepeatGroupIndex, actionType);
-        const { updatedEnableWhenExpressions, isUpdated } = yield mutateRepeatEnableWhenExpressionInstances({
+        const updatedEnableWhenItems = mutateRepeatEnableWhenItemInstances({
+            ...enableWhenItems
+        }, parentRepeatGroupLinkId, parentRepeatGroupIndex, actionType);
+        const { updatedEnableWhenExpressions, isUpdated } = await mutateRepeatEnableWhenExpressionInstances({
             questionnaireResponse: questionnaireResponseStore.getState().updatableResponse,
             questionnaireResponseItemMap: questionnaireResponseStore.getState().updatableResponseItems,
             variables: get().variables,
@@ -207,121 +224,99 @@ export const questionnaireStore = createStore()((set, get) => ({
                 enableWhenExpressions: updatedEnableWhenExpressions
             }));
         }
-    }),
+    },
     toggleEnableWhenActivation: (isActivated) => set(() => ({ enableWhenIsActivated: isActivated })),
-    updateExpressions: (updatedResponse) => __awaiter(void 0, void 0, void 0, function* () {
-        const sourceQuestionnaire = get().sourceQuestionnaire;
+    updateExpressions: async (updatedResponse, isInitialUpdate) => {
+        /* Expression evaluation and application workflow
+        1. Evaluate calculatedExpressions to update answers in the QuestionnaireResponse.
+           - This must happen first, as these answers may affect subsequent expressions.
+           - Call updateResponse() once before proceeding to the next steps.
+    
+        2. Evaluate other expressions using the QR with updated calculated answers.
+           - Target constraints
+           - Enable when expressions
+           - Answer options toggle expressions
+           - Dynamic valueSets (e.g. parameterised valueSets)
+    
+        3. Apply computed updates from answerOptionsToggleExpressions and updated Dynamic ValueSets into the QuestionnaireResponse.
+    
+        4. Re-run calculatedExpressions as a final step to ensure all calculations are up-to-date, incorporating any toggled options or dynamic value set changes.
+        5. Update store state based on the expressions that changed
+        */
+        const { sourceQuestionnaire, itemMap, itemPreferredTerminologyServers, variables, targetConstraints, answerOptionsToggleExpressions, enableWhenExpressions, processedValueSets, calculatedExpressions, fhirPathContext, fhirPathTerminologyCache } = get();
         const updateResponse = questionnaireResponseStore.getState().updateResponse;
         const validateResponse = questionnaireResponseStore.getState().validateResponse;
-        const updatedResponseItemMap = createQuestionnaireResponseItemMap(sourceQuestionnaire, updatedResponse);
-        const { isUpdated, updatedTargetConstraints, updatedAnswerOptionsToggleExpressions, updatedEnableWhenExpressions, updatedCalculatedExpressions, updatedProcessedValueSets, updatedFhirPathContext, fhirPathTerminologyCache, computedQRItemUpdates } = yield evaluateUpdatedExpressions({
-            updatedResponse,
-            updatedResponseItemMap,
-            targetConstraints: get().targetConstraints,
-            answerOptionsToggleExpressions: get().answerOptionsToggleExpressions,
-            enableWhenExpressions: get().enableWhenExpressions,
-            calculatedExpressions: get().calculatedExpressions,
-            processedValueSets: get().processedValueSets,
-            variables: get().variables,
-            existingFhirPathContext: get().fhirPathContext,
-            fhirPathTerminologyCache: get().fhirPathTerminologyCache,
-            terminologyServerUrl: terminologyServerStore.getState().url
-        });
-        /**
-         * Applies computed updates to the QR before updating the store.
-         * Before this, we were updating the store before applying the computed updates. This may cause downstream useEffects to use a stale QR.
-         * By applying the computed updates first, we ensure that the QR is up-to-date when downstream useEffects are fired.
-         */
-        let lastUpdatedResponse = structuredClone(updatedResponse);
-        if (Object.keys(computedQRItemUpdates).length > 0) {
-            lastUpdatedResponse = applyComputedUpdates(get().sourceQuestionnaire, updatedResponse, computedQRItemUpdates);
-            updateResponse(lastUpdatedResponse, 'async');
-        }
-        if (isUpdated) {
+        const defaultTerminologyServerUrl = terminologyServerStore.getState().url;
+        // Helper function to extract common state update logic
+        function updateStoreState(updatedResponse, calculatedExpressions, fhirPathContext, fhirPathTerminologyCache, otherExpressions) {
+            // Update QuestionnaireStore state
             set(() => ({
-                targetConstraints: updatedTargetConstraints,
-                answerOptionsToggleExpressions: updatedAnswerOptionsToggleExpressions,
-                enableWhenExpressions: updatedEnableWhenExpressions,
-                calculatedExpressions: updatedCalculatedExpressions,
-                processedValueSets: updatedProcessedValueSets,
-                fhirPathContext: updatedFhirPathContext,
-                fhirPathTerminologyCache: fhirPathTerminologyCache
+                calculatedExpressions,
+                fhirPathContext,
+                fhirPathTerminologyCache,
+                ...(otherExpressions?.targetConstraints && {
+                    targetConstraints: otherExpressions.targetConstraints
+                }),
+                ...(otherExpressions?.enableWhenExpressions && {
+                    enableWhenExpressions: otherExpressions.enableWhenExpressions
+                }),
+                ...(otherExpressions?.answerOptionsToggleExpressions && {
+                    answerOptionsToggleExpressions: otherExpressions.answerOptionsToggleExpressions
+                }),
+                ...(otherExpressions?.processedValueSets && {
+                    processedValueSets: otherExpressions.processedValueSets
+                })
             }));
-            // Besides setting QuestionnaireStore state, we also need to update `invalidItems` and `responseIsValid` in QuestionnaireResponseStore
-            validateResponse(sourceQuestionnaire, lastUpdatedResponse); // Validate the updated response asynchronously
+            // Final validation
+            validateResponse(sourceQuestionnaire, updatedResponse);
         }
-        set(() => ({
-            fhirPathContext: updatedFhirPathContext,
-            fhirPathTerminologyCache: fhirPathTerminologyCache
-        }));
-    }),
+        // Step 1: Process calculated expressions first
+        let { updatedResponse: lastUpdatedResponse, updatedCalculatedExpressions: updatedCalculatedExpressions } = await processCalculatedExpressions(sourceQuestionnaire, updatedResponse, itemMap, calculatedExpressions, variables, fhirPathContext, fhirPathTerminologyCache, itemPreferredTerminologyServers, defaultTerminologyServerUrl);
+        // Perform an immediate QR update first, then process other expressions asynchronously
+        updateResponse(lastUpdatedResponse, isInitialUpdate);
+        // Step 2: Evaluate other expressions
+        const updatedResponseItemMap = createQuestionnaireResponseItemMap(sourceQuestionnaire, lastUpdatedResponse);
+        const { updatedFhirPathContext, updatedFhirPathTerminologyCache, targetConstraintsUpdate, enableWhenExpressionsUpdate, answerOptionsToggleExpressionsUpdate, processedValueSetsUpdate, computedQRItemUpdates } = await evaluateOtherExpressions(lastUpdatedResponse, updatedResponseItemMap, variables, fhirPathContext, fhirPathTerminologyCache, targetConstraints, enableWhenExpressions, answerOptionsToggleExpressions, processedValueSets, defaultTerminologyServerUrl);
+        /* Step 3 & 4: Handle computed updates and re-run calculations if needed */
+        if (Object.keys(computedQRItemUpdates).length > 0) {
+            lastUpdatedResponse = applyComputedUpdates(sourceQuestionnaire, lastUpdatedResponse, computedQRItemUpdates);
+            // Re-run calculated expressions with the updated response
+            const finalCalculatedResult = await processCalculatedExpressions(sourceQuestionnaire, lastUpdatedResponse, itemMap, updatedCalculatedExpressions, variables, updatedFhirPathContext, updatedFhirPathTerminologyCache, itemPreferredTerminologyServers, defaultTerminologyServerUrl);
+            lastUpdatedResponse = finalCalculatedResult.updatedResponse;
+            updatedCalculatedExpressions = finalCalculatedResult.updatedCalculatedExpressions;
+            updateResponse(lastUpdatedResponse, isInitialUpdate);
+        }
+        /* Step 5: Update store state based on the expressions that changed */
+        const otherExpressionsToUpdate = {};
+        if (targetConstraintsUpdate.isUpdated) {
+            otherExpressionsToUpdate.targetConstraints = targetConstraintsUpdate.value;
+        }
+        if (enableWhenExpressionsUpdate.isUpdated) {
+            otherExpressionsToUpdate.enableWhenExpressions = enableWhenExpressionsUpdate.value;
+        }
+        if (answerOptionsToggleExpressionsUpdate.isUpdated) {
+            otherExpressionsToUpdate.answerOptionsToggleExpressions =
+                answerOptionsToggleExpressionsUpdate.value;
+        }
+        if (processedValueSetsUpdate.isUpdated) {
+            otherExpressionsToUpdate.processedValueSets = processedValueSetsUpdate.value;
+        }
+        updateStoreState(lastUpdatedResponse, updatedCalculatedExpressions, updatedFhirPathContext, updatedFhirPathTerminologyCache, Object.keys(otherExpressionsToUpdate).length > 0 ? otherExpressionsToUpdate : undefined);
+    },
     addCodingToCache: (valueSetUrl, codings) => set(() => ({
-        cachedValueSetCodings: Object.assign(Object.assign({}, get().cachedValueSetCodings), { [valueSetUrl]: codings })
+        cachedValueSetCodings: {
+            ...get().cachedValueSetCodings,
+            [valueSetUrl]: codings
+        }
     })),
-    updatePopulatedProperties: (populatedResponse, populatedContext, persistTabIndex, persistPageIndex) => __awaiter(void 0, void 0, void 0, function* () {
-        const sourceQuestionnaire = get().sourceQuestionnaire;
-        const fhirPathContext = Object.assign(Object.assign({}, get().fhirPathContext), (populatedContext !== null && populatedContext !== void 0 ? populatedContext : {}));
-        const initialResponseItemMap = createQuestionnaireResponseItemMap(sourceQuestionnaire, populatedResponse);
-        const evaluateInitialCalculatedExpressionsResult = yield evaluateInitialCalculatedExpressions({
-            initialResponse: populatedResponse,
-            initialResponseItemMap: initialResponseItemMap,
-            calculatedExpressions: get().calculatedExpressions,
-            variables: get().variables,
-            existingFhirPathContext: fhirPathContext,
-            fhirPathTerminologyCache: get().fhirPathTerminologyCache,
-            terminologyServerUrl: terminologyServerStore.getState().url
-        });
-        const { initialCalculatedExpressions } = evaluateInitialCalculatedExpressionsResult;
-        let updatedFhirPathContext = evaluateInitialCalculatedExpressionsResult.updatedFhirPathContext;
-        let fhirPathTerminologyCache = evaluateInitialCalculatedExpressionsResult.fhirPathTerminologyCache;
-        const updatedResponse = initialiseCalculatedExpressionValues(sourceQuestionnaire, populatedResponse, initialCalculatedExpressions);
-        const { initialTargetConstraints, initialEnableWhenItems, initialEnableWhenLinkedQuestions, initialEnableWhenExpressions, initialAnswerOptionsToggleExpressions, firstVisibleTab, firstVisiblePage } = yield initialiseFormFromResponse({
-            sourceQuestionnaire,
-            questionnaireResponse: updatedResponse,
-            targetConstraints: get().targetConstraints,
-            enableWhenItems: get().enableWhenItems,
-            enableWhenExpressions: get().enableWhenExpressions,
-            calculatedExpressions: initialCalculatedExpressions,
-            answerOptionsToggleExpressions: get().answerOptionsToggleExpressions,
-            variables: get().variables,
-            processedValueSets: get().processedValueSets,
-            tabs: get().tabs,
-            pages: get().pages,
-            fhirPathContext: updatedFhirPathContext,
-            fhirPathTerminologyCache: fhirPathTerminologyCache,
-            terminologyServerUrl: terminologyServerStore.getState().url
-        });
-        updatedFhirPathContext = evaluateInitialCalculatedExpressionsResult.updatedFhirPathContext;
-        fhirPathTerminologyCache = evaluateInitialCalculatedExpressionsResult.fhirPathTerminologyCache;
-        set(() => ({
-            targetConstraints: initialTargetConstraints,
-            answerOptionsToggleExpressions: initialAnswerOptionsToggleExpressions,
-            enableWhenItems: initialEnableWhenItems,
-            enableWhenLinkedQuestions: initialEnableWhenLinkedQuestions,
-            enableWhenExpressions: initialEnableWhenExpressions,
-            calculatedExpressions: initialCalculatedExpressions,
-            currentTabIndex: persistTabIndex ? get().currentTabIndex : firstVisibleTab,
-            currentPageIndex: persistPageIndex ? get().currentPageIndex : firstVisiblePage,
-            fhirPathContext: updatedFhirPathContext,
-            fhirPathTerminologyCache: fhirPathTerminologyCache,
-            populatedContext: populatedContext !== null && populatedContext !== void 0 ? populatedContext : get().populatedContext
-        }));
-        return updatedResponse;
-    }),
     onFocusLinkId: (linkId) => set(() => ({
         focusedLinkId: linkId
     })),
-    setPopulatedContext: (newPopulatedContext, addToFhirPathContext) => {
-        if (addToFhirPathContext) {
-            const newFhirPathContext = Object.assign(Object.assign({}, get().fhirPathContext), newPopulatedContext);
-            set(() => ({
-                populatedContext: newPopulatedContext,
-                fhirPathContext: newFhirPathContext
-            }));
-            return;
-        }
+    setAdditionalContext: (additionalContext) => {
+        const newFhirPathContext = { ...get().fhirPathContext, ...additionalContext };
         set(() => ({
-            populatedContext: newPopulatedContext
+            additionalContext: additionalContext,
+            fhirPathContext: newFhirPathContext
         }));
     },
     setFormAsReadOnly: (readOnly) => set(() => ({
@@ -331,8 +326,8 @@ export const questionnaireStore = createStore()((set, get) => ({
 /**
  * Questionnaire state management store which contains all properties and methods to manage the state of the questionnaire.
  * This is the React version of the store which can be used as React hooks in React functional components.
- * @see QuestionnaireStoreType for available properties and methods.
- * @see questionnaireStore for the vanilla store.
+ * @see {@link QuestionnaireStoreType} for available properties and methods.
+ * @see {@link questionnaireStore} for the vanilla store.
  *
  * @author Sean Fong
  */