Low-level State Manipulation

Overview

The WeaveStateManipulation class is a collection of static helpers for reading and writing the Yjs document that backs the collaborative canvas state.

All canvas state in Weave.js is stored as two Y.Map roots inside a Y.Doc:

weave — the node tree (stage → layers → nodes)
weaveMetadata — metadata not directly rendered

WeaveStateManipulation gives you direct access to that tree, letting you build, insert, update, delete, and query nodes at the Yjs level without going through the higher-level Weave instance methods.

Low-level API

Prefer the Weave instance methods (addNode, updateNode, removeNode, etc.) for everyday node management. Use WeaveStateManipulation only when you need precise, transactional control over the Yjs document — for example when writing a custom store, seeding initial state, or implementing a bulk-import operation.

Import

import { WeaveStateManipulation } from "@inditextech/weave-sdk";

Static Methods

mapValueToYjs

static mapValueToYjs(value: unknown): unknown

Converts any JavaScript value to its Yjs-compatible equivalent, recursively:

Input type	Output type
`null` / `undefined` / primitive	returned as-is
`Array`	`Y.Array` (elements mapped recursively)
plain `object`	`Y.Map` (values mapped recursively)

Parameters

Prop	Type	Default
`value`	`unknown`	-

Returns

The Yjs-compatible representation of value.

mapPropsToYjs

static mapPropsToYjs(props: Record<string, unknown>): Y.Map<unknown>

Converts a flat or nested props object into a Y.Map, mapping each value through mapValueToYjs.

Parameters

Prop	Type	Default
`props`	`Record<string, unknown>`	-

Returns

Y.Map<unknown> — a Yjs map with all props converted to Yjs types.

mapNodeToYjs

static mapNodeToYjs(node: WeaveStateElement): {
  nodeId: string;
  element: Y.Map<WeaveStateElement>;
}

Converts a WeaveStateElement JSON model into a Yjs Y.Map structure ready to be inserted into the document. Children are handled recursively as Y.Array elements.

Parameters

Prop	Type	Default
`node`	`WeaveStateElement`	-

Returns

An object with:

nodeId — the key of the input node
element — the Y.Map representing the node, with key, type, and props fields

addElements

static addElements(
  layerYjsElement: Y.Map<unknown>,
  yjsElements: Y.Map<unknown>[]
): void

Appends one or more Yjs element maps to the children array of the given layer element.

Parameters

Prop	Type	Default
`yjsElements`	`Y.Map<unknown>[]`	-
`layerYjsElement`	`Y.Map<unknown>`	-

updateElements

static updateElements(
  layerYjsElement: Y.Map<unknown>,
  yjsElements: { nodeId: string; element: Y.Map<unknown> }[]
): void

Replaces existing child elements inside a layer by matching on nodeId. For each entry, the old element at that position is deleted and the new one is inserted at the same index.

Parameters

Prop	Type	Default
`yjsElements`	`{ nodeId: string; element: Y.Map<unknown> }[]`	-
`layerYjsElement`	`Y.Map<unknown>`	-

deleteElements

static deleteElements(
  layerYjsElement: Y.Map<unknown>,
  yjsElementsIds: string[]
): void

Removes child elements from a layer by their node ids.

Parameters

Prop	Type	Default
`yjsElementsIds`	`string[]`	-
`layerYjsElement`	`Y.Map<unknown>`	-

getYjsElement

static getYjsElement(doc: Y.Doc, nodeId: string): Y.Map<unknown> | null

Searches the weave root of the document for a node by its id prop. Looks in both direct children of the stage and one level deeper (grandchildren / container children).

Parameters

Prop	Type	Default
`nodeId`	`string`	-
`doc`	`Y.Doc`	-

Returns

The Y.Map for the matching node, or null if not found.

getNodesBoundingBox

static getNodesBoundingBox(nodes: WeaveStateElement[]): BoundingBox

Computes the axis-aligned bounding box that contains all the provided nodes, based on their x, y, width, and height props.

Parameters

Prop	Type	Default
`nodes`	`WeaveStateElement[]`	-

Returns

BoundingBox — { x, y, width, height } of the combined bounding box.

Low-level State Manipulation

On this page