@grafloria/element 0.3.19 → 0.3.20

package/esm/src/lib/load.js

@@ -0,0 +1,252 @@
+/**
+ * `fromDocument()` — the LOAD front door.
+ *
+ * ---------------------------------------------------------------------------
+ * THE GAP THIS CLOSES
+ * ---------------------------------------------------------------------------
+ * Saving was never the problem. `DiagramSerializer.serialize()` already emits a
+ * document that round-trips byte-identically, carrying nodes, links, ports,
+ * groups and every scrap of kit metadata. LOADING was the problem, in three
+ * layers:
+ *
+ *   1. THERE WAS NO FRONT DOOR. `CreateDiagramOptions` takes `nodes`/`edges`;
+ *      nothing took a saved document. `deserialize()` handed back a
+ *      `DiagramModel` that no entry point would render.
+ *   2. THE KITS' POST-RENDER WIRING NEVER RAN. `erDiagram()`/`umlDiagram()` do
+ *      their interaction wiring in `finalize(api)` — row selection, in-canvas
+ *      editing, the suppressed resize handles. A document has no `finalize`, so
+ *      a "successfully loaded" ERD was a PICTURE of an ERD: it looked right and
+ *      did nothing.
+ *   3. CUSTOM NODES HAD NO PAINTER. `renderCustomNode` is a function; functions
+ *      do not serialize. A loaded dashboard mounted 14 widget hosts and painted
+ *      into none of them.
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THE NODES GO BACK IN AS LIVE MODELS
+ * ---------------------------------------------------------------------------
+ * The obvious implementation projects every loaded `NodeModel` back down into a
+ * `NodeSpec` and lets `buildNode()` rebuild it. That is a LOSSY detour, and it
+ * loses exactly the things a saved diagram is made of: `toNodeSpec()` carries
+ * id/position/size/data/label/shape and nothing else — no ports, no metadata,
+ * no behavior. An ER card would come back with four default side ports instead
+ * of its field ports, and every FK→PK edge would silently reroute.
+ *
+ * It is also unnecessary. `applyNodes()`/`applyEdges()` have always accepted a
+ * live `NodeModel`/`LinkModel` and pass it through untouched — the documented
+ * "mix data with your own model" seam. So the loaded models ARE the input, and
+ * nothing is projected, converted or lost.
+ *
+ * ---------------------------------------------------------------------------
+ * HOW PAINTERS COME BACK
+ * ---------------------------------------------------------------------------
+ * ER and UML need NOTHING: their card is `metadata.html`, a structured tree the
+ * renderer paints itself, and metadata round-trips. Measured, not assumed — a
+ * loaded ER document paints byte-identical cards with no painter in sight.
+ *
+ * Dashboard widgets are custom HTML nodes and do need one. The kit REBUILDS the
+ * widget spec from the node's own metadata (`widgetKind` / `widgetSpec` /
+ * `widgetTitle`) and hands it to the same `defaultWidgetRenderer` the authoring
+ * path uses, so a loaded board is drawn by the identical code.
+ *
+ * Precedence, and why:
+ *
+ *   caller's `renderCustomNode`  — an explicit override outranks everything.
+ *   caller's `renderWidget`      — the app's own chart painter; a board that was
+ *                                  authored with one must be reloaded with it.
+ *   the kit's own painter        — but ONLY for nodes the kit actually stamped.
+ *   {@link getNodeType} registry — everything else, exactly as `render()` does.
+ *
+ * The kit claims a node by its METADATA, never by `type === 'widget'` alone.
+ * Hijacking a type name would mean any unrelated diagram with a node called
+ * "widget" got dashboard chrome painted over it; requiring the stamp the kit
+ * itself wrote keeps the registry the general seam it is meant to be.
+ */
+import { DiagramSerializer } from '@grafloria/engine';
+import { getNodeType } from './node-type-registry';
+import { bindRowInteractions } from './diagram-kit/rows';
+import { bindCardEditing } from './diagram-kit/editing';
+import { ensureDiagramKitStyles } from './diagram-kit/styles';
+import { bindDashboardGrid } from './dashboard-kit/grid-binder';
+import { ensureDashboardKitStyles } from './dashboard-kit/styles';
+import { defaultWidgetRenderer } from './dashboard-kit/widgets';
+import { createDashboardHandle, } from './dashboard-kit/dashboard';
+/** True when the node is an ER entity card or a UML class card. */
+function isDiagramKitCard(node) {
+    return node.getMetadata('kitEntity') !== undefined || node.getMetadata('kitClass') !== undefined;
+}
+/**
+ * Rebuild the widget spec the kit's renderers eat, from the node's own metadata.
+ * Returns null for a node the dashboard kit did not stamp — see the header on
+ * why the type name alone is not enough.
+ */
+function widgetSpecOf(node) {
+    var _a;
+    const kind = node.getMetadata('widgetKind');
+    if (kind === undefined)
+        return null;
+    const title = node.getMetadata('widgetTitle');
+    return Object.assign(Object.assign({ id: node.id, kind: kind }, (typeof title === 'string' ? { title } : {})), { data: ((_a = node.getMetadata('widgetSpec')) !== null && _a !== void 0 ? _a : {}), span: node.getMetadata('columnSpan'), rows: node.getMetadata('rowSpan') });
+}
+/**
+ * Turn a saved document back into something `render()` can mount.
+ *
+ * ```ts
+ * const json = JSON.stringify(new DiagramSerializer().serialize(api.getModel()));
+ * // …later, in a fresh page:
+ * render(fromDocument(json), host);
+ * ```
+ *
+ * Accepts the flat serializer form, the portable envelope, or the JSON string
+ * of either.
+ */
+export function fromDocument(document, options = {}) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s;
+    const parsed = typeof document === 'string' ? parseDocument(document) : document;
+    const model = new DiagramSerializer().deserialize(parsed);
+    const nodes = model.getNodes();
+    const groups = model.getGroups();
+    const boards = new Map();
+    // The kits inject their stylesheet from their builder; a load never calls one,
+    // so an un-styled card would come back as unstyled divs. Only for documents
+    // that actually contain that kit's nodes.
+    if (nodes.some(isDiagramKitCard))
+        ensureDiagramKitStyles();
+    if (nodes.some((n) => widgetSpecOf(n) !== null))
+        ensureDashboardKitStyles();
+    const paintWidget = (_a = options.renderWidget) !== null && _a !== void 0 ? _a : defaultWidgetRenderer;
+    // -- reconstruct the dashboard handle's context from the loaded model -------
+    // Every board group carries `dashboardBoard` geometry; its widget members
+    // carry `widgetSpec`/title/span/rows — the canonical, lossless source for
+    // widgets (the load.ts principle that non-widget nodes go back as LIVE models
+    // is untouched; only widgets are rebuilt from metadata, exactly as the
+    // renderCustomNode painter already does). That is enough to build the SAME
+    // handle dashboard() does, through the SAME builder — no drifting twin.
+    const dashGroups = groups.filter((g) => g.getMetadata('dashboardBoard') !== undefined);
+    const specById = new Map();
+    const viewOfWidget = new Map();
+    const ctxViews = dashGroups.map((g) => {
+        var _a, _b, _c;
+        const board = g.getMetadata('dashboardBoard');
+        const widgets = [];
+        for (const memberId of (_a = g.members) !== null && _a !== void 0 ? _a : []) {
+            const node = model.getNode(memberId);
+            const ws = node ? widgetSpecOf(node) : null;
+            if (!ws)
+                continue; // non-widget members (e.g. a nested slab group) are not widgets
+            specById.set(ws.id, ws);
+            viewOfWidget.set(ws.id, g.id);
+            widgets.push(ws);
+        }
+        return { id: g.id, name: g.name, widgets, columns: board.columns, width: (_b = g.size) === null || _b === void 0 ? void 0 : _b.width, height: (_c = g.size) === null || _c === void 0 ? void 0 : _c.height };
+    });
+    const firstBoard = (_b = dashGroups[0]) === null || _b === void 0 ? void 0 : _b.getMetadata('dashboardBoard');
+    // The active view is the one the save left ON camera (x≈0); the others were
+    // parked far off-screen by showView. Falls back to the first board when
+    // positions are ambiguous (e.g. a single view, or positions not restored).
+    const activeGroup = (_c = dashGroups.find((g) => g.position.x > -1000)) !== null && _c !== void 0 ? _c : dashGroups[0];
+    const ctx = {
+        views: ctxViews,
+        groups: new Map(dashGroups.map((g) => [g.id, g])),
+        // The SAME map the LoadedDiagramSpec exposes as `boards` — derived, not a copy.
+        binders: boards,
+        specById,
+        viewOfWidget,
+        hosts: new Map(),
+        renderWidget: paintWidget,
+        columns: (_d = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.columns) !== null && _d !== void 0 ? _d : 12,
+        gap: (_e = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.gap) !== null && _e !== void 0 ? _e : 8,
+        rowHeight: (_f = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.baseRowHeight) !== null && _f !== void 0 ? _f : 130,
+        boardW: (_j = (_h = (_g = dashGroups[0]) === null || _g === void 0 ? void 0 : _g.size) === null || _h === void 0 ? void 0 : _h.width) !== null && _j !== void 0 ? _j : 1180,
+        boardH: (_m = (_l = (_k = dashGroups[0]) === null || _k === void 0 ? void 0 : _k.size) === null || _l === void 0 ? void 0 : _l.height) !== null && _m !== void 0 ? _m : 660,
+        // responsive is NOT in the document (a runtime seam), so it is deliberately
+        // absent from the round-trip; width/height/columns/gap/sizing/float/rtl are.
+        optionsBase: firstBoard
+            ? {
+                columns: firstBoard.columns,
+                gap: firstBoard.gap,
+                rowHeight: firstBoard.baseRowHeight,
+                sizing: firstBoard.sizing,
+                float: firstBoard.float,
+                rtl: firstBoard.rtl,
+                width: (_p = (_o = dashGroups[0]) === null || _o === void 0 ? void 0 : _o.size) === null || _p === void 0 ? void 0 : _p.width,
+                height: (_r = (_q = dashGroups[0]) === null || _q === void 0 ? void 0 : _q.size) === null || _r === void 0 ? void 0 : _r.height,
+            }
+            : {},
+        active: (_s = activeGroup === null || activeGroup === void 0 ? void 0 : activeGroup.id) !== null && _s !== void 0 ? _s : 'main',
+        apiRef: null,
+    };
+    const handle = createDashboardHandle(ctx);
+    const renderCustomNode = (node, host) => {
+        var _a, _b;
+        if (options.renderCustomNode)
+            return options.renderCustomNode(node, host);
+        // Prefer the ctx spec object so a later handle.update()/repaint() mutates the
+        // SAME object this initial paint used; fall back to a fresh rebuild for a
+        // loose widget node that belongs to no reconstructed board.
+        const widget = (_a = specById.get(node.id)) !== null && _a !== void 0 ? _a : widgetSpecOf(node);
+        if (widget) {
+            ctx.hosts.set(node.id, host); // captured so update()/repaint() can find the host
+            return paintWidget(widget, host);
+        }
+        (_b = getNodeType(node.type)) === null || _b === void 0 ? void 0 : _b(node, host);
+    };
+    const finalize = (api) => {
+        var _a, _b, _c, _d;
+        const a = api;
+        if (!a)
+            return;
+        // -- groups ---------------------------------------------------------------
+        // Groups are not part of `nodes`/`edges`, so nothing else would carry them
+        // across. A dashboard without its view group is a set of loose widgets: no
+        // board frame, and nothing for the grid binder to bind to.
+        const live = (_a = a.getModel) === null || _a === void 0 ? void 0 : _a.call(a);
+        if (live) {
+            for (const group of groups) {
+                if (!((_b = live.getGroup) === null || _b === void 0 ? void 0 : _b.call(live, group.id)))
+                    (_c = live.addGroup) === null || _c === void 0 ? void 0 : _c.call(live, group);
+            }
+        }
+        if (options.interactive === false)
+            return;
+        // -- ER / UML -------------------------------------------------------------
+        const cards = nodes.filter(isDiagramKitCard);
+        if (cards.length > 0 && a.container) {
+            for (const node of cards) {
+                // The card draws its own selection ring; the node's resize handles would
+                // frame it a second time. `erDiagram().finalize` does this on the live
+                // model for the same reason — and behaviour is NOT in the document.
+                (_d = node.setBehavior) === null || _d === void 0 ? void 0 : _d.call(node, { resizable: false });
+            }
+            // `rowSelection: false` is recorded only when it is the non-default, so an
+            // ordinary document stays byte-identical to what it always was.
+            if (!cards.some((n) => n.getMetadata('kitRowSelection') === false)) {
+                bindRowInteractions(a);
+            }
+            if (cards.some((n) => n.getMetadata('kitEditable') === true)) {
+                bindCardEditing(a);
+            }
+        }
+        // -- dashboard boards -----------------------------------------------------
+        // Wire the render API into the handle's boxed cell, then bind each board.
+        // `bindDashboardGrid` sync()s on construction, so the handle's cellOf/toJSON
+        // work immediately — no camera move, no showView, so the paint is byte-for-
+        // byte what a boards-only load produced.
+        ctx.apiRef = a;
+        for (const group of groups) {
+            const board = group.getMetadata('dashboardBoard');
+            if (!board)
+                continue;
+            boards.set(group.id, bindDashboardGrid(a, group, Object.assign({}, board)));
+        }
+    };
+    return { nodes, edges: model.getLinks(), renderCustomNode, finalize, model, boards, handle };
+}
+function parseDocument(json) {
+    try {
+        return JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`fromDocument: not a saved diagram (${error.message})`);
+    }
+}
+//# sourceMappingURL=load.js.map

package/esm/src/lib/node-type-registry.js

@@ -0,0 +1,42 @@
+const registry = new Map();
+/** Register (or replace) a node type globally. */
+export function registerNodeType(type, renderer) {
+    registry.set(type, renderer);
+}
+export function getNodeType(type) {
+    return registry.get(type);
+}
+export function hasNodeType(type) {
+    return registry.has(type);
+}
+/** Drop a registration (mostly for tests). */
+export function unregisterNodeType(type) {
+    registry.delete(type);
+}
+/** Every registered type name. */
+export function registeredNodeTypes() {
+    return [...registry.keys()];
+}
+/**
+ * Render a node from a slotted `<template data-node-type="...">`.
+ *
+ * Clones the template's content into `element` and substitutes `node.data` into
+ * every `[data-field="key"]` descendant's text. Values are written with
+ * `textContent`, never `innerHTML`: a diagram's `data` is frequently
+ * user-supplied, and a template engine that injected raw HTML here would be an
+ * XSS vector in every host that embeds us.
+ */
+export function renderFromTemplate(template, node, element) {
+    const fragment = template.content.cloneNode(true);
+    const fields = fragment.querySelectorAll('[data-field]');
+    for (const field of Array.from(fields)) {
+        const key = field.getAttribute('data-field');
+        if (!key)
+            continue;
+        const value = key === 'id' ? node.id : node.data[key];
+        field.textContent = value === undefined || value === null ? '' : String(value);
+    }
+    element.textContent = '';
+    element.appendChild(fragment);
+}
+//# sourceMappingURL=node-type-registry.js.map

package/esm/src/lib/stencil-kit/builders.js

@@ -0,0 +1,18 @@
+const builders = new Map();
+/** Register the builder for a master id. Last registration wins. */
+export function registerStencilBuilder(masterId, builder) {
+    builders.set(masterId, builder);
+}
+/** The builder for a master id, or undefined for the default template path. */
+export function getStencilBuilder(masterId) {
+    return builders.get(masterId);
+}
+/** Drop a registration (tests, or a host replacing a built-in). */
+export function unregisterStencilBuilder(masterId) {
+    return builders.delete(masterId);
+}
+/** Every master id that currently resolves to a card builder. */
+export function registeredStencilBuilders() {
+    return [...builders.keys()].sort();
+}
+//# sourceMappingURL=builders.js.map

package/esm/src/lib/stencil-kit/card-builders.js

@@ -0,0 +1,105 @@
+/**
+ * Card builders for the stencil palette — the bridge that finally lets a
+ * dropped "Entity" or "Class" be a REAL kit card instead of a rectangle.
+ *
+ * Everything here is reuse. `entityCardContent` / `classCardContent` and their
+ * auto-height helpers are the same functions `erDiagram()` / `umlDiagram()`
+ * use, so a dropped card is byte-for-byte the card those kits produce — which
+ * means the row-selection layer (`axk:row-select`), the inline editors and the
+ * `erTable(api, id)` / `umlClass(api, id)` handles all work on it for free.
+ *
+ * The kit's own bindings are idempotent per container, so binding them again
+ * after a drop is safe and is what makes the FIRST dropped card interactive on
+ * a canvas that was never built by a kit.
+ */
+import { NodeModel } from '@grafloria/engine';
+import { entityCardContent, entityAutoHeight, classCardContent, classAutoHeight, bindRowInteractions, bindCardEditing, ensureDiagramKitStyles, } from '../diagram-kit';
+import { registerStencilBuilder } from './builders';
+/** Cards are transparent: the HTML body IS the card, the shape must not paint. */
+const CARD_SHAPE = { type: 'rect', fill: 'none', stroke: 'none' };
+const CARD_STYLE = { fill: 'transparent', stroke: 'transparent', strokeWidth: 0 };
+let seq = 0;
+const nextId = (prefix) => `${prefix}-${++seq}`;
+/** Turn the kit's card spec into a live node, and make the canvas interactive. */
+function mountCard(ctx, opts) {
+    var _a, _b, _c, _d;
+    ensureDiagramKitStyles();
+    const node = new NodeModel({
+        id: opts.id,
+        type: 'kit-card',
+        position: { x: ctx.at.x, y: ctx.at.y },
+        size: { width: opts.width, height: opts.height },
+    });
+    // The SAME metadata shape erDiagram()/umlDiagram() stamp — that is what the
+    // row and editing layers key off.
+    node.setMetadata('html', { content: opts.content, interactive: true });
+    node.setMetadata(opts.metaKey, opts.spec);
+    node.setMetadata('kitEditable', true);
+    node.setMetadata('shape', CARD_SHAPE);
+    (_a = node.setStyle) === null || _a === void 0 ? void 0 : _a.call(node, CARD_STYLE);
+    ctx.api.getModel().addNode(node);
+    // Bind the kit runtime for this container. Both are idempotent, so a canvas
+    // that already ran a kit's finalize() is unaffected, and one that never did
+    // becomes editable on the first drop.
+    const container = (_b = ctx.api.container) !== null && _b !== void 0 ? _b : (_d = (_c = ctx.api).getContainer) === null || _d === void 0 ? void 0 : _d.call(_c);
+    if (container) {
+        const kitApi = Object.assign(Object.assign({}, ctx.api), { container });
+        try {
+            bindRowInteractions(kitApi);
+        }
+        catch ( /* optional */_e) { /* optional */ }
+        try {
+            bindCardEditing(kitApi);
+        }
+        catch ( /* optional */_f) { /* optional */ }
+    }
+    return node;
+}
+/** Register the built-in card builders (ER entity/table, UML classifiers). */
+export function registerCardBuilders() {
+    for (const masterId of ['erd-entity', 'erd-table', 'erd-associative-entity', 'erd-bridge-entity']) {
+        registerStencilBuilder(masterId, (ctx) => {
+            var _a, _b;
+            const id = nextId('entity');
+            const spec = {
+                id,
+                name: (_b = (_a = ctx.master.meta) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : 'Entity',
+                columns: [
+                    { name: 'id', type: 'uuid', pk: true },
+                    { name: 'name', type: 'varchar' },
+                ],
+            };
+            return mountCard(ctx, {
+                id,
+                width: 220,
+                height: entityAutoHeight(spec, true),
+                content: entityCardContent(spec, true),
+                metaKey: 'kitEntity',
+                spec,
+            });
+        });
+    }
+    for (const masterId of ['uml-class', 'uml-abstract-class', 'uml-interface']) {
+        registerStencilBuilder(masterId, (ctx) => {
+            var _a, _b;
+            const id = nextId('class');
+            const spec = {
+                id,
+                name: (_b = (_a = ctx.master.meta) === null || _a === void 0 ? void 0 : _a.name) !== null && _b !== void 0 ? _b : 'Class',
+                abstract: masterId === 'uml-abstract-class',
+                stereotype: masterId === 'uml-interface' ? 'interface' : undefined,
+                attributes: ['- field: Type'],
+                methods: ['+ method(): void'],
+            };
+            return mountCard(ctx, {
+                id,
+                width: 220,
+                height: classAutoHeight(spec, true),
+                content: classCardContent(spec, true),
+                metaKey: 'kitClass',
+                spec,
+            });
+        });
+    }
+}
+//# sourceMappingURL=card-builders.js.map

package/esm/src/lib/stencil-kit/index.js

@@ -0,0 +1,9 @@
+export { bindStencilPalette } from './palette';
+export { bindShapeDataPanel } from './shape-data';
+export { ensureStencilKitStyles } from './styles';
+export { registerStencilBuilder, getStencilBuilder, unregisterStencilBuilder, registeredStencilBuilders, } from './builders';
+import { registerCardBuilders } from './card-builders';
+// The ER/UML card builders ship registered — dropping "Entity" gives a real,
+// editable table out of the box.
+registerCardBuilders();
+//# sourceMappingURL=index.js.map