@alfadocs/ui-kit 1.47.0 → 1.48.0

package/dist/patterns/calendar/calendar-appointment-details.d.ts

@@ -1,87 +1,23 @@
 import { type ReactNode } from 'react';
+import { parseAppointmentStartIso, type AppointmentDetailsLoader, type AppointmentDetailsRead, type AppointmentDetailsSnapshot, type AppointmentDocumentKind } from '../../components/appointment-details-panel';
 import type { CalendarEventStatus } from '../../components/calendar';
-import { type RecurrenceFrequency } from './calendar.model';
-import { type PatientNotesSeam } from './calendar.sheets';
-import { type CalendarHistoryEntry, type CalendarPatient, type CalendarSignChannel } from './calendar.types';
-export type CalendarDocumentKind = 'folder' | 'template' | 'empty' | 'identification' | 'webcam' | 'bill';
-/** One appointment occurrence as the host reads it for the read-only details
- * panel (P-C2). An absent member renders nothing: never a zero, never an
- * empty-state claim. */
-export interface CalendarAppointmentDetails {
-    /** The occurrence id the panel asked for, echoed back. */
-    eventId: string;
-    appointment: {
-        /** Local wall clock of THIS occurrence, 'YYYY-MM-DDTHH:mm:ss', no zone. */
-        startIso: string;
-        durationMin: number;
-        allDay: boolean;
-        isTelehealth: boolean;
-        /** Absent = no status recorded. */
-        status?: CalendarEventStatus;
-        name?: string;
-        /** Host-composed heading (the platform popover title). */
-        title: string;
-        colorHex?: string;
-        operatorId?: string;
-        chairId?: string;
-        branchLabel?: string;
-        bookedOnline: boolean;
-        /** Read side only. `requiresScope` is informational (the series rule
-         * line); the scope question lives in the editor. */
-        recurrence?: {
-            frequency: RecurrenceFrequency;
-            count?: number;
-            requiresScope: boolean;
-        };
-    };
+import type { PatientNotesSeam } from './calendar.sheets';
+import type { CalendarHistoryEntry, CalendarPatient } from './calendar.types';
+export type CalendarDocumentKind = AppointmentDocumentKind;
+/** One appointment occurrence as the host reads it for the details panel
+ * (P-C2). An absent member renders nothing: never a zero, never an
+ * empty-state claim. The read fields are AppointmentDetailsRead's; the
+ * calendar adds its richer patient record and the host's actions. */
+export interface CalendarAppointmentDetails extends Omit<AppointmentDetailsRead, 'patient' | 'history'> {
     /** Absent = no patient; `phones` carries every labelled number. */
     patient?: CalendarPatient;
-    /** Absent = not permitted; an absent figure is gated on its own. */
-    money?: {
-        billableAmount?: number;
-        unpaidAmount?: number;
-    };
-    care?: {
-        /** Without `number` the section shows the plan name alone. */
-        plan?: {
-            id: string;
-            number?: string;
-            name: string;
-        };
-        lines: Array<{
-            entryId: string;
-            careId: string;
-            name: string;
-            code?: string;
-            elementsLabel?: string;
-            done: boolean;
-            billed: boolean;
-            phases: string[];
-            /** Absent = prices withheld for this viewer. */
-            priceCents?: number;
-        }>;
-    };
-    booking?: {
-        typedName?: string;
-        phone?: string;
-        email?: string;
-        note?: string;
-        bookedAtIso?: string;
-        paidOnlineAmount?: number;
-    };
-    signing?: {
-        required: number;
-        toComplete: number;
-        requestedVia?: CalendarSignChannel;
-        aesSetUp: boolean;
-    };
     history: CalendarHistoryEntry[];
     /** Host-owned; the kit never sees the session code. */
     onJoinTelehealth?: () => void;
     /** Host-composed; absent = not available. */
     whatsappUrl?: string;
     /** Host-owned bridge to the practice's WhatsApp snippets; absent = not
-     * offered. With `whatsappUrl` too, the one button calls this. */
+     *  offered. With `whatsappUrl` too, the one button calls this. */
     onWhatsApp?: () => void;
     /** Server-built link to the task page, same tab; absent = not offered. */
     createTaskUrl?: string;
@@ -91,34 +27,29 @@ export interface CalendarAppointmentDetails {
         onCreate: (kind: CalendarDocumentKind) => void;
     };
 }
-export type CalendarAppointmentDetailsSnapshot = {
-    status: 'ready';
-    details: CalendarAppointmentDetails;
-} | {
-    status: 'refused';
-    reason: string;
-    retryable?: boolean;
-};
+export type CalendarAppointmentDetailsSnapshot = AppointmentDetailsSnapshot<CalendarAppointmentDetails>;
 /** A rejected promise is a transient failure (error with Retry); 'refused'
  * means not visible (the reason, with Retry only when retryable). */
-export type CalendarAppointmentDetailsLoader = (eventId: string, options: {
-    signal: AbortSignal;
-}) => Promise<CalendarAppointmentDetailsSnapshot>;
-/** The host's zone-less wall clock as a local Date, or undefined when it is
- * not a real 'YYYY-MM-DDTHH:mm:ss' reading. Ranges are checked rather than
- * round-tripped, so a time inside a daylight-saving gap still parses. */
-export declare function parseDetailsStartIso(startIso: string | undefined): Date | undefined;
+export type CalendarAppointmentDetailsLoader = AppointmentDetailsLoader<CalendarAppointmentDetails>;
+/** The host's zone-less wall clock as a local Date; see
+ *  `parseAppointmentStartIso`. */
+export declare const parseDetailsStartIso: typeof parseAppointmentStartIso;
 export interface CalendarDetailsHydrationProps {
     /** The occurrence to read; a new id aborts the previous read. */
     eventId: string;
+    /** Keep it stable: a new function reads the occurrence again. */
     load: CalendarAppointmentDetailsLoader;
     /** Mounted only with details whose eventId and startIso passed the checks. */
     children: (details: CalendarAppointmentDetails) => ReactNode;
 }
 /** The details panel is not mounted until the host's read answers for this
- * occurrence. A late answer for a replaced id or loader is ignored. */
+ * occurrence. A late answer for a replaced id or loader is ignored. A new
+ * `load` reads the same occurrence again while the current read stays on
+ * screen, so a host re-reads after a change by handing a new loader. Until
+ * the first answer the panel's own shell shows the skeleton, the error with
+ * Retry, or the refusal. */
 export declare function CalendarDetailsHydration({ eventId, load, children, }: CalendarDetailsHydrationProps): import("react/jsx-runtime").JSX.Element;
-export interface AppointmentDetailsPanelProps {
+export interface CalendarAppointmentDetailsPanelProps {
     /** The occurrence as the host read it (P-C2). */
     details: CalendarAppointmentDetails;
     /** The row's patient id (N-C5); defaults to the read's patient. */
@@ -153,9 +84,8 @@ export interface AppointmentDetailsPanelProps {
     privacyTitle?: string;
     locale?: string;
 }
-/** The appointment details panel (P-C2, P-C3): the patient card, the
- *  appointment, notes and treatments cards, a pinned footer with the
- *  status and the actions, and a History sub-view in place of the body.
+/** The appointment details panel of the calendar (P-C2, P-C3): the published
+ *  AppointmentDetailsPanel, fed from CalendarData and the calendar's read.
  *  It docks in the rail, is no dialog and asks no series scope. */
-export declare function AppointmentDetailsPanel(props: AppointmentDetailsPanelProps): import("react/jsx-runtime").JSX.Element;
+export declare function CalendarAppointmentDetailsPanel({ details, patientId, notesSeam, onOpenNotes, readOnly, onEdit, onMove, onCopy, onStatusChange, onDescriptionChange, mapsLink, privacy, privacyTitle, locale, }: CalendarAppointmentDetailsPanelProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=calendar-appointment-details.d.ts.map

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

@@ -1,11 +1,12 @@
-interface PatientPickerProps {
+interface CalendarPatientPickerProps {
     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;
+/** One id-valued patient control for the editor and waiting surfaces: the
+ *  shared PatientPicker fed from `CalendarData`. */
+export declare function CalendarPatientPicker(props: CalendarPatientPickerProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=calendar-patient-picker.d.ts.map

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

@@ -1,23 +1,2 @@
-import type { ReactNode } from 'react';
-/** The mask privacy mode shows for a name. TOTAL, as `maskedTitle` is: an
- *  empty or absent host mask degrades to the bullets, never to a blank. */
-export declare function privacyMask(mask?: string): string;
-/** One muted line where a personal value would have been. */
-export declare function PrivacyHiddenLine({ block }: {
-    block?: string;
-}): import("react/jsx-runtime").JSX.Element;
-/** The patient card under privacy: the grid's mask, no photo, no contact
- *  fields and no chips. Keeps `data-card="patient"` for host hooks. */
-export declare function PrivacyIdentityCard({ mask }: {
-    mask?: string;
-}): import("react/jsx-runtime").JSX.Element;
-/** A whole rail panel withheld under privacy: a form or a notes list that
- *  could only open by showing what the mask hides. */
-export declare function PrivacyNoticePanel({ title, icon, onTurnOff, }: {
-    /** The panel's own title, so the rail still says which tool this is. */
-    title: string;
-    icon?: ReactNode;
-    /** Absent: the notice explains, and the toolbar's toggle is the way out. */
-    onTurnOff?: () => void;
-}): import("react/jsx-runtime").JSX.Element;
+export { privacyMask, PrivacyHiddenLine, PrivacyIdentityCard, PrivacyNoticePanel, } from '../../components/_shared/privacy-mask';
 //# sourceMappingURL=calendar-privacy.d.ts.map

package/dist/patterns/calendar/calendar-sticky-offset.d.ts

@@ -1,20 +1,27 @@
 export declare const STICKY_HEADER_CELL = ".fc-scrollgrid-section-header.fc-scrollgrid-section-sticky > *";
+/** The kit Calendar's create, Move and Copy banner. */
+export declare const MODE_BANNER = "[data-calendar-mode-banner]";
 /** The box `position: sticky` resolves against: the nearest ancestor that
  *  is a scroll container (`clip` is not one), or null for the viewport. */
 export declare function stickyScrollport(el: Element): Element | null;
-/** How far the header must sit below its natural `top: 0`. The nav only
- *  covers it in a SHARED scrollport; in the grid's own (the platform's
- *  table) any offset lands the header on the all-day lane. No header, no
- *  offset: a nav height set blind is exactly that bug. */
+/** How far the header sits below its natural `top: 0` to clear the nav. The
+ *  kit resets `.fc-view` and its table; any other host scroll container
+ *  still yields 0, as an offset there covers the all-day lane. */
 export declare function stickyHeaderOffset(navigation: HTMLElement, header: Element | null): number;
-/**
- * Keeps `--inc1-nav-offset` on `surface` current and returns the cleanup.
- * Re-measures when the nav or surface resizes AND when FullCalendar
- * inserts or replaces the header, which can happen with no size change.
- *
- * Not re-measured: a host changing an ancestor's `overflow` at runtime
- * with no resize. Watching style across FullCalendar's subtree would fire
- * on every hover and drag; no host does this. Remount if you must.
- */
+export interface StickyOffsets {
+    /** `--inc1-nav-offset`: the nav alone, as the header sees it. */
+    nav: number;
+    /** `--inc1-banner-top`: where the mode banner parks. */
+    bannerTop: number;
+    /** `--inc1-header-offset`: the nav plus a banner in the header's scrollport. */
+    header: number;
+    /** `--inc1-pinned-block-size`: everything pinned above the grid's events. */
+    pinned: number;
+}
+/** Every sticky offset the surface needs, from one measurement. */
+export declare function stickyOffsets(navigation: HTMLElement, header: Element | null, banner: Element | null): StickyOffsets;
+/** Keeps the sticky offsets on `surface` current; re-measures on resize and
+ *  when the header or banner is inserted or replaced. A runtime `overflow`
+ *  change with no resize is not seen: remount. Returns the cleanup. */
 export declare function trackStickyHeaderOffset(navigation: HTMLElement, surface: HTMLElement): () => void;
 //# sourceMappingURL=calendar-sticky-offset.d.ts.map

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

@@ -3,29 +3,25 @@ export interface CalendarTaskEditorProps {
     mode: 'create' | 'edit';
     /** Edit mode: which task to load via `loadTask`. */
     taskId?: string;
-    /** Create mode: the date/time to prefill — the grid's selection, or
-     *  today when none. Local wall-clock, never re-read after mount. */
+    /** Create mode: the date and time to prefill, the grid's selection or
+     *  now. Local wall-clock, never re-read after mount. */
     initialDate?: Date;
     onCancel: () => void;
-    /** Fires once a create/update/delete lands, so the host can close the
-     *  rail or refresh whatever list is showing. */
+    /** Fires once a create or update lands. */
     onSaved?: (task: CalendarTask) => void;
     onDeleted?: (id: string) => void;
-    /** Must resolve WITH the saved record — the host assigns the new id. */
+    /** Must resolve WITH the saved record: the host assigns the new id. */
     onCreateTask?: (draft: TaskDraft) => Promise<CalendarTask>;
-    /** Full re-send, not a patch. Resolves with nothing: the subject is
-     *  already named by `taskId`. */
+    /** Full re-send, not a patch. Resolves with nothing. */
     onUpdateTask?: (id: string, draft: TaskDraft) => Promise<void>;
     onDeleteTask?: (id: string) => Promise<void>;
     onSetTaskDone?: (id: string, done: boolean) => Promise<void>;
     loadTask?: (id: string) => Promise<CalendarTask>;
-    /** Withholds every write control and disables the fieldset — same
-     *  contract as the appointment editor's `readOnly`. */
+    /** Withholds every write control and disables the fieldset. */
     readOnly?: boolean;
-    /** Privacy mode: the linked patient's identity is masked, never the
-     *  fact that one is linked. A task about nobody has nothing to mask. */
+    /** Privacy mode: the linked patient's identity is masked, never the fact
+     *  that one is linked. */
     privacy?: boolean;
-    locale?: string;
 }
-export declare function CalendarTaskEditor({ mode, taskId, initialDate, onCancel, onSaved, onDeleted, onCreateTask, onUpdateTask, onDeleteTask, onSetTaskDone, loadTask, readOnly, privacy, }: CalendarTaskEditorProps): import("react/jsx-runtime").JSX.Element;
+export declare function CalendarTaskEditor(props: CalendarTaskEditorProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=calendar-task-editor.d.ts.map

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

@@ -1,3 +1,44 @@
+/**
+ * Calendar pattern — the WORKSPACE ROOT.
+ *
+ * The practice agenda page the platform mounts from the kit: the grid
+ * and its two-strip toolbar (`calendar.surface.tsx`) beside a MINIMAL
+ * Control Room rail docked inline-end — up to six tools, in strip
+ * order: the upcoming Appointments panel (the rail's resting state and
+ * its default), ONE appointment editor / details tool, the waiting list,
+ * patient notes when in context, online bookings and the free-slot
+ * finder. The kit adds nothing else: no Inbox, no Alia, no patient tabs,
+ * no care plan, no tasks. A host may append its own tools after these
+ * (`extraTools`), which is how a host mounts TasksPanel. The panels are
+ * the extracted modules from `calendar.sheets.tsx`; `calendar.host.ts`'s
+ * open / close seam maps onto the rail's dock, with `close()` returning
+ * to the Appointments panel so no path leaves an empty rail.
+ *
+ * Six is the ceiling, not the floor: `availableTools` narrows the set
+ * to what the host can actually back with data, hiding the rail tool AND
+ * the toolbar control that opens it, and routing anything aimed at a
+ * withheld tool to the Appointments panel. A host with no business
+ * hours, holidays or closures must withhold the free-slot finder — it
+ * would otherwise report booked and shut-day times as free.
+ *
+ * The host owns the data and the domain state: it hands in a
+ * `CalendarData` read model (`calendar.data.ts`) and a `CalendarJourney`
+ * (`calendar.journey.ts`) — the demos from their fixtures and the
+ * fixture-backed journey hook, the platform island from
+ * `/internalApi/...`. The workspace owns what sits between the two: the
+ * cog's display settings, the privacy flag, the one polite region, the
+ * editor tool's mode, the placement / create modes, the deep-link
+ * effects and the tasks filter. It renders NO header or sidebar — the
+ * host page has its own — and expects a bounded block-size from its
+ * parent (it fills it; the surface scrolls inside, the rail stays put),
+ * exactly what `AppFrame`'s `<main>` gives a page.
+ *
+ * The confirmations stay kit `Dialog`s — they interrupt rather than
+ * dock: the move confirm, the delete confirm with its recurring scope
+ * and care-plan cleanup and the Create-bill confirm.
+ */
+import type { CalendarView } from '../../components/calendar';
+import { type ControlRoomFavoriteChange, type ControlRoomTool } from '../../components/control-room-rail';
 import { type CalendarAppointmentEditorLoader } from './calendar-editor-hydration';
 import { type CalendarAppointmentDetailsLoader } from './calendar-appointment-details';
 import { type CalendarData } from './calendar.data';
@@ -18,6 +59,81 @@ export interface CalendarOnlineBookings {
     createdAtById?: Readonly<Record<string, string>>;
     onRetry?: () => void;
 }
+/** Where a tool panel was opened from. `system` is a dock the workspace
+ *  made on its own (the resting panel, a return after a save, a
+ *  toolbar or journey hand-off), not a pick on the rail. */
+export type CalendarToolOpenSource = 'rail' | 'appointment_panel' | 'selection' | 'system';
+/** Where the appointment behind a details panel was selected. `host` is
+ *  a selection the journey made itself. */
+export type CalendarDetailsOpenSource = 'calendar' | 'appointments_panel' | 'bookings_panel' | 'waiting_list' | 'deep_link' | 'host';
+/**
+ * A host tool on the workspace rail (`CalendarWorkspaceProps.extraTools`):
+ * a Control Room tool, plus what privacy mode does to it. `scope` and
+ * `reorderable` are ignored: the workspace rail orders by favourites.
+ */
+export interface CalendarWorkspaceExtraTool extends ControlRoomTool {
+    /**
+     * What privacy mode does to this tool's panel. The kit cannot see what
+     * the panel shows, so the default is the safe one.
+     *
+     * - `'withhold'` (default): while privacy mode is on, the panel and its
+     *   `header` are replaced by the privacy notice, titled with `label` and
+     *   offering "Turn off privacy mode". The host's panel is unmounted until
+     *   privacy is turned off. The strip button and `badgeCount` stay.
+     * - `'host'`: the panel stays mounted and the host masks it, reading the
+     *   mode from `onPrivacyChange` (a task list sets `linkedLabelMasked`;
+     *   mind free-text titles, which the grid hides under privacy).
+     *   Also the right value for a panel that shows no patient data at all.
+     *   The kit cannot check either claim.
+     */
+    privacy?: 'withhold' | 'host';
+}
+/**
+ * Usage callbacks for the host's analytics. The kit raises no event of
+ * its own and passes identifiers only, never patient data: the host owns
+ * the calls, the property allow-list and any once-per guard.
+ */
+export interface CalendarWorkspaceAnalytics {
+    /** A built-in tool panel opened. Not raised again while it stays open,
+     *  and never for an id no tool carries. Host tools report through
+     *  `onExtraToolOpen` instead. */
+    onToolOpen?: (event: {
+        toolId: CalendarWorkspaceToolId;
+        source: CalendarToolOpenSource;
+        view: CalendarView;
+    }) => void;
+    /** An appointment's preview opened. Raised on EVERY opening: the
+     *  once-per-appointment guard is the host's. */
+    onAppointmentPreviewOpen?: (event: {
+        eventId: string;
+        view: CalendarView;
+        privacy: boolean;
+    }) => void;
+    /** An appointment's details docked for a new selection. Not raised when
+     *  details come back after an edit. */
+    onAppointmentDetailsOpen?: (event: {
+        eventId: string;
+        source: CalendarDetailsOpenSource;
+        view: CalendarView;
+    }) => void;
+    /** A rail preference was saved on this device. `toolId` may be a host
+     *  tool's id. `resize` is raised only with `persistPanelWidthKey`, since
+     *  without it nothing is saved. */
+    onToolPreferencesChange?: (event: {
+        action: ControlRoomFavoriteChange['action'] | 'resize';
+        toolId: string;
+    }) => void;
+    /**
+     * A host tool's panel opened (`extraTools`). Not raised again while it
+     * stays open. `rail` is a pick on the strip; `system` is any other open
+     * (the host's own `useControlRoomActions().openTool`, an agent).
+     */
+    onExtraToolOpen?: (event: {
+        toolId: string;
+        source: Extract<CalendarToolOpenSource, 'rail' | 'system'>;
+        view: CalendarView;
+    }) => void;
+}
 export interface CalendarWorkspaceProps {
     /** Optional canonical read for every existing-appointment editor route.
      * The form waits for this response; failures/refusals expose no editable
@@ -26,7 +142,9 @@ export interface CalendarWorkspaceProps {
     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. */
+     * re-reads the details; without it details stays the editor form. Keep
+     * it stable: passing a new function re-reads the open details panel,
+     * which is how a host shows a change made outside the panel. */
     loadAppointmentDetails?: CalendarAppointmentDetailsLoader;
     /** The domain state and its handlers — the host implements them. */
     journey: CalendarJourney;
@@ -131,6 +249,47 @@ export interface CalendarWorkspaceProps {
      *  it cannot show never marks the cog. */
     backlogFilters?: Readonly<Record<BacklogGap, boolean>>;
     onBacklogFiltersChange?: (filters: Readonly<Record<BacklogGap, boolean>>) => void;
+    /** Device key the rail saves pinned tools and their order under. Omit
+     *  it and the rail keeps its generic default, `ui.controlRoom.favorites`. */
+    persistFavoritesKey?: string;
+    /** Device key the rail saves the panel width under. Omit it and width
+     *  is not saved, as before. On-device only; nothing reaches a server. */
+    persistPanelWidthKey?: string;
+    /** Usage callbacks for the host's analytics. Omit it and nothing is
+     *  reported. */
+    analytics?: CalendarWorkspaceAnalytics;
+    /**
+     * Host tools, appended to the rail after the built-in ones, in this
+     * order. A tool is offered by passing it and withheld by leaving it out:
+     * `availableTools` narrows the built-in tools only.
+     *
+     * Ids: every `WORKSPACE_TOOL` id is reserved, even for a tool
+     * `availableTools` withholds, and a tool using one is left off the rail.
+     * A repeated id keeps its first tool. Nothing throws. The kit's own
+     * Storybook and tests warn; the published build drops the tool silently.
+     *
+     * The panel renders inside the workspace, so the host's own providers
+     * reach it. It unmounts when another tool opens, so keep state that must
+     * survive in the host. Render a kit `PanelHeader` first and the rail puts
+     * its favourite and close controls in it. Opening one reports through
+     * `analytics.onExtraToolOpen`. The workspace passes no permission to host
+     * tools. Only the strip, an agent and code inside an open panel
+     * (`useControlRoomActions`) open a tool: code outside the workspace
+     * cannot, since the workspace owns its rail provider. If the host stops
+     * passing the open tool, the rail docks the Appointments panel. Memoise
+     * the array: a new one re-registers the rail.
+     */
+    extraTools?: readonly CalendarWorkspaceExtraTool[];
+    /**
+     * Raised when privacy mode turns on or off, from the toolbar toggle or a
+     * withheld panel's "Turn off privacy mode". Observe-only: the workspace
+     * owns the flag, it starts off on every mount (not reported) and is
+     * never persisted. Unmounting with privacy on reports `false`, so the
+     * host's copy never outlives the workspace. Raised in the same handler,
+     * so a host that sets state here renders its masked tool in the same
+     * commit as the masked grid.
+     */
+    onPrivacyChange?: (privacy: boolean) => void;
 }
 /**
  * The cog's settings as the workspace opens with them: the remembered

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

@@ -35,6 +35,22 @@ export declare const ALL_WORKSPACE_TOOLS: readonly CalendarWorkspaceToolId[];
  * kit it mounts must not crash the agenda.
  */
 export declare function resolveAvailableTools(requested: readonly string[]): ReadonlySet<CalendarWorkspaceToolId>;
+/** Whether `id` is one of the built-in rail tools. */
+export declare function isWorkspaceToolId(id: string): id is CalendarWorkspaceToolId;
+/** Why a host tool was left off the rail. */
+export type ExtraToolRejection = 'reserved' | 'duplicate' | 'empty';
+/** The host tools the rail can carry, in the host's order. Built-in ids are
+ *  reserved even when withheld, a repeated id keeps its first tool, an empty
+ *  id is dropped, and nothing throws: a host mistake must not sink the page. */
+export declare function resolveExtraTools<T extends {
+    readonly id: string;
+}>(requested: readonly T[]): {
+    tools: T[];
+    rejected: {
+        id: string;
+        reason: ExtraToolRejection;
+    }[];
+};
 /** The platform's four ranges; "Working week" became the Show-weekends
  *  item, so it is no longer a view of its own. */
 export type WorkspaceViewId = 'day' | 'threeDays' | 'week' | 'month';
@@ -207,18 +223,7 @@ export declare function signChannelStates(ref: PatientRef): {
  *  email, else nothing. "Can take one" is `ready` alone — a channel we
  *  know nothing about is not a channel to send on by default. */
 export declare function defaultSignMode(ref: PatientRef): RequiredDocsSignMode;
-/** The patient's address as one line — the map link's search text, and
- *  the link's own label. Empty when the host supplied no address at all,
- *  which is the caller's signal to leave the map row out rather than
- *  offer a search for nothing. */
-export declare function patientAddressLine(patient: CalendarPatient): string;
-/** The map link's own LABEL — street and city, the pair the popover has
- *  always printed. The postcode belongs in the search query, not in the
- *  visible text, so widening `patientAddressLine` for the URL must not
- *  drag the label along with it. */
-export declare function patientAddressLabel(patient: CalendarPatient): string;
-/** Google Maps search for the patient's address — the popover's map link. */
-export declare function patientMapsUrl(patient: CalendarPatient): string;
+export { patientAddressLabel, patientAddressLine, patientMapsUrl, } from '../../components/_shared/appointment-format';
 /** A CREATE mode armed by a deep link (`createParameters`) or the
  *  Backlog's Schedule: the next empty-slot click opens the editor with
  *  this context already filled in (platform `_switchMode('create')`). */

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

@@ -12,7 +12,7 @@
  */
 import type { CalendarEventStatus } from '../../components/calendar';
 import type { Dispatch, SetStateAction } from 'react';
-import type { NotesPanelNote, NotesPanelProps, NotesPanelSubmission, AiConsentGate } from '../../components/notes-panel';
+import type { NotesPanelNote, NotesPanelProps, NotesPanelSubmission, NotesPanelWriteFailure, AiConsentGate } from '../../components/notes-panel';
 import type { PatientNotesSeam } from './calendar.sheets';
 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';
@@ -171,14 +171,50 @@ export interface CalendarJourney {
      * stored note — its id, its timestamp and its AUTHOR, who is the
      * signed-in operator the host knows and the kit does not. The panel
      * hands over only what was typed, so no name the kit invented can
-     * ever be attributed to a clinical note.
+     * ever be attributed to a clinical note. Reject with a translated
+     * Error: the draft stays in the composer with the message while the
+     * Notes tool is open, and `handleNoteWriteError` hears a refusal that
+     * lands after the reader left it.
      */
     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. */
+     *  rejected write keeps the draft in the composer with its message, as
+     *  `handleAddNote` does. */
     handleEditNote: (patientId: string, noteId: string, content: string) => void | Promise<void>;
+    /**
+     * Delete a note. Called on the click that confirms it. Resolve once the
+     * delete has landed. A rejection brings the row back and the notes
+     * panel shows the error's message, so reject with a translated Error
+     * and do not also toast it.
+     *
+     * A clinical note is taken as kept for the record: its row waits in
+     * place, paused, until `notesByPatient` marks it `deleted`. Any other
+     * note fades and stays hidden until `notesByPatient` drops it. Set
+     * `keptOnDelete` on a note to say otherwise. The panel holds this only
+     * while the Notes tool stays open for that patient: reopened, it shows
+     * the note as `notesByPatient` does, with a live delete. So return the
+     * same promise for a second delete of a note already being deleted.
+     */
     handleDeleteNote: (patientId: string, noteId: string) => void | Promise<void>;
-    handleToggleNotePin: (patientId: string, noteId: string) => void | Promise<void>;
+    /**
+     * Pin or unpin a note. `next` is the value the note moves to, so set it
+     * rather than flipping what you hold. A returned promise holds the new
+     * value until the notes agree; a rejection rolls it back and the notes
+     * panel shows the message. Do not also toast it.
+     */
+    handleToggleNotePin: (patientId: string, noteId: string, next: boolean) => void | Promise<void>;
+    /** As `handleToggleNotePin`, for the flag. Omit it and the flag control
+     *  is not offered. */
+    handleToggleNoteFlag?: (patientId: string, noteId: string, next: boolean) => void | Promise<void>;
+    /**
+     * Hears every refused note write: a save, a delete, a pin or a flag.
+     * `failure.shown` says whether the notes panel told the reader. Toast
+     * only the ones with `shown: false`, for example a refusal that arrives
+     * after the reader switched tool or patient; a save among them has lost
+     * its draft. Wire it in the same change that stops you toasting every
+     * refusal yourself: without it, those late refusals reach no one.
+     */
+    handleNoteWriteError?: (patientId: string, failure: NotesPanelWriteFailure) => void;
     /** Read a patient's notes: the latest few, or every note. */
     handleLoadNotes?: (patientId: string, scope: 'preview' | 'all') => void;
     /**