Weave.js
prerelease Prerelease 5.7.0 Latest 5.6.0 5.4.2 5.4.1 5.4.0 5.3.0 5.2.2 5.2.1
↑↓ navigate · ↵ select · esc close
Weave.js
Weave.js
prerelease Prerelease 5.7.0 Latest 5.6.0 5.4.2 5.4.1 5.4.0 5.3.0 5.2.2 5.2.1

WeaveEllipseNode

Ellipse node API Reference

Overview

The WeaveEllipseNode class represents a basic ellipse shape within the Weave.js canvas.

Built on top of Konva’s Ellipse class shape under the hood, the WeaveEllipseNode offers a simple yet powerful primitive that supports full interaction, styling, and real-time synchronization.

Ellipse nodes support an optional text label that is displayed centred inside the shape. The label can be edited interactively by double-clicking the ellipse while it is selected. All label appearance properties (font, colour, alignment, padding, …) are configurable via the label* props described below.

The class extends the WeaveNode class

Label engine

By default the label is rendered with Konva’s text and edited through a DOM textarea overlay (legacy). Set config.label.engine to native to render the label with the on-canvas text engine and edit it with the native editing session instead: no DOM overlay, and caret and selection are drawn on the canvas.

new WeaveEllipseNode({ config: { label: { engine: "native" } } });

Both engines read and write the same labelText and label* props, so clients using different engines can edit the same document. The native engine enables rich text in labels (bold, italic, underline, lists, alignment). Formatted content is stored in the optional labelBlocks prop, and labelText always holds the plain text, so the legacy engine shows the plain text.

Label edit events

With the native label engine the node emits onEnterShapeLabelEditMode when a label edit session starts and onExitShapeLabelEditMode when it ends. Exit receives { node: Konva.Group }; enter also receives the live session, so an app can build a formatting toolbar by running format commands on it. While editing, onShapeLabelFormatChange receives { node, format } whenever the selection format changes. The legacy engine does not emit them.

Type

This node nodeType property value is ellipse.

Import

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

Instantiation

new WeaveEllipseNode(params?: WeaveEllipseNodeParams);

TypeScript types

type WeaveNodeTransformerProperties = Konva.TransformerConfig;

type WeaveShapeLabelConfig = {
  engine: "legacy" | "native"; // default "legacy"
};

type WeaveEllipseProperties = {
  transform: WeaveNodeTransformerProperties;
  label?: Partial<WeaveShapeLabelConfig>;
};

type WeaveEllipseNodeParams = {
  config: Partial<WeaveEllipseProperties>;
};

type WeaveShapeLabelProps = {
  labelText?: string;
  labelFontFamily?: string;
  labelFontSize?: number;
  labelFontStyle?: string;
  labelFontVariant?: string;
  labelTextDecoration?: string;
  labelFill?: string;
  labelAlign?: string;
  labelVerticalAlign?: string;
  labelLetterSpacing?: number;
  labelLineHeight?: number;
  labelPaddingX?: number;
  labelPaddingY?: number;
  labelBlocks?: WeaveTextBlock[]; // rich content written by the native engine
};

Parameters

For WeaveEllipseNodeParams:

Property Type Required Description

config

Partial<WeaveEllipseProperties>

Required

Config parameters for the node.

For WeaveEllipseProperties:

Property Type Required Default Description

transform

object

check default values

Setup the transform properties for the ellipse (if can be resized, rotated, anchors, etc.).

Label properties

The following props control the optional text label rendered inside the ellipse. They map directly to WeaveShapeLabelProps and are all optional — omit them to use the defaults.

Property Type Required Default Description

labelText

string

Text content of the label. Set to an empty string to hide the label.

labelFontFamily

string

Arial, sans-serif

CSS font-family string for the label text.

labelFontSize

number

14

Font size of the label text in pixels.

labelFontStyle

string

normal

Font style for the label. Accepts CSS font-style/weight keywords or a numeric weight (e.g. "normal", "bold", "italic", "bold italic", "700").

labelFontVariant

string

normal

CSS font-variant for the label (e.g. "normal", "small-caps").

labelTextDecoration

string

CSS text-decoration for the label (e.g. "underline", "line-through").

labelFill

string

#000000

Colour of the label text in hex format (e.g. #RRGGBBAA).

labelAlign

string

center

Horizontal alignment of the label text ("left", "center", "right").

labelVerticalAlign

string

middle

Vertical alignment of the label text ("top", "middle", "bottom").

labelLetterSpacing

number

0

Letter spacing for the label text in pixels.

labelLineHeight

number

1

Line-height multiplier for the label text.

labelPaddingX

number

8

Horizontal inset (padding) in pixels applied on each side of the label area.

labelPaddingY

number

8

Vertical inset (padding) in pixels applied on the top and bottom of the label area.

Default values

const WEAVE_TRANSFORMER_ANCHORS = {
  ["TOP_LEFT"]: "top-left",
  ["TOP_CENTER"]: "top-center",
  ["TOP_RIGHT"]: "top-right",
  ["MIDDLE_RIGHT"]: "middle-right",
  ["MIDDLE_LEFT"]: "middle-left",
  ["BOTTOM_LEFT"]: "bottom-left",
  ["BOTTOM_CENTER"]: "bottom-center",
  ["BOTTOM_RIGHT"]: "bottom-right",
};

const WEAVE_DEFAULT_ENABLED_ANCHORS: string[] = Object.values(
  WEAVE_TRANSFORMER_ANCHORS
);

const WEAVE_DEFAULT_TRANSFORM_PROPERTIES: WeaveNodeTransformerProperties = {
  rotateEnabled: true,
  resizeEnabled: true,
  enabledAnchors: WEAVE_DEFAULT_ENABLED_ANCHORS,
  borderStrokeWidth: 3,
  padding: 0,
};

const WEAVE_SHAPE_LABEL_DEFAULTS: WeaveShapeLabelProps = {
  labelText: "",
  labelFontFamily: "Arial, sans-serif",
  labelFontSize: 14,
  labelFontStyle: "normal",
  labelFontVariant: "normal",
  labelTextDecoration: "",
  labelFill: "#000000",
  labelAlign: "center",
  labelVerticalAlign: "middle",
  labelLetterSpacing: 0,
  labelLineHeight: 1,
  labelPaddingX: 8,
  labelPaddingY: 8,
};