Diagram - Model

DiagramModel is the saved graph. It contains authored records and JSON metadata. Selection, focus, viewport, live measurements, route caches and editing previews belong to runtime state and are excluded from serialization.

#Usage

import { createDiagramStore, type DiagramModel } from '@primeui/vue-diagram';

const model: DiagramModel = {
    schemaVersion: 1,
    id: 'document',
    pages: [{ id: 'page', name: 'Page' }],
    layers: [{ id: 'layer', pageId: 'page', name: 'Main' }],
    nodes: [
        {
            id: 'node',
            pageId: 'page',
            layerId: 'layer',
            type: 'rectangle',
            bounds: { x: 40, y: 40, width: 160, height: 80 },
            rotation: 0,
            ports: [],
            labels: []
        }
    ],
    connectors: []
};
const created = createDiagramStore(model);
if (!created.ok) throw new Error(created.diagnostics.map((item) => item.message).join('; '));
const store = created.value;
// Dispose this application-owned store when its owner is destroyed.

IDs are caller-assigned, case-sensitive strings of 1–128 ASCII letters, digits, dots, colons, underscores or hyphens, starting with a letter or digit. Identity must be unique across the model's records, including nested labels and ports. A page and its layer cannot share an ID. Preserve IDs when changing an existing record; assign fresh IDs when creating a separate record or remapping pasted content.

The primary Vue entry's DiagramPort name is a rendering component; use the portable port shape through DiagramNodeRecord['ports'][number] when that name is needed in consumer code. The API retains each entry's exact exported identity and all nested option fields.

Connector lineCap is an optional saved 'butt' | 'round' | 'square' value. Omission preserves the flat 'butt' default. For round dots, use it with strokeDash: [0, 6]; dash arrays allow 1–8 finite lengths from 0 to 64 and require at least one positive length. See Connector decorators for editing and export behavior. These optional fields retain native schema version 1.

Array order is authored order. Reordering changes stacking/order through a store command; sorting a readonly snapshot does not update the graph.

#Ownership and coordinates

Nodes and connectors belong to a page and a layer on that page. A parentId must identify a valid node without creating an ownership cycle. Structural commands preserve world placement when reparenting; a raw store update must provide consistent parent-local coordinates itself.

Use session.screenToWorld() and worldToScreen() at the interaction boundary. Subtract the viewport element's bounding-rectangle origin before supplying a browser pointer as a session point. Export pixel dimensions follow explicit scene/raster scale; Diagram export does not multiply them by device pixel ratio. Device pixel ratio does not redefine saved model coordinates.

Authored bounds, measured effective bounds and transient preview bounds are different values. A children-sized container derives its scene extents without rewriting saved bounds. Measured ports override effective attachment geometry; model ports retain their identity and authored configuration. See Geometry measurement.

#Portable metadata and notation

data and extensions accept DiagramJsonValue: null, booleans, finite numbers, strings, arrays and string-keyed objects. Functions, undefined, cycles and non-finite numbers are invalid. Keep runtime registries, component types, maps and callbacks outside these fields.

Symbols use an inert extensions.primeuiSymbol reference or a validated embedded definition. Notation uses the inert extensions.primeuiNotation envelope. A store's notationModules are fixed at creation; installing a visual symbol registry does not install semantic validation. Copying opaque notation without its module cannot manufacture resolved semantic references.

#Validate and change state

createDiagramModel() accepts Omit<DiagramModel, 'schemaVersion'> and assigns the current schema version. createDiagramStore() validates an unknown candidate with its supplied schema version. Both return DiagramResult<T>. Narrow on ok: success has value; failure has diagnostic code, JSON Pointer path and message. Unsupported schema versions, duplicate IDs, invalid geometry, ownership cycles and invalid references are failures. Fix the candidate before replacing a working store.

getSnapshot(), getRecord() and scene/session snapshots are readonly. Use a transaction or the relevant editor to change authored state. Serialization round-trips the portable model, not runtime caches or session navigation. An import preview is a detached candidate until an explicit accepted store transaction installs it.

Events and commands · History · Groups and containers · Save and load

#Related Docs

• Architecture
• Imports
• API