@medplum/react-scheduling 5.1.36 → 5.1.38

package/dist/esm/index.d.ts

@@ -1,4 +1,6 @@
 import type { Appointment } from '@medplum/fhirtypes';
+import type { Coding } from '@medplum/fhirtypes';
+import type { Dereference } from '@medplum/core';
 import type { HealthcareService } from '@medplum/fhirtypes';
 import type { HealthcareServiceAvailableTime } from '@medplum/fhirtypes';
 import type { JSX } from 'react';
@@ -10,7 +12,9 @@ import type { Patient } from '@medplum/fhirtypes';
 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';
+import type { ValueSetExpansionContains } from '@medplum/fhirtypes';
 import type { WithId } from '@medplum/core';
 
 /**
@@ -27,15 +31,15 @@ export declare interface ActorCombination {
 }
 
 /**
- * What an appointment is being asked for: the schedules chosen, per role.
+ * What an appointment is being asked for: the schedules chosen, per actor type.
  * Everything named attends.
  */
-export declare type ActorSelections = Partial<Record<SchedulingRole, readonly ScheduleCandidate[]>>;
+export declare type ActorSelections = Partial<Record<SchedulingActorType, readonly ScheduleCandidate[]>>;
 
 export declare function addDays(date: Date, days: number): Date;
 
 /**
- * Chooses the actors an appointment is held on, for one role.
+ * Chooses the actors an appointment is held on, for one actor type.
  *
  * Everything chosen attends: `$find` intersects the schedules behind them,
  * so naming a second actor narrows the times to the ones both are free for.
@@ -43,13 +47,12 @@ export declare function addDays(date: Date, days: number): Date;
  * Schedules are searched for as the name is typed (via `AsyncAutocomplete`).
  *
  * @param props - The React props.
- * @returns The field for one role.
+ * @returns The field for one actor type.
  */
 export declare function AppointmentActorSelect(props: AppointmentActorSelectProps): JSX.Element;
 
 export declare interface AppointmentActorSelectProps {
-    /** The role being filled. */
-    readonly role: SchedulingRole;
+    readonly actorType: BookableActorType;
     /** The service being booked. Nothing is offered until it resolves. */
     readonly service: Reference<HealthcareService> | WithId<HealthcareService> | undefined;
     /**
@@ -124,6 +127,7 @@ export declare interface AppointmentDayTimesProps {
     readonly onSelectAppointment: (appointment: Appointment) => void;
     /** IANA timezone the times are read in. Defaults to the browser's. */
     readonly timezone?: string;
+    readonly viewerTimezone?: string;
     readonly selected?: Appointment;
 }
 
@@ -192,6 +196,18 @@ export declare interface AppointmentProposalFormProps {
     readonly onToggleTimeFinder?: (open: boolean) => void;
     /** Called with the visit type as it changes. */
     readonly onChangeService?: (service: WithId<HealthcareService> | undefined) => void;
+    /**
+     * Called with the time chosen, and with `undefined` once it is dropped.
+     *
+     * Every answer above the time drops it — a different day, a different provider —
+     * so a host pointing at the time on a calendar of its own takes the marker down
+     * rather than leaving it on a time nobody chose.
+     */
+    readonly onChangeTime?: (time: DateTimeRange | undefined) => void;
+    /** The ValueSet the procedure code field binds to. Defaults to the full CPT value set. */
+    readonly procedureBinding?: string;
+    /** The ValueSet the diagnosis code field binds to. Defaults to the full ICD-10-CM value set. */
+    readonly diagnosisBinding?: string;
     /**
      * Performs the booking with the proposal the form assembled.
      *
@@ -246,23 +262,41 @@ export declare function AppointmentSlotGroupCard(props: AppointmentSlotGroupCard
 export declare interface AppointmentSlotGroupCardProps {
     readonly group: AppointmentSlotGroup;
     readonly onSelectAppointment: (appointment: Appointment) => void;
-    /** IANA timezone the times are shown in. Defaults to the browser's. */
+    /** Timezone the times are shown in. */
     readonly timezone?: string;
+    /** The viewer's own timezone. */
+    readonly viewerTimezone?: string;
     readonly selected?: Appointment;
     readonly disabled?: boolean;
 }
 
 /**
- * Actor types whose schedules may be offered for booking.
+ * Actor types whose schedules may be offered for booking, in the order they are
+ * asked about.
  *
- * Does not include `PractitionerRole` to prevent double-booking
- * a `Practitioner` who holds multiple roles. See `getSchedulingRole` for how
- * `PractitionerRole` is still used to determine eligibility for a schedule.
+ * 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.
+ *
+ * Does not include `PractitionerRole` to prevent double-booking a `Practitioner`
+ * who holds multiple roles. A practitioner is booked on their `Practitioner`,
+ * but their `PractitionerRole`s still decide which schedules they are eligible
+ * for and where they practice.
  */
-export declare const BOOKABLE_ACTOR_TYPES: readonly ["Practitioner", "Location", "Device"];
+export declare const BOOKABLE_ACTOR_TYPES: ["Practitioner", "Location", "Device"];
 
 export declare type BookableActorType = (typeof BOOKABLE_ACTOR_TYPES)[number];
 
+/**
+ * What the booking form captures for a visit type's requirements: one value per requirement it
+ * can be asked for.
+ */
+export declare interface BookingRequirementValues {
+    readonly procedure: readonly Coding[];
+    readonly diagnosis: readonly Coding[];
+    readonly medicalNecessity: boolean;
+}
+
 export declare function Calendar(props: CalendarProps): JSX.Element;
 
 export declare interface CalendarProps {
@@ -302,6 +336,14 @@ export declare type DateTimeRange = {
     end: Date;
 };
 
+/** The value set the diagnosis code field binds to when a host names none. */
+export declare const DEFAULT_DIAGNOSIS_VALUE_SET = "http://hl7.org/fhir/sid/icd-10-cm/vs";
+
+/** The value set the procedure code field binds to when a host names none. */
+export declare const DEFAULT_PROCEDURE_VALUE_SET = "http://www.ama-assn.org/go/cpt/vs";
+
+export declare const EMPTY_REQUIREMENT_VALUES: BookingRequirementValues;
+
 /**
  * Returns the last instant of a day, so that a range covers the whole of it.
  * @param date - Any instant during the day.
@@ -352,13 +394,6 @@ export declare interface FilterCandidatesOptions {
     readonly signal?: AbortSignal;
 }
 
-/**
- * Says in words which days a search covers.
- * @param range - The days asked for.
- * @returns The range as a phrase, or undefined when both ends are open.
- */
-export declare function formatDateRange(range: DateRange): string | undefined;
-
 /**
  * Formats a calendar day as a heading (e.g. "Monday, July 27").
  * @param date - Local midnight of the day.
@@ -366,13 +401,26 @@ export declare function formatDateRange(range: DateRange): string | undefined;
  */
 export declare function formatDayHeading(date: Date): string;
 
+/**
+ * Names a timezone the short way it is written beside a time, e.g. "ET" or "GMT+2".
+ * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @returns The zone's short name.
+ */
+export declare function formatTimezoneLabel(timezone?: string): string;
+
 /**
  * Formats an instant's time of day in a given timezone (e.g. "12:30 PM").
  * @param date - The instant to format.
  * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @param options - Whether to name the zone as well.
  * @returns The formatted time.
  */
-export declare function formatZonedTime(date: Date, timezone?: string): string;
+export declare function formatZonedTime(date: Date, timezone?: string, options?: FormatZonedTimeOptions): string;
+
+export declare interface FormatZonedTimeOptions {
+    /** Names the zone alongside the time, e.g. "12:30 PM ET". */
+    readonly withTimezone?: boolean;
+}
 
 /**
  * Builds the sets of actors an appointment could be held on.
@@ -394,22 +442,31 @@ export declare function getActorCombinations(selections: ActorSelections): Actor
 export declare function getActorGroupKey(appointment: Appointment): string;
 
 /**
- * Names the role an actor is filling, from its own reference.
+ * Builds a key identifying a set of actors, independent of their order.
+ * @param actors - The actors to key.
+ * @returns The key.
+ */
+export declare function getActorsKey(actors: readonly Reference[]): string;
+
+/**
+ * Extracts the resource type from a reference to an actor.
  *
- * Needed where an actor is shown away from the field it was chosen in, which is
- * the only thing that would otherwise say which role it answers.
+ * 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 actor - A reference to a scheduling actor.
- * @returns The role's label, or undefined for a reference of another type.
+ * @param reference - A Reference to a schedulable resource
+ * @returns The type that the reference refers to.
  */
-export declare function getActorRoleLabel(actor: Reference): string | undefined;
+export declare function getActorType(reference: SchedulingActor): SchedulingActorType;
 
 /**
- * Builds a key identifying a set of actors, independent of their order.
- * @param actors - The actors to key.
- * @returns The key.
+ * Provides the label we use for scheduling resource types in this UI
+ *
+ * @param resourceType - A scheduling actor type
+ * @returns The type's label
  */
-export declare function getActorsKey(actors: readonly Reference[]): string;
+export declare function getActorTypeLabel(resourceType: SchedulingActorType): string;
 
 /**
  * Returns a key uniquely identifying a proposed appointment.
@@ -422,6 +479,19 @@ export declare function getActorsKey(actors: readonly Reference[]): string;
  */
 export declare function getAppointmentKey(appointment: Appointment): string;
 
+/**
+ * The IANA timezone the browser is set to.
+ * @returns The viewer's own timezone identifier.
+ */
+export declare function getBrowserTimezone(): string;
+
+/**
+ * Returns the actor a candidate's schedule is held on.
+ * @param candidate - The candidate to read.
+ * @returns Its schedule's only actor.
+ */
+export declare function getCandidateActor(candidate: ScheduleCandidate): SchedulingActor;
+
 /**
  * Names a candidate's actor, for use in plain-text option lists.
  * @param candidate - The candidate to name.
@@ -430,11 +500,12 @@ export declare function getAppointmentKey(appointment: Appointment): string;
 export declare function getCandidateDisplay(candidate: ScheduleCandidate): string;
 
 /**
- * Returns the role a candidate fills, from the type of its actor.
- * @param candidate - The candidate to read.
- * @returns The role, or undefined for an actor of a type nothing books against.
+ * Counts the days a window covers, a part of a day counting as a whole one.
+ * @param start - The first instant of the window.
+ * @param end - Its last instant.
+ * @returns The number of days the window reaches over.
  */
-export declare function getCandidateRole(candidate: ScheduleCandidate): SchedulingRole | undefined;
+export declare function getDayCount(start: Date, end: Date): number;
 
 /**
  * Returns an appointment's length in whole minutes.
@@ -486,16 +557,9 @@ export declare function getFindWindowError(range: DateRange): string | undefined
 export declare function getNativeInputType(type: 'date' | 'time'): string;
 
 /**
- * Returns the role an actor type is chosen as.
- * @param actorType - A `Schedule.actor` resource type.
- * @returns The role that actor fills.
- */
-export declare function getSchedulingRole(actorType: SchedulingActorType): SchedulingRole;
-
-/**
- * Returns everything chosen, across roles.
+ * Returns everything chosen, across actor types
  * @param selections - What has been chosen.
- * @returns The chosen candidates, in `SCHEDULING_ROLES` order.
+ * @returns The chosen candidates in `BOOKABLE_ACTOR_TYPES` order
  */
 export declare function getSelectedCandidates(selections: ActorSelections): ScheduleCandidate[];
 
@@ -506,34 +570,59 @@ export declare function getSelectedCandidates(selections: ActorSelections): Sche
  */
 export declare function getSelectionError(selections: ActorSelections): string | undefined;
 
+/**
+ * Search window for a calendar day in the given timezone, starting from now if that day is already underway.
+ * @param day - The day to search, as local midnight. Bound to the site's timezone.
+ * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @returns Range from the start of that day, or from now, through the next day's midnight.
+ */
+export declare function getZonedDayRange(day: Date, timezone?: string): Required<DateRange>;
+
 /**
  * Groups proposed appointments into days, and each day into the sets of actors
  * offering those times.
  *
  * @param appointments - Proposed appointments from `$find`.
  * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @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.
  * @returns Days in ascending order, each holding its groups.
  */
-export declare function groupAppointmentsByDay(appointments: readonly Appointment[], timezone?: string): AppointmentDay[];
+export declare function groupAppointmentsByDay(appointments: readonly Appointment[], timezone?: string, searched?: DateRange): AppointmentDay[];
 
-export declare function isBookableActorType(value: string | undefined): value is BookableActorType;
+/**
+ * Whether every requirement a visit type names has been answered.
+ * @param values - What the fields are holding.
+ * @param requirements - What the visit type requires, from its eligibility codes.
+ * @returns True once each required field holds a value. A value nothing asked for is not weighed.
+ */
+export declare function hasRequiredValues(values: BookingRequirementValues, requirements: ReadonlySet<SchedulingRequirement>): boolean;
 
 /**
- * Reports whether a role has to be filled.
- * @param role - The role being filled.
+ * Reports whether an actorType has to be chosen to be a valid booking
+ * @param actorType - The actor type being chosen.
  * @returns Whether a search can run without it.
  */
-export declare function isRoleRequired(role: SchedulingRole): boolean;
+export declare function isActorTypeRequired(actorType: SchedulingActorType): boolean;
+
+export declare function isBookableActorType(value: string | undefined): value is BookableActorType;
 
 /**
- * Returns whether two instants fall on the same local day.
- * @param left - The first instant.
- * @param right - The second, or undefined when there is nothing to compare.
- * @returns True when both fall on the same local day.
+ * Whether one requirement has been answered.
+ * @param requirement - The requirement to weigh.
+ * @param values - What the fields are holding.
+ * @returns True when the field answering that requirement holds a value.
  */
-export declare function isSameDay(left: Date, right: Date | undefined): boolean;
+export declare function isRequirementAnswered(requirement: SchedulingRequirement, values: BookingRequirementValues): boolean;
 
-export declare function isSchedulingActorType(value: string | undefined): value is SchedulingActorType;
+/**
+ * Whether a timezone is the viewer's own.
+ * @param timezone - IANA timezone the times are in, or undefined when it could not be resolved.
+ * @param viewer - The viewer's IANA timezone. Defaults to the browser's
+ * @returns True when the zone is the viewer's, or when there is no zone to compare.
+ */
+export declare function isViewerTimezone(timezone: string | undefined, viewer?: string): boolean;
 
 /**
  * The longest window `Appointment/$find` accepts. Requests wider than this are
@@ -591,7 +680,13 @@ export declare function parseDayKey(key: string): Date;
  */
 export declare function parseZonedTime(day: Date, time: string, timezone?: string): Date | undefined;
 
-export declare const ROLE_LABELS: Record<SchedulingRole, string>;
+/**
+ * Actor types that must be chosen before a search can run.
+ *
+ * Locations and devices are left optional: a service may have location schedules
+ * configured without every booking needing to hold one.
+ */
+export declare const REQUIRED_ACTOR_TYPES: ReadonlySet<SchedulingActorType>;
 
 /**
  * Edits weekly availability for one visit service type, either as a Schedule's
@@ -633,27 +728,13 @@ export declare interface ScheduleOverrideEditorProps extends CommonProps {
     readonly onSave: (updatedSchedule: Schedule) => void | Promise<void>;
 }
 
-/** Resource types that may appear in `Schedule.actor`. */
-export declare const SCHEDULING_ACTOR_TYPES: readonly ["Practitioner", "PractitionerRole", "Location", "Device"];
-
-/**
- * The parts of an appointment a user chooses, in the order they are asked about.
- *
- * Each role becomes one question, because `$find` intersects the schedules it is
- * given: a time is offered only when the provider *and* the room *and* the
- * device are all free for it.
- */
-export declare const SCHEDULING_ROLES: readonly ["provider", "room", "device"];
-
 /**
  * A reference to something a Schedule belongs to. The same union an Appointment
  * accepts as a participant, so an actor can be carried straight across.
  */
 export declare type SchedulingActor = Schedule['actor'][number];
 
-export declare type SchedulingActorType = (typeof SCHEDULING_ACTOR_TYPES)[number];
-
-export declare type SchedulingRole = (typeof SCHEDULING_ROLES)[number];
+export declare type SchedulingActorType = Dereference<SchedulingActor>['resourceType'];
 
 /**
  * A data-coordination component pairing {@link CalendarsPanel} with {@link MultiCalendar}.
@@ -665,6 +746,13 @@ export declare type SchedulingRole = (typeof SCHEDULING_ROLES)[number];
  *   The form writes the booking and announces what it wrote, which is what puts the
  *   new appointment on the calendar beside it — a host supplies no data for any of it.
  *   What was written is reported through `onBooked`, for a host that wants to say so.
+ * - Shows what is booked: clicking an appointment opens {@link AppointmentDetails} in a
+ *   drawer over the calendar, describing the visit and offering to cancel it. Cancelling
+ *   is what takes the time back off the calendar, again without a host supplying anything.
+ * - Highlights the time last chosen, wherever it was chosen: the click that opened the
+ *   pane, then whatever the form's time search settles on, and nothing while the form
+ *   holds no time. The calendar is never moved to reach it — a highlight off the week
+ *   on screen is kept, and is drawn again on paging back to it.
  *
  * @param props - Component props
  * @returns A React Node with the coordinated Calendars panel + calendar UI in it
@@ -673,7 +761,17 @@ export declare function SchedulingWorkspace(props: SchedulingWorkspaceProps): JS
 
 export declare interface SchedulingWorkspaceProps {
     readonly className?: string;
+    /** The ValueSet the procedure code field binds to. Defaults to full CPT valueset. */
+    readonly procedureBinding?: string;
+    /** The ValueSet the diagnosis code field binds to. Defaults to full ICD-10-CM valueset. */
+    readonly diagnosisBinding?: string;
     readonly onBooked?: (booking: AppointmentBooking) => void | Promise<void>;
+    readonly onCancelled?: (appointment: WithId<Appointment>) => void | Promise<void>;
+    /**
+     * Overrides the value set the appointment detail view offers cancellation reasons
+     * from, for a host coding them against its own terminology.
+     */
+    readonly appointmentCancellationReasonValueSet?: string;
 }
 
 /**
@@ -689,8 +787,8 @@ export declare function searchScheduleCandidates(medplum: MedplumClient, service
 
 export declare interface SearchScheduleCandidatesOptions {
     /** Which of the service's actors to offer. */
-    readonly role: SchedulingRole;
-    /** What the user typed. Empty offers whatever the role has, unfiltered by name. */
+    readonly actorType: SchedulingActorType;
+    /** What the user typed. Empty offers whatever the actor type has, unfiltered by name. */
     readonly query: string;
     /**
      * The site being booked at. Actors sited elsewhere are left out: a room or a
@@ -738,10 +836,28 @@ export declare interface ServiceDefaultEditorProps extends CommonProps {
  */
 export declare function setScheduleAvailability(schedule: Schedule, service: WithId<HealthcareService>, availableTime: HealthcareServiceAvailableTime[]): Schedule;
 
+/**
+ * Returns the first instant of a day, so that a range opens at the top of it.
+ * @param date - Any instant during the day.
+ * @returns Local midnight at the start of that day.
+ */
+export declare function startOfDay(date: Date): Date;
+
 export declare type TimeOfDay = 'any' | 'morning' | 'afternoon';
 
+/**
+ * Reads the codes a field is holding into a list of codings.
+ * @param elements - What the field is holding.
+ * @returns The codings to record, dropping anything that never became a code.
+ */
+export declare function toCodings(elements: readonly ValueSetExpansionContains[]): Coding[];
+
 /**
  * Searches for the times an appointment could be held at.
+ *
+ * A window `$find` would refuse is caught here rather than sent: this is the layer that
+ * decides whether the request is made, so it is the layer that says why it was not.
+ *
  * @param options - The service, actor combinations, days, and page size.
  * @returns The times offered, plus load and error state.
  */
@@ -768,6 +884,8 @@ export declare interface UseProposedAppointmentsResult {
     readonly loading: boolean;
     /** Set only when every combination failed. */
     readonly error: Error | undefined;
+    /** A window `$find` will not answer, caught before the request is made. */
+    readonly windowError: string | undefined;
 }
 
 /**