@medplum/react-scheduling 5.1.39 → 5.1.40

package/dist/esm/index.d.ts

@@ -1,6 +1,8 @@
 import type { Appointment } from '@medplum/fhirtypes';
+import type { Bundle } from '@medplum/fhirtypes';
 import type { Coding } from '@medplum/fhirtypes';
 import type { Dereference } from '@medplum/core';
+import type { Extension } from '@medplum/fhirtypes';
 import type { HealthcareService } from '@medplum/fhirtypes';
 import type { HealthcareServiceAvailableTime } from '@medplum/fhirtypes';
 import type { JSX } from 'react';
@@ -122,16 +124,12 @@ export declare interface AppointmentActorSelectProps {
 }
 
 /** What a booking wrote, as `Appointment/$book` returned it. */
-export declare interface AppointmentBooking {
-    readonly appointment: WithId<Appointment>;
-    /** The times reserved for it, one per schedule it is held on. */
-    readonly slots: readonly WithId<Slot>[];
-}
+export declare type AppointmentBooking = AppointmentWrite;
 
 /**
  * The booking form, writing the booking itself.
  *
- * Wraps {@link AppointmentProposalForm}: posts `Appointment/$book`, announces the
+ * Wraps {@link AppointmentProposalForm}: writes the booking, announces the
  * appointment and every time it reserved so views reading them refresh, then
  * reports what was written through `onBooked` — the only required prop.
  *
@@ -142,7 +140,7 @@ export declare interface AppointmentBooking {
  */
 export declare function AppointmentBookingForm(props: AppointmentBookingFormProps): JSX.Element;
 
-export declare interface AppointmentBookingFormProps extends Omit<AppointmentProposalFormProps, 'onBook'> {
+export declare interface AppointmentBookingFormProps extends Omit<AppointmentProposalFormProps, 'onSubmit' | 'mode' | 'ignoreAppointment'> {
     /**
      * Called with what the booking wrote.
      *
@@ -201,12 +199,13 @@ 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.
+ * hands the proposal out to be written.
  *
- * Writes nothing and announces nothing: `onBook` owns that. Mount this to do
+ * Writes nothing and announces nothing: `onSubmit` 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
- * one that books.
+ * one that books, and {@link AppointmentRescheduleForm} the one that moves a visit
+ * already on file.
  *
  * @param props - The React props.
  * @returns The form.
@@ -214,6 +213,8 @@ export declare interface AppointmentOptionRowProps {
 export declare function AppointmentProposalForm(props: AppointmentProposalFormProps): JSX.Element;
 
 export declare interface AppointmentProposalFormProps {
+    /** What the proposal is for. Defaults to booking a new visit. */
+    readonly mode?: AppointmentProposalMode;
     /** Pre-fills where the visit is, for a host that already knows. */
     readonly defaultLocation?: WithId<Location_2>;
     /** Pre-fills the visit type, for a deep link or a reschedule. */
@@ -221,9 +222,23 @@ export declare interface AppointmentProposalFormProps {
     /** Pre-fills who the visit is for, for a host launching from a patient's chart. */
     readonly defaultPatient?: WithId<Patient>;
     /**
-     * The day the time search opens on. Defaults to today.
+     * Pre-fills who and what the visit is held on, for a host that already knows — the
+     * actors an appointment being moved is currently held on, say.
+     *
+     * Read once, at mount: the fields own what they are asked for afterwards.
+     */
+    readonly defaultSelections?: ActorSelections;
+    /**
+     * An appointment whose own times are not to count as taken.
      *
-     * A day, not a time: only a time `$find` offered can be chosen.
+     * For a form searching on behalf of an appointment that already exists: without it,
+     * the time it holds blocks every search that keeps any of the actors holding it, and
+     * moving a visit to a different room at the same hour finds nothing.
+     */
+    readonly ignoreAppointment?: Reference<Appointment> | WithId<Appointment>;
+    /**
+     * The day the time search opens on, and the day a typed time starts out on.
+     * Defaults to today.
      */
     readonly defaultStart?: Date;
     /**
@@ -256,12 +271,78 @@ export declare interface AppointmentProposalFormProps {
     /** 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.
+     * Writes the proposal the form assembled.
      *
-     * Resolving marks the form booked, so it stops offering to book until an answer
-     * changes; rejecting shows the reason as the booking's refusal, every answer kept.
+     * Resolving marks the form written, so it stops offering to write until an answer
+     * changes; rejecting shows the reason as the write's refusal, every answer kept.
+     *
+     * In `book` mode the proposal carries the patient and the visit type's required
+     * codes; in `reschedule` mode it is the time as `$find` offered it, untouched.
+     */
+    readonly onSubmit: (proposal: Appointment, options: BookOptions) => void | Promise<void>;
+    /** Extensions to put on every appointment this form books. */
+    readonly appointmentExtensions?: readonly Extension[];
+    /**
+     * Allows for manual entry of a time and length, bypassing the `$find` search and
+     * `$book` endpoint.
      */
-    readonly onBook: (proposal: Appointment) => void | Promise<void>;
+    readonly canBypassSchedulingRules?: boolean;
+}
+
+/**
+ * What the proposal the form assembles is for, which decides what it asks for.
+ *
+ * `book` gathers everything a new visit is written with: who it is for, and whatever
+ * its visit type requires. `reschedule` gathers only what decides the time, because
+ * `Appointment/[id]/$reschedule` moves a visit already on file and writes nothing else
+ * about it — asking for details it would drop is asking for them under false pretences.
+ *
+ * The visit type goes the same way: in `reschedule` mode a `defaultService` is shown
+ * rather than asked for, since the operation is measured against it but will not change
+ * it. Without one it is still asked, because the search cannot run without a visit type.
+ */
+export declare type AppointmentProposalMode = 'book' | 'reschedule';
+
+/** What a reschedule wrote, as `Appointment/[id]/$reschedule` returned it. */
+export declare type AppointmentReschedule = AppointmentWrite;
+
+/**
+ * The form that moves a visit already on file, to another time or another set of actors.
+ *
+ * Wraps {@link AppointmentProposalForm}, opened on what the appointment is held on now
+ * and searching as though it were not: the time it occupies is the time it is being
+ * moved off, so `$find` is told to ignore it, which is what lets the same hour in a
+ * different room be found.
+ *
+ * Posts `Appointment/[id]/$reschedule`, announces the appointment, the times it gave up
+ * and the times it took, so views reading them refresh, then reports what was written
+ * through `onRescheduled`.
+ *
+ * Only the time and the actors are asked for. Everything else on the appointment — who
+ * it is for, its status, its visit type, whatever clinical detail it carries — is left
+ * exactly as it was, because that is all the operation will write. The visit type is
+ * shown rather than offered: `$reschedule` takes none, reading the one the appointment
+ * is on file for instead, since changing what a visit *is* would leave its required
+ * codes, its authorization, and anything applied at booking keyed to a type it no
+ * longer has.
+ *
+ * @param props - The React props.
+ * @returns The form.
+ */
+export declare function AppointmentRescheduleForm(props: AppointmentRescheduleFormProps): JSX.Element;
+
+export declare interface AppointmentRescheduleFormProps extends Omit<AppointmentProposalFormProps, 'onSubmit' | 'mode' | 'defaultService' | 'defaultSelections' | 'defaultPatient' | 'ignoreAppointment' | 'mrnSystem' | 'procedureBinding' | 'diagnosisBinding' | 'canBypassSchedulingRules' | 'appointmentExtensions'> {
+    /** The appointment being moved. */
+    readonly appointment: WithId<Appointment>;
+    /**
+     * Called with what the move wrote.
+     *
+     * The answers stay on screen and the form stops offering to move until one of them
+     * changes, so a host can keep this mounted without it writing twice. A failure here
+     * is logged rather than shown as a refusal: the appointment has already moved by the
+     * time it runs.
+     */
+    readonly onRescheduled: (reschedule: AppointmentReschedule) => void | Promise<void>;
 }
 
 /**
@@ -285,6 +366,8 @@ export declare interface AppointmentServiceSelectProps {
     /** 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 placeholder?: string;
+    readonly required?: boolean;
     readonly error?: string;
     readonly disabled?: boolean;
 }
@@ -317,6 +400,13 @@ export declare interface AppointmentSlotGroupCardProps {
     readonly disabled?: boolean;
 }
 
+/** What a scheduling operation wrote: the appointment, and the times it holds. */
+export declare interface AppointmentWrite {
+    readonly appointment: WithId<Appointment>;
+    /** The times reserved for it, one set per schedule it is held on. */
+    readonly slots: readonly WithId<Slot>[];
+}
+
 /**
  * Actor types whose schedules may be offered for booking, in the order they are
  * asked about.
@@ -346,6 +436,12 @@ export declare interface BookingRequirementValues {
     readonly medicalNecessity: boolean;
 }
 
+/** What `onBook` is told about the proposal it was handed. */
+export declare interface BookOptions {
+    /** True when the time was typed (& unvalidated) rather than chosen from the search. */
+    readonly manual: boolean;
+}
+
 export declare function Calendar(props: CalendarProps): JSX.Element;
 
 export declare interface CalendarProps {
@@ -630,14 +726,14 @@ export declare function getFindWindowError(range: DateRange): string | 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
+ * JSDOM does not fire change events for `<input type="date">`, `<input type="time">`
+ * or `<input type="datetime-local">`, 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;
+export declare function getNativeInputType(type: 'date' | 'time' | 'datetime-local'): string;
 
 /**
  * Returns every row across every actor type, in the order they are asked about.
@@ -787,6 +883,14 @@ export declare interface MultiCalendarSource {
  */
 export declare function parseDayKey(key: string): Date;
 
+/**
+ * Reads a native datetime input's value as an instant in a timezone.
+ * @param value - A `YYYY-MM-DDTHH:MM` value, as the input reports it.
+ * @param timezone - IANA timezone identifier. Defaults to the browser's.
+ * @returns The instant, or undefined while the value is not a complete date and time.
+ */
+export declare function parseZonedDateTimeInput(value: string, timezone?: string): Date | undefined;
+
 /**
  * Reads a wall-clock time on a given day as an instant in a timezone.
  *
@@ -797,6 +901,18 @@ export declare function parseDayKey(key: string): Date;
  */
 export declare function parseZonedTime(day: Date, time: string, timezone?: string): Date | undefined;
 
+/**
+ * Reads what a scheduling operation wrote out of the bundle it answers with.
+ *
+ * `$book` and `$reschedule` both answer with the appointment and every Slot they
+ * created, in one transaction bundle.
+ *
+ * @param written - The bundle the operation returned.
+ * @param operation - What was called, for the error a bundle without an appointment raises.
+ * @returns The appointment and the times reserved for it.
+ */
+export declare function readAppointmentWrite(written: Bundle<WithId<Appointment> | WithId<Slot>>, operation: string): AppointmentWrite;
+
 /**
  * Actor types that must be chosen before a search can run.
  *
@@ -805,6 +921,35 @@ export declare function parseZonedTime(day: Date, time: string, timezone?: strin
  */
 export declare const REQUIRED_ACTOR_TYPES: ReadonlySet<SchedulingActorType>;
 
+export declare interface RescheduleDefaults {
+    /** The visit type the appointment is on file under, where it records one. */
+    readonly service: WithId<HealthcareService> | undefined;
+    /** Who and what it is held on now, arranged into the rows a form asks for them in. */
+    readonly selections: ActorSelections;
+    /**
+     * Actors the visit is held on whose schedules cannot be offered back, named where they
+     * could be read.
+     *
+     * A Schedule that is inactive, no longer names the visit type, or is held on an actor
+     * this form does not book leaves its actors out of the rows above — and a move writes
+     * the actors it is given, so these are about to be dropped off the visit.
+     */
+    readonly droppedActors: readonly SchedulingActor[];
+    /**
+     * Set when the visit type, or a Slot or Schedule the visit is held on, could not be read.
+     *
+     * `$reschedule` reads those same references, so no move from here would be accepted.
+     */
+    readonly error: unknown;
+    /**
+     * True until the reads settle.
+     *
+     * A form reads its defaults once, at mount, so one mounted while this is true would
+     * open on nothing and never take them.
+     */
+    readonly loading: boolean;
+}
+
 /**
  * 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.
@@ -871,9 +1016,9 @@ export declare type SchedulingActorValue = SchedulingActor | SchedulingActorReso
  *   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.
+ * - Shows what is booked: clicking an appointment opens {@link AppointmentDetails} in the
+ *   same pane the booking form uses, describing the visit and offering to cancel or
+ *   reschedule it.
  * - 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
@@ -892,11 +1037,32 @@ export declare interface SchedulingWorkspaceProps {
     readonly diagnosisBinding?: string;
     readonly onBooked?: (booking: AppointmentBooking) => void | Promise<void>;
     readonly onCancelled?: (appointment: WithId<Appointment>) => void | Promise<void>;
+    readonly onRescheduled?: (reschedule: AppointmentReschedule) => 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;
+    /**
+     * Lets the booking form take a typed time and length, placing a visit the scheduling
+     * rules would refuse: over occupied or blocked time, past the configured capacity,
+     * or at a time or length the visit type does not offer.
+     *
+     * Passing it draws the fields; it enforces nothing. Which users get it is the host
+     * application's responsibility.
+     *
+     * Such a booking is sent as a transaction, so the appointment and its Slots commit
+     * together on projects with the `transaction-bundles` feature enabled. Without it they
+     * are applied as a plain batch, where an appointment that failed to write would leave
+     * Slots holding no visit.
+     * @see https://www.medplum.com/docs/fhir-datastore/fhir-batch-requests#batches-vs-transactions
+     */
+    readonly canBypassSchedulingRules?: boolean;
+    /**
+     * Extensions to put on every appointment booked from this workspace. See
+     * {@link AppointmentProposalFormProps.appointmentExtensions}.
+     */
+    readonly appointmentExtensions?: readonly Extension[];
 }
 
 /**
@@ -955,10 +1121,10 @@ export declare interface ServiceDefaultEditorProps extends CommonProps {
 /**
  * Immutably gives a Schedule its own hours for a HealthcareService, in place of the service default.
  * Reads back through `getEffectiveAvailability`; to drop the calendar back to the default, clear the
- * parameter with `clearScheduleParameter(schedule, service, 'availability')` from `@medplum/core`.
+ * parameter with `clearScheduleSchedulingParameter(schedule, service, 'availability')` from `@medplum/core`.
  *
  * Availability is the one parameter with a typed wrapper, because it is the only one that is not a single
- * `value[x]`: `bufferBefore` and the rest go through `setScheduleParameter` directly, already legible as
+ * `value[x]`: `bufferBefore` and the rest go through `setScheduleSchedulingParameter` directly, already legible as
  * `{ url: 'bufferBefore', valueDuration: { value: 10, unit: 'min' } }`. Availability is a repeating nested
  * structure, so hand-building it at every call site would mean re-deriving the encoding.
  *
@@ -991,6 +1157,8 @@ export declare type TimeOfDay = 'any' | 'morning' | 'afternoon';
  */
 export declare function toCodings(elements: readonly ValueSetExpansionContains[]): Coding[];
 
+export declare function toScheduleCandidate(schedule: WithId<Schedule>, service: WithId<HealthcareService> | undefined, actors: Map<string, SchedulingActorResource>): ScheduleCandidate | undefined;
+
 /** 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. */
@@ -1019,6 +1187,14 @@ export declare interface UseProposedAppointmentsOptions {
     readonly range: DateRange;
     /** Times to ask for per combination. Defaults to 20. */
     readonly count?: number;
+    /**
+     * An appointment whose own times are not to count as taken.
+     *
+     * For searching on behalf of an appointment that already exists: the times it holds
+     * are the times it is being moved off, and left standing they would block every
+     * search that keeps any of the actors it is held on.
+     */
+    readonly ignoreAppointment?: Reference<Appointment> | WithId<Appointment>;
 }
 
 export declare interface UseProposedAppointmentsResult {
@@ -1035,6 +1211,23 @@ export declare interface UseProposedAppointmentsResult {
     readonly windowError: string | undefined;
 }
 
+/**
+ * Reads what an appointment is currently held on, for a form that offers to move it.
+ *
+ * The visit type comes off `Appointment.serviceType`, which carries a reference to the
+ * HealthcareService it was booked under; the actors come off the Slots it holds, which
+ * name the Schedules — the appointment's own participants would not say which of an
+ * actor's schedules is the one being moved off.
+ *
+ * An actor that cannot be read keeps its schedule, shown under the name the schedule
+ * gives it: the move is written against the schedule, not the actor.
+ *
+ * @param appointment - The appointment being moved.
+ * @returns Its visit type and actors, whether they are still being read, who a move
+ * would drop off it, and why it could not be read, where it could not.
+ */
+export declare function useRescheduleDefaults(appointment: WithId<Appointment>): RescheduleDefaults;
+
 /**
  * Loads the Appointments for a set of schedules within a date range and keeps them live.
  *