@medplum/react-hooks/dist/cjs/index.d.ts

Medplum React Hooks Library

import { Bundle } from '@medplum/fhirtypes';
import { Context } from 'react';
import { Encounter } from '@medplum/fhirtypes';
import { ExtractResource } from '@medplum/fhirtypes';
import { JSX } from 'react';
import { MedplumClient } from '@medplum/core';
import { OperationOutcome } from '@medplum/fhirtypes';
import { ProfileResource } from '@medplum/core';
import { QueryTypes } from '@medplum/core';
import { Questionnaire } from '@medplum/fhirtypes';
import { QuestionnaireItem } from '@medplum/fhirtypes';
import { QuestionnaireItemAnswerOption } from '@medplum/fhirtypes';
import { QuestionnaireItemEnableWhen } from '@medplum/fhirtypes';
import { QuestionnaireItemInitial } from '@medplum/fhirtypes';
import { QuestionnaireResponse } from '@medplum/fhirtypes';
import { QuestionnaireResponseItem } from '@medplum/fhirtypes';
import { QuestionnaireResponseItemAnswer } from '@medplum/fhirtypes';
import { ReactNode } from 'react';
import { Reference } from '@medplum/fhirtypes';
import { Resource } from '@medplum/fhirtypes';
import { ResourceArray } from '@medplum/core';
import { ResourceType } from '@medplum/fhirtypes';
import { Signature } from '@medplum/fhirtypes';
import { Subscription } from '@medplum/fhirtypes';
import { TypedValue } from '@medplum/core';

export declare function buildInitialResponse(questionnaire: Questionnaire, questionnaireResponse?: QuestionnaireResponse): QuestionnaireResponse;

export declare function buildInitialResponseItem(item: QuestionnaireItem): QuestionnaireResponseItem;

/**
 * Evaluates the calculated expressions in a questionnaire.
 * Updates response item answers in place with the calculated values.
 *
 * See: https://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-calculatedExpression.html
 *
 * @param items - The questionnaire items to evaluate.
 * @param response - The questionnaire response to evaluate against.
 * @param responseItems - The response items to update.
 */
export declare function evaluateCalculatedExpressionsInQuestionnaire(items: QuestionnaireItem[], response: QuestionnaireResponse, responseItems?: QuestionnaireResponseItem[] | undefined): void;

export declare function getItemAnswerOptionValue(option: QuestionnaireItemAnswerOption): TypedValue;

export declare function getItemEnableWhenValueAnswer(enableWhen: QuestionnaireItemEnableWhen): TypedValue;

export declare function getItemInitialValue(initial: QuestionnaireItemInitial | undefined): TypedValue;

export declare function getNewMultiSelectValues(selected: string[], propertyName: string, item: QuestionnaireItem): QuestionnaireResponseItemAnswer[];

/**
 * Returns the reference filter for the given questionnaire item.
 * @see https://build.fhir.org/ig/HL7/fhir-extensions/StructureDefinition-questionnaire-referenceFilter-definitions.html
 * @param item - The questionnaire item to get the reference filter for.
 * @param subject - Optional subject reference.
 * @param encounter - Optional encounter reference.
 * @returns The reference filter as a map of key/value pairs.
 */
export declare function getQuestionnaireItemReferenceFilter(item: QuestionnaireItem, subject: Reference | undefined, encounter: Reference<Encounter> | undefined): Record<string, string> | undefined;

export declare function getQuestionnaireItemReferenceTargetTypes(item: QuestionnaireItem): ResourceType[] | undefined;

export declare function getResponseItemAnswerValue(answer: QuestionnaireResponseItemAnswer): TypedValue | undefined;

/**
 * Returns true if the item is a choice question.
 * @param item - The questionnaire item to check.
 * @returns True if the item is a choice question, false otherwise.
 */
export declare function isChoiceQuestion(item: QuestionnaireItem): boolean;

/**
 * Returns true if the questionnaire item is enabled based on the enableWhen conditions or expression.
 * @param item - The questionnaire item to check.
 * @param questionnaireResponse - The questionnaire response to check against.
 * @returns True if the question is enabled, false otherwise.
 */
export declare function isQuestionEnabled(item: QuestionnaireItem, questionnaireResponse: QuestionnaireResponse | undefined): boolean;

export declare interface MedplumContext {
    medplum: MedplumClient;
    navigate: MedplumNavigateFunction;
    profile?: ProfileResource;
    loading: boolean;
}

export declare type MedplumNavigateFunction = (path: string) => void;

/**
 * The MedplumProvider component provides Medplum context state.
 *
 * Medplum context includes:
 *   1) medplum - Medplum client library
 *   2) profile - The current user profile (if signed in)
 * @param props - The MedplumProvider React props.
 * @returns The MedplumProvider React node.
 */
export declare function MedplumProvider(props: MedplumProviderProps): JSX.Element;

export declare interface MedplumProviderProps {
    readonly medplum: MedplumClient;
    readonly navigate?: MedplumNavigateFunction;
    readonly children: ReactNode;
}

export declare const QUESTIONNAIRE_CALCULATED_EXPRESSION_URL = "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-calculatedExpression";

export declare const QUESTIONNAIRE_ENABLED_WHEN_EXPRESSION_URL = "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-enableWhenExpression";

export declare const QUESTIONNAIRE_ITEM_CONTROL_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl";

export declare const QUESTIONNAIRE_REFERENCE_FILTER_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceFilter";

export declare const QUESTIONNAIRE_REFERENCE_RESOURCE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-referenceResource";

export declare const QUESTIONNAIRE_SIGNATURE_REQUIRED_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-signatureRequired";

export declare const QUESTIONNAIRE_SIGNATURE_RESPONSE_URL = "http://hl7.org/fhir/StructureDefinition/questionnaireresponse-signature";

export declare const QUESTIONNAIRE_VALIDATION_ERROR_URL = "http://hl7.org/fhir/StructureDefinition/questionnaire-validationError";

export declare interface QuestionnaireFormLoadedState {
    /** Not loading */
    readonly loading: false;
    /** The loaded questionnaire */
    questionnaire: Questionnaire;
    /** The current draft questionnaire response */
    questionnaireResponse: QuestionnaireResponse;
    /** Optional questionnaire subject */
    subject?: Reference;
    /** Optional questionnaire encounter */
    encounter?: Reference<Encounter>;
    /** The top level items for the current page */
    items: QuestionnaireItem[];
    /** The response items for the current page */
    responseItems: QuestionnaireResponseItem[];
    /**
     * Adds a new group item to the current context.
     * @param context - The current context of the questionnaire response items.
     * @param item - The questionnaire item that is being added to the group.
     */
    onAddGroup: (context: QuestionnaireResponseItem[], item: QuestionnaireItem) => void;
    /**
     * Adds an answer to a repeating item.
     * @param context - The current context of the questionnaire response items.
     * @param item - The questionnaire item that is being answered.
     */
    onAddAnswer: (context: QuestionnaireResponseItem[], item: QuestionnaireItem) => void;
    /**
     * Changes an answer value.
     * @param context - The current context of the questionnaire response items.
     * @param item - The questionnaire item that is being answered.
     * @param answer - The answer(s) provided by the user for the questionnaire item.
     */
    onChangeAnswer: (context: QuestionnaireResponseItem[], item: QuestionnaireItem, answer: QuestionnaireResponseItemAnswer[]) => void;
    /**
     * Sets or updates the signature for the questionnaire response.
     * @param signature - The signature to set, or undefined to clear the signature.
     */
    onChangeSignature: (signature: Signature | undefined) => void;
}

export declare interface QuestionnaireFormLoadingState {
    /** Currently loading data such as the Questionnaire or the QuestionnaireResponse default value */
    readonly loading: true;
}

export declare interface QuestionnaireFormPage {
    readonly linkId: string;
    readonly title: string;
    readonly group: QuestionnaireItem & {
        type: 'group';
    };
}

export declare interface QuestionnaireFormPaginationState extends QuestionnaireFormLoadedState {
    readonly pagination: true;
    pages: QuestionnaireFormPage[];
    activePage: number;
    onNextPage: () => void;
    onPrevPage: () => void;
}

export declare interface QuestionnaireFormSinglePageState extends QuestionnaireFormLoadedState {
    readonly pagination: false;
}

export declare type QuestionnaireFormState = QuestionnaireFormLoadingState | QuestionnaireFormSinglePageState | QuestionnaireFormPaginationState;

export declare const QuestionnaireItemType: {
    readonly group: "group";
    readonly display: "display";
    readonly question: "question";
    readonly boolean: "boolean";
    readonly decimal: "decimal";
    readonly integer: "integer";
    readonly date: "date";
    readonly dateTime: "dateTime";
    readonly time: "time";
    readonly string: "string";
    readonly text: "text";
    readonly url: "url";
    readonly choice: "choice";
    readonly openChoice: "open-choice";
    readonly attachment: "attachment";
    readonly reference: "reference";
    readonly quantity: "quantity";
};

export declare type QuestionnaireItemType = (typeof QuestionnaireItemType)[keyof typeof QuestionnaireItemType];

export declare const reactContext: Context<MedplumContext | undefined>;

export declare type SearchOptions = {
    debounceMs?: number;
};

export declare function setQuestionnaireItemReferenceTargetTypes(item: QuestionnaireItem, targetTypes: ResourceType[] | undefined): QuestionnaireItem;

export declare function typedValueToResponseItem(item: QuestionnaireItem, value: TypedValue): QuestionnaireResponseItemAnswer | undefined;

export declare const useCachedBinaryUrl: (binaryUrl: string | undefined) => string | undefined;

/**
 * Returns the MedplumClient instance.
 * This is a shortcut for useMedplumContext().medplum.
 * @returns The MedplumClient instance.
 */
export declare function useMedplum(): MedplumClient;

/**
 * Returns the MedplumContext instance.
 * @returns The MedplumContext instance.
 */
export declare function useMedplumContext(): MedplumContext;

/**
 * Returns the Medplum navigate function.
 * @returns The Medplum navigate function.
 */
export declare function useMedplumNavigate(): MedplumNavigateFunction;

/**
 * Returns the current Medplum user profile (if signed in).
 * This is a shortcut for useMedplumContext().profile.
 * @returns The current user profile.
 */
export declare function useMedplumProfile(): ProfileResource | undefined;

/**
 * React Hook to keep track of the passed-in value from the previous render of the containing component.
 * @param value - The value to track.
 * @returns The value passed in from the previous render.
 */
export declare function usePrevious<T>(value: T): T | undefined;

export declare function useQuestionnaireForm(props: UseQuestionnaireFormProps): Readonly<QuestionnaireFormState>;

export declare interface UseQuestionnaireFormProps {
    readonly questionnaire: Questionnaire | Reference<Questionnaire>;
    readonly defaultValue?: QuestionnaireResponse | Reference<QuestionnaireResponse>;
    readonly subject?: Reference;
    readonly encounter?: Reference<Encounter>;
    readonly source?: QuestionnaireResponse['source'];
    readonly disablePagination?: boolean;
    readonly onChange?: (response: QuestionnaireResponse) => void;
}

/**
 * React Hook to use a FHIR reference.
 * Handles the complexity of resolving references and caching resources.
 * @param value - The resource or reference to resource.
 * @param setOutcome - Optional callback to set the OperationOutcome.
 * @returns The resolved resource.
 */
export declare function useResource<T extends Resource>(value: Reference<T> | Partial<T> | undefined, setOutcome?: (outcome: OperationOutcome) => void): T | undefined;

/**
 * React hook for searching FHIR resources.
 *
 * This is a convenience hook for calling the MedplumClient.search() method.
 *
 * @param resourceType - The FHIR resource type to search.
 * @param query - Optional search parameters.
 * @param options - Optional options for configuring the search.
 * @returns A 3-element tuple containing the search result, loading flag, and operation outcome.
 */
export declare function useSearch<K extends ResourceType>(resourceType: K, query?: QueryTypes, options?: SearchOptions): [Bundle<ExtractResource<K>> | undefined, boolean, OperationOutcome | undefined];

/**
 * React hook for searching for a single FHIR resource.
 *
 * This is a convenience hook for calling the MedplumClient.searchOne() method.
 *
 * @param resourceType - The FHIR resource type to search.
 * @param query - Optional search parameters.
 * @param options - Optional options for configuring the search.
 * @returns A 3-element tuple containing the search result, loading flag, and operation outcome.
 */
export declare function useSearchOne<K extends ResourceType>(resourceType: K, query?: QueryTypes, options?: SearchOptions): [ExtractResource<K> | undefined, boolean, OperationOutcome | undefined];

/**
 * React hook for searching for an array of FHIR resources.
 *
 * This is a convenience hook for calling the MedplumClient.searchResources() method.
 *
 * @param resourceType - The FHIR resource type to search.
 * @param query - Optional search parameters.
 * @param options - Optional options for configuring the search.
 * @returns A 3-element tuple containing the search result, loading flag, and operation outcome.
 */
export declare function useSearchResources<K extends ResourceType>(resourceType: K, query?: QueryTypes, options?: SearchOptions): [ResourceArray<ExtractResource<K>> | undefined, boolean, OperationOutcome | undefined];

/**
 * Creates an in-memory `Subscription` resource with the given criteria on the Medplum server and calls the given callback when an event notification is triggered by a resource interaction over a WebSocket connection.
 *
 * Subscriptions created with this hook are lightweight, share a single WebSocket connection, and are automatically untracked and cleaned up when the containing component is no longer mounted.
 *
 * @param criteria - The FHIR search criteria to subscribe to.
 * @param callback - The callback to call when a notification event `Bundle` for this `Subscription` is received.
 * @param options - Optional options used to configure the created `Subscription`. See {@link UseSubscriptionOptions}
 *
 * --------------------------------------------------------------------------------------------------------------------------------
 *
 * `options` contains the following properties, all of which are optional:
 * - `subscriptionProps` - Allows the caller to pass a `Partial<Subscription>` to use as part of the creation
 * of the `Subscription` resource for this subscription. It enables the user namely to pass things like the `extension` property and to create
 * the `Subscription` with extensions such the {@link https://www.medplum.com/docs/subscriptions/subscription-extensions#interactions | Supported Interaction} extension which would enable to listen for `create` or `update` only events.
 * - `onWebsocketOpen` - Called when the WebSocket connection is established with Medplum server.
 * - `onWebsocketClose` - Called when the WebSocket connection disconnects.
 * - `onSubscriptionConnect` - Called when the corresponding subscription starts to receive updates after the subscription has been initialized and connected to.
 * - `onSubscriptionDisconnect` - Called when the corresponding subscription is destroyed and stops receiving updates from the server.
 * - `onError` - Called whenever an error occurs during the lifecycle of the managed subscription.
 */
export declare function useSubscription(criteria: string | undefined, callback: (bundle: Bundle) => void, options?: UseSubscriptionOptions): void;

export declare type UseSubscriptionOptions = {
    subscriptionProps?: Partial<Subscription>;
    onWebSocketOpen?: () => void;
    onWebSocketClose?: () => void;
    onSubscriptionConnect?: (subscriptionId: string) => void;
    onSubscriptionDisconnect?: (subscriptionId: string) => void;
    onError?: (err: Error) => void;
};

export { }