@dotbase/safe-frame-sync 1.13.2 → 1.15.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type MessageType = "editResource" | "createResource" | "closeBuilder" | "closeDocument" | "setBreadcrumbs" | "goToPatient" | "iframeRouteChange" | "sessionExpired" | "iframeReady" | "createDraft" | "createdDraft" | "draftSaved" | "openDocumentCapture" | "documentLoadError" | "reloadDocument" | "openDoctorsLetterExport";
+export type MessageType = "editResource" | "createResource" | "closeBuilder" | "closeDocument" | "setBreadcrumbs" | "goToPatient" | "iframeRouteChange" | "sessionExpired" | "iframeReady" | "createDraft" | "createdDraft" | "draftSaved" | "openDocumentCapture" | "documentLoadError" | "reloadDocument" | "openDoctorsLetterExport" | "patientLoaded" | "createDraftFailed" | "lockDocument" | "documentLocked" | "unlockDocument" | "draftUpdated" | "leaveEditingRequested" | "leaveEditingDecided";
 export type WorkflowType = "document" | "patient-report";
 export interface BreadcrumbItemType {
     to: string;
@@ -45,19 +45,59 @@ export interface SessionExpiredType {
 export interface IframeReadyType {
     type: "iframeReady";
 }
+/**
+ * The embedded app has a patient open and is able to answer messages about it.
+ *
+ * `iframeReady` only says the shell mounted; the handlers for patient-scoped messages live in the
+ * lazily loaded patient view and do not exist yet at that point, so a message sent in between is
+ * delivered to a window with no listener and lost. This carries the patient id because readiness is
+ * per patient: a patient switch makes the frame un-ready until the next one arrives.
+ */
+export interface PatientLoadedType {
+    type: "patientLoaded";
+    patientId: string;
+}
 export interface CreateDraftType {
     type: "createDraft";
     templateId: string;
     patientId: string;
+    /**
+     * Correlates the reply with this request, so an answer to a superseded or already abandoned
+     * request is not mistaken for the answer to the current one.
+     */
+    requestId: string;
 }
 export interface CreatedDraftType {
     type: "createdDraft";
     documentId: string;
     patientId: string;
+    /** Echoes `CreateDraftType.requestId`. */
+    requestId: string;
+}
+/** Why a `createDraft` request produced no draft, at the granularity the sender can act on. */
+export type CreateDraftFailureReason = 
+/** The template could not be resolved or could not be assembled into a draft. */
+"template-unavailable"
+/** The patient could not be loaded, or is no longer the one the request named. */
+ | "patient-unavailable"
+/** The draft was built but could not be stored locally. */
+ | "save-failed";
+export interface CreateDraftFailedType {
+    type: "createDraftFailed";
+    templateId: string;
+    patientId: string;
+    reason: CreateDraftFailureReason;
+    /** Echoes `CreateDraftType.requestId`. */
+    requestId: string;
 }
 export interface DraftSavedType {
     type: "draftSaved";
 }
+/**
+ * @deprecated Iframe to shell. Sent by dotclinic's former capture button; the
+ * assistant now opens on its own from the document mode. Kept so an older
+ * dotclinic keeps working against a newer shell. Removed in the next major.
+ */
 export interface OpenDocumentCaptureType {
     type: "openDocumentCapture";
     procedureId: string;
@@ -75,7 +115,86 @@ export interface OpenDoctorsLetterExportType {
     procedureId: string;
     documentTemplateId: string;
 }
-export type MesssageDataType = EditResourceType | CreateResourceType | CloseBuilderType | CloseDocumentType | SetBreadcrumbsType | GoToPatientType | IframeRouteChangeType | SessionExpiredType | IframeReadyType | CreateDraftType | CreatedDraftType | DraftSavedType | OpenDocumentCaptureType | DocumentLoadErrorType | ReloadDocumentType | OpenDoctorsLetterExportType;
+/**
+ * Shell to iframe. The assistant is about to read the draft, send it to the
+ * model and write the result back, and every keystroke in between would be
+ * overwritten by that write-back. The iframe blocks input on the document,
+ * shows it as locked, and answers with `documentLocked` once no write of its
+ * own is pending any more; scrolling stays possible.
+ *
+ * Carries the document id because the lock belongs to one document: the user
+ * may have navigated on while the fill was running, and a lock must not land
+ * on the document they are looking at now.
+ */
+export interface LockDocumentType {
+    type: "lockDocument";
+    patientId: string;
+    documentId: string;
+    /** Correlates the `documentLocked` reply with this request. */
+    requestId: string;
+}
+/**
+ * Iframe to shell. The document is locked and the iframe's own pending writes
+ * to the draft have been flushed or dropped, so the draft in IndexedDB is the
+ * one the user sees. The shell reads it only after this arrives: reading
+ * earlier could miss the last keystroke, and the iframe's debounced write would
+ * later overwrite the filled draft. A shell that receives no reply in time
+ * treats the fill as failed rather than running it unlocked.
+ */
+export interface DocumentLockedType {
+    type: "documentLocked";
+    patientId: string;
+    documentId: string;
+    /** Echoes `LockDocumentType.requestId`. */
+    requestId: string;
+}
+/**
+ * Shell to iframe. Releases `lockDocument`. Sent on every exit path of a fill,
+ * success and failure alike, so a failed fill never leaves a dead document.
+ * A `draftUpdated` for the same document also releases the lock.
+ */
+export interface UnlockDocumentType {
+    type: "unlockDocument";
+    patientId: string;
+    documentId: string;
+}
+/**
+ * Shell to iframe. The draft in the shared IndexedDB changed underneath the
+ * open document, so the iframe re-reads and re-renders it. Replaces reloading
+ * the whole frame. Implies `unlockDocument` for the same document.
+ */
+export interface DraftUpdatedType {
+    type: "draftUpdated";
+    patientId: string;
+    documentId: string;
+}
+/**
+ * Iframe to shell. The user wants to leave editing mode for the open document.
+ * The shell may hold unsubmitted assistant input for it and gets to ask first.
+ * The iframe waits for `leaveEditingDecided` with the same request id and
+ * proceeds on its own if none arrives in time, so a shell that does not know
+ * this message cannot trap the user in editing mode.
+ */
+export interface LeaveEditingRequestedType {
+    type: "leaveEditingRequested";
+    patientId: string;
+    documentId: string;
+    /** Correlates the decision with this request. */
+    requestId: string;
+}
+/** What the shell decided for a `leaveEditingRequested`. */
+export type LeaveEditingDecision = 
+/** Continue the transition the user asked for. */
+"proceed"
+/** Remain in editing mode; the user chose to keep working or to submit first. */
+ | "stay";
+export interface LeaveEditingDecidedType {
+    type: "leaveEditingDecided";
+    decision: LeaveEditingDecision;
+    /** Echoes `LeaveEditingRequestedType.requestId`. */
+    requestId: string;
+}
+export type MesssageDataType = EditResourceType | CreateResourceType | CloseBuilderType | CloseDocumentType | SetBreadcrumbsType | GoToPatientType | IframeRouteChangeType | SessionExpiredType | IframeReadyType | PatientLoadedType | CreateDraftType | CreatedDraftType | CreateDraftFailedType | DraftSavedType | OpenDocumentCaptureType | DocumentLoadErrorType | ReloadDocumentType | OpenDoctorsLetterExportType | LockDocumentType | DocumentLockedType | UnlockDocumentType | DraftUpdatedType | LeaveEditingRequestedType | LeaveEditingDecidedType;
 export interface MessageDataMapType {
     editResource: EditResourceType;
     createResource: CreateResourceType;
@@ -86,13 +205,21 @@ export interface MessageDataMapType {
     iframeRouteChange: IframeRouteChangeType;
     sessionExpired: SessionExpiredType;
     iframeReady: IframeReadyType;
+    patientLoaded: PatientLoadedType;
     createDraft: CreateDraftType;
     createdDraft: CreatedDraftType;
+    createDraftFailed: CreateDraftFailedType;
     draftSaved: DraftSavedType;
     openDocumentCapture: OpenDocumentCaptureType;
     documentLoadError: DocumentLoadErrorType;
     reloadDocument: ReloadDocumentType;
     openDoctorsLetterExport: OpenDoctorsLetterExportType;
+    lockDocument: LockDocumentType;
+    documentLocked: DocumentLockedType;
+    unlockDocument: UnlockDocumentType;
+    draftUpdated: DraftUpdatedType;
+    leaveEditingRequested: LeaveEditingRequestedType;
+    leaveEditingDecided: LeaveEditingDecidedType;
 }
 export declare const publishMessage: (data: MesssageDataType, target?: Window) => void;
 declare function subscribeMessage<T extends MessageType>(type: T, callback: (data: MessageDataMapType[T]) => void): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotbase/safe-frame-sync",
-  "version": "1.13.2",
+  "version": "1.15.0",
   "description": "Typesafe iframe and parent communication between Dotstudio and Dotclinic",
   "homepage": "https://github.com/dot-base/safe-frame-sync",
   "types": "dist/index.d.ts",