@aehrc/smart-forms-renderer 0.30.2 → 0.31.0

package/src/hooks/useValueSetCodings.ts

@@ -73,6 +73,7 @@ function useValueSetCodings(qItem: QuestionnaireItem): {
     return [];
   }, [cachedValueSetCodings, processedValueSetCodings, valueSetUrl]);
 
+  // Attempt to get codings from answer expression
   const answerExpression = getAnswerExpression(qItem)?.expression;
   initialCodings = useMemo(() => {
     if (initialCodings.length === 0 && answerExpression) {

package/src/index.ts

@@ -1,96 +1,59 @@
-import { questionnaireResponseStore, questionnaireStore } from './stores';
-import type { Questionnaire, QuestionnaireResponse } from 'fhir/r4';
-import { removeEmptyAnswers } from './utils/removeEmptyAnswers';
-import type { ItemToRepopulate } from './utils/repopulateItems';
-import { getItemsToRepopulate } from './utils/repopulateItems';
-import { repopulateItemsIntoResponse } from './utils/repopulateIntoResponse';
-
-export * from './components';
-export * from './stores';
-export * from './hooks';
-export * from './utils';
-export * from './interfaces';
-export type { ItemToRepopulate };
-
-/**
- * Destroy the form to clean up the questionnaire and questionnaireResponse stores.
- *
- * @author Sean Fong
- */
-export function destroyForm(): void {
-  questionnaireStore.getState().destroySourceQuestionnaire();
-  questionnaireResponseStore.getState().destroySourceResponse();
-}
-
-/**
- * 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 the questionnaire-hidden extension, enableWhens, enableWhenExpressions 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
-  });
-}
-
-/**
- * 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
-  });
-}
-
-/**
- * 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
-  );
-}
+// interface exports
+export type { Tab, Tabs, Variables, VariableXFhirQuery, LaunchContext } from './interfaces';
+
+// component exports
+export type { SmartFormsRendererProps } from './components';
+export {
+  SmartFormsRenderer,
+  BaseRenderer,
+  SingleItem,
+  RepeatItem,
+  RepeatGroup,
+  GroupTable,
+  GridGroup,
+  parseFhirDateToDisplayDate
+} from './components';
+
+// state management store exports
+export type {
+  QuestionnaireStoreType,
+  QuestionnaireResponseStoreType,
+  SmartConfigStoreType,
+  TerminologyServerStoreType
+} from './stores';
+export {
+  questionnaireStore,
+  useQuestionnaireStore,
+  questionnaireResponseStore,
+  useQuestionnaireResponseStore,
+  smartConfigStore,
+  useSmartConfigStore,
+  terminologyServerStore,
+  useTerminologyServerStore
+} from './stores';
+
+// hooks exports
+export { useHidden, useBuildForm, useRendererQueryClient } from './hooks';
+
+// utils exports
+export type { ItemToRepopulate } from './utils';
+export {
+  buildForm,
+  destroyForm,
+  getResponse,
+  removeEmptyAnswersFromResponse,
+  isSpecificItemControl,
+  isRepeatItemAndNotCheckbox,
+  initialiseQuestionnaireResponse,
+  generateItemsToRepopulate,
+  repopulateResponse
+} from './utils';
+
+// theme provider exports
+export { RendererThemeProvider } from './theme';
+
+export {
+  InitialiseFormWrapperForStorybook,
+  BuildFormButtonTesterWrapperForStorybook,
+  PrePopWrapperForStorybook
+} from './stories/StorybookWrappers';

package/src/interfaces/calculatedExpression.interface.ts

@@ -1,3 +1,27 @@
+/*
+ * 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.
+ */
+
+/**
+ * CalculatedExpression interface
+ *
+ * @property expression - CalculatedExpression FHIRPath expression
+ * @property from - Whether the expressions is for the item itself or for item._text
+ * @property value - Evaluated value of the expression via FHIRPath
+ */
 export interface CalculatedExpression {
   expression: string;
   from: 'item' | 'item._text';

package/src/interfaces/enableWhen.interface.ts

@@ -21,6 +21,12 @@ import type {
   QuestionnaireResponseItemAnswer
 } from 'fhir/r4';
 
+/**
+ * EnableWhenExpressions interface
+ *
+ * @property singleExpressions - Key-value pair of non-repeat group enableWhen expressions `Record<linkId, enableWhenExpression properties>`
+ * @property repeatExpressions - Key-value pair of repeat group enableWhen expressions `Record<linkId, enableWhenExpression properties>`
+ */
 export interface EnableWhenExpressions {
   singleExpressions: Record<string, EnableWhenSingleExpression>;
   repeatExpressions: Record<string, EnableWhenRepeatExpression>;
@@ -37,6 +43,12 @@ export interface EnableWhenRepeatExpression {
   enabledIndexes: boolean[];
 }
 
+/**
+ * EnableWhenItems interface
+ *
+ * @property singleItems - Key-value pair of non-repeat group enableWhen items `Record<linkId, enableWhen properties>`
+ * @property repeatItems - Key-value pair of repeat group enableWhen items `Record<linkId, enableWhen properties>`
+ */
 export interface EnableWhenItems {
   singleItems: Record<string, EnableWhenSingleItemProperties>;
   repeatItems: Record<string, EnableWhenRepeatItemProperties>;

package/src/interfaces/index.ts

@@ -1,10 +1,21 @@
-export {
-  EnableWhenItems,
-  EnableWhenSingleItemProperties,
-  EnableWhenRepeatItemProperties,
-  EnableWhenSingleLinkedItem,
-  EnableWhenRepeatLinkedItem,
-  EnableWhenExpressions,
-  EnableWhenSingleExpression,
-  EnableWhenRepeatExpression
-} from './enableWhen.interface';
+/*
+ * 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.
+ */
+
+export type { Tab, Tabs } from './tab.interface';
+export type { Variables, VariableXFhirQuery } from './variables.interface';
+export type { LaunchContext } from './populate.interface';
+export type { EnableWhenItems, EnableWhenExpressions } from './enableWhen.interface';

package/src/interfaces/populate.interface.ts

@@ -17,6 +17,12 @@
 
 import type { Coding, Expression, Extension, Reference } from 'fhir/r4';
 
+/**
+ * LaunchContext interface
+ *
+ * @property url - Launch context URL
+ * @property extension - Possible contents of the launch context as an array of extensions
+ */
 export interface LaunchContext extends Extension {
   url: 'http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-launchContext';
   extension: LaunchContextExtensions;

package/src/interfaces/tab.interface.ts

@@ -14,5 +14,17 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
+/**
+ * Tab interface
+ *
+ * @property tabIndex - The index of the tab
+ * @property isComplete - Whether the tab is marked as complete
+ * @property isHidden - Whether the tab is hidden
+ */
 export type Tab = { tabIndex: number; isComplete: boolean; isHidden: boolean };
+
+/**
+ * Key-value pair of tabs `Record<linkId, Tab>`
+ */
 export type Tabs = Record<string, Tab>;

package/src/interfaces/variables.interface.ts

@@ -17,11 +17,23 @@
 
 import type { Expression, FhirResource } from 'fhir/r4';
 
+/**
+ * Variables interface
+ *
+ * @property fhirPathVariables - Key-value pair of FHIRPath variable expressions in a Questionnaire item `Record<linkId, array of FHIRPath expressions>`
+ * @property xFhirQueryVariables - Key-value pair of x-fhir-query variables `Record<variable name, x-fhir-query variable properties>`
+ */
 export interface Variables {
   fhirPathVariables: Record<string, Expression[]>;
   xFhirQueryVariables: Record<string, VariableXFhirQuery>;
 }
 
+/**
+ * VariableXFhirQuery interface
+ *
+ * @property valueExpression - FHIRPath Expression of the variable
+ * @property result - FHIR resource result of the executed query
+ */
 export interface VariableXFhirQuery {
   valueExpression: Expression;
   result?: FhirResource;

package/src/stores/index.ts

@@ -1,7 +1,14 @@
+export type { QuestionnaireStoreType } from './questionnaireStore';
 export { questionnaireStore, useQuestionnaireStore } from './questionnaireStore';
+
+export type { QuestionnaireResponseStoreType } from './questionnaireResponseStore';
 export {
   questionnaireResponseStore,
   useQuestionnaireResponseStore
 } from './questionnaireResponseStore';
+
+export type { SmartConfigStoreType } from './smartConfigStore';
 export { smartConfigStore, useSmartConfigStore } from './smartConfigStore';
+
+export type { TerminologyServerStoreType } from './terminologyServerStore';
 export { terminologyServerStore, useTerminologyServerStore } from './terminologyServerStore';

package/src/stores/questionnaireResponseStore.ts

@@ -31,7 +31,28 @@ import { validateQuestionnaire } from '../utils/validateQuestionnaire';
 import { questionnaireStore } from './questionnaireStore';
 import { createQuestionnaireResponseItemMap } from '../utils/questionnaireResponseStoreUtils/updatableResponseItems';
 
-interface QuestionnaireResponseStoreType {
+/**
+ * QuestionnaireResponseStore properties and methods
+ * Properties can be accessed for fine-grain details.
+ * Methods are usually used internally, using them from an external source is not recommended.
+ *
+ * @property sourceResponse - The original response created when the form is first initialised i.e. empty, pre-populated, opened saved draft
+ * @property updatableResponse - The current state of the response that is being updated via form fields
+ * @property updatableResponseItems - Key-value pair of updatableResponse items `Record<linkId, QR.item(s)>`
+ * @property formChangesHistory - Array of form changes history in the form of deep-diff objects
+ * @property invalidItems - Key-value pair of invalid items based on defined value constraints in the questionnaire `Record<linkId, OperationOutcome>`
+ * @property responseIsValid - Whether there are any invalid items in the response
+ * @method validateQuestionnaire - Used to validate the questionnaire response based on the questionnaire
+ * @method buildSourceResponse - Used to build the source response when the form is first initialised
+ * @method setUpdatableResponseAsPopulated - Used to set a pre-populated response as the current response
+ * @method updateResponse - Used to update the current response
+ * @method setUpdatableResponseAsSaved - Used to set a saved response as the current response
+ * @method setUpdatableResponseAsEmpty - Used to set an empty response as the current response
+ * @method destroySourceResponse - Used to destroy the source response  and reset all properties
+ *
+ * @author Sean Fong
+ */
+export interface QuestionnaireResponseStoreType {
   sourceResponse: QuestionnaireResponse;
   updatableResponse: QuestionnaireResponse;
   updatableResponseItems: Record<string, QuestionnaireResponseItem[]>;
@@ -50,6 +71,13 @@ interface QuestionnaireResponseStoreType {
   destroySourceResponse: () => void;
 }
 
+/**
+ * QuestionnaireResponse state management store which contains all properties and methods to manage the state of the questionnaireResponse.
+ * This is the vanilla version of the store which can be used in non-React environments.
+ * @see {QuestionnaireResponseStoreType} for available properties and methods.
+ *
+ * @author Sean Fong
+ */
 export const questionnaireResponseStore = createStore<QuestionnaireResponseStoreType>()(
   (set, get) => ({
     sourceResponse: cloneDeep(emptyResponse),
@@ -62,16 +90,9 @@ export const questionnaireResponseStore = createStore<QuestionnaireResponseStore
       questionnaire: Questionnaire,
       updatedResponse: QuestionnaireResponse
     ) => {
-      const enableWhenIsActivated = questionnaireStore.getState().enableWhenIsActivated;
-      const enableWhenItems = questionnaireStore.getState().enableWhenItems;
-      const enableWhenExpressions = questionnaireStore.getState().enableWhenExpressions;
-
       const updatedInvalidItems = validateQuestionnaire({
         questionnaire,
-        questionnaireResponse: updatedResponse,
-        enableWhenIsActivated,
-        enableWhenItems,
-        enableWhenExpressions
+        questionnaireResponse: updatedResponse
       });
 
       set(() => ({
@@ -80,49 +101,99 @@ export const questionnaireResponseStore = createStore<QuestionnaireResponseStore
       }));
     },
     buildSourceResponse: (questionnaireResponse: QuestionnaireResponse) => {
+      const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
+      const initialInvalidItems = validateQuestionnaire({
+        questionnaire: sourceQuestionnaire,
+        questionnaireResponse: questionnaireResponse
+      });
+
       set(() => ({
         sourceResponse: questionnaireResponse,
         updatableResponse: questionnaireResponse,
-        updatableResponseItems: createQuestionnaireResponseItemMap(questionnaireResponse)
+        updatableResponseItems: createQuestionnaireResponseItemMap(questionnaireResponse),
+        invalidItems: initialInvalidItems,
+        responseIsValid: Object.keys(initialInvalidItems).length === 0
       }));
     },
     setUpdatableResponseAsPopulated: (populatedResponse: QuestionnaireResponse) => {
+      const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
       const formChanges = diff(get().updatableResponse, populatedResponse) ?? null;
+      const updatedInvalidItems = validateQuestionnaire({
+        questionnaire: sourceQuestionnaire,
+        questionnaireResponse: populatedResponse
+      });
       set(() => ({
         updatableResponse: populatedResponse,
         updatableResponseItems: createQuestionnaireResponseItemMap(populatedResponse),
-        formChangesHistory: [...get().formChangesHistory, formChanges]
+        formChangesHistory: [...get().formChangesHistory, formChanges],
+        invalidItems: updatedInvalidItems,
+        responseIsValid: Object.keys(updatedInvalidItems).length === 0
       }));
     },
     updateResponse: (updatedResponse: QuestionnaireResponse) => {
+      const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
       const formChanges = diff(get().updatableResponse, updatedResponse) ?? null;
+      const updatedInvalidItems = validateQuestionnaire({
+        questionnaire: sourceQuestionnaire,
+        questionnaireResponse: updatedResponse
+      });
       set(() => ({
         updatableResponse: updatedResponse,
         updatableResponseItems: createQuestionnaireResponseItemMap(updatedResponse),
-        formChangesHistory: [...get().formChangesHistory, formChanges]
+        formChangesHistory: [...get().formChangesHistory, formChanges],
+        invalidItems: updatedInvalidItems,
+        responseIsValid: Object.keys(updatedInvalidItems).length === 0
       }));
     },
-    setUpdatableResponseAsSaved: (savedResponse: QuestionnaireResponse) =>
+    setUpdatableResponseAsSaved: (savedResponse: QuestionnaireResponse) => {
+      const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
+      const updatedInvalidItems = validateQuestionnaire({
+        questionnaire: sourceQuestionnaire,
+        questionnaireResponse: savedResponse
+      });
+
       set(() => ({
         sourceResponse: savedResponse,
         updatableResponse: savedResponse,
         updatableResponseItems: createQuestionnaireResponseItemMap(savedResponse),
-        formChangesHistory: []
-      })),
-    setUpdatableResponseAsEmpty: (clearedResponse: QuestionnaireResponse) =>
+        formChangesHistory: [],
+        invalidItems: updatedInvalidItems,
+        responseIsValid: Object.keys(updatedInvalidItems).length === 0
+      }));
+    },
+    setUpdatableResponseAsEmpty: (clearedResponse: QuestionnaireResponse) => {
+      const sourceQuestionnaire = questionnaireStore.getState().sourceQuestionnaire;
+      const updatedInvalidItems = validateQuestionnaire({
+        questionnaire: sourceQuestionnaire,
+        questionnaireResponse: clearedResponse
+      });
+
       set(() => ({
         updatableResponse: clearedResponse,
         updatableResponseItems: createQuestionnaireResponseItemMap(clearedResponse),
-        formChangesHistory: []
-      })),
+        formChangesHistory: [],
+        invalidItems: updatedInvalidItems,
+        responseIsValid: Object.keys(updatedInvalidItems).length === 0
+      }));
+    },
     destroySourceResponse: () =>
       set(() => ({
         sourceResponse: cloneDeep(emptyResponse),
         updatableResponse: cloneDeep(emptyResponse),
         updatableResponseItems: createQuestionnaireResponseItemMap(cloneDeep(emptyResponse)),
-        formChangesHistory: []
+        formChangesHistory: [],
+        invalidItems: {},
+        responseIsValid: true
       }))
   })
 );
 
+/**
+ * QuestionnaireResponse 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 {QuestionnaireResponseStoreType} for available properties and methods.
+ * @see {questionnaireResponseStore} for the vanilla store.
+ *
+ * @author Sean Fong
+ */
 export const useQuestionnaireResponseStore = createSelectors(questionnaireResponseStore);

package/src/stores/questionnaireStore.ts

@@ -25,7 +25,7 @@ import type {
 import type { Variables } from '../interfaces/variables.interface';
 import type { LaunchContext } from '../interfaces/populate.interface';
 import type { CalculatedExpression } from '../interfaces/calculatedExpression.interface';
-import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces';
+import type { EnableWhenExpressions, EnableWhenItems } from '../interfaces/enableWhen.interface';
 import type { AnswerExpression } from '../interfaces/answerExpression.interface';
 import type { Tabs } from '../interfaces/tab.interface';
 import {
@@ -47,7 +47,47 @@ import { mutateRepeatEnableWhenExpressionInstances } from '../utils/enableWhenEx
 import { questionnaireResponseStore } from './questionnaireResponseStore';
 import { createQuestionnaireResponseItemMap } from '../utils/questionnaireResponseStoreUtils/updatableResponseItems';
 
-interface QuestionnaireStoreType {
+/**
+ * QuestionnaireStore properties and methods
+ * Properties can be accessed for fine-grain details.
+ * Methods are usually used internally, using them from an external source is not recommended.
+ *
+ * @property sourceQuestionnaire - FHIR R4 Questionnaire to render
+ * @property itemTypes - Key-value pair of item types `Record<linkId, item.type>`
+ * @property tabs - Key-value pair of tabs `Record<linkId, Tab>`
+ * @property currentTabIndex - Index of the current tab
+ * @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 enableWhenItems - EnableWhenItems object containing enableWhen items and their linked questions
+ * @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 processedValueSetCodings - Key-value pair of processed value set codings `Record<valueSetUrl, codings>`
+ * @property processedValueSetUrls - Key-value pair of contained value set urls `Record<valueSetName, valueSetUrl>`
+ * @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 populatedContext - Key-value pair of one-off pre-populated FHIRPath values `Record<variable/launchContext/sourceQueries batch name, evaluated value(s)>`
+ * @property focusedLinkId - LinkId of the currently focused item
+ * @property readOnly - Flag to set the form to read-only mode
+ * @method buildSourceQuestionnaire - Used to build the source questionnaire with the provided questionnaire and optionally questionnaire response, additional variables, terminology server url and readyOnly flag
+ * @method destroySourceQuestionnaire - Used to destroy the source questionnaire and reset all properties
+ * @method switchTab - Used to switch the current tab index
+ * @method markTabAsComplete - Used to mark a tab index as complete
+ * @method updateEnableWhenItem - Used to update linked enableWhen items by updating a question with a new answer
+ * @method mutateRepeatEnableWhenItems - Used to add or remove instances of repeating enableWhen items
+ * @method toggleEnableWhenActivation - Used to toggle enableWhen checks on/off
+ * @method updateExpressions - Used to update all SDC expressions based on the updated questionnaire response
+ * @method addCodingToCache - Used to add a coding to the cached value set codings
+ * @method updatePopulatedProperties - Used to update all SDC expressions based on a pre-populated questionnaire response
+ * @method onFocusLinkId - Used to set the focused linkId
+ * @method setPopulatedContext - Used to set the populated contexts (launchContext, sourceQueries, x-fhir-query vars) for debugging purposes
+ * @method setFormAsReadOnly - Used to set the form as read-only
+ *
+ * @author Sean Fong
+ */
+export interface QuestionnaireStoreType {
   sourceQuestionnaire: Questionnaire;
   itemTypes: Record<string, string>;
   tabs: Tabs;
@@ -97,8 +137,16 @@ interface QuestionnaireStoreType {
   ) => QuestionnaireResponse;
   onFocusLinkId: (linkId: string) => void;
   setPopulatedContext: (newPopulatedContext: 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.
+ *
+ * @author Sean Fong
+ */
 export const questionnaireStore = createStore<QuestionnaireStoreType>()((set, get) => ({
   sourceQuestionnaire: cloneDeep(emptyQuestionnaire),
   itemTypes: {},
@@ -349,7 +397,19 @@ export const questionnaireStore = createStore<QuestionnaireStoreType>()((set, ge
   setPopulatedContext: (newPopulatedContext: Record<string, any>) =>
     set(() => ({
       populatedContext: newPopulatedContext
+    })),
+  setFormAsReadOnly: (readOnly: boolean) =>
+    set(() => ({
+      readOnly: readOnly
     }))
 }));
 
+/**
+ * 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.
+ *
+ * @author Sean Fong
+ */
 export const useQuestionnaireStore = createSelectors(questionnaireStore);

package/src/stores/smartConfigStore.ts

@@ -20,6 +20,22 @@ import type { Encounter, Patient, Practitioner } from 'fhir/r4';
 import type Client from 'fhirclient/lib/Client';
 import { createSelectors } from './selector';
 
+/**
+ * SmartConfigStore properties and methods
+ * Properties can be accessed for fine-grain details.
+ * Methods are usually used internally, using them from an external source is not recommended.
+ *
+ * @property client - The FHIRClient object (https://github.com/smart-on-fhir/client-js)
+ * @property patient - The patient resource in context
+ * @property user - The user resource in context
+ * @property encounter - The encounter resource in context
+ * @method setClient - Set the FHIRClient object when launching via SMART App Launch
+ * @method setPatient - Set the patient resource in context
+ * @method setUser - Set the user resource in context
+ * @method setEncounter - Set the encounter resource in context
+ *
+ * @author Sean Fong
+ */
 export interface SmartConfigStoreType {
   client: Client | null;
   patient: Patient | null;
@@ -31,6 +47,16 @@ export interface SmartConfigStoreType {
   setEncounter: (encounter: Encounter) => void;
 }
 
+/**
+ * Smart Config state management store. This is only used for answerExpressions.
+ * It is recommended to manage the state of the FHIRClient, patient, user, and encounter in the parent application, since the renderer doesn't provide pre-population capabilities.
+ * Will be deprecated in version 1.0.0.
+ *
+ * This is the vanilla version of the store which can be used in non-React environments.
+ * @see {SmartConfigStoreType} for available properties and methods.
+ *
+ * @author Sean Fong
+ */
 export const smartConfigStore = createStore<SmartConfigStoreType>()((set) => ({
   client: null,
   patient: null,
@@ -42,4 +68,15 @@ export const smartConfigStore = createStore<SmartConfigStoreType>()((set) => ({
   setEncounter: (encounter: Encounter) => set(() => ({ encounter: encounter }))
 }));
 
+/**
+ * Smart Config state management store. This is only used for answerExpressions.
+ * It is recommended to manage the state of the FHIRClient, patient, user, and encounter in the parent application, since the renderer doesn't provide pre-population capabilities.
+ * Will be deprecated in version 1.0.0.
+ *
+ * This is the React version of the store which can be used as React hooks in React functional components.
+ * @see {SmartConfigStoreType} for available properties and methods.
+ * @see {smartConfigStore} for the vanilla store.
+ *
+ * @author Sean Fong
+ */
 export const useSmartConfigStore = createSelectors(smartConfigStore);