@medplum/react 5.1.24 → 5.1.27

package/dist/esm/index.d.ts

@@ -52,8 +52,14 @@ import type { MantineColor } from '@mantine/core';
 import type { MeasureReport } from '@medplum/fhirtypes';
 import type { Media } from '@medplum/fhirtypes';
 import type { Medication } from '@medplum/fhirtypes';
+import type { MedicationCartClearRequest } from '@medplum/core';
+import type { MedicationCartManageResponse } from '@medplum/core';
+import type { MedicationCartRemoveRequest } from '@medplum/core';
+import type { MedicationCheckoutRequest } from '@medplum/core';
+import type { MedicationCheckoutResponse } from '@medplum/core';
 import type { MedicationOrderRequest } from '@medplum/core';
 import type { MedicationOrderResponse } from '@medplum/core';
+import type { MedicationRequest } from '@medplum/fhirtypes';
 import type { MedicationSearchParams } from '@medplum/core';
 import type { MedplumClient } from '@medplum/core';
 import { MemoExoticComponent } from 'react';
@@ -66,8 +72,10 @@ import type { ObservationDefinitionQualifiedInterval } from '@medplum/fhirtypes'
 import type { OperationOutcome } from '@medplum/fhirtypes';
 import type { OperationOutcomeIssue } from '@medplum/fhirtypes';
 import { Operator } from '@medplum/core';
+import type { OrderSetSyncResponse } from '@medplum/core';
 import type { Organization } from '@medplum/fhirtypes';
 import type { PaperProps } from '@mantine/core';
+import type { PasswordInputProps } from '@mantine/core';
 import type { Patient } from '@medplum/fhirtypes';
 import { PATIENT_PREFERRED_PHARMACY_URL } from '@medplum/core';
 import type { Period } from '@medplum/fhirtypes';
@@ -98,6 +106,7 @@ import { removePreferredPharmacyFromPatient } from '@medplum/core';
 import type { RequestGroup } from '@medplum/fhirtypes';
 import type { Resource } from '@medplum/fhirtypes';
 import type { ResourceArray } from '@medplum/core';
+import type { ResourceModifiedEvent } from '@medplum/core';
 import type { ResourceType } from '@medplum/fhirtypes';
 import type { Schedule } from '@medplum/fhirtypes';
 import type { SearchParameter } from '@medplum/fhirtypes';
@@ -469,6 +478,16 @@ export declare function buildInitialResponse(questionnaire: Questionnaire, quest
 
 export declare function buildInitialResponseItem(item: QuestionnaireItem): QuestionnaireResponseItem;
 
+/**
+ * Returns a display label for a search parameter code.
+ *
+ * Meta fields keep their underscore-prefixed code so they don't collide with same-named
+ * elements (e.g. `ProjectMembership.project` vs `_project`).
+ * @param code - The search parameter code.
+ * @returns The display label for the search parameter.
+ */
+export declare function buildSearchParamFieldLabel(code: string): string;
+
 export declare function CalendarDateInput(props: CalendarDateInputProps): JSX.Element;
 
 export declare interface CalendarDateInputProps {
@@ -1048,6 +1067,13 @@ export declare function isCheckboxCell(el: Element): boolean;
  */
 export declare function isChoiceQuestion(item: QuestionnaireItem): boolean;
 
+/**
+ * Returns true if the given search parameter code refers to a resource metadata field.
+ * @param code - The search parameter code.
+ * @returns True if the code is a meta search parameter.
+ */
+export declare function isMetaSearchParam(code: string): boolean;
+
 export { isOrganizationArray }
 
 /**
@@ -1062,6 +1088,15 @@ export declare function isSortDescending(definition: SearchRequest): boolean;
 
 export declare function isSupportedProfileStructureDefinition(profile?: StructureDefinition): profile is SupportedProfileStructureDefinition;
 
+/**
+ * Returns true if an error thrown while expanding a ValueSet means the value set itself is
+ * unavailable — a permanent 400/404 (e.g. "ValueSet not found"). Transient failures (429 rate
+ * limit, 401, 5xx, network) return false so a blip never disables a field.
+ * @param err - The error thrown by `valueSetExpand`.
+ * @returns True for a permanent 400/404, false for a transient failure.
+ */
+export declare function isValueSetUnavailableError(err: unknown): boolean;
+
 /**
  * Kills a browser event.
  * Prevents default behavior.
@@ -1090,8 +1125,8 @@ export declare interface LinkTabsProps extends Omit<TabsProps, 'value' | 'onChan
  * @returns The ListWithDetailPane React node.
  */
 export declare function ListWithDetailPane<T extends {
-    id: string;
-} = WithId<Resource>>(props: ListWithDetailPaneProps<T>): JSX.Element;
+    id?: string;
+} = Resource>(props: ListWithDetailPaneProps<T>): JSX.Element;
 
 export declare interface ListWithDetailPaneDetailContext {
     readonly refresh: () => Promise<void>;
@@ -1101,21 +1136,21 @@ export declare interface ListWithDetailPaneDetailContext {
 export declare type ListWithDetailPaneHeaderProps = ListWithDetailPaneTextHeaderProps | ListWithDetailPaneTabsHeaderProps;
 
 export declare interface ListWithDetailPaneItemContext<T extends {
-    id: string;
-} = WithId<Resource>> {
+    id?: string;
+} = Resource> {
     readonly selected: boolean;
     readonly index: number;
     readonly items: T[];
 }
 
 export declare type ListWithDetailPaneProps<T extends {
-    id: string;
-} = WithId<Resource>> = ListWithDetailPanePropsBase<T> & ListWithDetailPaneHeaderProps;
+    id?: string;
+} = Resource> = ListWithDetailPanePropsBase<T> & ListWithDetailPaneHeaderProps;
 
 /** Props shared by every ListWithDetailPane, independent of the header style. */
 export declare interface ListWithDetailPanePropsBase<T extends {
-    id: string;
-} = WithId<Resource>> {
+    id?: string;
+} = Resource> {
     /** The current page of items to render in the list. */
     readonly items: T[];
     /** When true, the list area shows the skeleton instead of items. */
@@ -1189,8 +1224,13 @@ export declare interface MeasureReportDisplayProps {
     readonly measureReport: MeasureReport | Reference<MeasureReport>;
 }
 
+/** Thrown by {@link UseMedicationCartReturn.checkout} when an {@link UseMedicationCartReturn.addToCart} call is still in flight. */
+export declare const MEDICATION_CART_ADD_IN_PROGRESS = "Cannot checkout while a medication is still being added to the cart";
+
 export declare interface MedicationIFrameOptions {
     readonly patientId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
     readonly onPatientSyncSuccess?: () => void;
     readonly onIframeSuccess?: (url: string) => void;
     readonly onError?: (err: unknown) => void;
@@ -1439,6 +1479,7 @@ export declare function OperationOutcomeAlert(props: OperationOutcomeAlertProps)
 export declare interface OperationOutcomeAlertProps extends AlertProps {
     readonly outcome?: OperationOutcome;
     readonly issues?: OperationOutcomeIssue[];
+    readonly displayOkOutcomes?: boolean;
 }
 
 export declare function Panel(props: PanelProps): JSX.Element;
@@ -1463,6 +1504,15 @@ export declare interface ParticipantFilterProps {
     readonly onFilterChange: (participants: Reference<Patient | Practitioner>[]) => void;
 }
 
+/**
+ * Mantine's `PasswordInput` sets `tabIndex={-1}` and `aria-hidden` on the visibility toggle button
+ * unless `visibilityToggleButtonProps` is provided, which removes it from the keyboard tab order and
+ * hides it from assistive technology. This wrapper defaults the toggle to be keyboard accessible.
+ * @param props - The password input props.
+ * @returns The password input component.
+ */
+export declare function PasswordInput(props: PasswordInputProps): JSX.Element;
+
 export { PATIENT_PREFERRED_PHARMACY_URL }
 
 export declare function PatientAccountsForm(props: PatientAccountsFormProps): JSX.Element;
@@ -1561,8 +1611,33 @@ export declare interface PharmacyDialogProps {
     readonly patient: Patient;
     readonly onSubmit: (pharmacy: Organization) => void;
     readonly onClose: () => void;
-    readonly onSearch: (params: PharmacySearchParams) => Promise<Organization[]>;
+    readonly onSearch: (params: PharmacySearchParams & Record<string, unknown>) => Promise<Organization[]>;
     readonly onAddToFavorites: (params: AddFavoriteParams) => Promise<AddPharmacyResponse>;
+    /** Optional fields rendered inside the search form above the submit button. */
+    readonly renderBeforeSearchButton?: ReactNode;
+    /**
+     * Extra search parameters merged into the bot request (e.g. vendor-specific filters).
+     * `handleSearch` depends on this callback, so callers should memoize it (e.g. `useCallback`)
+     * to avoid re-creating the search handler on every render.
+     */
+    readonly getExtraSearchParams?: () => Record<string, unknown>;
+    /** Optional per-field placeholder overrides for the search form. */
+    readonly searchPlaceholders?: PharmacySearchFieldPlaceholders;
+}
+
+/**
+ * Placeholder text for each pharmacy search field. Vendors can override these to
+ * reflect their own API constraints (e.g. DoseSpot requires a 3-character minimum
+ * on text searches, whereas ScriptSure expects a 2-letter state and 5-digit ZIP).
+ */
+export declare interface PharmacySearchFieldPlaceholders {
+    readonly name?: string;
+    readonly city?: string;
+    readonly state?: string;
+    readonly zip?: string;
+    readonly phoneOrFax?: string;
+    readonly address?: string;
+    readonly ncpdpID?: string;
 }
 
 export { PharmacySearchParams }
@@ -1837,6 +1912,7 @@ export declare interface RegisterFormProps {
     readonly recaptchaSiteKey?: string;
     readonly children?: ReactNode;
     readonly onSuccess: () => void;
+    readonly onSignIn?: () => void;
 }
 
 /**
@@ -2184,6 +2260,22 @@ export declare class SearchClickEvent extends Event {
  */
 export declare function SearchControl(props: SearchControlProps): JSX.Element;
 
+/**
+ * An additional, computed column appended after the search-result columns.
+ *
+ * Unlike the columns derived from {@link SearchControlProps.search} fields, an
+ * additional column is not backed by a search parameter and has no sort/filter
+ * menu: it renders arbitrary content per row. Use it for values that must be
+ * computed or fetched separately from the searched resource (e.g. a related
+ * resource's status).
+ */
+export declare interface SearchControlAdditionalColumn {
+    /** The column header text. */
+    readonly name: string;
+    /** Renders the cell contents for the given row resource. */
+    readonly renderCell: (resource: Resource) => ReactNode;
+}
+
 /**
  * The SearchControlField type describes a field in the search control.
  *
@@ -2220,6 +2312,8 @@ export declare interface SearchControlField {
 export declare interface SearchControlProps {
     readonly search: SearchRequest;
     readonly checkboxesEnabled?: boolean;
+    /** Additional computed columns rendered after the search-result columns. */
+    readonly additionalColumns?: readonly SearchControlAdditionalColumn[];
     readonly hideToolbar?: boolean;
     readonly hideFilters?: boolean;
     readonly onLoad?: (e: SearchLoadEvent) => void;
@@ -2558,8 +2652,63 @@ export declare type TranscriptItem = {
 
 export declare function typedValueToResponseItem(item: QuestionnaireItem, value: TypedValue): QuestionnaireResponseItemAnswer | undefined;
 
+export declare function UnavailableNote({ text, color, message }: UnavailableNoteProps): JSX.Element;
+
+export declare interface UnavailableNoteProps {
+    readonly text: string;
+    readonly color: string;
+    readonly message: string;
+}
+
 export declare const useCachedBinaryUrl: (binaryUrl: string | undefined) => string | undefined;
 
+/**
+ * Vendor-neutral hook for the full **medication cart** lifecycle: add a draft
+ * line (`createResource`), check out a set of drafts into the vendor's batch
+ * approval queue (`$checkout-medications`), and remove/clear cart lines
+ * (`$remove-cart-medication` / `$clear-cart`).
+ *
+ * Cart checkout / remove / clear hit project-scoped **FHIR custom operations**
+ * whose backing Bot is chosen at deploy time via an `OperationDefinition`
+ * carrying the `operationDefinition-implementation` extension — see
+ * [bot operations docs](https://www.medplum.com/docs/bots/custom-fhir-operations).
+ * The server's `tryCustomOperation` dispatch handles the OD → Bot lookup, so
+ * projects swap vendors by deploying a different bot under the same code.
+ *
+ * `addToCart` is plain FHIR `createResource` (no `$add-cart` operation): the
+ * Medplum-side cart is the set of draft `MedicationRequest`s. Vendor staging
+ * (e.g. ScriptSure MedCart) happens at checkout. Vendors without a batch
+ * approval queue (e.g. DoseSpot iframe-first) simply never call `checkout` /
+ * `removeFromCart` / `clearCart`.
+ *
+ * Requests for the custom operations are encoded as `Parameters` bodies and
+ * decoded by the matching `@medplum/core` helpers. Per-line outcomes arrive in
+ * `response.items`.
+ *
+ * @returns Cart add / checkout / remove / clear callbacks plus `adding` state.
+ */
+export declare function useMedicationCart(): UseMedicationCartReturn;
+
+export declare interface UseMedicationCartReturn {
+    /**
+     * Persist a draft `MedicationRequest` as a cart line via plain FHIR
+     * `createResource` (no custom operation). Vendor staging happens later at
+     * {@link UseMedicationCartReturn.checkout}.
+     */
+    addToCart: (medicationRequest: MedicationRequest) => Promise<MedicationRequest>;
+    /** True while one or more {@link UseMedicationCartReturn.addToCart} calls are in flight. */
+    adding: boolean;
+    /**
+     * Submit draft cart lines to the vendor's batch approval queue and return an
+     * embeddable approval-widget URL. Refuses while {@link UseMedicationCartReturn.adding} is true.
+     */
+    checkout: (input: MedicationCheckoutRequest) => Promise<MedicationCheckoutResponse>;
+    /** Remove a single draft `MedicationRequest` from the patient's vendor cart. */
+    removeFromCart: (input: MedicationCartRemoveRequest) => Promise<MedicationCartManageResponse>;
+    /** Remove every item from the patient's vendor cart. */
+    clearCart: (input: MedicationCartClearRequest) => Promise<MedicationCartManageResponse>;
+}
+
 /**
  * Generic React hook that syncs a patient to a medication-order vendor and
  * returns the chart iframe URL.
@@ -2643,6 +2792,8 @@ export declare interface UseMedicationOrderSetOptions {
     /** Vendor-side order set id, when picked directly (escape hatch when no synced PD exists yet). */
     readonly vendorOrderSetId?: number | string;
     readonly appId?: string;
+    /** Selected practice location for multi-practice deployments. */
+    readonly organization?: Reference<Organization>;
 }
 
 export declare interface UseMedicationOrderSetReturn {
@@ -2725,14 +2876,18 @@ export declare function usePatientSummaryData(patient: Patient | Reference<Patie
  * Encapsulates calls to a search-pharmacy bot and an add-patient-pharmacy bot,
  * and can be composed with the generic `PharmacyDialog` component from `@medplum/react`.
  *
+ * The search param type is generic so vendor hooks can widen it with their own
+ * filters (e.g. ScriptSure `specialties`); the extra keys are passed through to
+ * the bot as-is at runtime.
+ *
  * @param searchBotIdentifier - Bot identifier for the pharmacy search bot.
  * @param addPharmacyBotIdentifier - Bot identifier for the add-patient-pharmacy bot.
  * @returns An object with `searchPharmacies` and `addToFavorites` callbacks.
  */
-export declare function usePharmacySearch(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn;
+export declare function usePharmacySearch<T extends PharmacySearchParams = PharmacySearchParams>(searchBotIdentifier: Identifier, addPharmacyBotIdentifier: Identifier): UsePharmacySearchReturn<T>;
 
-export declare interface UsePharmacySearchReturn {
-    searchPharmacies: (params: PharmacySearchParams) => Promise<Organization[]>;
+export declare interface UsePharmacySearchReturn<T extends PharmacySearchParams = PharmacySearchParams> {
+    searchPharmacies: (params: T) => Promise<Organization[]>;
     addToFavorites: (params: AddFavoriteParams) => Promise<AddPharmacyResponse>;
 }
 
@@ -2802,6 +2957,30 @@ export declare interface UseResourceBoardResult<T extends Resource = Resource> {
     readonly refresh: () => Promise<void>;
 }
 
+/**
+ * React hook for observing FHIR resource modifications made through the Medplum client.
+ *
+ * The callback is invoked whenever this client instance creates, updates, patches, or deletes
+ * a resource of one of the given types, including modifications announced with
+ * `MedplumClient.notifyResourceModified`. Use it to keep local component state in sync with
+ * mutations made elsewhere in the application. Subscribing to a single resource type narrows
+ * the event so `event.resource` is typed to that resource, no type guard required:
+ *
+ * ```tsx
+ * useResourceModified('Slot', (event) => {
+ *   // event.resource is `WithId<Slot> | undefined`
+ * });
+ * useResourceModified(['Slot', 'Appointment'], () => refreshSchedule());
+ * ```
+ *
+ * Modifications made by other clients (or other users) are not observed;
+ * use `useSubscription` for server-side change notifications.
+ *
+ * @param resourceType - The resource type or types to observe.
+ * @param callback - Invoked with the event payload for each matching modification.
+ */
+export declare function useResourceModified<K extends ResourceType>(resourceType: K | K[], callback: (event: ResourceModifiedEvent<ExtractResource<K>>) => void): void;
+
 /**
  * React hook for searching FHIR resources.
  *
@@ -2875,13 +3054,18 @@ export declare type UseSubscriptionOptions = {
  * to the configured e-prescribing vendor via the `$sync-orderset` custom FHIR operation
  * (`POST /fhir/R4/PlanDefinition/$sync-orderset`).
  *
- * Silently no-ops when the operation is not deployed (i.e. no e-prescribing vendor
- * is configured for the project), so callers do not need to guard against missing
- * integrations.
+ * Resolves with the decoded `OrderSetSyncResponse` so callers can surface
+ * per-action failures (`results[i].status === 'failed'` / `failedCount > 0`) —
+ * without this, an order set that only partially synced would silently apply
+ * with fewer meds than the PlanDefinition requested.
+ *
+ * Resolves with `undefined` when the operation is not deployed (i.e. no
+ * e-prescribing vendor is configured for the project), so callers do not need to
+ * guard against missing integrations.
  *
- * @returns A stable `syncOrderSet(planDefinitionId)` callback.
+ * @returns A stable `syncOrderSet(planDefinitionId, organization?)` callback.
  */
-export declare function useSyncOrderSet(): (planDefinitionId: string) => Promise<void>;
+export declare function useSyncOrderSet(): (planDefinitionId: string, organization?: Reference<Organization>) => Promise<OrderSetSyncResponse | undefined>;
 
 export declare function useThreadInbox({ query, threadId }: UseThreadInboxOptions): UseThreadInboxReturn;
 
@@ -2901,6 +3085,30 @@ export declare interface UseThreadInboxReturn {
     refreshThreadMessages: () => Promise<void>;
 }
 
+/**
+ * Probes a set of ValueSet URLs for availability, each with a filter-free, count-limited expansion.
+ *
+ * A filter-free probe means a 400/404 unambiguously describes the value set itself (unlike a
+ * user-typed search, whose 400 can be filter-specific), so the verdict is safe to act on. Repeated
+ * probes of the same URL are deduplicated by the `MedplumClient` request cache, which caches
+ * rejections too, so many fields bound to the same missing value set cost one request. Recovery
+ * after a value set is imported happens on the next mount (i.e. a page refresh) — there is no live
+ * subscription. Transient failures (429/5xx/network) resolve as available so a blip never disables
+ * a field; only a permanent 400/404 marks a URL unavailable.
+ * @param urls - The ValueSet URLs to probe. Falsy entries are ignored, and duplicates collapse to a
+ * single probe.
+ * @returns The availability verdict, with `loading` true until every requested URL has settled.
+ */
+export declare function useValueSetAvailabilities(urls: readonly (string | undefined)[]): ValueSetAvailability;
+
+/**
+ * Probes a single ValueSet's availability once on mount. A thin wrapper around
+ * {@link useValueSetAvailabilities} for the common single-value-set case.
+ * @param url - The ValueSet URL, or undefined for unbound inputs (always available).
+ * @returns undefined while the probe is in flight, true if available, false if unavailable.
+ */
+export declare function useValueSetAvailability(url: string | undefined): boolean | undefined;
+
 export declare function useWhisper({ language, model, onTranscript, idleTimeoutMs, }: UseWhisperOptions): UseWhisperResult;
 
 export declare type UseWhisperOptions = {
@@ -2922,6 +3130,8 @@ export declare type UseWhisperResult = {
     start: () => Promise<void>;
     stop: () => void;
     isListening: boolean;
+    muted: boolean;
+    setMuted: (value: boolean) => void;
 };
 
 /**
@@ -2940,6 +3150,18 @@ export declare interface ValueSetAutocompleteProps extends Omit<AsyncAutocomplet
     readonly withHelpText?: boolean;
 }
 
+/**
+ * The result of probing one or more ValueSet URLs for availability.
+ */
+export declare interface ValueSetAvailability {
+    /** True while at least one requested URL is still being probed. */
+    readonly loading: boolean;
+    /** The subset of requested URLs known to be available. */
+    readonly available: string[];
+    /** The subset of requested URLs known to be unavailable (a permanent 400/404). */
+    readonly unavailable: string[];
+}
+
 export declare function valueSetElementToCoding(element: ValueSetExpansionContains): Coding;
 
 /** Vitals section — searches for Observation resources with category vital-signs. */