@medplum/react-scheduling 5.1.38 → 5.1.39

package/dist/esm/index.d.ts

@@ -9,8 +9,8 @@ import type { MantineThemeColors } from '@mantine/core';
 import type { MedplumClient } from '@medplum/core';
 import type { OperationOutcome } from '@medplum/fhirtypes';
 import type { Patient } from '@medplum/fhirtypes';
+import type { ReactNode } from 'react';
 import type { Reference } from '@medplum/fhirtypes';
-import type { Resource } from '@medplum/fhirtypes';
 import type { Schedule } from '@medplum/fhirtypes';
 import type { SchedulingRequirement } from '@medplum/core';
 import type { Slot } from '@medplum/fhirtypes';
@@ -19,8 +19,8 @@ import type { WithId } from '@medplum/core';
 
 /**
  * One way of holding an appointment: a set of actors whose schedules `$find`
- * intersects in a single request. A role contributes as many actors as were
- * chosen for it, since everything chosen attends.
+ * intersects in a single request. Each requirement contributes exactly one
+ * actor, since a row is satisfied by any one of its alternatives.
  */
 export declare interface ActorCombination {
     /** Matches `getActorGroupKey` of the appointments offered for these actors. */
@@ -31,26 +31,70 @@ export declare interface ActorCombination {
 }
 
 /**
- * What an appointment is being asked for: the schedules chosen, per actor type.
- * Everything named attends.
+ * One thing an appointment needs, of a single actor type.
+ *
+ * The candidates in it are alternatives: a row naming two
+ * providers asks for *either* of them rather than both.
  */
-export declare type ActorSelections = Partial<Record<SchedulingActorType, readonly ScheduleCandidate[]>>;
+export declare interface ActorRequirement {
+    readonly id: string;
+    readonly candidates: readonly ScheduleCandidate[];
+}
+
+/**
+ * What an appointment is being asked for, per actor type.
+ *
+ * Each actor type holds a list of requirements, and the two directions read
+ * differently: requirements are ANDed, so two provider rows ask for two
+ * providers, while the candidates within one row are ORed.
+ */
+export declare type ActorSelections = Partial<Record<SchedulingActorType, readonly ActorRequirement[]>>;
 
 export declare function addDays(date: Date, days: number): Date;
 
 /**
- * Chooses the actors an appointment is held on, for one actor type.
+ * Chooses which actors of one type can hold an appointment.
  *
- * Everything chosen attends: `$find` intersects the schedules behind them,
- * so naming a second actor narrows the times to the ones both are free for.
+ * The names in one of these fields are **alternatives** to each other.
+ * Several actors that all have to attend go in a field each - see {@link AppointmentActorSelections},
+ * which arranges these into rows.
  *
- * Schedules are searched for as the name is typed (via `AsyncAutocomplete`).
+ * The results are `Schedule` resources, bound to the actors that can hold the appointment.
  *
  * @param props - The React props.
  * @returns The field for one actor type.
  */
 export declare function AppointmentActorSelect(props: AppointmentActorSelectProps): JSX.Element;
 
+/**
+ * Asks what an appointment needs by actor type (e.g., provider, room, device).
+ *
+ * Each actor type gets a stack of rows. **The rows are ANDed and the names
+ * within a row are ORed**: two provider rows ask for two providers, while two
+ * names in one row ask for either of them.
+ *
+ * A row is one alternative set, so it is also one dimension of the search:
+ * `getActorCombinations` takes one name from each row, and every way of doing
+ * that is one `$find` request.
+ *
+ * @param props - The React props.
+ * @returns One group of rows per bookable actor type.
+ */
+export declare function AppointmentActorSelections(props: AppointmentActorSelectionsProps): JSX.Element;
+
+export declare interface AppointmentActorSelectionsProps {
+    /** What the appointment is being asked for so far, per actor type. */
+    readonly value: ActorSelections;
+    /** The service being booked. Nothing is offered until it resolves. */
+    readonly service: Reference<HealthcareService> | WithId<HealthcareService> | undefined;
+    /** The site being booked at. Actors sited elsewhere are left out. */
+    readonly location?: Reference<Location_2> | WithId<Location_2>;
+    readonly disabled?: boolean;
+    /** What is wrong with a type's rows, shown under them. None by default. */
+    readonly errors?: Partial<Record<BookableActorType, string>>;
+    readonly onChange: (selections: ActorSelections) => void;
+}
+
 export declare interface AppointmentActorSelectProps {
     readonly actorType: BookableActorType;
     /** The service being booked. Nothing is offered until it resolves. */
@@ -65,6 +109,16 @@ export declare interface AppointmentActorSelectProps {
     readonly onChange: (candidates: readonly ScheduleCandidate[]) => void;
     readonly error?: string;
     readonly disabled?: boolean;
+    /** Names the field. Defaults to the actor type's own label. */
+    readonly label?: ReactNode;
+    /** The line under the field. None by default. */
+    readonly description?: ReactNode;
+    /** What the empty field invites. Defaults to searching the actor type by name. */
+    readonly placeholder?: string;
+    /** Whether the field must be answered. Defaults to whether its actor type is required. */
+    readonly required?: boolean;
+    /** Whether to mark the field with an asterisk. Defaults to `required`. */
+    readonly withAsterisk?: boolean;
 }
 
 /** What a booking wrote, as `Appointment/$book` returned it. */
@@ -149,13 +203,6 @@ export declare interface AppointmentOptionRowProps {
  * Gathers what a visit is held on, finds a time every one of them is free, and
  * hands the proposal out to be booked.
  *
- * One field per scheduling role, each searching the schedules bookable for the
- * chosen visit type. Everything named attends, because `$find` intersects their
- * schedules — so naming a second room narrows the times rather than widening them.
- *
- * Only a time the search offered can be chosen: the field holding it accepts no
- * input, so nothing can be booked onto time nobody checked availability for.
- *
  * Writes nothing and announces nothing: `onBook` owns that. Mount this to do
  * something other than `$book` with the proposal — hold it through `$hold`, or
  * write it inside a transaction of your own. {@link AppointmentBookingForm} is the
@@ -246,7 +293,7 @@ export declare interface AppointmentServiceSelectProps {
 export declare interface AppointmentSlotGroup {
     /** Stable key derived from the actors, so React keys survive a refetch. */
     readonly key: string;
-    readonly actors: readonly SchedulingActor[];
+    readonly actors: readonly SchedulingActorValue[];
     readonly durationMinutes: number;
     /** Sorted by start time. */
     readonly appointments: readonly Appointment[];
@@ -274,9 +321,11 @@ export declare interface AppointmentSlotGroupCardProps {
  * Actor types whose schedules may be offered for booking, in the order they are
  * asked about.
  *
- * Each type becomes one question, because `$find` intersects the schedules it is
- * given: a time is offered only when the practitioner *and* the location *and*
- * the device are all free for it.
+ * Each type becomes its own question, because `$find` intersects the schedules it
+ * is given: a time is offered only when the practitioner *and* the location *and*
+ * the device are all free for it. Asking for *either* of two practitioners is a
+ * second request rather than a second schedule on the same one — see
+ * `getActorCombinations`.
  *
  * Does not include `PractitionerRole` to prevent double-booking a `Practitioner`
  * who holds multiple roles. A practitioner is booked on their `Practitioner`,
@@ -325,6 +374,26 @@ declare interface CommonProps {
     readonly onCancel?: () => void;
 }
 
+/**
+ * Counts the combinations the selections expand into, without building them.
+ *
+ * An upper bound rather than an exact count: the ones that would name the same
+ * actor twice are only recognised while building. Enough to decide whether the
+ * product is worth expanding at all.
+ *
+ * @param selections - What has been chosen.
+ * @returns How many ways there are of satisfying every row, or 0 when nothing
+ *   has been chosen.
+ */
+export declare function countActorCombinations(selections: ActorSelections): number;
+
+/**
+ * Opens a new requirement row.
+ * @param candidates - What it starts out asking for. Empty by default.
+ * @returns The row.
+ */
+export declare function createActorRequirement(candidates?: readonly ScheduleCandidate[]): ActorRequirement;
+
 /** The days a search covers. Either end may be open. */
 export declare interface DateRange {
     readonly start?: Date;
@@ -426,11 +495,17 @@ export declare interface FormatZonedTimeOptions {
  * Builds the sets of actors an appointment could be held on.
  *
  * One combination is one `$find` request: the schedules within it are
- * intersected, so its times are the times all of those actors are free.
+ * intersected, so its times are the times all of those actors are free. Rows are
+ * ANDed and the alternatives within a row are ORed, so the combinations are the
+ * product of the rows — one alternative taken from each.
+ *
+ * Ordered as an odometer with the last row turning fastest, so the first
+ * combination is every row's first pick and the rounds the search runs stay
+ * predictable.
  *
  * @param selections - What has been chosen.
- * @returns One combination holding every chosen actor, in role order, or an
- *   empty list when nothing is chosen.
+ * @returns One combination per way of satisfying every row, or an empty list
+ *   when nothing is chosen.
  */
 export declare function getActorCombinations(selections: ActorSelections): ActorCombination[];
 
@@ -449,16 +524,16 @@ export declare function getActorGroupKey(appointment: Appointment): string;
 export declare function getActorsKey(actors: readonly Reference[]): string;
 
 /**
- * Extracts the resource type from a reference to an actor.
+ * Extracts the resource type of an actor, given as itself or as a reference.
  *
  * Only supports references that may be used for Scheduling operations, which are
  * those that have a qualified `reference` attribute. The attribute must be present,
  * and may not be a reference to a "contained" resource (eg. `{ reference: "#cid" }`)
  *
- * @param reference - A Reference to a schedulable resource
- * @returns The type that the reference refers to.
+ * @param actor - A schedulable resource, or a Reference to one
+ * @returns The type of the actor.
  */
-export declare function getActorType(reference: SchedulingActor): SchedulingActorType;
+export declare function getActorType(actor: SchedulingActorValue): SchedulingActorType;
 
 /**
  * Provides the label we use for scheduling resource types in this UI
@@ -468,6 +543,14 @@ export declare function getActorType(reference: SchedulingActor): SchedulingActo
  */
 export declare function getActorTypeLabel(resourceType: SchedulingActorType): string;
 
+/**
+ * Get the actor(s) of an appointment.
+ * @param appointment - The proposed appointment.
+ * @param actorResources - Map of actor resources that have already been previously loaded.
+ * @returns List of actors. Resource if it's already loaded, reference otherwise.
+ */
+export declare function getAppointmentActors(appointment: Appointment | undefined, actorResources?: ReadonlyMap<string, SchedulingActorResource>): SchedulingActorValue[];
+
 /**
  * Returns a key uniquely identifying a proposed appointment.
  *
@@ -557,18 +640,41 @@ export declare function getFindWindowError(range: DateRange): string | undefined
 export declare function getNativeInputType(type: 'date' | 'time'): string;
 
 /**
- * Returns everything chosen, across actor types
+ * Returns every row across every actor type, in the order they are asked about.
  * @param selections - What has been chosen.
- * @returns The chosen candidates in `BOOKABLE_ACTOR_TYPES` order
+ * @returns The rows, empty ones included.
+ */
+export declare function getRequirements(selections: ActorSelections): ActorRequirement[];
+
+/**
+ * Flattens the loaded actor resources into a map, keyed by their reference.
+ * @param selections - What has been chosen.
+ * @returns The resource behind each chosen actor the search was able to include.
+ */
+export declare function getSelectedActorResources(selections: ActorSelections): Map<string, SchedulingActorResource>;
+
+/**
+ * Returns everything chosen, across rows and actor types.
+ * @param selections - What has been chosen.
+ * @returns The chosen candidates in `BOOKABLE_ACTOR_TYPES` order, then row order.
  */
 export declare function getSelectedCandidates(selections: ActorSelections): ScheduleCandidate[];
 
 /**
  * Reports why the current selections cannot be searched, if they cannot.
  * @param selections - What has been chosen.
- * @returns A message to show the user, or undefined when the search can run.
+ * @returns The blocker to show the user, or undefined when the search can run.
+ */
+export declare function getSelectionError(selections: ActorSelections): SelectionBlocker | undefined;
+
+/**
+ * Finds the rows that cannot all be filled at once, when there are any. Specifically happens
+ * when two rows offer the same resource, so one resource cannot fill both halves of a visit.
+ * @param selections - What has been chosen.
+ * @returns The first type whose rows have no answer between them, or undefined when
+ *   every type can be satisfied.
  */
-export declare function getSelectionError(selections: ActorSelections): string | undefined;
+export declare function getUnsatisfiableRows(selections: ActorSelections): UnsatisfiableRows | undefined;
 
 /**
  * Search window for a calendar day in the given timezone, starting from now if that day is already underway.
@@ -587,9 +693,11 @@ export declare function getZonedDayRange(day: Date, timezone?: string): Required
  * @param searched - Days to list whether or not they offer anything, so a searched day
  *   that came back empty still shows up rather than going missing. Read on the local
  *   calendar, matching how a day is picked.
+ * @param actorResources - The actors' own resources, keyed by reference, for
+ *   whichever of them the caller has already read. See {@link getAppointmentActors}.
  * @returns Days in ascending order, each holding its groups.
  */
-export declare function groupAppointmentsByDay(appointments: readonly Appointment[], timezone?: string, searched?: DateRange): AppointmentDay[];
+export declare function groupAppointmentsByDay(appointments: readonly Appointment[], timezone?: string, searched?: DateRange, actorResources?: ReadonlyMap<string, SchedulingActorResource>): AppointmentDay[];
 
 /**
  * Whether every requirement a visit type names has been answered.
@@ -624,6 +732,15 @@ export declare function isRequirementAnswered(requirement: SchedulingRequirement
  */
 export declare function isViewerTimezone(timezone: string | undefined, viewer?: string): boolean;
 
+/**
+ * The most alternatives worth expanding into requests at all.
+ *
+ * The search runs a few combinations at a time, so this is not the size of a
+ * round: it is the point past which the whole product is more than anyone is
+ * going to sit through, whatever order it is asked in.
+ */
+export declare const MAX_ACTOR_COMBINATIONS = 100;
+
 /**
  * The longest window `Appointment/$find` accepts. Requests wider than this are
  * rejected outright, so callers have to keep their own date range inside it.
@@ -713,7 +830,7 @@ export declare type ScheduleAvailabilityEditorProps = ScheduleOverrideEditorProp
 export declare interface ScheduleCandidate {
     readonly schedule: WithId<Schedule>;
     /** The actor itself, when the search was able to include it. */
-    readonly actorResource: WithId<Resource> | undefined;
+    readonly actorResource: SchedulingActorResource | undefined;
 }
 
 /**
@@ -734,7 +851,15 @@ export declare interface ScheduleOverrideEditorProps extends CommonProps {
  */
 export declare type SchedulingActor = Schedule['actor'][number];
 
-export declare type SchedulingActorType = Dereference<SchedulingActor>['resourceType'];
+/** A loaded actor resource. */
+export declare type SchedulingActorResource = WithId<Dereference<SchedulingActor>>;
+
+export declare type SchedulingActorType = SchedulingActorResource['resourceType'];
+
+/**
+ * An actor as a reference, or as the resource when it has already been read.
+ */
+export declare type SchedulingActorValue = SchedulingActor | SchedulingActorResource;
 
 /**
  * A data-coordination component pairing {@link CalendarsPanel} with {@link MultiCalendar}.
@@ -801,6 +926,20 @@ export declare interface SearchScheduleCandidatesOptions {
     readonly count?: number;
 }
 
+/** Why the current selections cannot be searched. */
+export declare interface SelectionBlocker {
+    /** A whole sentence to show the user. */
+    readonly message: string;
+    readonly severity: SelectionBlockerSeverity;
+}
+
+/**
+ * Whether a blocker is a form that is not finished yet, or answers that cannot work.
+ *
+ * Only `invalid` is the user's to undo, so only it is worth showing as an error.
+ */
+export declare type SelectionBlockerSeverity = 'incomplete' | 'invalid';
+
 /**
  * Props for editing a service's own default hours, in place of any one calendar's override.
  * @param schedule - Omitted, which is what selects this mode.
@@ -852,6 +991,14 @@ export declare type TimeOfDay = 'any' | 'morning' | 'afternoon';
  */
 export declare function toCodings(elements: readonly ValueSetExpansionContains[]): Coding[];
 
+/** Rows that cannot all be filled at once, and where to say so. */
+export declare interface UnsatisfiableRows {
+    /** The actor type whose rows have no answer between them. */
+    readonly actorType: BookableActorType;
+    /** What to do about it, to show against those rows. */
+    readonly message: string;
+}
+
 /**
  * Searches for the times an appointment could be held at.
  *