@alfadocs/ui-kit 1.13.0 → 1.15.0

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

@@ -0,0 +1,74 @@
+/**
+ * Calendar pattern — remembered per-user preferences.
+ *
+ * SHIPPED runtime module of the calendar pattern: everything exported
+ * here is public API of `@alfadocs/ui-kit/patterns/calendar`.
+ *
+ * The platform stores each user's calendar view and chair/operator
+ * selections server-side (`DoctorAddressUser.calendarView`,
+ * `calendarSelectedChairIds`, `calendarSelectedOperatorIds`, written by
+ * `setCalendarView` and the events-fetch side effect) and its display
+ * knobs in per-user settings. `CalendarPreferenceAdapter` is that seam:
+ * a host passes `CalendarWorkspace` a `preferences` adapter backed by
+ * whatever it already has — a PATCH-on-change client, `localStorage`,
+ * anything with get / set / clear — and the workspace, its surface and
+ * its cog all read and write through it.
+ *
+ * The default is `memoryPreferenceAdapter`, a module-level map: it
+ * survives remounts, re-renders and locale switches within one page
+ * load and resets on reload. Deliberately NOT `localStorage` and not
+ * the kit's `usePersistentState` — an unconfigured host (and every
+ * Storybook story) must not leak one mount's selections into the next,
+ * or into Chromatic. A host that wants durable preferences supplies the
+ * adapter.
+ *
+ * The adapter validates nothing; each call site passes a `read` guard,
+ * so a stale or foreign stored shape falls back to the default rather
+ * than leaking into render.
+ */
+import { type Dispatch, type SetStateAction } from 'react';
+/** The per-user preference store — the platform's server-side seam. */
+export interface CalendarPreferenceAdapter {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    clear(): void;
+}
+/** Session-scoped, per-reload store — the default adapter. */
+export declare const memoryPreferenceAdapter: CalendarPreferenceAdapter;
+/** Forget everything in the default adapter — the tests' `afterEach`. */
+export declare function resetCalendarPreferences(): void;
+/**
+ * The storage keys the workspace remembers, in one place.
+ *
+ * The VALUES are load-bearing: they are what is already sitting in every
+ * host store and browser that has run this workspace. Renaming a key
+ * here silently forgets that user's view, weekend choice, chair and
+ * operator selections and cog settings — change a value only with a
+ * migration. The member names are free to change; the strings are not.
+ */
+export declare const CALENDAR_PREFERENCE_KEYS: {
+    readonly view: "calendarWorkspace.view";
+    readonly display: "calendarWorkspace.display";
+    readonly showWeekends: "calendarWorkspace.showWeekends";
+    readonly chairIds: "calendarWorkspace.chairIds";
+    readonly operatorIds: "calendarWorkspace.operatorIds";
+};
+/**
+ * `useState` whose value is remembered through the adapter. `read`
+ * validates the stored value — a stale or foreign shape falls back to
+ * `defaultValue` rather than leaking into render. Writes happen on set,
+ * never on mount, so merely opening a story remembers nothing.
+ */
+export declare function usePersistedPreference<T>(key: string, defaultValue: T | (() => T), read: (raw: unknown) => T | undefined, adapter?: CalendarPreferenceAdapter): [T, Dispatch<SetStateAction<T>>];
+/** One of a closed set of string literals, else undefined. */
+export declare function readEnum<T extends string>(allowed: readonly T[]): (raw: unknown) => T | undefined;
+export declare function readBoolean(raw: unknown): boolean | undefined;
+/**
+ * A remembered id selection, kept to the ids that still exist (a retired
+ * chair or operator drops out silently). Any non-array is rejected; an
+ * empty array is a real "nothing selected" choice.
+ */
+export declare function readIdList(known: ReadonlyArray<{
+    id: string;
+}>): (raw: unknown) => string[] | undefined;
+//# sourceMappingURL=calendar.preferences.d.ts.map

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

@@ -0,0 +1,398 @@
+/**
+ * Calendar demo — the SECONDARY SURFACES (the sheets): task details, the
+ * patient record / notes / appointments / tasks panels, the appointment
+ * editor (create, edit and details in ONE form) with its identity and
+ * extras blocks, the patient care plan, the Final State's Backlog and
+ * Increment 1's platform waiting list with their shared entry form,
+ * Increment 1's online-bookings panel, the find-free-slots finder and
+ * the front-desk print sheet.
+ *
+ * The editor's form is a DENSITY-TIERED grid: a container query on the
+ * panel's own inline size pairs its short fields from 30rem and moves the
+ * label beside the control from 44rem, so it fits the rail without
+ * scrolling. No target shrinks — only the column count and the label's
+ * position change.
+ *
+ * Every panel composes kit primitives over the host-supplied read model
+ * (`useCalendarData()`, see `calendar.data.ts`) and the pure model in
+ * `calendar.model.ts`; none knows WHERE it is hosted — the open / close
+ * seam is `calendar.host.ts`, which the Final State demo maps onto its
+ * full Control Room rail and the shipped `CalendarWorkspace` onto a
+ * minimal five-tool one. Nothing here imports from the stories module,
+ * the demos or the shared story shell.
+ */
+import { type ReactNode } from 'react';
+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 } from './calendar.types';
+import { type CalendarRow, type DisplaySettings, type EditorPrefill, type EditorDraft, type DraftSlot, type SlotPatch, type BacklogFilter, type BacklogItem, type WaitingEntryDraft, type CalendarFreeSlot, type PrintDaySection, type FindSlotsSeed, type AvailabilityContext } from './calendar.model';
+import { type EditorDraftExtras, type DeleteOptions } from './calendar-workspace.model';
+export declare function TaskDetailsPanel({ row, locale, }: {
+    row: CalendarRow;
+    locale: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PatientRecordPanel({ patientId, locale, }: {
+    patientId: string;
+    locale: string;
+}): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Where a note WRITE goes. The workspace builds one of these from its
+ * `CalendarJourney` and hands it down; the panel renders `notes` and
+ * reports intent, holding no note state and composing no note text of
+ * its own. Nothing the kit invented — a draft paragraph, a transcript,
+ * an author's name — can reach a patient's record through it.
+ */
+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;
+    /** The practice's own drafting endpoint. Omitted → no AI affordance. */
+    onRequestAiDraft?: NotesPanelProps['onRequestAiDraft'];
+    /** The host's live transcription. Omitted → no microphone. */
+    onDictate?: NotesPanelProps['onDictate'];
+}
+export declare function PatientNotesPanel({ patientId, seam, editable, }: {
+    patientId: string;
+    /**
+     * Where every write goes. WITHOUT one the panel is a read-only
+     * timeline read from the host's read model: there is nowhere to
+     * persist to, so no write is offered and none can be lost.
+     */
+    seam?: PatientNotesSeam;
+    /**
+     * Whether this reader may write at all — the platform's
+     * `practice_appointment_edit` right, off in read-only mode. False (or
+     * no `seam`) leaves the composer, the pin and the per-note edit /
+     * delete dialogs unmounted.
+     */
+    editable?: boolean;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PatientAppointmentsTimeline({ patientId, locale, }: {
+    patientId: string;
+    locale?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PatientTasksPanel({ patientId }: {
+    patientId: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function DurationCombobox({ value, onChange, }: {
+    value: number | null;
+    onChange: (next: number | null) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/** Channels the editor's send-reminder group may offer. */
+export type ReminderChannel = 'whatsapp' | 'sms' | 'email';
+/** The Final State's full set — the default when a host says nothing. */
+export declare const REMINDER_CHANNELS: readonly ReminderChannel[];
+/** The platform facts the Increment 1 editor adds — every field optional,
+ *  so a host that passes nothing gets the Final State form unchanged. */
+export interface EditorPlatformOptions {
+    /** Practice branches (platform "Branca"); the select shows for > 1. */
+    branches?: readonly {
+        id: string;
+        name: string;
+    }[];
+    /** Care id → device names; drives the read-only devices line. */
+    devicesByCare?: Readonly<Record<string, readonly string[]>>;
+    /** Required documents still unsigned for a patient (sign-mode radios). */
+    unsignedRequiredDocs?: (patientId: string) => number;
+    /** The agenda, for the busy chair / busy operator warnings. */
+    rows?: readonly CalendarRow[];
+    /** Enter in a text field submits (the platform's modal never did). */
+    submitOnEnter?: boolean;
+    /** The edited appointment belongs to a series — offer the save scope. */
+    recurringScope?: boolean;
+    /** Price-list recurrence parent — ask about the care-plan lines on delete. */
+    carePlanCleanup?: boolean;
+    /** Create bill asks before executing the linked treatments. */
+    confirmCreateBill?: boolean;
+    /** Operator options for the select — defaults to the shared active
+     *  cast. A host whose appointment is held by an operator the practice
+     *  has since DISABLED passes the wider list, so the name still shows
+     *  (a new appointment keeps the active cast, as on the platform). */
+    operatorOptions?: readonly {
+        id: string;
+        title: string;
+    }[];
+    /** Reminder channels in the action footer — defaults to all three.
+     *  The platform has NO "send reminder now" action on the calendar; its
+     *  only outbound bridge is the popover's WhatsApp Snippets island, so
+     *  Increment 1 narrows this to `['whatsapp']` (audit A2). */
+    reminderChannels?: readonly ReminderChannel[];
+    /** Offer the Final State's extra recurrence rules — the "Ends: after N
+     *  / on a date" choice and the skip-closed-days switch. The platform's
+     *  modal only ever sets a repetition count, so Increment 1 turns this
+     *  off and keeps frequency + count alone (audit A3). */
+    recurrenceExtras?: boolean;
+    /** Warn — never block — when the chosen operator is away that day, as
+     *  a third sibling of the busy warnings. Off: an absence keeps the
+     *  date-side closure banner and holds the save (audit C9). */
+    operatorAbsenceWarning?: boolean;
+    /** Show the reminder checkboxes only once a patient is chosen, and
+     *  disable each channel the patient cannot take, with the platform's
+     *  "(disabled)" suffix on the label (audit C10). */
+    reminderCapability?: boolean;
+    /** Show "First visit" only once a patient is chosen (audit C11). */
+    firstVisitRequiresPatient?: boolean;
+    /** Give each price-list row its catalogue phases, and lock a row the
+     *  practice has already invoiced (audit C12). */
+    priceListPhases?: boolean;
+    /** Refuse a description longer than this and say so (platform: 255
+     *  characters, silently blocking; audit C14). */
+    descriptionMaxLength?: number;
+    /** Where "save and go back" goes — the deep link's origin. Only ever
+     *  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, }: {
+    prefill?: EditorPrefill;
+    onSave: (draft: EditorDraft, extras?: EditorDraftExtras) => 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;
+    /** 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. */
+    slotPatch?: SlotPatch | null;
+    /** Edit mode only — removes the event; confirmed via an alert dialog
+     *  that also asks the recurring scope and the care-plan cleanup. */
+    onDelete?: (eventId: string, options?: DeleteOptions) => void;
+    /** Edit mode only — re-seeds the CREATE editor from the current form
+     *  state (everything but the identity). Unset hides the Duplicate icon
+     *  altogether, leaving Copy… placement as the one copy path. */
+    onDuplicate?: (prefill: EditorPrefill) => void;
+    /** Panel-chrome heading override — "Appointment details" reuses this
+     *  SAME form so read and edit are one surface, not two paradigms. */
+    panelTitle?: string;
+    headerIcon?: ReactNode;
+    /** Identity block (avatar · name · status chip) above the form. */
+    identity?: ReactNode;
+    /** Read-only extras (billing, patient contact) below the form. */
+    after?: ReactNode;
+    closeOnSave?: boolean;
+    /** The cog's colour association: the default colour on create and the
+     *  re-colour when the chair/operator select changes. */
+    colorAssociation: ColorAssociation;
+    /** BCP 47 locale for the checklist's scheduled-date chips and prices. */
+    locale?: string;
+    /** Plan line id → its booked appointments (`scheduleByEntryId`). */
+    scheduleByEntry?: Record<string, Array<{
+        eventId: string;
+        startIso: string;
+    }>>;
+    /** 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
+     *  the platform's two copies (appointment only / with treatments). */
+    onCopy?: (withTreatments: boolean) => void;
+    /** Bridge the WhatsApp reminder to the legacy Snippets island. */
+    onWhatsApp?: () => void;
+    /** No edit permission: every write action goes, the form locks and a
+     *  note says why. */
+    readOnly?: boolean;
+    /** Platform parity extras — see `EditorPlatformOptions`. */
+    platform?: EditorPlatformOptions;
+    /** Root class — a dialog host bounds the panel's height through it. */
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function IndicatorChips({ event }: {
+    event: CalendarEvent;
+}): import("react/jsx-runtime").JSX.Element | null;
+export declare function AppointmentIdentity({ row, patient, showAge, onOpenPatient, anamnesisAnswers, }: {
+    row: CalendarRow;
+    patient?: CalendarPatient;
+    /** Append the platform popover's "(NN anni)" to the name (audit C15). */
+    showAge?: boolean;
+    /** Set = the name becomes the platform's patient-folder link. */
+    onOpenPatient?: (patient: CalendarPatient) => void;
+    /** The highlighted anamnesis answers themselves — the platform's
+     *  details dialog lists them, the popover only counts (audit C16). */
+    anamnesisAnswers?: readonly CalendarAnamnesisAnswer[];
+}): import("react/jsx-runtime").JSX.Element;
+export declare function SendReminderGroup({ patient, onWhatsApp, channels: allowed, }: {
+    patient: CalendarPatient;
+    /** When set, the WhatsApp segment bridges to the legacy Snippets
+     *  island instead of the demo-fake send. */
+    onWhatsApp?: () => void;
+    /** Which channels to offer — defaults to all three. Increment 1 keeps
+     *  the WhatsApp bridge alone, the platform's only outbound path. */
+    channels?: readonly ReminderChannel[];
+}): import("react/jsx-runtime").JSX.Element | null;
+/** The platform popover facts the Final State never modelled — every
+ *  field optional, so a host that passes nothing sees the extras as before. */
+export interface ExtrasPlatformOptions {
+    /** The patient has an advanced e-signature setup (else "Enable AES"). */
+    aesEnabled?: boolean;
+    /** Deposit paid online when booking (Stripe). */
+    paidOnlineAmount?: number;
+    /** The patient's outstanding balance. */
+    toCollectAmount?: number;
+    /** Payment automation is off and the upsell toggle is on. */
+    pauUpsell?: boolean;
+    /** The user's map-link setting (the display cog). */
+    mapsLink?: boolean;
+    /** The phone typed on the booking site, when it differs from the record. */
+    bookingPhone?: string;
+}
+export declare function AppointmentExtras({ row, patient, locale, signRequestedVia, onRequestSignature, onRequestSignatureOnDevice, readOnly, platform, }: {
+    row: CalendarRow;
+    patient?: CalendarPatient;
+    locale: string;
+    /** Channel the signature request went out on (journey state wins). */
+    signRequestedVia?: CalendarSignChannel;
+    onRequestSignature?: (eventId: string, channel: CalendarSignChannel) => void;
+    /** "On this device…" — bridges to the legacy e-signature flow. */
+    onRequestSignatureOnDevice?: () => void;
+    /** No edit permission: the request menu and the setup links go. */
+    readOnly?: boolean;
+    /** Platform parity extras — see `ExtrasPlatformOptions`. */
+    platform?: ExtrasPlatformOptions;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function PatientCarePlanPanel({ plans, linkedPlanId, linkedEntryIds, schedule, locale, onReveal, }: {
+    plans: CalendarCarePlan[];
+    /** The selected appointment's plan — listed first, entries expanded. */
+    linkedPlanId?: string;
+    linkedEntryIds: string[];
+    schedule: Record<string, Array<{
+        eventId: string;
+        startIso: string;
+    }>>;
+    locale: string;
+    /** Navigate the grid to the appointment and select it. */
+    onReveal: (eventId: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function BacklogPanel({ items, locale, seed, signRequests, onProcess, onFocusEvent, onConfirm, onRequestSignature, onScheduleWaiting, onRemoveWaiting, onFindSlotsForWaiting, onUpsertWaiting, quickView, onOpenEntryForm, onPlaceWaiting, }: {
+    items: BacklogItem[];
+    locale: string;
+    /** A fresh tick preselects `type` — how every caller opens the queue
+     *  on one segment without reaching into panel state. */
+    seed: {
+        tick: number;
+        type: BacklogFilter;
+    };
+    /** Event id → the channel a signature request went out on this session. */
+    signRequests: Record<string, CalendarSignChannel>;
+    /** Dock the editor prefilled (Process booking, Assign operator). */
+    onProcess: (prefill: EditorPrefill) => void;
+    /** Ring the appointment on the grid so it is clear which one is meant. */
+    onFocusEvent: (eventId: string) => void;
+    /** Unconfirmed → confirmed, in place. */
+    onConfirm: (eventId: string) => void;
+    onRequestSignature: (eventId: string, channel: CalendarSignChannel) => void;
+    onScheduleWaiting: (entry: CalendarWaitingEntry) => void;
+    onRemoveWaiting: (entry: CalendarWaitingEntry) => void;
+    /** Hand the entry to the find-free-slots tool, prefilled. */
+    onFindSlotsForWaiting: (entry: CalendarWaitingEntry) => void;
+    /** The entry form's Save — add (no id) or update (id) in the queue. */
+    onUpsertWaiting: (draft: WaitingEntryDraft) => void;
+    /** Increment 1: the platform's waiting-list quick views above the queue. */
+    quickView?: boolean;
+    /** Set = Add entry and the row's edit open the HOST's entry form (a
+     *  dialog) instead of the in-panel sub-view. */
+    onOpenEntryForm?: (entry?: CalendarWaitingEntry) => void;
+    /** Set = Schedule / Reschedule hands the entry to the host's placement
+     *  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, }: {
+    bookings: readonly CalendarRow[];
+    locale?: string;
+    /** Masks the patient names, in step with the grid. */
+    privacy?: boolean;
+    /** 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;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function WaitingListPanel({ entries, rows, locale, onPlaceWaiting, onRemoveWaiting, onOpenEntryForm, onOpenPatient, onOpenAppointment, }: {
+    entries: CalendarWaitingEntry[];
+    /** Live grid rows — the linked appointment's date, colour and care. */
+    rows: CalendarRow[];
+    locale: string;
+    /** Schedule / Reschedule → the host's create / move placement mode. */
+    onPlaceWaiting: (entry: CalendarWaitingEntry) => void;
+    /** Delete — immediate, as on the platform (the host toasts an Undo). */
+    onRemoveWaiting: (entry: CalendarWaitingEntry) => void;
+    /** Add entry, and a row's edit → the host's entry sub-view. */
+    onOpenEntryForm: (entry?: CalendarWaitingEntry) => void;
+    /** The patient-folder hop the platform's name link makes. */
+    onOpenPatient: (patient: CalendarPatient) => void;
+    /** The platform's `focusAppointmentId` deep link — steer and ring. */
+    onOpenAppointment: (eventId: string) => void;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The platform's waiting-list AddModal as a rail sub-view — same field
+ * order (patient, operator, colour, description) and its one rule:
+ * a patient OR a description, checked on submit with an inline error.
+ */
+export declare function WaitingListEntryForm({ entry, onSave, onCancel, chrome, }: {
+    /** Set = edit this entry; unset = add a new one. */
+    entry?: CalendarWaitingEntry;
+    onSave: (draft: WaitingEntryDraft) => void;
+    onCancel: () => void;
+    /** `'dialog'` drops the rail's back arrow — the dialog's own Close and
+     *  the form's Cancel already dismiss it. */
+    chrome?: 'panel' | 'dialog';
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * The call sheet itself. A portal to `document.body`: the shell's AppFrame
+ * is an `h-dvh overflow-hidden` clamp that prints one screenful, so the
+ * sheet lives outside it — hidden on screen, the only thing on paper.
+ */
+export declare function PrintSheet({ sections, rangeTitle, axisKind, visibleChairIds, visibleOperatorIds, privacy, locale, }: {
+    sections: PrintDaySection[];
+    rangeTitle: string;
+    axisKind: DisplaySettings['resourceKind'];
+    visibleChairIds: string[];
+    visibleOperatorIds: string[];
+    privacy: boolean;
+    locale: string;
+}): import("react").ReactPortal | null;
+/** The platform depth the dialog host asks for (decision 6). Every field
+ *  is optional, so the rail keeps exactly the behaviour it had. */
+export interface FindSlotsPlatformOptions {
+    /** Results as clickable rows and NO grid projection — the dialog host. */
+    listOnly?: boolean;
+    /** Care id → medical devices it needs (`FIND_FREE_SLOTS_BY_CARE`). */
+    devicesByCare?: Readonly<Record<string, readonly string[]>>;
+    /** Warn past the platform's look-ahead ceiling; the search still runs. */
+    maxRangeDays?: number;
+    /** "Show more slots" pushes the To date out by this many days. */
+    pagerStepDays?: number;
+    /** Advisory: the practice has at least one business-hours row. */
+    practiceHasBusinessHours?: boolean;
+    /** Advisory: at least one operator has business-hours rows. */
+    operatorsHaveBusinessHours?: boolean;
+    /** The advisory's scheduler link. */
+    onOpenScheduler?: () => void;
+    /** Operator and chair scope as grouped checklists (the platform's
+     *  `OperatorDropdown` / `ChairDropdown`) instead of one Select plus
+     *  "Any". Nothing ticked means every eligible resource, exactly as
+     *  the platform's empty selection does server-side. */
+    multiSelectScope?: boolean;
+    /** Group sections for that operator checklist (platform
+     *  `GetGroupedOperatorService`); absent = one flat list. */
+    operatorGroups?: readonly CalendarOperatorGroup[];
+}
+export declare function FindFreeSlotsPanel({ rows, locale, seed, onBookSlot, onShowInCalendar, platform, }: {
+    rows: CalendarRow[];
+    locale: string;
+    /** Prefill context (the tool keys its panel by seed.tick). */
+    seed?: FindSlotsSeed | null;
+    onBookSlot: (prefill: EditorPrefill) => void;
+    /** 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;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=calendar.sheets.d.ts.map

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

@@ -0,0 +1,85 @@
+import { type CalendarPreferenceAdapter } from './calendar.preferences';
+import { type CalendarRow, type RailFocus, type EditorPrefill, type HistoryInput, type AvailabilityContext, type CalendarFreeSlot } from './calendar.model';
+import { type WorkspaceDisplaySettings, type CreateModeRequest, type PlacementRequest, type SaveNotice, type CalendarWorkspaceToolId } from './calendar-workspace.model';
+export declare function CalendarSurface({ rows, setRows, onFocus, locale, onComposeNew, onOpenWaitingList, onAddWaitingEntry, onOpenOnlineBookings, onlineBookingsCount, waitingBadgeCount, onVisibleRangeChange, selectedEventId, gotoRequest, onBookSlot, display, setDisplay, onHistory, readOnly, placement, onPlacementEnd, createMode, onCreateModeEnd, focusScroll, saveNotice, privacy, onPrivacyChange, availability, availabilityContext, availableTools, schedulerLicenseKey, id, preferences, }: {
+    rows: CalendarRow[];
+    setRows: React.Dispatch<React.SetStateAction<CalendarRow[]>>;
+    onFocus: (focus: RailFocus) => void;
+    locale: string;
+    /** Masks patient names on the grid, the peek and the print sheet. Owned
+     *  by the journey so the rail's Appointments panel masks in step. */
+    privacy: boolean;
+    onPrivacyChange: (next: boolean) => void;
+    /** The finder's live projection: free ranges glow, booked cards dim,
+     *  and a click inside a range books it. Null when no search is shown. */
+    availability: CalendarFreeSlot[] | null;
+    availabilityContext: AvailabilityContext | null;
+    /** No edit permission: no drag, no slot-click create. */
+    readOnly?: boolean;
+    /** A Move… / Copy… armed from the details panel — the grid shows the
+     *  mode banner and the next empty-slot click places the appointment. */
+    placement?: PlacementRequest | null;
+    /** The placement landed (`true`) or was cancelled. */
+    onPlacementEnd?: (landed?: boolean) => void;
+    /** A create mode armed by a deep link or the Backlog's Schedule — the
+     *  banner stands until the next empty-slot click or Cancel. */
+    createMode?: CreateModeRequest | null;
+    /** The create mode landed or was cancelled. */
+    onCreateModeEnd?: () => void;
+    /** Deep link `focusAppointmentId`: scroll the card into view and ring
+     *  it. Tick-keyed so the same id can be re-focused. */
+    focusScroll?: {
+        tick: number;
+        eventId: string;
+    } | null;
+    /** A save just landed — toast "Saved for {date}" and, when the day is
+     *  off screen or filtered out, a Go to action (decision 10). */
+    saveNotice?: SaveNotice | null;
+    /** New appointment — seeds a clean editor (the host docks the panel). */
+    onComposeNew: () => void;
+    /** The split button's main segment — the waiting-list panel. */
+    onOpenWaitingList: () => void;
+    /** The split button's plus segment — the waiting-list entry form. */
+    onAddWaitingEntry: () => void;
+    /** Waiting ENTRIES only — online bookings carry their own count. */
+    waitingBadgeCount: number;
+    /** The Online bookings button — the platform's page hop (a toast). */
+    onOpenOnlineBookings: () => void;
+    /** Bookings of the last thirty days still missing a patient or an
+     *  operator — the count the platform's alert strip carries. */
+    onlineBookingsCount: number;
+    /** The grid event whose details panel is docked — ringed on the grid. */
+    selectedEventId: string | null;
+    /** Navigate seam — tick-keyed so re-steering to the same day works. */
+    gotoRequest: {
+        tick: number;
+        date: Date;
+    } | null;
+    /** Seed the editor prefilled (an empty-slot click, a booking to process). */
+    onBookSlot: (prefill: EditorPrefill) => void;
+    /** The cog's settings — owned by the journey (the editor reads them). */
+    display: WorkspaceDisplaySettings;
+    setDisplay: React.Dispatch<React.SetStateAction<WorkspaceDisplaySettings>>;
+    /** Ledger feed — a committed drag or resize of a patient appointment. */
+    onHistory: (eventId: string, entry: HistoryInput) => void;
+    /** The grid's visible range (epoch ms) — scopes the unconfirmed queue. */
+    onVisibleRangeChange: (range: {
+        start: number;
+        end: number;
+    }) => void;
+    /** The rail tools this host can back. A toolbar control whose tool is
+     *  not in the set is not rendered at all — a button that opens a
+     *  panel the host has no data for is worse than a missing one. */
+    availableTools: ReadonlySet<CalendarWorkspaceToolId>;
+    /** The host's FullCalendar Scheduler licence key, handed to the kit
+     *  `Calendar`. Undefined leaves the component on its own environment
+     *  default — the grid behaves exactly as it did without this prop. */
+    schedulerLicenseKey?: string;
+    /** The kit Calendar's instance id — the agent registry's handle and a
+     *  public DOM hook. One workspace per page keeps the default. */
+    id?: string;
+    /** Where the toolbar's remembered choices live — the host's per-user
+     *  store. Defaults to the session-scoped in-memory adapter. */
+    preferences?: CalendarPreferenceAdapter;
+}): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=calendar.surface.d.ts.map