Functions

Import these from @grafloria/element.

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.