@aehrc/smart-forms-renderer 1.0.0-alpha.99 → 1.1.0

package/src/hooks/useDateCalculatedExpression.ts

@@ -1,90 +0,0 @@
-/*
- * Copyright 2025 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 { useEffect, useState } from 'react';
-import type { QuestionnaireItem } from 'fhir/r4';
-import { useQuestionnaireStore } from '../stores';
-
-interface UseDateCalculatedExpressionReturn {
-  calcExpUpdated: boolean;
-}
-
-interface UseDateCalculatedExpressionProps {
-  qItem: QuestionnaireItem;
-  valueDateFhir: string;
-  onChangeByCalcExpressionString: (newValueDateFhir: string) => void;
-  onChangeByCalcExpressionNull: () => void;
-}
-
-function useDateCalculatedExpression(
-  props: UseDateCalculatedExpressionProps
-): UseDateCalculatedExpressionReturn {
-  const { qItem, valueDateFhir, onChangeByCalcExpressionString, onChangeByCalcExpressionNull } =
-    props;
-
-  const calculatedExpressions = useQuestionnaireStore.use.calculatedExpressions();
-
-  const [calcExpUpdated, setCalcExpUpdated] = useState(false);
-
-  useEffect(
-    () => {
-      const calcExpression = calculatedExpressions[qItem.linkId]?.find(
-        (exp) => exp.from === 'item'
-      );
-
-      if (!calcExpression) {
-        return;
-      }
-
-      // If both input and calculated value are falsy, there is nothing to update
-      const inputAndCalcValueAreBothFalsy = valueDateFhir === '' && !calcExpression.value;
-      if (inputAndCalcValueAreBothFalsy) {
-        return;
-      }
-
-      // only update if calculated value is different from current value
-      if (
-        calcExpression.value !== valueDateFhir &&
-        (typeof calcExpression.value === 'string' || calcExpression.value === null)
-      ) {
-        // update ui to show calculated value changes
-        setCalcExpUpdated(true);
-        const timeoutId = setTimeout(() => {
-          setCalcExpUpdated(false);
-        }, 500);
-
-        // calculatedExpression value is null
-        if (calcExpression.value === null) {
-          onChangeByCalcExpressionNull();
-          return () => clearTimeout(timeoutId);
-        }
-
-        // calculatedExpression value is string
-        onChangeByCalcExpressionString(calcExpression.value as string);
-        return () => clearTimeout(timeoutId);
-      }
-      return undefined;
-    },
-    // Only trigger this effect if calculatedExpression of item changes
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [calculatedExpressions]
-  );
-
-  return { calcExpUpdated };
-}
-
-export default useDateCalculatedExpression;

package/src/hooks/useDateTimeCalculatedExpression.ts

@@ -1,90 +0,0 @@
-/*
- * Copyright 2025 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 { useEffect, useState } from 'react';
-import type { QuestionnaireItem } from 'fhir/r4';
-import { useQuestionnaireStore } from '../stores';
-
-interface UseDateTimeCalculatedExpressionReturn {
-  calcExpUpdated: boolean;
-}
-
-interface UseDateTimeCalculatedExpressionProps {
-  qItem: QuestionnaireItem;
-  valueDateTimeFhir: string;
-  onChangeByCalcExpressionString: (newValueDateTimeFhir: string) => void;
-  onChangeByCalcExpressionNull: () => void;
-}
-
-function useDateTimeCalculatedExpression(
-  props: UseDateTimeCalculatedExpressionProps
-): UseDateTimeCalculatedExpressionReturn {
-  const { qItem, valueDateTimeFhir, onChangeByCalcExpressionString, onChangeByCalcExpressionNull } =
-    props;
-
-  const calculatedExpressions = useQuestionnaireStore.use.calculatedExpressions();
-
-  const [calcExpUpdated, setCalcExpUpdated] = useState(false);
-
-  useEffect(
-    () => {
-      const calcExpression = calculatedExpressions[qItem.linkId]?.find(
-        (exp) => exp.from === 'item'
-      );
-
-      if (!calcExpression) {
-        return;
-      }
-
-      // If both input and calculated value are falsy, there is nothing to update
-      const inputAndCalcValueAreBothFalsy = valueDateTimeFhir === '' && !calcExpression.value;
-      if (inputAndCalcValueAreBothFalsy) {
-        return;
-      }
-
-      // only update if calculated value is different from current value
-      if (
-        calcExpression.value !== valueDateTimeFhir &&
-        (typeof calcExpression.value === 'string' || calcExpression.value === null)
-      ) {
-        // update ui to show calculated value changes
-        setCalcExpUpdated(true);
-        const timeoutId = setTimeout(() => {
-          setCalcExpUpdated(false);
-        }, 500);
-
-        // calculatedExpression value is null
-        if (calcExpression.value === null) {
-          onChangeByCalcExpressionNull();
-          return () => clearTimeout(timeoutId);
-        }
-
-        // calculatedExpression value is string
-        onChangeByCalcExpressionString(calcExpression.value as string);
-        return () => clearTimeout(timeoutId);
-      }
-      return undefined;
-    },
-    // Only trigger this effect if calculatedExpression of item changes
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [calculatedExpressions]
-  );
-
-  return { calcExpUpdated };
-}
-
-export default useDateTimeCalculatedExpression;

package/src/hooks/useDisplayCqfAndCalculatedExpression.ts

@@ -17,14 +17,30 @@
 
 import { useQuestionnaireStore } from '../stores';
 import type { QuestionnaireItem } from 'fhir/r4';
+import type { CalculatedExpression } from '../interfaces';
 
-function useDisplayCqfAndCalculatedExpression(qItem: QuestionnaireItem): string | null {
+/**
+ * Returns the value of a cqf-expression, calculatedExpression or ItemTextAriaLabelExpression.
+ *
+ * - If no expression is found → returns null.
+ * - If the value is null → returns an empty string.
+ * - If the value is a string or number → returns it as a string.
+ *
+ * @param {QuestionnaireItem} qItem - The questionnaire item.
+ * @param {CalculatedExpression['from']} from - The expression source. Should be a one of 'item._text' or 'item._text.aria-label'
+ * @returns {string | null} The display value as a string, empty string, or null.
+ */
+function useDisplayCqfAndCalculatedExpression(
+  qItem: QuestionnaireItem,
+  from: CalculatedExpression['from']
+): string | null {
   const calculatedExpressions = useQuestionnaireStore.use.calculatedExpressions();
 
   const cqfOrCalcExpression = calculatedExpressions?.[qItem.linkId]?.find(
-    (exp) => exp && exp.from === 'item._text' // Add null check for exp
+    (exp) => exp && exp.from === from
   );
 
+  // Add null check for exp
   if (!cqfOrCalcExpression) {
     return null;
   }

package/src/hooks/useHidden.ts

@@ -19,7 +19,7 @@ import type { QuestionnaireItem } from 'fhir/r4';
 import { useQuestionnaireStore } from '../stores';
 import { isHiddenByEnableWhen } from '../utils/qItem';
 import { structuredDataCapture } from 'fhir-sdc-helpers';
-import { useRendererStylingStore } from '../stores/rendererStylingStore';
+import { useRendererConfigStore } from '../stores/rendererConfigStore';
 
 /**
  * React hook to determine if a QuestionnaireItem is hidden via item.hidden, enableWhens, enableWhenExpressions.
@@ -32,7 +32,7 @@ function useHidden(qItem: QuestionnaireItem, parentRepeatGroupIndex?: number): b
   const enableWhenItems = useQuestionnaireStore.use.enableWhenItems();
   const enableWhenExpressions = useQuestionnaireStore.use.enableWhenExpressions();
 
-  const enableWhenAsReadOnly = useRendererStylingStore.use.enableWhenAsReadOnly();
+  const enableWhenAsReadOnly = useRendererConfigStore.use.enableWhenAsReadOnly();
 
   if (structuredDataCapture.getHidden(qItem)) {
     return true;

package/src/hooks/useInitialiseForm.ts

@@ -27,6 +27,9 @@ import { initialiseFhirClient } from '../utils/manageForm';
  * - Calling the buildForm() function to build a form from a questionnaire, an optional QuestionnaireResponse and other optional properties.
  * - Setting a FHIRClient object to make further FHIR calls i.e. answerExpressions.
  *
+ * Deprecated in favour of directly calling {@link buildForm} or using the {@link useBuildForm} hook in your own code.
+ * You can still use it, but it might not be compatible with renderer appearance and behaviour customisation via {@link rendererConfigStore}.
+ *
  * @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
@@ -34,8 +37,6 @@ import { initialiseFhirClient } from '../utils/manageForm';
  * @param additionalVariables - Additional key-value pair of SDC variables `Record<name, variable extension>` for testing (optional)
  * @param fhirClient - FHIRClient object to perform further FHIR calls. At the moment it's only used in answerExpressions (optional)
  *
- * @see buildForm() for more information.
- *
  * @author Sean Fong
  */
 function useInitialiseForm(
@@ -65,13 +66,13 @@ function useInitialiseForm(
 
     // Initialise form including Questionnaire and other optionally provided parameters
     // Includes initialisation for enableWhen, enableWhenExpressions, calculatedExpressions, initialExpressions, answerExpressions, cache answerValueSets
-    buildForm(
+    buildForm({
       questionnaire,
       questionnaireResponse,
       readOnly,
       terminologyServerUrl,
-      additionalVariables
-    ).then(() => {
+      additionalContext: additionalVariables
+    }).then(() => {
       setIsBuilding(false);
     });
   }, [

package/src/hooks/useReadOnly.ts

@@ -17,7 +17,7 @@
 
 import type { QuestionnaireItem } from 'fhir/r4';
 import useRenderingExtensions from './useRenderingExtensions';
-import { useRendererStylingStore } from '../stores/rendererStylingStore';
+import { useRendererConfigStore } from '../stores/rendererConfigStore';
 import { isHiddenByEnableWhen } from '../utils/qItem';
 import { useQuestionnaireStore } from '../stores';
 
@@ -32,7 +32,7 @@ function useReadOnly(
   const enableWhenItems = useQuestionnaireStore.use.enableWhenItems();
   const enableWhenExpressions = useQuestionnaireStore.use.enableWhenExpressions();
 
-  const enableWhenAsReadOnly = useRendererStylingStore.use.enableWhenAsReadOnly();
+  const enableWhenAsReadOnly = useRendererConfigStore.use.enableWhenAsReadOnly();
 
   // If enableWhenAsReadOnly is true, then items hidden by enableWhen should be displayed, but set as readOnly
   // If enableWhenAsReadOnly is a Set, all item types in the set should be displayed, but set as readOnly

package/src/hooks/useResizeColumns.ts

@@ -0,0 +1,53 @@
+/*
+ * Copyright 2025 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 { useLayoutEffect } from 'react';
+
+/**
+ * Hook to observe a container element's width and call a callback whenever it changes.
+ *
+ * Uses `ResizeObserver` to track changes to the element’s dimensions.
+ * Works with libraries like Allotment that resize elements without triggering a window resize event.
+ *
+ */
+export function useResizeColumns(
+  ref: React.RefObject<HTMLDivElement | null>,
+  onSetTableWidth: (width: number) => void
+) {
+  useLayoutEffect(() => {
+    if (!ref.current) {
+      return;
+    }
+
+    const node = ref.current;
+    const observer = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        if (entry.contentRect) {
+          onSetTableWidth(entry.contentRect.width);
+        }
+      }
+    });
+    observer.observe(node);
+
+    // Set initial width
+    onSetTableWidth(node.offsetWidth);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [onSetTableWidth, ref]);
+}

package/src/hooks/useValueSetCodings.ts

@@ -18,6 +18,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import type { Coding, FhirResource, QuestionnaireItem, ValueSet } from 'fhir/r4';
 import {
+  getCodingsForAnswerValueSet,
   getResourceFromLaunchContext,
   getValueSetCodings,
   getValueSetPromise
@@ -56,33 +57,10 @@ function useValueSetCodings(qItem: QuestionnaireItem): {
   const defaultTerminologyServerUrl = useTerminologyServerStore.use.url();
 
   const answerValueSetUrl = qItem.answerValueSet;
-  let initialCodings = useMemo(() => {
-    // set options from cached answer options if present
-    if (answerValueSetUrl) {
-      let valueSetUrl = answerValueSetUrl;
-
-      // answerValueSetUrl is a reference to a contained value set
-      // If found, return early
-      if (valueSetUrl.startsWith('#')) {
-        const valueSetReference = answerValueSetUrl.slice(1);
-        if (cachedValueSetCodings[valueSetReference]) {
-          return cachedValueSetCodings[valueSetReference];
-        }
-      }
-
-      // Get updatableValueSetUrl and use it as the current valueSetUrl
-      if (processedValueSets[valueSetUrl]?.updatableValueSetUrl) {
-        valueSetUrl = processedValueSets[valueSetUrl].updatableValueSetUrl;
-      }
-
-      // attempt to get codings from cached queried value sets
-      if (cachedValueSetCodings[valueSetUrl]) {
-        return cachedValueSetCodings[valueSetUrl];
-      }
-    }
-
-    return [];
-  }, [cachedValueSetCodings, processedValueSets, answerValueSetUrl]);
+  let initialCodings = useMemo(
+    () => getCodingsForAnswerValueSet(answerValueSetUrl, cachedValueSetCodings, processedValueSets),
+    [cachedValueSetCodings, processedValueSets, answerValueSetUrl]
+  );
 
   // Attempt to get codings from answer expression
   const answerExpression = getAnswerExpression(qItem)?.expression;

package/src/index.ts

@@ -41,8 +41,8 @@ export type {
   QuestionnaireResponseStoreType,
   SmartConfigStoreType,
   TerminologyServerStoreType,
-  RendererStyling,
-  RendererStylingStoreType
+  RendererConfig,
+  RendererConfigStoreType
 } from './stores';
 export {
   questionnaireStore,
@@ -53,8 +53,8 @@ export {
   useSmartConfigStore,
   terminologyServerStore,
   useTerminologyServerStore,
-  rendererStylingStore,
-  useRendererStylingStore
+  rendererConfigStore,
+  useRendererConfigStore
 } from './stores';
 
 // hooks exports
@@ -67,17 +67,15 @@ export {
   useRenderingExtensions,
   useValidationFeedback,
   useValueSetCodings,
-  useStringCalculatedExpression,
   useDisplayCqfAndCalculatedExpression,
-  useCodingCalculatedExpression,
-  objectIsCoding,
   useResponsive
 } from './hooks';
 
 // utils exports
-export type { ItemToRepopulate } from './utils';
+export type { ItemToRepopulate, BuildFormParams, RepopulateFormParams } from './utils';
 export {
   buildForm,
+  repopulateForm,
   destroyForm,
   getResponse,
   removeEmptyAnswersFromResponse,
@@ -117,7 +115,3 @@ export {
   tableOverride,
   rendererThemeOptions
 } from './theme';
-
-// wrapper exports - only for smartforms.csiro.au/standalone use
-export type { InitialiseFormWrapperProps } from './stories/storybookWrappers';
-export { InitialiseFormWrapperForStorybook } from './stories/storybookWrappers';

package/src/interfaces/calculatedExpression.interface.ts

@@ -24,6 +24,6 @@
  */
 export interface CalculatedExpression {
   expression: string;
-  from: 'item' | 'item._text' | 'item._answerValueSet';
+  from: 'item' | 'item._text' | 'item._text.aria-label' | 'item._answerValueSet';
   value?: number | string | boolean | object | null;
 }

package/src/interfaces/overrideComponent.interface.ts

@@ -19,12 +19,10 @@ import type { QuestionnaireItem, QuestionnaireResponseItem } from 'fhir/r4';
 import type { QrRepeatGroup } from './repeatGroup.interface';
 import type { RenderingExtensions } from '../hooks/useRenderingExtensions';
 import type { JSX } from 'react';
-import type { ItemPath } from './itemPath.interface';
 
 export interface QItemOverrideComponentProps {
   qItem: QuestionnaireItem;
   qrItem: QuestionnaireResponseItem | QuestionnaireResponseItem[] | null;
-  itemPath: ItemPath;
   isRepeated: boolean;
   isTabled?: boolean;
   renderingExtensions?: RenderingExtensions;
@@ -34,8 +32,9 @@ export interface QItemOverrideComponentProps {
   parentIsRepeatGroup?: boolean;
   parentRepeatGroupIndex?: number;
   parentStyles?: Record<string, string>;
-  onQrItemChange: (qrItem: QuestionnaireResponseItem, targetItemPath?: ItemPath) => unknown;
-  onQrRepeatGroupChange: (qrRepeatGroup: QrRepeatGroup, targetItemPath?: ItemPath) => unknown;
+  calcExpUpdated?: boolean;
+  onQrItemChange: (qrItem: QuestionnaireResponseItem) => unknown;
+  onQrRepeatGroupChange: (qrRepeatGroup: QrRepeatGroup) => unknown;
 }
 
 export interface SdcUiOverrideComponentProps {

package/src/interfaces/renderProps.interface.ts

@@ -18,21 +18,15 @@
 import type { QrRepeatGroup } from './repeatGroup.interface';
 import type { QuestionnaireItem, QuestionnaireResponseItem } from 'fhir/r4';
 import type { RenderingExtensions } from '../hooks/useRenderingExtensions';
-import type { ItemPath } from './itemPath.interface';
 
 /**
  * Props interface for components that emit a `QuestionnaireResponseItem` update.
  *
  * @property onQrItemChange - Callback function to handle an updated QR item.
  * - The `qrItem` represents the new or modified item.
- * - The optional `targetItemPath` identifies the item's full hierarchical location,
- *   represented as an array of path segments, each typically containing a `linkId` and (if applicable) an index.
- *
- * **Important**: If the update originates from a calculated expression,
- * `targetItemPath` must be provided so the form engine can locate and correctly update the item.
  */
 export interface PropsWithQrItemChangeHandler {
-  onQrItemChange: (qrItem: QuestionnaireResponseItem, targetItemPath?: ItemPath) => unknown;
+  onQrItemChange: (qrItem: QuestionnaireResponseItem) => unknown;
 }
 
 /**
@@ -40,29 +34,9 @@ export interface PropsWithQrItemChangeHandler {
  *
  * @property onQrRepeatGroupChange - Callback function to handle an updated repeating group item.
  * - The `qrRepeatGroup` represents the entire repeating group structure.
- * - The optional `targetItemPath` identifies the exact repeated group instance being updated,
- *   specified as a full path of segments (e.g., each with `linkId` and repeat index).
  */
 export interface PropsWithQrRepeatGroupChangeHandler {
-  onQrRepeatGroupChange: (qrRepeatGroup: QrRepeatGroup, targetItemPath?: ItemPath) => unknown;
-}
-
-/**
- * Props interface for components that are aware of their position within the `QuestionnaireResponse` hierarchy.
- *
- * @property itemPath - The full path to the current item within the `QuestionnaireResponse`,
- *   represented as an array of path segments. Each segment includes the `linkId` of the item
- *   and, if applicable, a `repeatIndex` for repeating items.
- *
- * This path is used to:
- * - Precisely locate the item within the response structure.
- * - Support efficient updates to nested or repeated items.
- * - Ensure accurate context for calculated expressions, conditional logic, and user input.
- *
- * Components that render or modify QR items should receive this prop to maintain correct hierarchy tracking.
- */
-export interface PropsWithItemPathAttribute {
-  itemPath: ItemPath;
+  onQrRepeatGroupChange: (qrRepeatGroup: QrRepeatGroup) => unknown;
 }
 
 export interface PropsWithRenderingExtensionsAttribute {
@@ -77,10 +51,6 @@ export interface PropsWithIsTabledAttribute {
   isTabled: boolean;
 }
 
-export interface PropsWithIsTabledRequiredAttribute {
-  isTabled: boolean;
-}
-
 export interface PropsWithParentIsReadOnlyAttribute {
   parentIsReadOnly?: boolean;
 }
@@ -94,18 +64,22 @@ export interface PropsWithParentIsRepeatGroupAttribute {
   parentRepeatGroupIndex?: number;
 }
 
+export interface PropsWithCalculatedExpressionUpdatedAttribute {
+  calcExpUpdated: boolean;
+}
+
 export interface PropsWithParentStylesAttribute {
   parentStyles?: Record<string, string>;
 }
 
 export interface BaseItemProps
   extends PropsWithQrItemChangeHandler,
-    PropsWithItemPathAttribute,
     PropsWithIsRepeatedAttribute,
-    PropsWithIsTabledRequiredAttribute,
+    PropsWithIsTabledAttribute,
     PropsWithRenderingExtensionsAttribute,
     PropsWithParentIsReadOnlyAttribute,
     PropsWithFeedbackFromParentAttribute,
+    PropsWithCalculatedExpressionUpdatedAttribute,
     PropsWithParentStylesAttribute {
   qItem: QuestionnaireItem;
   qrItem: QuestionnaireResponseItem | null;

package/src/interfaces/valueSet.interface.ts

@@ -15,7 +15,7 @@
  * limitations under the License.
  */
 
-import type { ValueSet } from 'fhir/r4';
+import type { Parameters, ValueSet } from 'fhir/r4';
 
 export interface ProcessedValueSet {
   initialValueSetUrl: string;
@@ -30,7 +30,7 @@ export interface ValueSetPromise {
   valueSet?: ValueSet;
 }
 
-export interface ValidateCodeResponse extends Parameters<any> {
+export interface ValidateCodeResponse extends Parameters {
   parameter: [SystemParameter, CodeParameter, DisplayParameter];
 }
 

package/src/stores/formUpdateQueueStore.ts

@@ -20,7 +20,6 @@ import type { QuestionnaireResponse } from 'fhir/r4';
 import { questionnaireStore } from './questionnaireStore';
 import { useQuestionnaireResponseStore } from './questionnaireResponseStore';
 import { createSelectors } from './selector';
-import type { ItemPath } from '../interfaces/itemPath.interface';
 
 /**
  * A single form update task, representing a `QuestionnaireResponse` that should be processed.
@@ -29,8 +28,12 @@ export interface UpdateTask {
   /** The `QuestionnaireResponse` snapshot used to evaluate calculated expressions */
   questionnaireResponse: QuestionnaireResponse;
 
-  /** Optional path to the item that triggered the update. This can be really useful in the future as it provides the FHIRPath string */
-  targetItemPath?: ItemPath;
+  /**
+   * Optional flag indicating this update is the first update upon pre-population and form build.
+   * Useful for distinguishing initialization updates from subsequent user-triggered updates.
+   * Defaults to `false`.
+   */
+  isInitialUpdate?: boolean;
 }
 
 /**
@@ -51,15 +54,6 @@ export interface FormUpdateQueueStoreType {
    */
   enqueueFormUpdate: (task: UpdateTask) => void;
 
-  /**
-   * Replaces all pending tasks with the latest task.
-   * If a task is being processed, it is preserved at the head of the queue.
-   * Useful for calculated fields where only the latest state matters.
-   *
-   * @param task - The most recent form update task to keep
-   */
-  replaceLatestFormUpdate: (task: UpdateTask) => void;
-
   /**
    * Internal processor that handles one task at a time, in order.
    *
@@ -78,7 +72,6 @@ export interface FormUpdateQueueStoreType {
  * to avoid race conditions and inconsistent state during expression evaluation.
  *
  * - `enqueueFormUpdate` adds a new task to the end of the queue.
- * - `replaceLatestFormUpdate` drops all pending tasks in favor of the latest one.
  * - `_startProcessing` handles processing each task and re-triggers itself as needed.
  */
 export const formUpdateQueueStore = createStore<FormUpdateQueueStoreType>()((set, get) => ({
@@ -90,16 +83,6 @@ export const formUpdateQueueStore = createStore<FormUpdateQueueStoreType>()((set
     get()._startProcessing();
   },
 
-  replaceLatestFormUpdate: (task: UpdateTask) => {
-    const { isProcessing } = get();
-
-    // If already processing, keep current task and replace pending ones
-    set(() => ({
-      queue: isProcessing ? [get().queue[0], task] : [task]
-    }));
-    get()._startProcessing();
-  },
-
   _startProcessing: async () => {
     const { isProcessing, queue } = get();
 
@@ -112,18 +95,19 @@ export const formUpdateQueueStore = createStore<FormUpdateQueueStoreType>()((set
 
     set({ isProcessing: true });
 
-    const { questionnaireResponse } = queue[0];
+    /* Process first task in the queue */
+    const { questionnaireResponse, isInitialUpdate = false } = queue[0];
 
-    updateResponse(questionnaireResponse, 'initial'); // Immediate update (pre-computed)
-
-    await updateExpressions(questionnaireResponse);
+    // Perform an immediate QR update first, then process expressions asynchronously
+    updateResponse(questionnaireResponse, isInitialUpdate);
+    await updateExpressions(questionnaireResponse, isInitialUpdate);
 
+    /* Dequeue first task in and process next task in the queue */
     set((state) => ({
       queue: state.queue.slice(1),
       isProcessing: false
     }));
-
-    get()._startProcessing(); // Process next task in the queue
+    get()._startProcessing();
   }
 }));