Actions

Introduction

Actions are the core mechanism for handling user-driven changes in Weave.js. Whether you're adding a node, moving elements, updating properties, or triggering a custom behavior, Actions provide a structured, trackable way to apply changes to the shared state.

Actions help keep your application logic clean and consistent, and collaborative. In Weave.js, if something meaningful happens—it’s probably through an Action.

Weave.js includes a set of built-in Actions, but you can also create your own to tailor functionality to your specific application needs.

Action lifecycle

Weave.js action lifecycle is pretty simple:

Weave instance is started

Actions are registered

The getName method is used to identify the action.

Rendering cycle

After the first render, the init method of every action is called.

Decoupled from the lifecycle

The following methods are called outside the lifecycle:

When an user want to trigger an action, the trigger function is called.
When the action finishes or the user cancel the action, the cleanup function is called.

Available actions

Weave.js team maintain a set of actions, think of them as how the users interact with the canvas to build visual collaborative applications. This are the actions:

UX Tools

Move Tool

Allows users to enable/disable the panning of canvas. When enabled the user can pan the canvas at its will.

Selection Tool

Allows users to enable/disable the selection mode of the canvas. When enabled the users can select nodes, move then, resize them, etc.

Eraser Tool

Allows users to erase (delete) elements of the canvas. When enabled the user can click on an element and it will be erased.

Nodes Tools

Rectangle Tool

Enables users to create new rectangle nodes on the canvas.

Ellipse Tool

Enables users to create new ellipse nodes on the canvas.

Regular Polygon Tool

Enables users to create new regular polygons nodes on the canvas.

Pen Tool

Enables users to create continuos lines on the canvas with N segments on the canvas.

Brush Tool

Enables users to paint freeform strokes on the canvas, similar to a digital brush.

Image Tool

Enables users to add images to the canvas by selecting a file.

Text Tool

Enables users to add new text nodes to the canvas by clicking or touching on it.

Star Tool

Enables users to add new star nodes to the canvas by clicking or touching on it.

Arrow Tool

Enables users to add new arrow nodes to the canvas by clicking or touching on it.

Grouping Tools

Frame Tool

Enables users to create frame nodes by clicking on the canvas.

Zooming Tools

Zoom In Tool

Enables users to incrementally zoom into the canvas, providing a more detailed view of content.

Zoom Out Tool

Enables users to incrementally zoom out the canvas, providing a more general view of content.

Fit to Screen Tool

Automatically adjusts the zoom and position of the canvas to ensure all visible nodes fit neatly within the viewport.

Fit to Selection Tool

Automatically adjusts the zoom and position of the canvas to ensure all selected nodes fit neatly within the viewport.

Export Tools

Export Stage Tool

Automatically adjusts the zoom and position of the canvas to ensure all visible nodes fit neatly within the viewport, and then proceeds to export the viewport as an image.

Export Node Tool

Automatically adjusts the zoom and position of the canvas to ensure all selected nodes fit neatly within the viewport, and then proceeds to export the viewport as an image.

Custom Actions

Developers can also build their own actions, empowering this way their applications with new interactions closer to the needs of their applications.

For this we provide an extension mechanism that allows to define your own actions and use them on your application.

WeaveAction class

In Weave.js a Action is a class that extends the WeaveAction abstract class, and implements a set of methods that define the Action behavior.

Access the Weave instance

You can access Weave.js main instance via this.instance.

To build an action, create a class that extends the WeaveAction abstract class, and implement the following methods:

getName

getName(): string

The getName method returns the name of the action, used as an identifier on the Weave instance. The name of the action must be unique among other actions.

onInit

onInit?(): void

The onInit method is optional, and is called after the first render of the Weave instance. It's a good place to initialize the action state, events, etc.

trigger

trigger(cancelAction: () => void, params?: unknown): unknown

When a user wants to call an action, the trigger method is called, it receives the following parameters:

cancelAction: () => void: a callback that we call when then user wants to cancel the action, or if the action itself finishes.
params?: unknown: an optional parameter that the user can pass to the action, dependencies on the action implementation.

internalUpdate

internalUpdate?(): void

An action instance is wrapped with the Proxy object, which enables us to intercept the get and set operations on the action instance.

The internalUpdate method is called when the for example the props property of the instance is updated (via get/set), allowing us to dynamically pass parameters to an action after this is triggered.

cleanup

cleanup?(): void

The cleanup method is called when the action finishes or the user cancel the action. It's a good place to clean up the action state, events, etc.