@alfadocs/ui-kit 1.43.0 → 1.44.0

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

@@ -344,28 +344,38 @@ unresolvedPatientLabel: string,
  *  fetching (`detailsPending`). Such a row carries no patient id and
  *  no title, so without it the feed would print a nameless line. */
 pendingDetailsLabel?: string): AppointmentItem;
-/** How far back the platform's booking query looks, on `createdAt`. */
-export declare const ONLINE_BOOKINGS_WINDOW_DAYS = 30;
 /**
- * Bookings still to check: created online (or through the API) within
- * the last 30 days, not cancelled, and still missing a patient OR an
- * operator. Mirrors the repository query behind the platform's alert
- * strip; Increment 1 renders the same count on a toolbar button.
+ * True when a row still needs completing before it is a real, workable
+ * appointment: no patient record, no operator, or — only where the
+ * practice actually has chairs — no chair. Tasks never qualify (the
+ * caller already drops them from `rows`, but a defensive check costs
+ * nothing). Origin (online vs. desk-created) is irrelevant: a gap is a
+ * gap regardless of how the appointment was created.
+ */
+export declare function appointmentNeedsCompletion(row: CalendarRow, data: CalendarData): boolean;
+/**
+ * The backlog queue: every row in `rows` that still needs a patient, an
+ * operator or a chair. Mirrors the platform's alert-strip query in
+ * spirit, but is no longer scoped to online bookings or to a 30-day
+ * window — the caller already hands in only the rows in the loaded
+ * range, and a desk-created gap is exactly as real as an online one.
  */
 export declare function onlineBookingsToCheck(rows: readonly CalendarRow[], data: CalendarData): CalendarRow[];
 /**
- * One row of the platform's "Prenotazioni online" page, which Increment 1
- * hosts in the rail instead of sending the user to a separate page.
- * Columns mirror it: when it was booked, what was asked for, whether it
- * was paid online, and what is still missing before it is a real
- * appointment.
+ * One row of the backlog queue (formerly the platform's "Prenotazioni
+ * online" page, which Increment 1 hosts in the rail instead of sending
+ * the user to a separate page). Columns mirror it: when it was booked
+ * (a desk-created slot carries no `bookedAt` and groups under its own
+ * appointment date instead), what was asked for, whether it was paid
+ * online, and what is still missing before it is a real appointment.
  */
 export interface BookingRowView {
     row: CalendarRow;
     eventId: string;
     /** The appointment's own start. */
     start: Date;
-    /** Platform `createdAt` — "del <date>" under the appointment date. */
+    /** Platform `createdAt` — "del <date>" under the appointment date.
+     *  Null for a desk-created slot, which has no booking record. */
     bookedAt: Date | null;
     /** The booking reason, or the platform's "Non specificato". */
     reason: string | null;
@@ -374,10 +384,27 @@ export interface BookingRowView {
     paidOnline: number | null;
     needsPatient: boolean;
     needsOperator: boolean;
+    /** True only where the practice has chairs at all — see
+     *  `appointmentNeedsCompletion`. */
+    needsChair: boolean;
+    /** Badge fact, not a filter: origin no longer decides membership, but
+     *  the card still says where the appointment came from. */
+    bookedOnline: boolean;
     /** Booked after the user last opened the page — the "(Nuovo)" marker. */
     isNew: boolean;
 }
 export declare function bookingRowView(row: CalendarRow, data: CalendarData, lastSeenMs?: number | null, createdAtIso?: string): BookingRowView;
+/** The three completion gaps a backlog card can show, in filter order.
+ *  Chair is only ever offered when the practice has chair resources. */
+export type BacklogGap = 'patient' | 'operator' | 'chair';
+/** All three switches on by default — the uncontrolled starting point
+ *  for a host that does not persist the filter state itself. */
+export declare const DEFAULT_BACKLOG_FILTERS: Readonly<Record<BacklogGap, boolean>>;
+/** Applies the header's three switches to an already-built view list. A
+ *  view is kept when it carries at least one gap left switched on — an
+ *  appointment missing only a patient still shows with "Senza operatore"
+ *  and "Senza poltrona" off, since it still needs a patient. */
+export declare function filterBacklogViews(views: readonly BookingRowView[], filters: Readonly<Record<BacklogGap, boolean>>): BookingRowView[];
 /** The nine advanced inputs, all optional. Empty = the input is unset;
  *  `operatorId` also accepts `NONE`, the platform's "no operator". */
 export interface WaitingListFilters {

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

@@ -95,6 +95,15 @@ export interface CalendarData {
      *  through `carePlanById` / `openCarePlansForPatient`. */
     carePlans?: readonly CalendarCarePlan[];
     patients: readonly CalendarPatient[];
+    /** Companies a task may be "about" (platform `doctorCompany`). Omit it
+     *  and the task editor's "Riguarda" choice offers only Nobody / Patient
+     *  — a free-text company name is not an id and the platform would
+     *  reject or mis-link it, so the Company segment is withheld rather
+     *  than rendered over nothing to type an id into. */
+    companies?: ReadonlyArray<{
+        id: string;
+        name: 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

@@ -16,7 +16,7 @@ import type { NotesPanelNote, NotesPanelProps, NotesPanelSubmission, AiConsentGa
 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';
-import type { CalendarHistoryEntry, CalendarSignChannel, CalendarWaitingEntry } from './calendar.types';
+import type { CalendarHistoryEntry, CalendarSignChannel, CalendarTask, CalendarWaitingEntry, TaskDraft } from './calendar.types';
 /** The host's notes read for one patient (N-C3); `writable` follows the
  *  notes, not the appointment-edit right. */
 export type PatientNotesLoad = {
@@ -134,6 +134,38 @@ export interface CalendarJourney {
      * user-facing Error message to keep the editor open with its draft.
      * `extras` arrive untouched unless the kit expands a demo series row. */
     handleCreateAppointment: (draft: EditorDraft, extras?: EditorDraftExtras) => void | Promise<void>;
+    /**
+     * Task seams — mirroring the platform's DoctorReminder routes
+     * (`ic_dcp_task_create` / `ic_dcp_task_edit` / a `done` toggle / delete).
+     * Every seam here is OPTIONAL and each is independent: absent, the
+     * corresponding action is withheld from the task editor (kit convention
+     * — withheld, not disabled). A host with no task backend at all simply
+     * omits every one of them and the "New task" toolbar member opens a
+     * form nothing can save.
+     */
+    /**
+     * ONE promise contract across every task seam: reject with a
+     * user-facing Error to keep the editor open with its draft (and, for
+     * delete/done, to roll the confirm dialog / the Switch back rather than
+     * leave the form locked on a write that never landed); resolve and the
+     * editor treats the write as accepted. `handleCreateTask` alone must
+     * resolve WITH the saved record — the host assigns the new id, and
+     * nothing else can tell the editor what it is. The others resolve with
+     * nothing: an update or a delete names its subject by the id already in
+     * hand, so there is nothing new to report back.
+     */
+    handleCreateTask?: (draft: TaskDraft) => Promise<CalendarTask>;
+    /** Full re-send, not a patch — mirrors `handleCreateAppointment`. */
+    handleUpdateTask?: (id: string, draft: TaskDraft) => Promise<void>;
+    handleDeleteTask?: (id: string) => Promise<void>;
+    /** The task editor's Done switch — a dedicated seam rather than routing
+     *  through `handleUpdateTask` so a host whose `done` toggle is a
+     *  separate lightweight endpoint (the platform's is) can wire it
+     *  directly instead of resending the whole record. */
+    handleSetTaskDone?: (id: string, done: boolean) => Promise<void>;
+    /** Loads one task for the editor's edit mode — the same hydration
+     *  seam shape as `loadAppointmentEditor` (`CalendarEditorHydration`). */
+    loadTask?: (id: string) => Promise<CalendarTask>;
     /**
      * Commit a new note on the patient's record. The HOST builds the
      * stored note — its id, its timestamp and its AUTHOR, who is the
@@ -172,12 +204,12 @@ export interface CalendarJourney {
     /**
      * The notes composer's template-variable, Help-me-write and image-upload
      * seams for one patient, read as the details panel opens them — one hook
-     * instead of six props, mirroring `noteAiConsentFor`. Omit any key (or the
+     * instead of a prop each, mirroring `noteAiConsentFor`. Omit any key (or the
      * whole hook) and that affordance is not offered: the kit ships no
      * variables, no bring-your-own Help-me-write surface and no image upload
      * of its own. Typically backed by the host's own `useHelpMeWriteTemplates`
      * call, built once per patient and passed straight through.
      */
-    noteComposerExtrasFor?: (patientId: string) => Partial<Pick<PatientNotesSeam, 'variables' | 'validateVariable' | 'onVariableValidityChange' | 'renderHelpMeWrite' | 'onUploadImage' | 'onAiCreditsExhausted' | 'composerBefore' | 'composerAfter'>> | undefined;
+    noteComposerExtrasFor?: (patientId: string) => Partial<Pick<PatientNotesSeam, 'variables' | 'validateVariable' | 'onVariableValidityChange' | 'renderHelpMeWrite' | 'aiTemplates' | 'onAiApplied' | 'onUploadImage' | 'onAiCreditsExhausted' | 'composerBefore' | 'composerAfter'>> | undefined;
 }
 //# sourceMappingURL=calendar.journey.d.ts.map

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

@@ -149,7 +149,7 @@ export interface CalendarEditorCapabilities {
     editStatus?: boolean;
 }
 /** The editor field an arrival lands focus on. */
-export type EditorInitialFocus = 'patient' | 'operator';
+export type EditorInitialFocus = 'patient' | 'operator' | 'chair';
 export interface EditorPrefill {
     /** Set = the editor EDITS this existing event; unset = create. */
     editEventId?: string;
@@ -189,6 +189,12 @@ export interface EditorPrefill {
      *  assign intent). A hint, never saved: an absent or disabled field, or
      *  no value, moves no focus. */
     initialFocus?: EditorInitialFocus;
+    /** A pure ROUTING flag, not a presentational one: this kit has no
+     *  task-editor panel of its own, so nothing currently sets it and the
+     *  appointment editor does not read it. Reserved for the task-editor
+     *  PR (stacked on the calendar toolbar work) to route a future
+     *  "Nuova attività" hand-off to its own panel instead of this one. */
+    isTask?: boolean;
 }
 /** Platform's six `recurrence_frequency` values, in its dropdown order. */
 export type RecurrenceFrequency = 'daily' | 'weekly' | 'monthly' | 'quarterly' | 'semiannual' | 'yearly';
@@ -745,6 +751,22 @@ export interface CalendarFreeBand extends AvailabilityRange {
 }
 /** Union free time per local day while retaining the original booking choices. */
 export declare function buildFreeBands(slots: readonly CalendarFreeSlot[]): CalendarFreeBand[];
+export interface AvailabilitySlotCell extends AvailabilityRange {
+    /** Distinct chair x operator combinations sharing this exact
+     *  start + duration (+ resource column, on a resource axis). */
+    optionCount: number;
+}
+/**
+ * One cell per DISTINCT start + duration, not a merged band: the grid
+ * projection ("Show in calendar") highlights individual bookable slots
+ * rather than one filled range spanning everything free. On `'none'` the
+ * key is the slot's own start + duration, deduped across every chair x
+ * operator pair; on a resource axis the key also carries the resource, so
+ * two touching slots in the same column stay two cells, never merged into
+ * one (unlike `mergeAvailabilityRanges`). `buildFreeBands` is untouched —
+ * the finder's own list still unions by day, this is grid painting only.
+ */
+export declare function buildFreeSlotCells(slots: readonly CalendarFreeSlot[], axisKind: 'none' | 'chair' | 'operator'): AvailabilitySlotCell[];
 /**
  * The in-memory free-slot search over the loaded rows: closed dates and
  * holidays yield nothing, an operator away that day drops out of it, an

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

@@ -29,7 +29,7 @@ import { type NotesPanelNote, type NotesPanelProps, type NotesPanelSubmission, t
 import { type ColorAssociation, type CalendarCarePlan, type CalendarAnamnesisAnswer, type CalendarOperatorGroup, type CalendarPatient, type CalendarWaitingEntry, type CalendarHistoryEntry, type CalendarSignChannel, type PatientRef } from './calendar.types';
 import { type CalendarData } from './calendar.data';
 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';
+import { type BacklogGap, type EditorDraftExtras, type DeleteOptions, type WorkspaceDisplaySettings } from './calendar-workspace.model';
 import { type BookingCompleteIntent } from './calendar-bookings-panel';
 /** The operators a NEW booking may take — the practice's ACTIVE cast, as
  *  on the platform. A disabled operator reaches a list only through
@@ -92,6 +92,10 @@ export interface PatientNotesSeam {
     /** Bring your own Help-me-write surface (e.g. practice templates). See
      *  `RichTextEditor`. */
     renderHelpMeWrite?: NotesPanelProps['renderHelpMeWrite'];
+    /** Practice templates in the composer's AI pill. See `RichTextEditor`. */
+    aiTemplates?: NotesPanelProps['aiTemplates'];
+    /** After a pill action rewrote the draft. See `RichTextEditor`. */
+    onAiApplied?: NotesPanelProps['onAiApplied'];
     /** Upload an image yourself and resolve its URL. See `RichTextEditor`. */
     onUploadImage?: NotesPanelProps['onUploadImage'];
     /** An AI call ran out of credits. See `RichTextEditor`. */
@@ -385,7 +389,7 @@ export declare function BacklogPanel({ items, locale, seed, signRequests, onProc
      *  mode (create / move banner) instead of opening the editor at once. */
     onPlaceWaiting?: (entry: CalendarWaitingEntry) => void;
 }): import("react/jsx-runtime").JSX.Element;
-export declare function BookingsPanel({ bookings, locale, privacy, status, lastSeenIso, createdAtById, currentBookingId, currentBookingKey, onRetry, onShowInCalendar, onComplete, }: {
+export declare function BookingsPanel({ bookings, locale, privacy, status, lastSeenIso, createdAtById, currentBookingId, currentBookingKey, onRetry, onShowInCalendar, onComplete, resourceKind, filters, onFiltersChange, }: {
     bookings: readonly CalendarRow[];
     locale?: string;
     /** Masks the patient names, in step with the grid. */
@@ -405,6 +409,16 @@ export declare function BookingsPanel({ bookings, locale, privacy, status, lastS
     /** Opens the editor to complete it (platform "Completa appuntamento").
      *  `intent` says which assign segment was pressed; the pencil sends none. */
     onComplete?: (row: CalendarRow, intent?: BookingCompleteIntent) => void;
+    /** The grid's column axis — chair-columns hide a chairless row, so the
+     *  panel says so once when that is the current view. */
+    resourceKind?: WorkspaceDisplaySettings['resourceKind'];
+    /** The header's three switches. `bookings` already arrives filtered by
+     *  the host (`CalendarWorkspace` applies `filterBacklogViews` before
+     *  this panel ever sees the rows); these two only drive the controls
+     *  themselves and are optional so a host bypassing the workspace still
+     *  gets an unfiltered list rather than a crash. */
+    filters?: Readonly<Record<BacklogGap, boolean>>;
+    onFiltersChange?: (filters: Readonly<Record<BacklogGap, boolean>>) => void;
 }): import("react/jsx-runtime").JSX.Element;
 /**
  * The platform's waiting-list AddModal as a rail sub-view — same field
@@ -428,12 +442,16 @@ export declare function WaitingListEntryForm({ entry, onSave, onCancel, chrome,
  * The same entry form as a `PanelSubview`: it slides over the queue it was
  * opened from, pins Cancel and Save, and hands focus back to the opener.
  */
-export declare function WaitingListEntrySubview({ open, entry, onSave, onCancel, readOnly, }: {
+export declare function WaitingListEntrySubview({ open, entry, onSave, onCancel, onRemove, readOnly, }: {
     open: boolean;
     /** Set = edit this entry; unset = add a new one. */
     entry?: CalendarWaitingEntry;
     onSave: (draft: WaitingEntryDraft) => void;
     onCancel: () => void;
+    /** Edit mode only: the panel's EXISTING remove seam (the card's ⋮ menu
+     *  `onRemove`) — reused here rather than a second one. Unset or no
+     *  `entry` (add mode) and the footer's leading slot is not rendered. */
+    onRemove?: (entry: CalendarWaitingEntry) => void;
     readOnly?: boolean;
 }): import("react/jsx-runtime").JSX.Element;
 /**

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

@@ -2,7 +2,7 @@ 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, 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, }: {
     rows: CalendarRow[];
     setRows: React.Dispatch<React.SetStateAction<CalendarRow[]>>;
     onFocus: (focus: RailFocus) => void;
@@ -43,6 +43,11 @@ export declare function CalendarSurface({ rows, setRows, onFocus, locale, onComp
     saveNotice?: SaveNotice | null;
     /** New appointment — seeds a clean editor (the host docks the panel). */
     onComposeNew: () => void;
+    /** New task — the create group's second member. Omit it (the host has
+     *  no `handleCreateTask`) and the button is withheld entirely, leaving
+     *  a single "New appointment" button; this surface does not decide
+     *  what the click opens, only whether to offer it. */
+    onComposeTask?: () => void;
     /** The split button's main segment — the waiting-list panel. */
     onOpenWaitingList: () => void;
     /** The split button's plus segment — the waiting-list entry form. */

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

@@ -253,7 +253,9 @@ export interface CalendarAppointmentMeta {
     patientId: string;
     /** Absent = nobody assigned yet — a Backlog "No operator" item. */
     operatorId?: string;
-    chairId: string;
+    /** Absent = a desk-created slot with no chair yet (chairs are optional
+     *  on the platform) — the calendar backlog's "Senza poltrona" gap. */
+    chairId?: string;
     /** Derived care label — `careLabel(cares)`, tasks keep the task title.
      *  Also the event's always-on `suffix`. */
     care: string;
@@ -320,6 +322,35 @@ export interface CalendarBookingContact {
     /** When the booking was made (platform `createdAt`). */
     bookedAtIso: string;
 }
+/**
+ * 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.
+ */
+export interface CalendarTask {
+    id: string;
+    /** Local wall-clock instant (date + time), as an ISO string. */
+    dateIso: string;
+    /** The task text — the only required field. */
+    note: string;
+    /** Absent = nobody assigned (platform `practiceUser` optional target). */
+    operatorId?: string;
+    /** Mutually exclusive with `companyId`. */
+    patientId?: string;
+    /** Mutually exclusive with `patientId` (platform `doctorCompany`). */
+    companyId?: string;
+    done: boolean;
+}
+/** The same shape without an identity — what the editor hands the create
+ *  seam, and what an edit save re-sends in full (no partial patch).
+ *  `done` is optional here (defaults to `false`) so a caller building a
+ *  brand-new task never has to state the obvious; `CalendarTask.done` on
+ *  a saved record stays required — a saved task always has a value. */
+export type TaskDraft = Omit<CalendarTask, 'id' | 'done'> & {
+    done?: boolean;
+};
 /** One contiguous working range, minutes from local midnight. */
 export interface CalendarDayHours {
     startMin: number;

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-DhXqqu-D.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-DBYAtdyd.js";
 export {
   s as CALENDAR_PREFERENCE_KEYS,
   r as CalendarDataProvider,

package/dist/patterns/help-me-write-templates/help-me-write-templates.d.ts

@@ -1,20 +1,22 @@
 /**
- * Help me write templates (HTP-6383) — practice-shared AI templates inside the
- * RichTextEditor's "Help me write".
+ * Help me write templates (HTP-6383) — practice-shared AI templates in the
+ * RichTextEditor.
  *
  * Runtime pattern: real consuming apps mount this in production (surfaced via
  * `src/patterns/index.ts` and the `./patterns/help-me-write-templates`
- * subpath). It plugs into the editor through `renderHelpMeWrite`, so the kit
- * editor keeps its own AI pill, the patient AI-consent gate and the
- * resume-after-grant; this pattern supplies the bar that opens from it.
+ * subpath). Templates are an AI action of the editor itself, next to
+ * spelling and auto-format: a Templates segment in the AI pill and in the
+ * selection bubble (`aiTemplates`). Picking one rewrites the selection, else
+ * the whole note, then this pattern offers Undo. The editor keeps the
+ * patient AI-consent gate and resume-after-grant for all of it.
  *
  * Parts, usable on their own or wired together by `useHelpMeWriteTemplates`:
- *  - `HelpMeWriteTemplatesBar` — the docked bar: free prompt with an optional
- *    mic, a Templates menu, a side-by-side compare, Replace / Insert below.
+ *  - `HelpMeWriteTemplatesBar` — the Help-me-write bar (`renderHelpMeWrite`):
+ *    a free prompt with an optional mic, the draft and Insert.
  *  - `AiTemplateManager` — the dialog to list, create, edit and delete
  *    templates and pick the default.
  *  - `AiCreditsExhaustedNotice` — the out-of-credits state the bar shows when
- *    `onGenerate` rejects with `AiCreditsExhaustedError`.
+ *    an AI call rejects with `AiCreditsExhaustedError`, from the bar or the pill.
  *  - `HelpMeWriteUndoNotice` — the success notice with Undo after a template
  *    rewrote the note.
  *
@@ -22,7 +24,7 @@
  * never talks to a backend.
  */
 import { type ReactNode } from 'react';
-import type { HelpMeWriteRenderContext } from '../../components/rich-text-editor';
+import type { HelpMeWriteRenderContext, RichTextEditorAiApplied, RichTextEditorAiTemplates } from '../../components/rich-text-editor';
 /** A practice-shared AI template. */
 export interface AiTemplate {
     id: string;
@@ -32,8 +34,11 @@ export interface AiTemplate {
     description?: string;
     /** The instructions sent to the AI, up to 4000 characters. */
     prompt: string;
-    /** At most one per practice; listed first with a Default badge. */
-    isDefault: boolean;
+    /**
+     * @deprecated The list order is the menu order: the first template is the
+     * one most people use. Ignored; reorder with `onReorderTemplates`.
+     */
+    isDefault?: boolean;
 }
 /** What the manager hands `onSaveTemplate`: `id` is absent for a new one. */
 export type AiTemplateDraft = Omit<AiTemplate, 'id'> & {
@@ -44,8 +49,14 @@ export interface HelpMeWriteRequest {
     template?: AiTemplate;
     /** The free prompt, or extra instructions for a template. May be ''. */
     prompt: string;
-    /** Plain text the template rewrites: the selection, else the whole note. */
+    /**
+     * The context, as plain text. For a template, the text it rewrites. For
+     * the free prompt, what the draft is about. From the AI pill it is the
+     * whole note; from the selection bubble, the selected text.
+     */
     sourceText: string;
+    /** Where `sourceText` came from. */
+    scope?: 'document' | 'selection';
     signal: AbortSignal;
 }
 /**
@@ -90,15 +101,16 @@ export declare function AiCreditsExhaustedNotice({ credits, onBack, }: AiCredits
 export interface HelpMeWriteTemplatesBarProps {
     /** What `RichTextEditor`'s `renderHelpMeWrite` hands its host. */
     context: HelpMeWriteRenderContext;
-    templates: AiTemplate[];
-    /** The AI call. Reject with `AiCreditsExhaustedError` when out of credits. */
-    onGenerate: (request: HelpMeWriteRequest) => Promise<string>;
     /**
-     * Opens the template manager. Omit to hide "Manage templates" and
-     * "Create your first template" (e.g. for readers who may not manage).
+     * @deprecated Templates run from the editor's AI pill (`aiTemplates`),
+     * not from this bar. Ignored.
      */
+    templates?: AiTemplate[];
+    /** The AI call. Reject with `AiCreditsExhaustedError` when out of credits. */
+    onGenerate: (request: HelpMeWriteRequest) => Promise<string>;
+    /** @deprecated The manager opens from the pill's Templates menu. Ignored. */
     onManageTemplates?: (mode: 'list' | 'create') => void;
-    /** After a draft lands; the hook uses it for Undo. */
+    /** After a draft lands. */
     onApplied?: (applied: HelpMeWriteApplied) => void;
     /** Shown in the out-of-credits notice. */
     credits?: AiCreditsInfo;
@@ -107,8 +119,12 @@ export interface HelpMeWriteTemplatesBarProps {
     /** Ignore Escape (e.g. while the manager dialog above it is open). */
     suspendClose?: boolean;
 }
-/** The Help-me-write bar with templates, docked in the editor's AI slot. */
-export declare function HelpMeWriteTemplatesBar({ context, templates, onGenerate, onManageTemplates, onApplied, credits, enableDictation, suspendClose, }: HelpMeWriteTemplatesBarProps): React.JSX.Element;
+/**
+ * The Help-me-write bar, docked in the editor's AI slot: a free prompt with
+ * an optional mic, then the draft and Insert. It also shows the
+ * out-of-credits notice, including when a pill action ran out.
+ */
+export declare function HelpMeWriteTemplatesBar({ context, onGenerate, onApplied, credits, enableDictation, suspendClose, }: HelpMeWriteTemplatesBarProps): React.JSX.Element;
 export interface AiTemplateManagerProps {
     open: boolean;
     onOpenChange: (open: boolean) => void;
@@ -119,9 +135,14 @@ export interface AiTemplateManagerProps {
     onSaveTemplate: (draft: AiTemplateDraft) => void | Promise<void>;
     /** Omit to hide Delete. */
     onDeleteTemplate?: (id: string) => void | Promise<void>;
+    /**
+     * Persist a new order (every template id, first to last): the order of
+     * the Templates menu. Omit to hide the drag handles.
+     */
+    onReorderTemplates?: (orderedIds: string[]) => void | Promise<void>;
 }
 /** List, create, edit and delete the practice's templates. */
-export declare function AiTemplateManager({ open, onOpenChange, initialMode, templates, onSaveTemplate, onDeleteTemplate, }: AiTemplateManagerProps): React.JSX.Element;
+export declare function AiTemplateManager({ open, onOpenChange, initialMode, templates, onSaveTemplate, onDeleteTemplate, onReorderTemplates, }: AiTemplateManagerProps): React.JSX.Element;
 export interface HelpMeWriteUndoNoticeProps {
     /** The change to offer Undo for; `null` hides the notice. */
     applied: HelpMeWriteApplied | null;
@@ -132,20 +153,29 @@ export interface HelpMeWriteUndoNoticeProps {
 export declare function HelpMeWriteUndoNotice({ applied, onUndo, onDismiss, }: HelpMeWriteUndoNoticeProps): React.JSX.Element | null;
 export interface UseHelpMeWriteTemplatesOptions {
     templates: AiTemplate[];
+    /** The AI call, for both templates (from the pill) and the free prompt. */
     onGenerate: HelpMeWriteTemplatesBarProps['onGenerate'];
     /** Enables the manager (create / edit). Omit for read-only template users. */
     onSaveTemplate?: AiTemplateManagerProps['onSaveTemplate'];
     /** Enables Delete in the manager. */
     onDeleteTemplate?: AiTemplateManagerProps['onDeleteTemplate'];
+    /** Enables drag-and-drop reordering in the manager (the menu order). */
+    onReorderTemplates?: AiTemplateManagerProps['onReorderTemplates'];
     credits?: AiCreditsInfo;
     /** Mic in the bar's prompt when the editor has `onDictate`. Default true. */
     enableDictation?: boolean;
     /** Also told about every applied draft (e.g. for analytics). */
     onApplied?: (applied: HelpMeWriteApplied) => void;
 }
-export interface UseHelpMeWriteTemplatesResult {
-    /** Pass to `RichTextEditor`'s `renderHelpMeWrite`. */
+/** The `RichTextEditor` props the hook drives; spread them on the editor. */
+export interface HelpMeWriteTemplatesEditorProps {
     renderHelpMeWrite: (context: HelpMeWriteRenderContext) => ReactNode;
+    aiTemplates: RichTextEditorAiTemplates;
+    onAiApplied: (applied: RichTextEditorAiApplied) => void;
+}
+export interface UseHelpMeWriteTemplatesResult extends HelpMeWriteTemplatesEditorProps {
+    /** All three editor props at once: `<RichTextEditor {...hmw.editorProps} />`. */
+    editorProps: HelpMeWriteTemplatesEditorProps;
     /** Mount once, anywhere (a portalled dialog); `null` without `onSaveTemplate`. */
     manager: ReactNode;
     /** Place where the Undo notice should show, e.g. above the editor. */
@@ -153,12 +183,14 @@ export interface UseHelpMeWriteTemplatesResult {
     openManager: (mode?: 'list' | 'create') => void;
 }
 /**
- * Wires the bar, the manager and Undo together. Usage:
+ * Wires templates, the Help-me-write bar, the manager and Undo into the
+ * editor. Templates run from the editor's AI pill and selection bubble;
+ * the bar is the free prompt. Usage:
  *
  *   const hmw = useHelpMeWriteTemplates({ templates, onGenerate, onSaveTemplate });
  *   {hmw.undoNotice}
- *   <RichTextEditor renderHelpMeWrite={hmw.renderHelpMeWrite} … />
+ *   <RichTextEditor {...hmw.editorProps} … />
  *   {hmw.manager}
  */
-export declare function useHelpMeWriteTemplates({ templates, onGenerate, onSaveTemplate, onDeleteTemplate, credits, enableDictation, onApplied, }: UseHelpMeWriteTemplatesOptions): UseHelpMeWriteTemplatesResult;
+export declare function useHelpMeWriteTemplates({ templates, onGenerate, onSaveTemplate, onDeleteTemplate, onReorderTemplates, credits, enableDictation, onApplied, }: UseHelpMeWriteTemplatesOptions): UseHelpMeWriteTemplatesResult;
 //# sourceMappingURL=help-me-write-templates.d.ts.map

package/dist/patterns/help-me-write-templates/index.d.ts

@@ -1,3 +1,3 @@
 export { AiCreditsExhaustedError, AiCreditsExhaustedNotice, AiTemplateManager, HelpMeWriteTemplatesBar, HelpMeWriteUndoNotice, useHelpMeWriteTemplates, } from './help-me-write-templates';
-export type { AiCreditsExhaustedNoticeProps, AiCreditsInfo, AiTemplate, AiTemplateDraft, AiTemplateManagerProps, HelpMeWriteApplied, HelpMeWriteApplyMode, HelpMeWriteRequest, HelpMeWriteTemplatesBarProps, HelpMeWriteUndoNoticeProps, UseHelpMeWriteTemplatesOptions, UseHelpMeWriteTemplatesResult, } from './help-me-write-templates';
+export type { AiCreditsExhaustedNoticeProps, AiCreditsInfo, AiTemplate, AiTemplateDraft, AiTemplateManagerProps, HelpMeWriteApplied, HelpMeWriteApplyMode, HelpMeWriteRequest, HelpMeWriteTemplatesBarProps, HelpMeWriteUndoNoticeProps, UseHelpMeWriteTemplatesOptions, UseHelpMeWriteTemplatesResult, HelpMeWriteTemplatesEditorProps, } from './help-me-write-templates';
 //# sourceMappingURL=index.d.ts.map

package/dist/patterns/help-me-write-templates/index.js

@@ -1,4 +1,4 @@
-import { A as s, a as t, b as r, H as i, c as p, u as l } from "../../_chunks/help-me-write-templates-B-m7zgJa.js";
+import { A as s, a as t, b as r, H as i, c as p, u as l } from "../../_chunks/help-me-write-templates-GUeEn3Ff.js";
 export {
   s as AiCreditsExhaustedError,
   t as AiCreditsExhaustedNotice,