@alfadocs/ui-kit 1.47.1 → 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

@@ -6,9 +6,11 @@
  * 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. Nothing else — no Inbox,
- * no Alia, no patient tabs, no care plan, no tasks. The panels are the
- * extracted modules from `calendar.sheets.tsx`; `calendar.host.ts`'s
+ * 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.
  *
@@ -36,7 +38,7 @@
  * and care-plan cleanup and the Create-bill confirm.
  */
 import type { CalendarView } from '../../components/calendar';
-import { type ControlRoomFavoriteChange } from '../../components/control-room-rail';
+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';
@@ -64,13 +66,37 @@ export type CalendarToolOpenSource = 'rail' | 'appointment_panel' | 'selection'
 /** 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 tool panel opened. Not raised again while it stays open. */
+    /** 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;
@@ -90,12 +116,23 @@ export interface CalendarWorkspaceAnalytics {
         source: CalendarDetailsOpenSource;
         view: CalendarView;
     }) => void;
-    /** A rail preference was saved on this device. `resize` is raised only
-     *  with `persistPanelWidthKey`, since without it nothing is saved. */
+    /** 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.
@@ -105,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;
@@ -219,6 +258,38 @@ export interface CalendarWorkspaceProps {
     /** 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,16 +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>;
-    /** Flag or unflag a note. Omit it and the flag control is not offered. */
-    handleToggleNoteFlag?: (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;
     /**

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

@@ -9,9 +9,11 @@
  * — the host supplies it, the model never reaches for a module global.
  */
 import type { TFunction } from 'i18next';
-import { ThumbsUp } from 'lucide-react';
 import { type CalendarEvent, type CalendarEventStatus, type CalendarResource } from '../../components/calendar';
 import type { WorkflowStatusTone } from '../../components/workflow-status';
+import { APPOINTMENT_STATE_WORKFLOW } from '../../components/_shared/entity-card';
+import { APPOINTMENT_STATUS_BADGE_VARIANT } from '../../components/appointment-details-panel/appointment-details-panel.identity';
+import type { AppointmentRecurrenceFrequency } from '../../components/appointment-details-panel';
 import type { CalendarData } from './calendar.data';
 import { type CareDescriptionMode, type ColorAssociation, type CalendarBaseEvent, type CalendarBookingContact, type CalendarCareEntry, type CalendarCareLink, type CalendarClosure, type CalendarDayHours, type CalendarHistoryEntry, type CalendarPatient, type CalendarPhoneNumber, type CalendarSignDocument, type CalendarWaitingEntry, type CatalogueState, type PatientRef } from './calendar.types';
 export declare const STATUS_UI_KEY: Record<CalendarEventStatus, string>;
@@ -131,8 +133,7 @@ export declare const DAY_WINDOWS: Record<DisplaySettings['window'], {
     min: string;
     max: string;
 }>;
-export declare function formatTimeRange(locale: string, start: Date | string, end?: Date | string): string;
-export declare function formatDay(locale: string, value: Date | string): string;
+export { DETAIL_STAMP_FORMAT, formatDay, formatTimeRange, parseEventDate, RECURRENCE_LABEL_KEY, sortHistoryNewestFirst, } from '../../components/_shared/appointment-format';
 /** Completed years between a birth date and the practice's fixed "now" —
  *  the platform popover's "(NN anni)" beside the patient's name. Pinned
  *  to `data.nowIso` so the figure never drifts under a test. */
@@ -197,13 +198,11 @@ export interface EditorPrefill {
     isTask?: boolean;
 }
 /** Platform's six `recurrence_frequency` values, in its dropdown order. */
-export type RecurrenceFrequency = 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'semiannual' | 'yearly';
+export type RecurrenceFrequency = AppointmentRecurrenceFrequency;
 /** Repetition cap — platform asserts 2..100 on the entity. */
 export declare const RECURRENCE_MAX_COUNT = 100;
 /** Dropdown order, matching the platform modal's own. */
 export declare const RECURRENCE_FREQUENCIES: readonly RecurrenceFrequency[];
-/** Literal map (not a template) so key extractors see every key. */
-export declare const RECURRENCE_LABEL_KEY: Record<RecurrenceFrequency, string>;
 export interface EditorRecurrence {
     frequency: RecurrenceFrequency;
     /** Count XOR until — the exclusivity `DoctorAppointment` enforces. */
@@ -355,12 +354,8 @@ export declare function deriveCareLinkDefaults(link: CalendarCareLink | undefine
 export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 /** A ledger line before the journey stamps id, time and actor onto it. */
 export type HistoryInput = DistributiveOmit<CalendarHistoryEntry, 'id' | 'atIso' | 'actor'>;
-/** Absolute stamp for booked-at and ledger lines — day and time. */
-export declare const DETAIL_STAMP_FORMAT: Intl.DateTimeFormatOptions;
 /** Live stamps advance from the practice clock, never the real one. */
 export declare function historyStampIso(seq: number, data: CalendarData): string;
-/** Timeline 'newest-first' is a plain column — DOM order must already be. */
-export declare function sortHistoryNewestFirst(entries: readonly CalendarHistoryEntry[]): CalendarHistoryEntry[];
 /** Documents still awaiting a required party (the chip's own rule). */
 export declare function signingSummary(docs: readonly CalendarSignDocument[]): {
     toSign: number;
@@ -399,11 +394,12 @@ export declare function priceListState(data: CalendarData): CatalogueState;
  *  list the practice does not have, and `priceLists[0].id` on an empty
  *  catalogue threw and took the whole calendar down with it. */
 export declare function priceListIdFor(patientId: string | undefined, data: CalendarData): string | undefined;
-export declare const STATUS_CHIP: Record<CalendarEventStatus, {
-    variant: 'success' | 'info' | 'warning' | 'error' | 'accentSoft';
+type StatusChip = {
+    variant: (typeof APPOINTMENT_STATUS_BADGE_VARIANT)[CalendarEventStatus];
     tone: WorkflowStatusTone;
-    Icon: typeof ThumbsUp;
-}>;
+    Icon: (typeof APPOINTMENT_STATE_WORKFLOW)[CalendarEventStatus]['Icon'];
+};
+export declare const STATUS_CHIP: Record<CalendarEventStatus, StatusChip>;
 export type BacklogType = 'booking' | 'waiting' | 'unconfirmed' | 'noOperator' | 'signature';
 /** The filter strip's segments — every type, or all of them grouped. */
 export type BacklogFilter = BacklogType | 'all';
@@ -668,9 +664,6 @@ export interface PrintSheetInput {
     visibleOperatorIds: string[];
     privacy: boolean;
 }
-/** A date-only start (all-day rows) is already a local day; anything
- *  else parses as the wall clock the fixtures and the editor write. */
-export declare function parseEventDate(value: string | Date): Date;
 /** The title privacy mode shows. TOTAL in the masked branch: a host
  *  that supplies an EMPTY `privacyModeTitle` gets the bullets, never a
  *  blank and never a fallback that would leak what we do or do not hold