Diagram Kit

Import these from @grafloria/element.

On their own pages

• JoinColumn: Join guidance — live "which column should I join to?" scoring + tinting for

Functions

addColumnAt

Append a column (immutably) — returns the new column array.

ts
Copy
function addColumnAt(columns: ErColumn[], column: ErColumn, at = columns.length): ErColumn[]

assignTiers

Tier every candidate score at once: the FIRST candidate holding the maximum score is top when that maximum is >= 2 — exactly one gold row per drag.

ts
Copy
function assignTiers(scores: number[]): MatchTier[]

bindCardEditing

Wire the editing gestures onto a kit container. Idempotent per container (a re-bind disposes the previous one), matching bindRowInteractions.

ts
Copy
function bindCardEditing(api: EditApi): CardEditingHandle

bindJoinGuidance

Bind live join guidance to a diagram instance. Listens to the engine's connection lifecycle; while a drag is live, every kit-card row on every other table wears its tier class (and the best one its "★ BEST" chip), and the matching port glyphs glow via a generated stylesheet. Everything clears when the drag ends, however it ends.

ts
Copy
function bindJoinGuidance(api: JoinGuidanceApi, options: JoinGuidanceOptions = {}): JoinGuidanceHandle

ensureDiagramKitStyles

Inject the kit stylesheet once. Safe to call repeatedly and in SSR.

ts
Copy
function ensureDiagramKitStyles(doc: Document | undefined = typeof document !== 'undefined' ? document : undefined): void

ensureJoinGuidanceStyles

Inject the guidance tint stylesheet once. Safe to call repeatedly / in SSR.

ts
Copy
function ensureJoinGuidanceStyles(
  doc: Document | undefined = typeof document !== 'undefined' ? document : undefined
): void

erDiagram

Build a render() spec for an ER diagram.

Entities become HTML table cards; relationships become orthogonal edges with crow's-foot cardinality. A TABLE.column end pins the edge to that row via an absolute-layout port (the FK→PK look). Two edges landing on the same column are automatically spread apart.

ts
Copy
function erDiagram(options: ErDiagramOptions): {
  nodes: Array<Record<string, unknown>>;
  edges: Array<Record<string, unknown>>;
  finalize: (api: unknown) => void;
}

erRowCenterY

Node-local y of a row's centre (the +1 offsets past the card's top border).

ts
Copy
function erRowCenterY(rowIndex: number): number

erTable

Typed handle for a kit ER table. Throws for unknown ids / non-kit nodes.

ts
Copy
function erTable(api: HandleApi, id: string): ErTable

erTables

Every kit ER table in the diagram, as handles.

ts
Copy
function erTables(api: HandleApi): ErTable[]

matchColumns

Match old columns to new columns for port reconciliation. Returns a map from OLD index → NEW index; an old index absent from the map is a REMOVED column (its pinned ports and their edges are dropped).

Three passes, most-certain first, so a single edit is always read the way a human means it:

1. object identity — reorder / add / remove that preserved references;
2. name — a retype (same name, new object) or a rebuilt array;
3. positional remainder — the leftovers matched in order, which is exactly what a rename is (one old + one new in the same slot). Without pass 3 a rename reads as remove+add and the edge is severed.

ts
Copy
function matchColumns(oldCols: ErColumn[], newCols: ErColumn[]): Map<number, number>

matchTier

Per-score tier (rank-free half; assignTiers promotes the single best to top).

ts
Copy
function matchTier(score: number): Exclude<MatchTier, 'top'>

removeColumnAt

Remove the column at index — returns the new column array.

ts
Copy
function removeColumnAt(columns: ErColumn[], index: number): ErColumn[]

renameColumnAt

Rename the column at index — returns a new array with a NEW object there.

ts
Copy
function renameColumnAt(columns: ErColumn[], index: number, name: string): ErColumn[]

rowIndexFromY

Inverse of {@link erRowCenterY}: which column row a pinned port sits on.

ts
Copy
function rowIndexFromY(y: number): number

scoreMatch

Score a candidate join between two columns. Pure; the exact production logic. Higher is better; 0 means "no reason to join these".

ts
Copy
function scoreMatch(a: JoinEnd, b: JoinEnd): 0 | 1 | 2 | 3

singularize

Naive English singular — enough for schema names (orders, categories, statuses).

ts
Copy
function singularize(word: string): string

umlClass

Typed handle for a kit UML class. Throws for unknown ids / non-kit nodes.

ts
Copy
function umlClass(api: HandleApi, id: string): UmlClass

umlClasses

Every kit UML class in the diagram, as handles.

ts
Copy
function umlClasses(api: HandleApi): UmlClass[]

umlDiagram

Build a render() spec for a UML class diagram. Call spec.finalize(api) after render() — multiplicity chips are positioned labels, which only the live model's link.addLabel can express.

ts
Copy
function umlDiagram(options: UmlDiagramOptions): {
  nodes: Array<Record<string, unknown>>;
  edges: Array<Record<string, unknown>>;
  finalize: (api: unknown) => void;
}

updateClass

Edit a rendered UML class in place. delta may change the name, stereotype, abstract flag, attributes, methods, and width/height. One undoable step.

ts
Copy
function updateClass(api: KitApi, classId: string, delta: UmlClassDelta): Promise<boolean>

updateEntity

Edit a rendered ER table in place. delta may change the name, the column list (add / remove / reorder / rename / retype), and the width/height. Field ports and their edges are reconciled so the diagram stays correct, as ONE undoable step.

ts
Copy
function updateEntity(api: KitApi, entityId: string, delta: ErEntityDelta): Promise<boolean>

Returns whether the node existed and the edit was applied.

Classes

CardHandle

ts
Copy
abstract class CardHandle

Methods

• constructor( protected readonly api: HandleApi, readonly id: string )
• get exists(): boolean
• get node(): unknown — Escape hatch to the underlying NodeModel (typed loosely on purpose).
• get width(): number
• get height(): number
• abstract get name(): string
• abstract rename(name: string): Promise<boolean> — Rename the card title — one undoable step.
• abstract resize(size: { width?: number; height?: number }): Promise<boolean> — Resize the card — one undoable step (kit body scrolls when capped).
• select(): void
• async undo(): Promise<void>
• async redo(): Promise<void>
• onRowSelect( cb: (e: { field: ErField | null; selected: RowRef | null }) => void ): () => void — Row-selection events for THIS card only (the kit's axk:row-select, filtered). ER cards resolve the selection to a typed {@link ErField} when possible. Returns an unbind function.

ErColumnList

The columns collection of an {@link ErTable}. Iterable of {@link ErField}.

ts
Copy
class ErColumnList implements Iterable<ErField>

Methods

• constructor(private readonly table: ErTable)
• get length(): number
• names(): string[]
• at(index: number): ErField | undefined
• get(name: string): ErField | undefined
• [Symbol.iterator](): Iterator<ErField>
• add(column: ErColumn, opts: { at?: number } = {}): Promise<boolean>
• removeAt(index: number): Promise<boolean>
• renameAt(index: number, name: string): Promise<boolean>
• patchAt(index: number, patch: Partial<ErColumn>): Promise<boolean>
• move(from: number, to: number): Promise<boolean>

ErField

A column of an {@link ErTable} — itself just (table, name): stateless.

ts
Copy
class ErField

Methods

• constructor( readonly table: ErTable, private readonly columnName: string )
• get exists(): boolean
• get name(): string
• get index(): number
• get type(): string | undefined
• get pk(): boolean
• get fk(): boolean
• rename(name: string): Promise<boolean> — Rename — the field port keeps its id, so attached edges stay glued.
• setType(type: string): Promise<boolean>
• setKeys(keys: { pk?: boolean; fk?: boolean }): Promise<boolean>
• remove(): Promise<boolean> — Remove this column (its ports and attached edges are dropped).

ErTable

ts
Copy
class ErTable extends CardHandle

Properties

Methods

• get spec(): ErEntitySpec — A deep COPY of the stored entity spec — never a live reference.
• get name(): string
• rename(name: string): Promise<boolean> — Rename the card title — one undoable step.
• resize(size: { width?: number; height?: number }): Promise<boolean> — Resize the card — one undoable step (kit body scrolls when capped).
• update(delta: Parameters<typeof updateEntity>[2]): Promise<boolean> — The raw delta path — everything above funnels through here.

UmlClass

ts
Copy
class UmlClass extends CardHandle

Properties

Methods

• get spec(): UmlClassSpec — A deep COPY of the stored class spec — never a live reference.
• get name(): string
• get abstract(): boolean
• get stereotype(): string | undefined
• rename(name: string): Promise<boolean> — Rename the card title — one undoable step.
• resize(size: { width?: number; height?: number }): Promise<boolean> — Resize the card — one undoable step (kit body scrolls when capped).
• setAbstract(abstract: boolean): Promise<boolean>
• setStereotype(stereotype: string | undefined): Promise<boolean>
• update(delta: Parameters<typeof updateClass>[2]): Promise<boolean>

UmlMemberList

attributes / methods of a {@link UmlClass} (members are plain strings).

ts
Copy
class UmlMemberList

Methods

• constructor( private readonly cls: UmlClass, private readonly kind: 'attributes' | 'methods' )
• list(): string[]
• get length(): number
• at(index: number): string | undefined
• add(member: string, opts: { at?: number } = {}): Promise<boolean>
• removeAt(index: number): Promise<boolean>
• renameAt(index: number, member: string): Promise<boolean>

Constants

DIAGRAM_KIT_STYLE_ID

Diagram-kit stylesheet — injected once, on first use of any kit builder.

Everything is prefixed axk- and the selection overrides are scoped with :has(...) to kit cards only, so embedding the kit can never restyle a host's own nodes. The rules encode the lessons the diagrams/* demos learned the hard way:

• the card fills the node and draws the ONLY border (the node's own rect is hidden by the builders, and suppressed again on selection because the theme paints .selected with an accent stroke that overrides inline transparency);
• the default .selection-highlight outline (a dashed rect a few px OUTSIDE the node) reads as a second floating box around a bordered card — the kit hides it and rings the card itself instead.

ts
Copy
const DIAGRAM_KIT_STYLE_ID: "grafloria-diagram-kit-styles"

ER_HEAD_H

ts
Copy
const ER_HEAD_H: 28

ER_ROW_H

Row height / header height of the entity card — sizing is derived from these.

ts
Copy
const ER_ROW_H: 25

JOIN_GUIDANCE_STYLE_ID

ts
Copy
const JOIN_GUIDANCE_STYLE_ID: "grafloria-join-guidance-styles"

Interfaces

CardEditingHandle

ts
Copy
interface CardEditingHandle

Members

• dispose(): void

ErColumn

ts
Copy
interface ErColumn

Properties

ErDiagramOptions

ts
Copy
interface ErDiagramOptions

Properties

ErEntityDelta

What an ER table edit can change. Omitted fields are left as they were.

ts
Copy
interface ErEntityDelta

Properties

ErEntitySpec

ts
Copy
interface ErEntitySpec

Properties

ErRelationshipSpec

ts
Copy
interface ErRelationshipSpec

Properties

HandleApi

The slice of DiagramInstance the handles need (same shape update.ts uses).

ts
Copy
interface HandleApi

Properties

Members

• getModel(): { getNode(id: string): | { getMetadata?(key: string): unknown; size: { width: number; height: number }; state?: { selected?: boolean }; } | undefined; selectNode?(node: unknown): void; }
• getEngine?(): { undo(): Promise<void> | void; redo(): Promise<void> | void } | undefined
• renderNow?(): void

JoinEnd

One end of a candidate join: a table (node) and one of its columns.

ts
Copy
interface JoinEnd

Properties

JoinGuidanceApi

The slice of DiagramInstance the binding needs (matches HandleApi's shape).

ts
Copy
interface JoinGuidanceApi

Properties

Members

• getModel(): { getNode(id: string): NodeLike | undefined; getNodes?(): NodeLike[]; }
• getEngine?(): | { eventBus?: { on(event: string, handler: (data: unknown) => void): () => void } } | undefined

JoinGuidanceHandle

ts
Copy
interface JoinGuidanceHandle

Members

• activeTiers(): Map<string, Map<number, MatchTier>> — nodeId → rowIndex → tier for the drag in progress (empty when idle).
• dispose(): void

JoinGuidanceOptions

ts
Copy
interface JoinGuidanceOptions

Properties

UmlClassDelta

What a UML class edit can change.

ts
Copy
interface UmlClassDelta

Properties

UmlClassSpec

ts
Copy
interface UmlClassSpec

Properties

UmlDiagramOptions

ts
Copy
interface UmlDiagramOptions

Properties

UmlRelationshipSpec

ts
Copy
interface UmlRelationshipSpec

Properties

Types

ErCardinality

ts
Copy
type ErCardinality =
  | 'one-to-many'
  | 'one-to-one'
  | 'many-to-many'
  | 'one-to-zero-or-many'
  | 'one-to-one-or-many';

ErSide

ts
Copy
type ErSide = 'left' | 'right' | 'top' | 'bottom';

MatchTier

ts
Copy
type MatchTier = 'top' | 'good' | 'ok' | 'none';

UmlRelationKind

ts
Copy
type UmlRelationKind =
  | 'inheritance'
  | 'realization'
  | 'association'
  | 'directed-association'
  | 'aggregation'
  | 'composition'
  | 'dependency';

UmlSide

ts
Copy
type UmlSide = 'left' | 'right' | 'top' | 'bottom';