A diagram from a table

A table in the document can be drawn as a Mermaid flowchart, with one row per step. When the user edits the table, the diagram follows.
New tab

Quick start

In an editor with TableKit, a Mermaid Diagram Renderer and chart: { linkTables: true } in Diagrams.configure(), as in the Tables quick start, take this table:

StepNextTeamLabelShape
Order inCheck stockSalesstart
Check stockPack, Back orderWarehousein stock, missingdecision
PackInvoiceWarehouse

With the selection in the table, this draws it below:

editor.commands.insertDiagramFromTable({
  columns: { step: 'Step', next: 'Next', lane: 'Team', label: 'Label', shape: 'Shape' },
  title: 'Order process',
})

One undo takes back a table edit and the diagram's update. Without chart.linkTables, or with chart: false, which leaves out charts, these commands return false.

How the table is read

columns maps each role to a column by header text, ignoring case, or by position from 0. Without it, the extension guesses from headers such as Step, Task, Next, Then, Team, Owner, Label, Condition and Shape:

RoleRequiredCell holdsBecomes
stepYesThe step's nameA node
nextYesThe steps that follow, separated by commasArrows to those steps
laneNoA lane nameA framed group, a subgraph
labelNoArrow labels, separated by commasText on the arrows
shapeNoA shape name, see ShapesThe node's shape

When no header names step and next, it takes the first columns no other role took. A step named only in a next cell is drawn too, rows with the same step name are one node, and a row with an empty step cell is skipped.

A label cell gives one label per next step when the counts match, otherwise the whole cell to every arrow.

Shapes

ShapeCell text
Boxbox, rect, task
Rounded boxrounded, round
Stadiumstart, end, stadium, terminal
Diamonddecision, diamond, gateway
Circlecircle, event
Parallelogramdata
Cylinderdatabase
Subroutinesubroutine

Any other text gives a box, and case does not matter.

When the table changes

These edits do more than redraw the diagram:

  • Renaming a step in its row renames it in every next cell too, ignoring case. An edit that also adds or removes rows or moves columns is not followed as a rename.
  • Emptying a step cell, or giving it another step's name, is not a rename.
  • Changing a lane cell moves that one step, unlike renameDiagramLane.
  • Removing a column that the link names by its header text keeps the diagram as it is until the column is back. A column given by its position reads whichever column is there now, and keeps the diagram as it is only when the table has no column at that position.
  • Deleting the table leaves the diagram with its last source and its link, until a new source or detachDiagramFromTable ends it.
  • Changing the source with updateFlowDiagram ends the link.
  • Double-clicking a shape edits nothing, because the text belongs to the table.

Stored in the document

WhereWhat
The diagram's options.link{ tableId, columns, header?, range? }
The tableA chartTableId attribute, added by chart.linkTables

Read the link with flowDiagramLink(diagram) from @tiptap-pro/extension-diagrams on a listDiagrams() entry, or as link in listDiagrams(). updateLinkedTable changes how the table is read.

Commands

Each of these commands returns false and changes nothing when it cannot act.

insertDiagramFromTable

Inserts a flowchart of the table at the selection, or of the one at table, directly below that table rather than at the cursor, without selecting it. This call reads a table without a header row. to: -2 counts from the end, both ends included, so the last row is left out:

editor.commands.insertDiagramFromTable({
  header: 'none',
  range: { rows: { to: -2 } },
  columns: { step: 0, next: 1 },
})
OptionTypeDefaultDescription
columnsTableDiagramColumnsGuessed from the header{ step, next, lane?, label?, shape? }, header texts or positions
headerTableHeader'auto''none' reads every row as a step. 'auto' and 'first-row' read a header row
range{ rows }Every rowSome rows, as for insertLinkedChart
tablenumberThe table at the selectionThe table's position
titlestring | nullnullThe diagram's title
belowbooleantruefalse inserts above the table

Returns false when the selection is outside a table, or a named column is not in the table. Without columns, it also returns false for a header of fewer than two non-empty cells and for header: 'none'.

linkDiagramToTable

Draws an existing diagram from a table as a Mermaid flowchart, replacing its source, and makes it follow the table at tablePos, such as a pos from editor.storage.diagrams.listTables():

editor.commands.linkDiagramToTable({ table: tablePos, columns: { step: 'Step', next: 'Next' } })

table and columns are required, header and range work as for insertDiagramFromTable, and pos is the diagram's position, by default the selected diagram.

Returns false without a diagram at pos or in the selection, when table holds no table it can follow, and for a column the table does not have.

detachDiagramFromTable

Stops a diagram from following its table. The source stays and can be edited.

editor.commands.detachDiagramFromTable({ removeTable: true })
OptionTypeDefaultDescription
posnumberThe selected diagramThe diagram's position
removeTablebooleanfalseAlso removes the table, unless another chart or diagram follows it

Returns false for a diagram that follows no table.

renameDiagramLane

Renames a lane in every row of the table, also outside range, and the diagram follows in the same undo step.

editor.commands.renameDiagramLane({ lane: 'Warehouse', name: 'Warehouse North' })
OptionTypeDefaultDescription
lanestringRequiredThe lane's name, trimmed and case-sensitive
namestringRequiredThe new name, trimmed
posnumberThe selected diagramThe diagram's position

Returns false for a diagram that follows no table or has no lane column, a lane no cell names, and an empty name.

Without an editor

Functions from @tiptap-pro/extension-diagrams/core do the commands' work on a server. rows is an array of rows of cell texts, header row first unless header is 'none', and read takes header and range, or {} for the defaults:

import { tableToMermaid } from '@tiptap-pro/extension-diagrams/core'

const rows = [
  ['Step', 'Next'],
  ['Order in', 'Pack'],
  ['Pack', ''],
]
const source = tableToMermaid(rows, { step: 'Step', next: 'Next' })
// 'flowchart LR\n  order_in["Order in"]\n  pack["Pack"]\n  order_in --> pack'
FunctionReturns
tableToMermaid(rows, columns, read?)The flowchart source, or null when a named column or the header row is missing
guessTableDiagramColumns(header)The guessed columns, or null for fewer than two non-empty cells
tableDiagramLanes(rows, columns, read?)The lanes in order of appearance
tableLaneCells(rows, columns, read, lane){ row, column } of each cell naming lane, row counting the header row from 0
tableStepRenames(before, after, columns, read?)null when no step was renamed, otherwise { renames, firstRow, nextColumn }. renames is a Map from each old name, lower-cased and trimmed, to the new one. firstRow is 1 below a header, otherwise 0
stepRenameEdits(text, renames)The { from, to, text } replacements for one next cell