@alfadocs/ui-kit 1.30.0 → 1.32.0

package/dist/patterns/calendar/calendar-editor-hydration.d.ts

@@ -0,0 +1,59 @@
+import { type ReactNode } from 'react';
+import type { CalendarEditorCapabilities, CalendarRow, EditorPrefill, RecurrenceFrequency } from './calendar.model';
+import { type RecurringScope } from './calendar-workspace.model';
+/** The host's recurring occurrence. Rows never carry `CalendarRow.series`
+ * for such a host: the scope question is asked from this snapshot. */
+export interface CalendarEditorSeries {
+    /** The occurrence being edited, as a local Date on the host's wall clock. */
+    occurrence: Date;
+    /** Scopes the host can honour, in display order. Non-empty; the kit
+     * renders exactly this list and never adds a scope. */
+    scopes: readonly RecurringScope[];
+    /** Merged over snapshot.capabilities once a scope is chosen. */
+    capabilitiesByScope?: Partial<Record<RecurringScope, CalendarEditorCapabilities>>;
+    /** Offer the care-plan clean-up question in the delete dialog. */
+    offersCarePlanCleanup?: boolean;
+    /** Reserved for summary lines; the editor does not require it. */
+    summary?: {
+        frequency?: RecurrenceFrequency;
+        index?: number;
+        total?: number;
+    };
+}
+export type CalendarAppointmentEditorSnapshot = {
+    status: 'ready';
+    prefill: EditorPrefill & {
+        editEventId: string;
+        date: Date;
+        time: {
+            hours: number;
+            minutes: number;
+        };
+        durationMin: number;
+    };
+    capabilities?: CalendarEditorCapabilities;
+    series?: CalendarEditorSeries;
+} | {
+    status: 'refused';
+    reason: string;
+    retryable?: boolean;
+};
+export type CalendarAppointmentEditorLoader = (eventId: string, options: {
+    signal: AbortSignal;
+}) => Promise<CalendarAppointmentEditorSnapshot>;
+type ReadySnapshot = Extract<CalendarAppointmentEditorSnapshot, {
+    status: 'ready';
+}>;
+/** The editor is not mounted until the host returns its canonical data.
+ * Mounting this boundary per open also reloads a previously closed editor. */
+export declare function CalendarEditorHydration({ eventId, load, onCancel, children, }: {
+    eventId?: string;
+    load?: CalendarAppointmentEditorLoader;
+    /** Return to the host while loading or when the editor read fails. */
+    onCancel?: () => void;
+    children: (snapshot?: ReadySnapshot) => ReactNode;
+}): string | number | bigint | boolean | Iterable<ReactNode> | Promise<string | number | bigint | boolean | import("react").ReactPortal | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+/** Display-only projection. It never reaches journey.setRows. */
+export declare function rowWithCanonicalEditor(row: CalendarRow, snapshot: ReadySnapshot, patientName: string): CalendarRow;
+export {};
+//# sourceMappingURL=calendar-editor-hydration.d.ts.map

package/dist/patterns/calendar/calendar-notes-tool.d.ts

@@ -0,0 +1,14 @@
+import { type ReactNode } from 'react';
+/** Keep the editor draft mounted while visiting Notes, and vice versa. */
+export declare function CalendarNotesDock({ editor, notes, active, request, }: {
+    editor: ReactNode;
+    notes: ReactNode;
+    active: boolean;
+    request: number;
+}): import("react/jsx-runtime").JSX.Element;
+/** A canonical details read may resolve a patient before the grid's names do. */
+export declare function CalendarPatientContext({ patientId, onChange, }: {
+    patientId?: string;
+    onChange: (patientId?: string) => void;
+}): null;
+//# sourceMappingURL=calendar-notes-tool.d.ts.map

package/dist/patterns/calendar/calendar-patient-picker.d.ts

@@ -0,0 +1,11 @@
+interface PatientPickerProps {
+    value: string;
+    onValueChange: (value: string) => void;
+    selectedLabel?: string;
+    size?: 'sm' | 'md';
+    disabled?: boolean;
+}
+/** One id-valued patient control for the editor and waiting surfaces. */
+export declare function CalendarPatientPicker(props: PatientPickerProps): import("react/jsx-runtime").JSX.Element;
+export {};
+//# sourceMappingURL=calendar-patient-picker.d.ts.map

package/dist/patterns/calendar/calendar-series-scope-chooser.d.ts

@@ -0,0 +1,18 @@
+import { type RecurringScope } from './calendar-workspace.model';
+export interface CalendarSeriesScopeChooserProps {
+    /** The host's scopes in display order, rendered exactly as given. */
+    scopes: readonly RecurringScope[];
+    /** The occurrence being edited, named in the body for `locale`. */
+    occurrence: Date;
+    locale: string;
+    /** Starts checked; defaults to, and falls back on, `scopes[0]`. */
+    defaultScope?: RecurringScope;
+    /** Warn for a moved start; editors suppress this until date or time changes. */
+    warnOnWholeSeries?: boolean;
+    onContinue: (scope: RecurringScope) => void;
+    onCancel: () => void;
+}
+/** Asks which appointments of a series an edit applies to. The host's
+ * list is the only source of scopes: the kit never adds one. */
+export declare function CalendarSeriesScopeChooser(props: CalendarSeriesScopeChooserProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=calendar-series-scope-chooser.d.ts.map

package/dist/patterns/calendar/calendar-workspace.d.ts

@@ -1,14 +1,39 @@
+import { type CalendarAppointmentEditorLoader } from './calendar-editor-hydration';
+import { type CalendarAppointmentDetailsLoader } from './calendar-appointment-details';
 import { type CalendarData } from './calendar.data';
 import type { CalendarJourney } from './calendar.journey';
 import { type CalendarPreferenceAdapter } from './calendar.preferences';
-import { type EditorPrefill } from './calendar.model';
+import { type CalendarRow, type EditorPrefill } from './calendar.model';
 import { type CalendarWorkspaceToolId, type WorkspaceDisplaySettings } from './calendar-workspace.model';
 export { WORKSPACE_TOOL, type CalendarWorkspaceToolId, } from './calendar-workspace.model';
+/** Host-owned queue membership, independent of the visible calendar range. */
+export interface CalendarOnlineBookings {
+    rows: readonly CalendarRow[];
+    status: 'loading' | 'ready' | 'error';
+    /** Opt in only when the host can load and persist canonical editor data. */
+    canComplete?: boolean;
+    /** Unknown or invalid means no booking receives a New marker. */
+    lastSeenIso?: string | null;
+    /** Creation timestamps when the booking has no contact payload. */
+    createdAtById?: Readonly<Record<string, string>>;
+    onRetry?: () => void;
+}
 export interface CalendarWorkspaceProps {
+    /** Optional canonical read for every existing-appointment editor route.
+     * The form waits for this response; failures/refusals expose no editable
+     * grid-derived prefill. Keep the callback stable and cache patient data
+     * before resolving. Required for host online-booking completion. */
+    loadAppointmentEditor?: CalendarAppointmentEditorLoader;
+    /** The host's read for the read-only appointment details panel (P-C3).
+     * With it a selection docks that panel, Edit opens the editor and a save
+     * re-reads the details; without it details stays the editor form. */
+    loadAppointmentDetails?: CalendarAppointmentDetailsLoader;
     /** The domain state and its handlers — the host implements them. */
     journey: CalendarJourney;
     /** The practice's read model, stable for a page load. */
     data: CalendarData;
+    /** Supplied rows are authoritative, including an explicitly empty queue. */
+    onlineBookings?: CalendarOnlineBookings;
     locale?: string;
     /** Host-level cog overrides. */
     initialDisplay?: Partial<WorkspaceDisplaySettings>;

package/dist/patterns/calendar/calendar-workspace.model.d.ts

@@ -16,10 +16,11 @@ export declare const WORKSPACE_TOOL: {
     readonly appointments: "appointments";
     readonly editor: "appointment-editor";
     readonly waitingList: "waiting-list";
+    readonly notes: "patient-notes";
     readonly bookings: "online-bookings";
     readonly findSlots: "find-slots";
 };
-/** One of the workspace rail's five tools. */
+/** One of the workspace rail's six tools. Notes requires patient context. */
 export type CalendarWorkspaceToolId = (typeof WORKSPACE_TOOL)[keyof typeof WORKSPACE_TOOL];
 /** Strip order — the order the rail registers the tools in, and the
  *  order a host's `availableTools` is normalised back to. */
@@ -328,7 +329,11 @@ export declare function upcomingAppointmentRows(rows: CalendarRow[], bounds: {
  */
 export declare function upcomingAppointmentItem(row: CalendarRow, privacy: boolean, data: CalendarData, 
 /** Localised name-of-last-resort for an unresolvable patient id. */
-unresolvedPatientLabel: string): AppointmentItem;
+unresolvedPatientLabel: string, 
+/** Localised stand-in for a row whose details the host is still
+ *  fetching (`detailsPending`). Such a row carries no patient id and
+ *  no title, so without it the feed would print a nameless line. */
+pendingDetailsLabel?: string): AppointmentItem;
 /** How far back the platform's booking query looks, on `createdAt`. */
 export declare const ONLINE_BOOKINGS_WINDOW_DAYS = 30;
 /**
@@ -362,9 +367,7 @@ export interface BookingRowView {
     /** Booked after the user last opened the page — the "(Nuovo)" marker. */
     isNew: boolean;
 }
-/** Bookings made after this instant carry the platform's "(Nuovo)" tag. */
-export declare const DEFAULT_BOOKINGS_LAST_SEEN_ISO = "2026-06-23T00:00:00";
-export declare function bookingRowView(row: CalendarRow, data: CalendarData, lastSeenMs?: number): BookingRowView;
+export declare function bookingRowView(row: CalendarRow, data: CalendarData, lastSeenMs?: number | null, createdAtIso?: string): BookingRowView;
 /** The nine advanced inputs, all optional. Empty = the input is unset;
  *  `operatorId` also accepts `NONE`, the platform's "no operator". */
 export interface WaitingListFilters {

package/dist/patterns/calendar/calendar.data.d.ts

@@ -22,10 +22,14 @@
  */
 import { type ReactNode } from 'react';
 import type { CalendarResource } from '../../components/calendar';
+import type { PaletteSwatch } from '../../components/color-picker';
 import type { AppointmentItem } from '../../components/appointment-card';
 import type { NotesPanelNote } from '../../components/notes-panel';
 import type { TasksPanelItem } from '../../components/tasks-panel';
-import type { CalendarAppointmentMeta, CalendarBaseEvent, CalendarBookingContact, CalendarBranch, CalendarBusinessHours, CalendarCare, CalendarCareEntry, CalendarCareLink, CalendarCarePlan, CalendarClosure, CalendarHistoryEntry, CalendarHoliday, CalendarOperatorGroup, CalendarPatient, CalendarPracticeFeatures, CalendarPriceList, CalendarTaskDetail, CalendarWaitingEntry } from './calendar.types';
+import type { CalendarAppointmentMeta, CalendarBaseEvent, CalendarBookingContact, CalendarBranch, CalendarBusinessHours, CalendarDayHours, CalendarCare, CalendarCareEntry, CalendarCareLink, CalendarCarePlan, CalendarClosure, CalendarHistoryEntry, CalendarHoliday, CalendarOperatorGroup, CalendarPatient, CalendarPracticeFeatures, CalendarPriceList, CalendarTaskDetail, CalendarWaitingEntry, FreeSlotQuery } from './calendar.types';
+import type { CalendarFreeSlot } from './calendar.model';
+/** What the host has loaded for one local `Y-m-d`. */
+export type DayLoadState = 'loading' | 'ready' | 'error';
 export interface CalendarData {
     chairs: readonly CalendarResource[];
     operators: readonly CalendarResource[];
@@ -37,6 +41,13 @@ export interface CalendarData {
     operatorAbsences: Record<string, readonly string[]>;
     /** Operator id → absence display title (a sibling map, optional per operator). */
     operatorAbsenceTitles: Record<string, string>;
+    /**
+     * Appointment colours the host accepts. When omitted, the workspace uses
+     * its documented Google-style fallback palette for demos and legacy hosts.
+     * A platform host should provide its configured DoctorColor values so a
+     * colour selected in the editor always maps back to a writable colour id.
+     */
+    appointmentPalette?: readonly PaletteSwatch[];
     holidays: readonly CalendarHoliday[];
     /** Practice-closed local ISO dates. */
     closedDates: readonly string[];
@@ -45,6 +56,29 @@ export interface CalendarData {
      *  the weekend toggle; only the Final State demo reads this. */
     nonWorkingDays?: readonly number[];
     businessHours: CalendarBusinessHours;
+    /**
+     * Per-DATE closed periods — the one member that can say "shut 13:00–14:00".
+     * `businessHours` holds one range per weekday, so a split shift arrives as
+     * its envelope and the lunch closure inside it would read as bookable.
+     * Keyed by local `Y-m-d`; each window is minutes from local midnight,
+     * `1440` the following midnight, disjoint and ascending. The finder never
+     * offers a slot that overlaps one, and the grid washes it on every column
+     * of that date. A date without a key is one the host said nothing about:
+     * it adds no closure and takes nothing away from `businessHours`.
+     * Optional — the demos and hosts without per-date hours leave it out.
+     */
+    closedIntervals?: Readonly<Record<string, ReadonlyArray<CalendarDayHours>>>;
+    /**
+     * Per-DATE load state, keyed by local `Y-m-d` — for a host that fills
+     * the grid one range at a time. The grid washes every cell of a day
+     * that is not `'ready'` and the finder refuses to answer from one,
+     * because "no row here" and "no row here YET" are different answers.
+     * ABSENCE and presence differ: omit it and every rendered day is taken
+     * as loaded (the shape every host had before this existed); provide it
+     * and a date it does not name is NOT ready, so a host that knows its
+     * own days must name them all. Optional.
+     */
+    dayLoadState?: Readonly<Record<string, DayLoadState>>;
     /** The clock every relative label and ledger stamp is pinned to. */
     nowIso: string;
     /** The date the calendar opens on. */
@@ -61,6 +95,37 @@ export interface CalendarData {
      *  through `carePlanById` / `openCarePlansForPatient`. */
     carePlans?: readonly CalendarCarePlan[];
     patients: readonly CalendarPatient[];
+    /** Optional host typeahead. Omit for client filtering of `patients`.
+     * The picker debounces nonblank queries, aborts superseded requests and
+     * keeps the host's result order, including matches by phone or number.
+     * Before resolving, make returned records available through `patientById`
+     * so other patient-dependent fields can resolve the chosen id. Reject
+     * failures; an empty array means a successful search with no matches. */
+    searchPatients?(query: string, options: {
+        signal: AbortSignal;
+    }): Promise<readonly CalendarPatient[]>;
+    /**
+     * Optional host free-slot search. Omit it and the finder keeps its
+     * in-memory search over the loaded rows; provide it and the panel asks
+     * the practice's own finder instead.
+     *
+     * Called on Search and after every busy-set change — at most one call
+     * in flight, and one per background refresh tick while the panel is
+     * open. Abort a superseded call through `options.signal`; reject on
+     * failure (the panel says so and offers a retry); `[]` is a successful
+     * search with nothing free. Slots arrive floored at `nowIso` on
+     * whatever step the host's calendar interval implies — the kit names
+     * none. `medicalDeviceIds` are the host's own strings, round-tripped
+     * untouched, and `operatorIds` / `chairIds` are never empty: the panel
+     * publishes the empty answer itself rather than ask about nothing.
+     */
+    searchFreeSlots?(query: FreeSlotQuery, options: {
+        signal: AbortSignal;
+    }): Promise<readonly CalendarFreeSlot[]>;
+    /** The host's LOAD STAMP — a change re-runs the last server search (the
+     *  platform island hands in `loadedAt.getTime()`). Omit it and the busy
+     *  set alone triggers the re-search. */
+    revision?: number;
     /** The appointments and tasks as the host loaded them, no resource axis. */
     baseEvents: readonly CalendarBaseEvent[];
     /** Event id → appointment extras (patient, operator, chair, care, billing). */

package/dist/patterns/calendar/calendar.host.d.ts

@@ -2,6 +2,8 @@ export type SheetId = 'appointment-editor' | 'appointment-details' | 'find-slots
 export interface SheetHostContext {
     open(id: SheetId): void;
     close(): void;
+    /** Optional patient-context rail tool. Standalone panel hosts may omit it. */
+    openNotes?: (patientId: string, noteId?: string) => void;
 }
 /** Wrap whatever renders the panels and the surface — one provider per
  *  subtree is fine (a rail renders its panels outside the page tree). */

package/dist/patterns/calendar/calendar.journey.d.ts

@@ -13,7 +13,28 @@
 import type { Dispatch, SetStateAction } from 'react';
 import type { NotesPanelNote, NotesPanelProps, NotesPanelSubmission } from '../../components/notes-panel';
 import type { AvailabilityContext, BacklogFilter, BacklogItem, CalendarFreeSlot, CalendarRow, DisplaySettings, DraftSlot, EditorDraft, EditorPrefill, FindSlotsSeed, HistoryInput, RailFocus, SlotPatch, WaitingEntryDraft } from './calendar.model';
+import type { DeleteOptions, EditorDraftExtras, RecurringScope } from './calendar-workspace.model';
 import type { CalendarHistoryEntry, CalendarSignChannel, CalendarWaitingEntry } from './calendar.types';
+/** The host's notes read for one patient (N-C3); `writable` follows the
+ *  notes, not the appointment-edit right. */
+export type PatientNotesLoad = {
+    status: 'loading' | 'ready' | 'error';
+    total: number | null;
+    complete: boolean;
+    canAddClinicalNote: boolean;
+    writable: boolean;
+    error?: string;
+};
+/** A grid move of a host recurring parent's occurrence beyond itself (S-C8). */
+export interface CalendarOccurrenceMove {
+    eventId: string;
+    scope: Exclude<RecurringScope, 'this'>;
+    oldStart: Date;
+    newStart: Date;
+    newEnd?: Date;
+    chairId?: string;
+    operatorId?: string;
+}
 export interface CalendarJourney {
     rows: CalendarRow[];
     setRows: Dispatch<SetStateAction<CalendarRow[]>>;
@@ -35,6 +56,8 @@ export interface CalendarJourney {
      * of being silently dropped.
      */
     notesByPatient: Record<string, NotesPanelNote[]>;
+    /** Each patient's notes read; absent, the notes count as loaded. */
+    notesLoadByPatient?: Record<string, PatientNotesLoad>;
     signRequests: Record<string, CalendarSignChannel>;
     editorSeed: {
         tick: number;
@@ -71,7 +94,13 @@ export interface CalendarJourney {
         start: number;
         end: number;
     }) => void;
-    handleDeleteAppointment: (eventId: string) => void;
+    /** `options` carry the delete dialog's scope and care-plan choice;
+     *  absent options mean 'this'. */
+    handleDeleteAppointment: (eventId: string, options?: DeleteOptions) => void;
+    /** Called before the kit moves the one dragged row through `setRows`.
+     *  Reject with a user-facing Error and the kit puts that row back.
+     *  Omit it and every move of a recurring parent stays 'this'. */
+    handleMoveOccurrence?: (move: CalendarOccurrenceMove) => Promise<void>;
     handleDuplicateAppointment: (prefill: EditorPrefill) => void;
     handleDraftMoved: (next: {
         date: Date;
@@ -90,7 +119,10 @@ export interface CalendarJourney {
     handleFindSlotsForWaiting: (entry: CalendarWaitingEntry) => void;
     clearFindSlotsSeed: () => void;
     handleBookSlotFromFinder: (prefill: EditorPrefill) => void;
-    handleCreateAppointment: (draft: EditorDraft) => void;
+    /** Resolve only after the write is accepted. Reject with a safe,
+     * user-facing Error message to keep the editor open with its draft.
+     * `extras` arrive untouched unless the kit expands a demo series row. */
+    handleCreateAppointment: (draft: EditorDraft, extras?: EditorDraftExtras) => void | Promise<void>;
     /**
      * Commit a new note on the patient's record. The HOST builds the
      * stored note — its id, its timestamp and its AUTHOR, who is the
@@ -98,11 +130,14 @@ export interface CalendarJourney {
      * hands over only what was typed, so no name the kit invented can
      * ever be attributed to a clinical note.
      */
-    handleAddNote: (patientId: string, submission: NotesPanelSubmission) => void;
-    /** Replace a note's body with the text typed in the edit dialog. */
-    handleEditNote: (patientId: string, noteId: string, content: string) => void;
-    handleDeleteNote: (patientId: string, noteId: string) => void;
-    handleToggleNotePin: (patientId: string, noteId: string) => void;
+    handleAddNote: (patientId: string, submission: NotesPanelSubmission) => void | Promise<void>;
+    /** Replace a note's body: HTML for an HTML note, else plain text. A
+     *  rejected write keeps the draft or dialog open with its message. */
+    handleEditNote: (patientId: string, noteId: string, content: string) => void | Promise<void>;
+    handleDeleteNote: (patientId: string, noteId: string) => void | Promise<void>;
+    handleToggleNotePin: (patientId: string, noteId: string) => void | Promise<void>;
+    /** Read a patient's notes: the latest few, or every note. */
+    handleLoadNotes?: (patientId: string, scope: 'preview' | 'all') => void;
     /**
      * The practice's OWN drafting endpoint, behind the composer's AI
      * affordance. Omit it and the affordance is not offered: the kit

package/dist/patterns/calendar/calendar.model.d.ts

@@ -136,6 +136,17 @@ export declare function formatDay(locale: string, value: Date | string): string;
  *  the platform popover's "(NN anni)" beside the patient's name. Pinned
  *  to `data.nowIso` so the figure never drifts under a test. */
 export declare function patientAgeYears(dobIso: string, data: CalendarData): number;
+/** Per-appointment capabilities from the host's canonical read. Omitted
+ * capabilities preserve the existing editor behaviour. Locked fields
+ * are omitted from drafts, so the host must preserve their stored values. */
+export interface CalendarEditorCapabilities {
+    editCare?: boolean;
+    editPatient?: boolean;
+    editDescription?: boolean;
+    editRecurrence?: boolean;
+    /** False disables the status control and omits status from the draft. */
+    editStatus?: boolean;
+}
 export interface EditorPrefill {
     /** Set = the editor EDITS this existing event; unset = create. */
     editEventId?: string;
@@ -442,7 +453,10 @@ export declare function backlogPatientRef(item: BacklogItem, data: CalendarData)
 export declare function backlogPatient(item: BacklogItem, data: CalendarData): CalendarPatient | undefined;
 /** The row's headline — patient name, the booker's typed name, or the
  *  free-text hold. */
-export declare function backlogName(item: BacklogItem, data: CalendarData): string | undefined;
+export declare function backlogName(item: BacklogItem, data: CalendarData, 
+/** Localised stand-in while the host is still fetching the row's
+ *  details — such a row carries no title of its own. */
+pendingDetailsLabel?: string): string | undefined;
 /**
  * Text search over what the ROW renders: the patient's name (own, or the
  * linked appointment's) and the description (own, or the linked
@@ -526,6 +540,8 @@ export interface CalendarFreeSlot {
     /** The care the search was scoped to — carries name/colour into the
      *  prefill when a projected slot is clicked on the grid. */
     careId?: string;
+    /** The device a SERVER answer allocated: the host's own string. */
+    medicalDeviceId?: string;
 }
 /** Local ISO date (YYYY-MM-DD) — the fixtures' local-wall-clock idiom;
  *  absence lookups and shading ids key on local days, never UTC. */
@@ -690,11 +706,44 @@ export interface FindSlotsSeed {
 /** Booking context that rides ALONG with a projection — so booking by
  *  clicking a green range on the GRID prefills the same patient/care
  *  the panel's own Book button would. */
-export type AvailabilityContext = Pick<FindSlotsSeed, 'patientId' | 'care' | 'cares' | 'colorHex'>;
+export type AvailabilityContext = Pick<FindSlotsSeed, 'patientId' | 'care' | 'cares' | 'colorHex'> & {
+    /** Optional search scope, retained for resource-axis consumers. */
+    scopeOperatorId?: string;
+    scopeChairId?: string;
+};
+/** One painted free range — see `mergeAvailabilityRanges`. */
+export interface AvailabilityRange {
+    /** Stable per range: `<resource or day>:<start ms>`. */
+    key: string;
+    start: Date;
+    end: Date;
+    /** The column the range belongs to on a resource axis. */
+    resourceId?: string;
+}
+/**
+ * Found slots as CONTIGUOUS ranges: one per resource on the chair and
+ * operator axes, one per day on the plain grid. Touching or overlapping
+ * slots collapse into a single range with a single label. The search
+ * emits one slot per chair x operator pair at every step, so painting
+ * them one by one stacks chips at the same minute and lights every step
+ * of the day where any pair is free.
+ */
+export declare function mergeAvailabilityRanges(slots: readonly CalendarFreeSlot[], axisKind: 'none' | 'chair' | 'operator'): AvailabilityRange[];
+export interface CalendarFreeBand extends AvailabilityRange {
+    /** Original bookable answers, in finder order, never a fabricated union slot. */
+    options: readonly CalendarFreeSlot[];
+    /** Distinct chair x operator combinations, not the number of start times. */
+    optionCount: number;
+}
+/** Union free time per local day while retaining the original booking choices. */
+export declare function buildFreeBands(slots: readonly CalendarFreeSlot[]): CalendarFreeBand[];
 /**
- * The in-memory free-slot search over the fixture week: closed dates and
- * holidays yield nothing, an operator away that day drops out of it, and
- * a slot clashes with any row on its chair or a non-task row's operator.
+ * The in-memory free-slot search over the loaded rows: closed dates and
+ * holidays yield nothing, an operator away that day drops out of it, an
+ * operator with hours of their own is held to them, a per-date closure
+ * (`closedIntervals`) is never offered over, a day the host is still
+ * loading (`dayLoadState`) is not answered from at all, and a slot clashes
+ * with any row on its chair or a non-task row's operator.
  */
 export declare function searchFreeSlots(args: {
     rows: CalendarRow[];

package/dist/patterns/calendar/calendar.sheets.d.ts

@@ -22,6 +22,8 @@
  * the demos or the shared story shell.
  */
 import { type ReactNode } from 'react';
+import type { CalendarEditorCapabilities } from './calendar.model';
+import type { CalendarEditorSeries } from './calendar-editor-hydration';
 import { type CalendarEvent } from '../../components/calendar';
 import { type NotesPanelNote, type NotesPanelProps, type NotesPanelSubmission } from '../../components/notes-panel';
 import { type ColorAssociation, type CalendarCarePlan, type CalendarAnamnesisAnswer, type CalendarOperatorGroup, type CalendarPatient, type CalendarWaitingEntry, type CalendarHistoryEntry, type CalendarSignChannel, type PatientRef } from './calendar.types';
@@ -46,17 +48,28 @@ export interface PatientNotesSeam {
     /** The patient's notes as the HOST holds them, newest first. */
     notes: NotesPanelNote[];
     /** Commit what was typed. The host stamps the id, date and author. */
-    onAddNote: (submission: NotesPanelSubmission) => void;
-    /** Replace a note's body with the plain text typed in the dialog. */
-    onEditNote: (noteId: string, content: string) => void;
-    onDeleteNote: (noteId: string) => void;
-    onTogglePin: (noteId: string) => void;
+    onAddNote: (submission: NotesPanelSubmission) => void | Promise<void>;
+    /** Replace a note's body: HTML for an HTML note, else plain text. */
+    onEditNote: (noteId: string, content: string) => void | Promise<void>;
+    onDeleteNote: (noteId: string) => void | Promise<void>;
+    onTogglePin: (noteId: string) => void | Promise<void>;
     /** The practice's own drafting endpoint. Omitted → no AI affordance. */
     onRequestAiDraft?: NotesPanelProps['onRequestAiDraft'];
     /** The host's live transcription. Omitted → no microphone. */
     onDictate?: NotesPanelProps['onDictate'];
+    /** The host's read. Absent while `onLoad` is present reads as loading. */
+    status?: 'loading' | 'ready' | 'error';
+    total?: number | null;
+    /** True once `notes` is the full list rather than a preview. */
+    complete?: boolean;
+    canAddClinicalNote?: boolean;
+    /** Whether this reader may write notes. Beats the panel's `editable`. */
+    writable?: boolean;
+    onLoad?: (scope: 'preview' | 'all') => void;
+    onRetry?: () => void;
 }
-export declare function PatientNotesPanel({ patientId, seam, editable, }: {
+export declare function PatientNotesPanel(props: Parameters<typeof PatientNotesPanelContent>[0]): import("react/jsx-runtime").JSX.Element;
+declare function PatientNotesPanelContent({ patientId, seam, editable, currentNoteId, currentNoteKey, }: {
     patientId: string;
     /**
      * Where every write goes. WITHOUT one the panel is a read-only
@@ -65,17 +78,39 @@ export declare function PatientNotesPanel({ patientId, seam, editable, }: {
      */
     seam?: PatientNotesSeam;
     /**
-     * Whether this reader may write at all — the platform's
-     * `practice_appointment_edit` right, off in read-only mode. False (or
+     * Whether this reader may write when `seam.writable` is absent: note
+     * writes follow the notes, not `practice_appointment_edit`. False (or
      * no `seam`) leaves the composer, the pin and the per-note edit /
      * delete dialogs unmounted.
      */
     editable?: boolean;
+    /** Address one note, exactly as `NotesPanel` does. */
+    currentNoteId?: string;
+    currentNoteKey?: string | number;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The latest few notes for the appointment details panel (N-C3, N-C5), in
+ * the notes tool's order and read-only. See more or a click on a note
+ * hands over to the host's Notes tool on the same seam.
+ */
+export declare function PatientNotesPreview({ patientId, seam, onOpenNotes, limit, }: {
+    patientId: string;
+    seam: PatientNotesSeam;
+    /** Open the notes tool, addressed to one note when an id is given. */
+    onOpenNotes?: (noteId?: string) => void;
+    limit?: number;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function PatientAppointmentsTimeline({ patientId, locale, }: {
     patientId: string;
     locale?: string;
 }): import("react/jsx-runtime").JSX.Element;
+/** The appointment's modification ledger as a kit Timeline, newest first,
+ *  shared by the editor's History sub-view and the read-only details panel.
+ *  An empty ledger shows the "No changes recorded" empty state. */
+export declare function AppointmentHistoryTimeline({ history, locale, }: {
+    history: readonly CalendarHistoryEntry[];
+    locale?: string;
+}): import("react/jsx-runtime").JSX.Element;
 export declare function PatientTasksPanel({ patientId }: {
     patientId: string;
 }): import("react/jsx-runtime").JSX.Element;
@@ -145,13 +180,20 @@ export interface EditorPlatformOptions {
      *  reached from a prefill with `simpleSave: false` (audit C13). */
     onSaveAndReturn?: () => void;
 }
-export declare function AppointmentEditorPanel({ prefill, onSave, onDelete, onDuplicate, panelTitle, headerIcon, identity, after, closeOnSave, onDraftChange, slotPatch, colorAssociation, locale, scheduleByEntry, history, notes, onMove, onCopy, onWhatsApp, readOnly, platform, className, }: {
+export declare function AppointmentEditorPanel({ prefill, onSave, onDelete, onDuplicate, panelTitle, headerIcon, identity, after, closeOnSave, returnsOnCancel, onDraftChange, onPatientContextChange, slotPatch, colorAssociation, locale, scheduleByEntry, history, onMove, onCopy, onWhatsApp, readOnly, capabilities: hostCapabilities, series, platform, className, }: {
     prefill?: EditorPrefill;
-    onSave: (draft: EditorDraft, extras?: EditorDraftExtras) => void;
+    capabilities?: CalendarEditorCapabilities;
+    /** A host-read occurrence: its scope is asked before the form. */
+    series?: CalendarEditorSeries;
+    /** The editor closes only after acceptance. A rejection leaves the
+     * draft intact and displays its safe, user-facing Error message. */
+    onSave: (draft: EditorDraft, extras?: EditorDraftExtras) => void | Promise<void>;
     /** Live composition feed — the grid mirrors the slot being filled as a
      *  draft placeholder while this panel is open. Emits `null` on unmount
      *  so the placeholder clears with the panel. */
     onDraftChange?: (draft: DraftSlot | null) => void;
+    /** Reports the current patient to an optional workspace Notes rail tool. */
+    onPatientContextChange?: (patientId?: string) => void;
     /** Slot edits made on the grid (dragging or resizing the draft mirror).
      *  Applied by `tick` and only to the slot fields, so everything else
      *  the user has typed survives. */
@@ -172,6 +214,9 @@ export declare function AppointmentEditorPanel({ prefill, onSave, onDelete, onDu
     /** Read-only extras (billing, patient contact) below the form. */
     after?: ReactNode;
     closeOnSave?: boolean;
+    /** Cancel returns somewhere (the details panel), so an unchanged edit
+     *  may cancel too. */
+    returnsOnCancel?: boolean;
     /** The cog's colour association: the default colour on create and the
      *  re-colour when the chair/operator select changes. */
     colorAssociation: ColorAssociation;
@@ -184,8 +229,6 @@ export declare function AppointmentEditorPanel({ prefill, onSave, onDelete, onDu
     }>>;
     /** Details only — the ledger behind the History sub-view (newest first). */
     history?: CalendarHistoryEntry[];
-    /** Details only — the patient notes behind the Notes sub-view. */
-    notes?: ReactNode;
     /** Edit only — arm the grid's move mode (the platform's "Sposta"). */
     onMove?: () => void;
     /** Edit only — arm the grid's copy mode; a linked appointment offers
@@ -297,15 +340,19 @@ export declare function BacklogPanel({ items, locale, seed, signRequests, onProc
      *  mode (create / move banner) instead of opening the editor at once. */
     onPlaceWaiting?: (entry: CalendarWaitingEntry) => void;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function BookingsPanel({ bookings, locale, privacy, onShowInCalendar, onComplete, }: {
+export declare function BookingsPanel({ bookings, locale, privacy, status, lastSeenIso, createdAtById, onRetry, onShowInCalendar, onComplete, }: {
     bookings: readonly CalendarRow[];
     locale?: string;
     /** Masks the patient names, in step with the grid. */
     privacy?: boolean;
+    status?: 'loading' | 'ready' | 'error';
+    lastSeenIso?: string | null;
+    createdAtById?: Readonly<Record<string, string>>;
+    onRetry?: () => void;
     /** Steers the grid to the booking and rings its card. */
     onShowInCalendar: (eventId: string) => void;
     /** Opens the editor to complete it (platform "Completa appuntamento"). */
-    onComplete: (row: CalendarRow) => void;
+    onComplete?: (row: CalendarRow) => void;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function WaitingListPanel({ entries, rows, locale, onPlaceWaiting, onRemoveWaiting, onOpenEntryForm, onOpenPatient, onOpenAppointment, readOnly, }: {
     entries: CalendarWaitingEntry[];
@@ -388,18 +435,23 @@ export interface FindSlotsPlatformOptions {
      *  `GetGroupedOperatorService`); absent = one flat list. */
     operatorGroups?: readonly CalendarOperatorGroup[];
 }
-export declare function FindFreeSlotsPanel({ rows, locale, seed, onBookSlot, onShowInCalendar, onSearchRange, platform, }: {
+export declare function FindFreeSlotsPanel({ rows, locale, seed, onBookSlot, onShowInCalendar, onSearchRange, platform, canBook, }: {
     rows: CalendarRow[];
     locale: string;
     /** Prefill context (the tool keys its panel by seed.tick). */
     seed?: FindSlotsSeed | null;
     onBookSlot: (prefill: EditorPrefill) => void;
+    /** False for a viewer without the appointment-edit right: the slots
+     *  still list and project, but no row offers Book. */
+    canBook?: boolean;
     /** Platform depth the rail never needed — absent = rail behaviour. */
     platform?: FindSlotsPlatformOptions;
     /** Project the found free ranges onto the grid (null = clear) — the
      *  Calendar dims booked cards and glows the free ranges. The context
      *  carries the seeded patient/care into grid-click bookings. */
     onShowInCalendar: (slots: CalendarFreeSlot[] | null, fromDate?: Date, context?: AvailabilityContext) => void;
+    /** Retained for host compatibility; projection supports every grid axis. */
+    gridAxis?: 'none' | 'chair' | 'operator';
     /**
      * The window a search is about to cover, raised BEFORE it runs.
      *
@@ -414,4 +466,5 @@ export declare function FindFreeSlotsPanel({ rows, locale, seed, onBookSlot, onS
         to: Date;
     }) => void;
 }): import("react/jsx-runtime").JSX.Element;
+export {};
 //# sourceMappingURL=calendar.sheets.d.ts.map