@medplum/react-scheduling 5.1.29 → 5.1.31

package/dist/esm/index.d.ts

@@ -2,10 +2,168 @@ import type { Appointment } from '@medplum/fhirtypes';
 import type { HealthcareService } from '@medplum/fhirtypes';
 import type { HealthcareServiceAvailableTime } from '@medplum/fhirtypes';
 import type { JSX } from 'react';
+import type { Location as Location_2 } from '@medplum/fhirtypes';
+import type { MedplumClient } from '@medplum/core';
+import type { Reference } from '@medplum/fhirtypes';
+import type { Resource } from '@medplum/fhirtypes';
 import type { Schedule } from '@medplum/fhirtypes';
 import type { Slot } from '@medplum/fhirtypes';
 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.
+ */
+export declare interface ActorCombination {
+    /** Matches `getActorGroupKey` of the appointments offered for these actors. */
+    readonly key: string;
+    readonly label: string;
+    readonly actors: readonly SchedulingActor[];
+    readonly schedules: readonly Reference<Schedule>[];
+}
+
+/**
+ * What an appointment is being asked for: the schedules chosen, per role.
+ * Everything named attends.
+ */
+export declare type ActorSelections = Partial<Record<SchedulingRole, readonly ScheduleCandidate[]>>;
+
+export declare function addDays(date: Date, days: number): Date;
+
+/**
+ * Chooses the actors an appointment is held on, for one role.
+ *
+ * Everything chosen attends: `$find` intersects the schedules behind them,
+ * so naming a second actor narrows the times to the ones both are free for.
+ *
+ * Schedules are searched for as the name is typed (via `AsyncAutocomplete`).
+ *
+ * @param props - The React props.
+ * @returns The field for one role.
+ */
+export declare function AppointmentActorSelect(props: AppointmentActorSelectProps): JSX.Element;
+
+export declare interface AppointmentActorSelectProps {
+    /** The role being filled. */
+    readonly role: SchedulingRole;
+    /** 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: a room or a
+     * device anywhere inside it counts, a provider only if one of their
+     * PractitionerRoles names it.
+     */
+    readonly location?: Reference<Location_2> | WithId<Location_2>;
+    readonly defaultValue?: readonly ScheduleCandidate[];
+    readonly onChange: (candidates: readonly ScheduleCandidate[]) => void;
+    readonly error?: string;
+    readonly disabled?: boolean;
+}
+
+export declare interface AppointmentDay {
+    /** `YYYY-MM-DD` in the scheduling timezone. */
+    readonly key: string;
+    /** Local midnight of the same calendar day, for the calendar and its heading. */
+    readonly date: Date;
+    readonly groups: readonly AppointmentSlotGroup[];
+}
+
+/**
+ * Shows one day's available times, a card per set of actors offering them.
+ *
+ * Holds no calendar of its own, so that a view wanting only a list of times can
+ * render it alone.
+ *
+ * @param props - The React props.
+ * @returns The day's heading and its times.
+ */
+export declare function AppointmentDayTimes(props: AppointmentDayTimesProps): JSX.Element;
+
+export declare interface AppointmentDayTimesProps {
+    /** Local midnight of the day being shown, which titles it. */
+    readonly date: Date;
+    /** The times offered on that day, empty for a day that offers none. */
+    readonly groups: readonly AppointmentSlotGroup[];
+    readonly onSelectAppointment: (appointment: Appointment) => void;
+    /** IANA timezone the times are read in. Defaults to the browser's. */
+    readonly timezone?: string;
+    readonly selected?: Appointment;
+}
+
+/**
+ * One option in an appointment pick list: what it is called, over what tells it
+ * apart from the others.
+ * @param props - The React props.
+ * @returns The row.
+ */
+export declare function AppointmentOptionRow(props: AppointmentOptionRowProps): JSX.Element;
+
+export declare interface AppointmentOptionRowProps {
+    readonly label: string;
+    /** What tells this option apart from one of the same name. Omitted when there is nothing on file. */
+    readonly detail?: string;
+}
+
+/**
+ * Chooses the service an appointment is for.
+ *
+ * Only services configured for scheduling are offered. A `HealthcareService`
+ * without a `SchedulingParameters` extension has no duration or alignment for
+ * `$find` to work from, so booking against it cannot succeed.
+ *
+ * @param props - The React props.
+ * @returns The service field.
+ */
+export declare function AppointmentServiceSelect(props: AppointmentServiceSelectProps): JSX.Element;
+
+export declare interface AppointmentServiceSelectProps {
+    readonly defaultValue?: WithId<HealthcareService>;
+    readonly onChange: (service: WithId<HealthcareService> | undefined) => void;
+    /** A chosen site, which narrows the services on offer to the ones held there. */
+    readonly location?: WithId<Location_2> | Reference<Location_2>;
+    readonly label?: string;
+    readonly error?: string;
+    readonly disabled?: boolean;
+}
+
+/** A calendar day's worth of available times, split by the actors offering them. */
+export declare interface AppointmentSlotGroup {
+    /** Stable key derived from the actors, so React keys survive a refetch. */
+    readonly key: string;
+    readonly actors: readonly SchedulingActor[];
+    readonly durationMinutes: number;
+    /** Sorted by start time. */
+    readonly appointments: readonly Appointment[];
+}
+
+/**
+ * One card of available times, headed by the actors offering them.
+ * @param props - The React props.
+ * @returns The card.
+ */
+export declare function AppointmentSlotGroupCard(props: AppointmentSlotGroupCardProps): JSX.Element;
+
+export declare interface AppointmentSlotGroupCardProps {
+    readonly group: AppointmentSlotGroup;
+    readonly onSelectAppointment: (appointment: Appointment) => void;
+    /** IANA timezone the times are shown in. Defaults to the browser's. */
+    readonly timezone?: string;
+    readonly selected?: Appointment;
+    readonly disabled?: boolean;
+}
+
+/**
+ * Actor types whose schedules may be offered for booking.
+ *
+ * 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.
+ */
+export declare const BOOKABLE_ACTOR_TYPES: readonly ["Practitioner", "Location", "Device"];
+
+export declare type BookableActorType = (typeof BOOKABLE_ACTOR_TYPES)[number];
+
 export declare function Calendar(props: CalendarProps): JSX.Element;
 
 export declare interface CalendarProps {
@@ -17,6 +175,7 @@ export declare interface CalendarProps {
     onDoubleClickAppointment?: (appointment: Appointment) => void;
     onRangeChange?: (range: DateTimeRange) => void;
     className?: string;
+    availableTime?: HealthcareServiceAvailableTime[];
 }
 
 declare interface CommonProps {
@@ -33,11 +192,158 @@ declare interface CommonProps {
     readonly onCancel?: () => void;
 }
 
+/** The days a search covers. Either end may be open. */
+export declare interface DateRange {
+    readonly start?: Date;
+    readonly end?: Date;
+}
+
 export declare type DateTimeRange = {
     start: Date;
     end: Date;
 };
 
+/**
+ * Returns the last instant of a day, so that a range covers the whole of it.
+ * @param date - Any instant during the day.
+ * @returns Local midnight less a millisecond, at the end of that day.
+ */
+export declare function endOfDay(date: Date): Date;
+
+/**
+ * Returns the last instant of a date's month.
+ * @param date - Any instant during the month.
+ * @returns The close of that month's last day.
+ */
+export declare function endOfMonth(date: Date): Date;
+
+/**
+ * Lists the days a range covers, for marking them on the calendar.
+ * @param range - The days asked for.
+ * @param limit - The most days to return, so an open-ended range stays bounded.
+ * @returns Local midnight of each day, or an empty array for an open range.
+ */
+export declare function enumerateDateRange(range: DateRange, limit?: number): Date[];
+
+/**
+ * Restricts appointments to a half of the day, read in the scheduling timezone.
+ * @param appointments - Appointments to filter.
+ * @param timeOfDay - The half of the day to keep, or `any` to keep all.
+ * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @returns The matching appointments.
+ */
+export declare function filterByTimeOfDay(appointments: readonly Appointment[], timeOfDay: TimeOfDay, timezone?: string): Appointment[];
+
+/**
+ * Narrows candidates to the ones available at one location.
+ *
+ * A candidate that says nothing about where it is, or whose ancestry cannot be
+ * read, is kept: hiding something the caller may be entitled to book is worse
+ * than offering something at the wrong site.
+ *
+ * @param medplum - The Medplum client.
+ * @param candidates - Candidates to narrow.
+ * @param location - The site being booked at, or undefined to keep everything.
+ * @param options - Abort signal.
+ * @returns The candidates, minus the ones sited elsewhere.
+ */
+export declare function filterCandidatesByLocation(medplum: MedplumClient, candidates: readonly ScheduleCandidate[], location: Reference<Location_2> | WithId<Location_2> | undefined, options?: FilterCandidatesOptions): Promise<ScheduleCandidate[]>;
+
+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.
+ * @returns The formatted day.
+ */
+export declare function formatDayHeading(date: Date): 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.
+ * @returns The formatted time.
+ */
+export declare function formatZonedTime(date: Date, timezone?: string): string;
+
+/**
+ * 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.
+ *
+ * @param selections - What has been chosen.
+ * @returns One combination holding every chosen actor, in role order, or an
+ *   empty list when nothing is chosen.
+ */
+export declare function getActorCombinations(selections: ActorSelections): ActorCombination[];
+
+/**
+ * Builds a key identifying the set of actors an appointment is offered by.
+ * @param appointment - The proposed appointment.
+ * @returns A key that is stable across refetches.
+ */
+export declare function getActorGroupKey(appointment: Appointment): string;
+
+/**
+ * Names the role an actor is filling, from its own reference.
+ *
+ * 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.
+ *
+ * @param actor - A reference to a scheduling actor.
+ * @returns The role's label, or undefined for a reference of another type.
+ */
+export declare function getActorRoleLabel(actor: Reference): string | undefined;
+
+/**
+ * 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;
+
+/**
+ * Returns a key uniquely identifying a proposed appointment.
+ *
+ * Proposed appointments have no id, and consecutive pages meet at the boundary
+ * of a day, so identity is the times plus the actors.
+ *
+ * @param appointment - The proposed appointment.
+ * @returns The de-duplication key.
+ */
+export declare function getAppointmentKey(appointment: Appointment): string;
+
+/**
+ * Names a candidate's actor, for use in plain-text option lists.
+ * @param candidate - The candidate to name.
+ * @returns The name to show.
+ */
+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.
+ */
+export declare function getCandidateRole(candidate: ScheduleCandidate): SchedulingRole | undefined;
+
+/**
+ * Returns an appointment's length in whole minutes.
+ * @param appointment - The proposed appointment.
+ * @returns The length in minutes, or 0 when either end is missing.
+ */
+export declare function getDurationMinutes(appointment: Appointment | undefined): number;
+
 /**
  * Resolves the availability in effect for a HealthcareService, on a given calendar or on its own.
  * Hours the Schedule sets for the service take precedence over the service default.
@@ -60,6 +366,93 @@ export declare type DateTimeRange = {
  */
 export declare function getEffectiveAvailability(service: WithId<HealthcareService> | undefined, schedule?: Schedule): HealthcareServiceAvailableTime[] | undefined;
 
+/**
+ * Returns the input type to use for a date or time field.
+ *
+ * JSDOM does not fire change events for `<input type="date">` or
+ * `<input type="time">`, so tests get a plain text field, matching what
+ * `DateTimeInput` does.
+ *
+ * @param type - The native input type to use outside of tests.
+ * @returns The input type for the current environment.
+ */
+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.
+ * @param selections - What has been chosen.
+ * @returns The chosen candidates, in `SCHEDULING_ROLES` 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.
+ */
+export declare function getSelectionError(selections: ActorSelections): string | undefined;
+
+/**
+ * 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.
+ * @returns Days in ascending order, each holding its groups.
+ */
+export declare function groupAppointmentsByDay(appointments: readonly Appointment[], timezone?: string): AppointmentDay[];
+
+export declare function isBookableActorType(value: string | undefined): value is BookableActorType;
+
+/**
+ * Reports whether a role has to be filled.
+ * @param role - The role being filled.
+ * @returns Whether a search can run without it.
+ */
+export declare function isRoleRequired(role: SchedulingRole): boolean;
+
+/**
+ * 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.
+ */
+export declare function isSameDay(left: Date, right: Date | undefined): boolean;
+
+export declare function isSchedulingActorType(value: string | undefined): value is SchedulingActorType;
+
+/**
+ * The longest window `Appointment/$find` accepts. Requests wider than this are
+ * rejected outright, so callers have to keep their own date range inside it.
+ */
+export declare const MAX_FIND_WINDOW_DAYS = 31;
+
+/**
+ * Converts a `YYYY-MM-DD` key into local midnight of that calendar day.
+ * @param key - A `YYYY-MM-DD` day key.
+ * @returns Local midnight of that day.
+ */
+export declare function parseDayKey(key: string): Date;
+
+/**
+ * Reads a wall-clock time on a given day as an instant in a timezone.
+ *
+ * @param day - Local midnight of the day the time falls on.
+ * @param time - A 24-hour `HH:MM` time.
+ * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @returns The instant, or undefined when the time is not a valid `HH:MM`.
+ */
+export declare function parseZonedTime(day: Date, time: string, timezone?: string): Date | undefined;
+
+export declare const ROLE_LABELS: Record<SchedulingRole, string>;
+
 /**
  * Edits weekly availability for one visit service type, either as a Schedule's
  * override of the service hours or as the service's own default hours.
@@ -78,6 +471,16 @@ export declare function ScheduleAvailabilityEditor(props: ScheduleAvailabilityEd
  */
 export declare type ScheduleAvailabilityEditorProps = ScheduleOverrideEditorProps | ServiceDefaultEditorProps;
 
+/**
+ * A Schedule that can be booked for a service, paired with the actor it belongs
+ * to.
+ */
+export declare interface ScheduleCandidate {
+    readonly schedule: WithId<Schedule>;
+    /** The actor itself, when the search was able to include it. */
+    readonly actorResource: WithId<Resource> | undefined;
+}
+
 /**
  * Props for editing the availability override a Schedule holds for one service.
  * @param schedule - The Schedule holding the availability override. Must have exactly one actor, as scheduling requires.
@@ -90,6 +493,54 @@ 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];
+
+/**
+ * Finds the Schedules that can be booked for one role of a HealthcareService,
+ * narrowed to the actors whose name matches what was typed.
+ * @param medplum - The Medplum client.
+ * @param service - The HealthcareService being booked.
+ * @param options - The role, the text typed, the site, an abort signal, and a page size.
+ * @returns The matching schedules, each with its actor, by display name.
+ */
+export declare function searchScheduleCandidates(medplum: MedplumClient, service: WithId<HealthcareService>, options: SearchScheduleCandidatesOptions): Promise<ScheduleCandidate[]>;
+
+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 query: string;
+    /**
+     * The site being booked at. Actors sited elsewhere are left out: a room or a
+     * device anywhere inside it counts, a provider only if one of their
+     * PractitionerRoles names it.
+     */
+    readonly location?: Reference<Location_2> | WithId<Location_2>;
+    readonly signal?: AbortSignal;
+    /** Maximum schedules to consider. Defaults to 25. */
+    readonly count?: number;
+}
+
 /**
  * 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.
@@ -125,4 +576,36 @@ export declare interface ServiceDefaultEditorProps extends CommonProps {
  */
 export declare function setScheduleAvailability(schedule: Schedule, service: WithId<HealthcareService>, availableTime: HealthcareServiceAvailableTime[]): Schedule;
 
+export declare type TimeOfDay = 'any' | 'morning' | 'afternoon';
+
+/**
+ * Searches for the times an appointment could be held at.
+ * @param options - The service, actor combinations, days, and page size.
+ * @returns The times offered, plus load and error state.
+ */
+export declare function useProposedAppointments(options: UseProposedAppointmentsOptions): UseProposedAppointmentsResult;
+
+export declare interface UseProposedAppointmentsOptions {
+    /** The service being booked, as a reference or the resource itself. */
+    readonly service: Reference<HealthcareService> | WithId<HealthcareService> | undefined;
+    /** The sets of actors to search for, from `getActorCombinations`. */
+    readonly combinations: readonly ActorCombination[];
+    /** The days to search. Both ends are needed; `$find` refuses an open range. */
+    readonly range: DateRange;
+    /** Times to ask for per combination. Defaults to 20. */
+    readonly count?: number;
+}
+
+export declare interface UseProposedAppointmentsResult {
+    /**
+     * Every time offered, never persisted — `$find` proposes.
+     */
+    readonly appointments: readonly Appointment[];
+    /** How many `$find` requests the current combinations take. */
+    readonly requestCount: number;
+    readonly loading: boolean;
+    /** Set only when every combination failed. */
+    readonly error: Error | undefined;
+}
+
 export { }