Whiteboard types

Import these TypeScript types for the camera, shapes, tools, styles, doc frames, board files and images from @tiptap-pro/extension-whiteboard.

Editor comes from @tiptap/core and UndoRedoOptions from @tiptap/extensions. ProseMirrorNode is Node from @tiptap/pm/model.

Camera

Where the board shows in the stage.

Properties

• x (number): In screen pixels.
• y (number): In screen pixels.
• zoom (number): The zoom, where 1 is 100%.

UpdateCamera

Type: (update: (camera: Camera) => Camera) => void. Changes the camera through an update function, like a React state setter.

Point, Rect and Size

Point

A point, with x to the right and y down.

• x (number)
• y (number)

Rect

A rectangle, from its top left corner.

• x (number)
• y (number)
• width (number)
• height (number)

Size

A width and a height.

• width (number)
• height (number)

Insets

Room to keep free at each edge of the stage, in screen pixels. Options that take insets also take one number for every edge.

Properties

• top (number)
• right (number)
• bottom (number)
• left (number)

ShapeAttributes

The attributes of shapes. Positions and sizes are in board units.

Properties

• id (string | null): Unique on the board.
• x (number)
• y (number)
• width (number)
• height (number)
• zIndex (string | null): A fractional index: shapes with a higher one are in front.
• color (string): The name of a board color, like yellow.
• kind? (GeoKind): The kind of a geometric shape, a name from geoKinds.

Arrows have no box, but ends, see ArrowEndAttributes, and also the style arrowheads. Doc frames have no color, but a docId. Shapes with text also have the styles fontSize, textAlign and font, see ShapeStyles. Pen lines also have points and strokeWidth.

ShapeGeometry

Type: Pick<ShapeAttributes, 'x' | 'y' | 'width' | 'height'>. The box of a shape, in board units.

ArrowEndAttributes

Where the ends of an arrow are. An end with the id of a shape on the board follows that shape. Otherwise it is free and sits at its point.

Properties

• fromId (string | null)
• toId (string | null)
• fromX (number)
• fromY (number)
• toX (number)
• toY (number)

ShapeUpdate

A change to the attributes of one shape. An update can change any of a shape's attributes, except the id.

Properties

• id (string)
• attributes (ShapeUpdateAttributes)

ShapeUpdateAttributes

Type: Partial<Omit<ShapeAttributes, 'id'> & ArrowEndAttributes & ShapeStyles & { points: string; strokeWidth: number; docId: string }> & { [attribute: string]: unknown; id?: never }.

points and strokeWidth are those of a pen line, and docId is the document of a doc frame. Custom shapes can have attributes of their own, like the data of a chart.

Tool, ShapeTool and ToolKeys

Tool

Type: 'select' | 'hand' | 'eraser' | ShapeTool. What a press on the board does: select shapes, pan the board, erase shapes, or add a shape.

ShapeTool

Type: 'note' | 'text' | 'doc' | 'rectangle' | 'ellipse' | 'diamond' | 'pen' | 'arrow'. A ShapeTool adds a shape of its kind.

ToolKeys

Type: Readonly<Partial<Record<Tool, string | null>>>. The key that chooses each tool. null leaves a tool without a key. See toolKeys.

GeoKind and ShapeColor

GeoKind

Type: (typeof geoKinds)[number], which is 'rectangle' | 'ellipse' | 'diamond' | 'triangle'. A kind of geometric shape, from geoKinds.

ShapeColor

Type: (typeof shapeColors)[number] | (string & {}). The name of a board color: one from shapeColors, like 'black' or 'red', or one of your own. See Colors.

ShapeStyles

Type: { [Name in ShapeStyleName]: ShapeStyleValue<Name> }. The styles of shapes come from shapeStyles. ShapeStyles has a value for each style.

ShapeStyleName

Type: keyof typeof shapeStyles, which is 'color' | 'fontSize' | 'textAlign' | 'font' | 'arrowheads'. The name of a style, like color or fontSize.

ShapeStyleValue

Type: (typeof shapeStyles)[Name][number] | (string & {}) for color, fontSize and font, and (typeof shapeStyles)[Name][number] for the other styles, where Name extends ShapeStyleName. The name of a value of a style, like blue for color. Colors, font sizes and fonts also take names of your own, because only your CSS gives them a look.

ShapeElementAttributes

Type: (node: ProseMirrorNode) => Record<string, unknown>. Returns extra attributes for the element of a shape, from the shape's node. Values become strings, and null or undefined leaves an attribute out.

WhiteboardKitOptions

The options of WhiteboardKit. See Extensions.

Properties

• undoRedo (Partial<UndoRedoOptions> | false)
• shapeElementAttributes (ShapeElementAttributes | null)
• docs (BoardDocs | null)
• colors (readonly ShapeColor[])
• toolKeys (ToolKeys | false)

BoardOptions, the options of Board, has shapeElementAttributes and docs. BoardStorage is what the board keeps in editor.storage.board, see Extensions.

The kit passes colors and toolKeys on to its extensions. BoardTextColorOptions, the options of BoardTextColor, has colors. BoardHighlightOptions, the options of BoardHighlight, has colors and the HighlightOptions of Tiptap's Highlight. ShapeSelectionOptions, the options of ShapeSelection, has toolKeys.

BoardDocs

Where the documents of doc frames live, like local storage or Tiptap Cloud. The app provides it, so the board stays free of any storage. See Doc frames.

Properties

• createEditor ((options: CreateDocEditorOptions) => Editor): Creates the editor of a document inside element, the frame's content element, [data-shape-content]. The board destroys it with its frame.
• start? ((docId: string) => void): Starts the document of every frame that a change in this editor brings onto the board: a new frame, a copy after copy, and frames that setContent or an undo with UndoRedo bring back. Runs before the frame shows, so keep a document that the frame already has. Frames that come through Yjs, from other editors or from its undo, don't start a document here.
• copy ((options: CopyDocOptions) => void): Copies a document for the copy of its frame. Runs before the copy shows, and before start.
• load? ((options: LoadDocOptions) => void): Fills a new document with the content of a frame from a board file, for importBoard. Runs before the frame shows, and before start. Without it, imported frames start empty.

CreateDocEditorOptions

• element (HTMLElement)
• docId (string)

CopyDocOptions

• fromDocId (string)
• toDocId (string)

LoadDocOptions

• docId (string): The id of the new document, which the imported frame shows.
• content (JSONContent): The JSON of the document, from the board file.

BoardFile

A board saved as JSON by exportBoard, with the documents that its doc frames show. importBoard opens it again. See Export and import.

Properties

• type ('tiptap-whiteboard'): Marks the JSON as a board file.
• version (number): The version of the file format. importBoard opens versions up to the one that exportBoard writes.
• content (JSONContent): The board's document, like editor.getJSON() returns it.
• docs (Record<string, JSONContent>): The documents that the doc frames show, by document id.

BoardFileError

A class that extends Error. importBoard throws it when the JSON is not a board file, or when a newer version of the whiteboard wrote it.

Properties

• code (BoardFileErrorCode): Why the file can't be opened.

BoardFileErrorCode

Type: 'not-a-board-file' | 'version-too-new'.

ImportBoardResult

What importBoard added, and what it left out.

Properties

• ids (string[]): The ids of the added shapes.
• skipped (SkippedShape[]): The shapes of the file that the editor can't show, like ones of a type that it doesn't have, or with attributes of the wrong type.

SkippedShape

• id (string | null): The shape's id in the file, or null when it has none.
• type (string): The shape's node type in the file.

BoardSvg

An SVG image of shapes on the board, as exportBoardSvg returns it.

Properties

• svg (string): The markup of the SVG.
• width (number): The width of the image, in board units.
• height (number): The height of the image, in board units.

RemoteSelection

The shapes that one other user selects, and their color as #RRGGBB. A selection with another color, like red or #abc, doesn't show.

Properties

• color (string)
• ids (readonly string[])

RemoteMoves

Shows the drags of other users, until they drop their shapes. createRemoteMoves returns it.

Properties

• show ((options: ShowRemoteMoveOptions) => void)
• end ((owner: unknown) => void)

ShowRemoteMoveOptions

• owner (unknown): Whose drag it is, like the client id of another user.
• ids (readonly string[])
• delta (Point): How far the drag has moved the shapes since it began, in board units.

FreehandShape

Type: ShapeGeometry & { points: string }. The box and the points of a pen line, as freehandFromPoints returns them.

StackPlace

Type: 'front' | 'back'. Where restackShapes puts shapes: in front of all others, or behind them.

Options types

The options of each function and command have a type of their own: