Diagram - Events and commands

#Usage

The root emits accepted changes without replacing its value input. This excerpt assumes a valid store and a recordCommit application handler.

<Diagram.Root :store="store" page-id="page" @commit="recordCommit">
    <Diagram.CommandButton command-id="undo" v-slot="{ getButtonProps }">
        <button type="button" v-bind="getButtonProps()">Undo</button>
    </Diagram.CommandButton>
    <Diagram.Viewport label="Review workflow" style="height: 24rem" />
</Diagram.Root>

The application’s onCommit handler receives an accepted DiagramCommit. Pending proposals and operation events have separate channels.

This skeleton assumes an initialized store with page page. Use First Diagram for model creation, style imports and store disposal.

Change saved state through the store or a session editor. Read snapshots to render state, and inspect each returned result before presenting an action as applied. A preview, pending proposal or successful file download is not a model commit.

#Store construction and authority

createDiagramStore(input, options) validates the candidate and returns DiagramResult<DiagramStore>. Defaults are mode: 'managed', revision: 0 and historyLimit: 100. historyLimit must be a nonnegative safe integer. Optional notationModules are immutable for that store's lifetime.

beforeTransaction(proposal) cancels a proposal when it returns false; a thrown exception rejects it. Reentrant writes are rejected. onObserverError(error) receives observer failures; an observer cannot undo a completed commit.

Editing policy is enforced by session editors and command availability. Direct host store writes remain application authority. Use the session command path when an operation must honor current editor policy.

#Transaction and command fields

DiagramTransaction requires id, origin and commands; baseRevision is optional. origin.kind is one of 'user', 'api', 'import', 'remote', 'undo' or 'redo', with optional actorId.

Collections are 'pages', 'layers', 'nodes' and 'connectors'. The mapped command union binds each record/changes type to its collection. Do not cast a node record into a layer command. All commands in a transaction validate and commit together; a failed transaction leaves the model unchanged.

DiagramProposal includes id, origin, baseRevision, readonly model and patches. Patches distinguish record, order and metadata changes. DiagramCommit adds the accepted revision.

#Result status and controlled mode

DiagramTransactionResult always includes status, transactionId, revision and diagnostics. Additional editor results may add created IDs or operation state. Read those fields from the narrowed result contract in the API.

Managed mode installs an accepted proposal immediately. Controlled mode exposes pendingProposal and emits it to proposal observers. An accepted DiagramAcknowledgement carries transactionId, status: 'accepted', baseRevision and revision; a rejection carries transactionId, baseRevision and status: 'rejected'. The host must match the pending proposal and current revision. See the separate acceptance and rejection cases in Controlled state.

#Observers and Vue emits

Subscriptions return unsubscribe functions. Release them with the owner that created them. Optional import/export/print emits describe their own operation; a preview is not acceptance, and prepared output is not a completed browser print action.

Subscriptions return unsubscribe functions. Keep them with the owner that created them and unsubscribe before replacing or disposing that owner. Outputs on optional import/export/print components describe those operations; they do not imply that a preview was accepted or that a print dialog completed.

#Commands, availability and history

The session's commands registry unifies node, clipboard, history, structure, swimlane, connection, drawing and view actions through DiagramAuthoringAction. state(id) returns DiagramCommandState, including available, diagnostics and a reason. execute(id) and executeAction(action) recheck policy.

Register an application DiagramCommandDefinition with id, label and resolve(context). Optional description, shortcut and availability callbacks provide presentation and application restrictions. The returned unregister function releases the registration. Replacement registrations form an owned stack when registered with register(definition, true); unregistering restores the preceding definition. The default replace: false rejects a duplicate ID.

Diagram.CommandButton binds availability, disabled state, and execution through getButtonProps. Use its slot to render a native button with a useful label. Custom controls can read useDiagramToolbar() under the root and invoke its bound actions.

History groups atomic transactions, ignores no-ops and invalidates redo after a new accepted edit. Session Undo/Redo restore interaction state where supported and check current policy. Navigation itself is not model history. Save uses an owned checkpoint: acknowledging that checkpoint does not mark later edits as saved. See History and Save and load.

#Related Docs

• Architecture
• Imports
• API