@alfadocs/ui-kit 1.46.0 → 1.47.1

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

@@ -1,3 +1,42 @@
+/**
+ * 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. 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
+ * 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 } 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 +57,46 @@ 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';
+/**
+ * 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. */
+    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. `resize` is raised only
+     *  with `persistPanelWidthKey`, since without it nothing is saved. */
+    onToolPreferencesChange?: (event: {
+        action: ControlRoomFavoriteChange['action'] | 'resize';
+        toolId: string;
+    }) => void;
+}
 export interface CalendarWorkspaceProps {
     /** Optional canonical read for every existing-appointment editor route.
      * The form waits for this response; failures/refusals expose no editable
@@ -131,6 +210,15 @@ 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;
 }
 /**
  * The cog's settings as the workspace opens with them: the remembered

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

@@ -113,6 +113,23 @@ export interface CalendarData {
         id: string;
         name: string;
     }>;
+    /** The task types this practice offers, system and practice-defined in
+     *  ONE list. Omit it (or `[]`) and the Type field is withheld, as with
+     *  `companies`. `id` is an opaque token, unique here and never `''`;
+     *  `custom` only groups the select; `label` is the host's own string,
+     *  already translated. See calendar.mdx § Tasks. */
+    taskTypes?: ReadonlyArray<{
+        id: string;
+        label: string;
+        custom?: boolean;
+    }>;
+    /** Practice USER accounts a task can be assigned to (platform
+     *  `practiceUser`) — NOT `operators`, which is the clinician axis. Same
+     *  withheld-not-disabled contract; `'none'` is reserved for Nobody. */
+    taskAssignees?: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
     /** Optional host typeahead. Omit for client filtering of `patients`.
      * The picker debounces nonblank queries, aborts superseded requests and
      * keeps the host's result order, including matches by phone or number.

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

@@ -179,6 +179,8 @@ export interface CalendarJourney {
     handleEditNote: (patientId: string, noteId: string, content: string) => void | Promise<void>;
     handleDeleteNote: (patientId: string, noteId: string) => void | Promise<void>;
     handleToggleNotePin: (patientId: string, noteId: string) => void | Promise<void>;
+    /** Flag or unflag a note. Omit it and the flag control is not offered. */
+    handleToggleNoteFlag?: (patientId: string, noteId: string) => void | Promise<void>;
     /** Read a patient's notes: the latest few, or every note. */
     handleLoadNotes?: (patientId: string, scope: 'preview' | 'all') => void;
     /**

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

@@ -73,6 +73,8 @@ export interface PatientNotesSeam {
     onEditNote: (noteId: string, content: string) => void | Promise<void>;
     onDeleteNote: (noteId: string) => void | Promise<void>;
     onTogglePin: (noteId: string) => void | Promise<void>;
+    /** Flag or unflag a note. Omitted → no flag control. */
+    onToggleFlag?: (noteId: string) => void | Promise<void>;
     /** The practice's own drafting endpoint. Omitted → no AI affordance. */
     onRequestAiDraft?: NotesPanelProps['onRequestAiDraft'];
     /** The host's live transcription. Omitted → no microphone. */

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

@@ -1,8 +1,9 @@
+import { type CalendarView } from '../../components/calendar';
 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';
 import type { CalendarOccurrenceMove } from './calendar.journey';
-export declare function CalendarSurface({ rows, setRows, onFocus, locale, onComposeNew, onComposeTask, onOpenWaitingList, onAddWaitingEntry, onOpenOnlineBookings, onlineBookingsCount, waitingBadgeCount, onVisibleRangeChange, selectedEventId, gotoRequest, onBookSlot, onBookSlotFromFinder, display, setDisplay, onHistory, readOnly, reviewOnlyEventIds, detailsOnEveryClick, placement, onPlacementEnd, createMode, onCreateModeEnd, focusScroll, saveNotice, privacy, onPrivacyChange, availability, availabilityContext, availableTools, schedulerLicenseKey, id, preferences, onMoveOccurrence, }: {
+export declare function CalendarSurface({ rows, setRows, onFocus, locale, onComposeNew, onComposeTask, onOpenWaitingList, onAddWaitingEntry, onOpenOnlineBookings, onlineBookingsCount, waitingBadgeCount, onVisibleRangeChange, selectedEventId, gotoRequest, onBookSlot, onBookSlotFromFinder, display, setDisplay, onHistory, readOnly, reviewOnlyEventIds, detailsOnEveryClick, placement, onPlacementEnd, createMode, onCreateModeEnd, focusScroll, saveNotice, privacy, onPrivacyChange, availability, availabilityContext, availableTools, schedulerLicenseKey, id, preferences, onMoveOccurrence, onViewChange, onPeekOpen, }: {
     rows: CalendarRow[];
     setRows: React.Dispatch<React.SetStateAction<CalendarRow[]>>;
     onFocus: (focus: RailFocus) => void;
@@ -96,5 +97,9 @@ export declare function CalendarSurface({ rows, setRows, onFocus, locale, onComp
     /** The host's series move (S-C8). With it, a recurring parent's move
      *  always confirms, asks the scope and hides the notify boxes. */
     onMoveOccurrence?: (move: CalendarOccurrenceMove) => Promise<void>;
+    /** The grid's view, on mount and on every change. Usage reporting only. */
+    onViewChange?: (view: CalendarView) => void;
+    /** An appointment's preview opened. Usage reporting only. */
+    onPeekOpen?: (eventId: string) => void;
 }): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=calendar.surface.d.ts.map

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

@@ -324,25 +324,39 @@ export interface CalendarBookingContact {
 }
 /**
  * A calendar task (platform `DoctorReminder`) — the model the task editor
- * saves. `note` is the only required field; a task may be about a patient,
- * about a company, or neither, but never both (mutually exclusive, like
- * `CalendarWaitingEntry`'s three connections). No title separate from the
- * note, no priority, no duration — the platform model has none.
+ * saves. A task has at most ONE counterpart: a patient, a company, an
+ * operator, or none. `TaskType::validate()` refuses more than one with
+ * "More than one counterpart is set", so the editor asks for one choice.
+ * `note` is required here though the platform allows an empty one; `date`
+ * is required on both sides. No title separate from the note, no priority,
+ * no duration — the platform model has none.
  */
 export interface CalendarTask {
     id: string;
-    /** Local wall-clock instant (date + time), as an ISO string. */
+    /** An instant as an ISO 8601 string. The editor emits `toISOString()`,
+     *  so UTC with a `Z`; parse it with `new Date()`, never by slicing the
+     *  first 16 characters. A zone-less string on read is taken as local. */
     dateIso: string;
-    /** The task text — the only required field. */
+    /** The task text. Required here, though the platform allows an empty
+     *  one. */
     note: string;
     /** The clinician the task concerns: platform `doctorOperator`, filled
-     *  from `data.operators`. NOT the assignee, which is a practice user
-     *  account the kit does not model. Absent = no operator. */
+     *  from `data.operators`. NOT the assignee (`assigneeId`), and mutually
+     *  exclusive with `patientId` and `companyId`. Absent = no operator. */
     operatorId?: string;
-    /** Mutually exclusive with `companyId`. */
+    /** Mutually exclusive with `companyId` and `operatorId`. */
     patientId?: string;
-    /** Mutually exclusive with `patientId` (platform `doctorCompany`). */
+    /** Mutually exclusive with `patientId` and `operatorId` (platform
+     *  `doctorCompany`). */
     companyId?: string;
+    /** Which kind of task — an OPAQUE token from `CalendarData.taskTypes`,
+     *  round-tripped untouched. The kit never parses it. Optional: a host
+     *  that supplies no `taskTypes` neither shows the field nor sends one. */
+    typeId?: string;
+    /** The practice USER the task is assigned to. Independent of the
+     *  counterpart above: an assigned task may still be about a patient. An
+     *  id from `CalendarData.taskAssignees`; absent = nobody. */
+    assigneeId?: string;
     done: boolean;
 }
 /** The same shape without an identity — what the editor hands the create

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

@@ -1,4 +1,4 @@
-export { CalendarWorkspace, initialWorkspaceDisplay, WORKSPACE_TOOL, type CalendarWorkspaceProps, type CalendarOnlineBookings, type CalendarWorkspaceToolId, } from './calendar-workspace';
+export { CalendarWorkspace, initialWorkspaceDisplay, WORKSPACE_TOOL, type CalendarWorkspaceProps, type CalendarOnlineBookings, type CalendarWorkspaceToolId, type CalendarWorkspaceAnalytics, type CalendarToolOpenSource, type CalendarDetailsOpenSource, } from './calendar-workspace';
 export { CalendarDataProvider, useCalendarData, type CalendarData, type DayLoadState, } from './calendar.data';
 export type { CalendarJourney, CalendarOccurrenceMove, PatientNotesLoad, } from './calendar.journey';
 export type { CalendarAppointmentEditorSnapshot, CalendarAppointmentEditorLoader, CalendarEditorSeries, } from './calendar-editor-hydration';

package/dist/patterns/calendar/index.js

@@ -1,4 +1,4 @@
-import { C as s, a as r, b as E, c as P, D as S, d as o, S as C, V as t, W as d, e as A, i, m as n, r as D, u as W, f as _, g as c } from "../../_chunks/calendar-workspace-BB-BZT7W.js";
+import { C as s, a as r, b as E, c as P, D as S, d as o, S as C, V as t, W as d, e as A, i, m as n, r as D, u as W, f as _, g as c } from "../../_chunks/calendar-workspace-BmscntRR.js";
 export {
   s as CALENDAR_PREFERENCE_KEYS,
   r as CalendarDataProvider,