@grafloria/element 0.3.19 → 0.3.20

package/esm/src/lib/dashboard-kit/dashboard.js

@@ -0,0 +1,590 @@
+/**
+ * `dashboard({ views, widgets })` — the DATA-FIRST dashboard authoring API.
+ *
+ * The exact shape `erDiagram()` / `umlDiagram()` have for ER and UML: you
+ * describe WHAT the dashboard is, `render()` runs the returned `finalize(api)`
+ * automatically, and every interactive part (the pack grid, drag/resize with
+ * live push and a truthful placeholder, fit/grow, float, pin, undoable
+ * commands) wires itself.
+ *
+ * Before this, a developer got `bindDashboardGrid()` — a gesture BINDER one
+ * layer down — and had to hand-assemble everything above it: a GroupModel per
+ * view, a NodeModel per widget, `useHTMLLayer` / `widgetKind` metadata, grid
+ * cells, membership, then the bind. The demo page needed ~143 lines just to
+ * build its boards. That was the missing authoring layer; this is it:
+ *
+ * ```js
+ * const SPEC = dashboard({
+ *   columns: 12,
+ *   sizing: 'fit',
+ *   views: [{
+ *     id: 'overview', name: 'Overview',
+ *     widgets: [
+ *       { id: 'rev',   kind: 'kpi',   span: 3, rows: 1, data: {…} },
+ *       { id: 'trend', kind: 'line',  span: 8, rows: 2, data: {…} },
+ *       { id: 'mix',   kind: 'donut', span: 4, rows: 2, pinned: true },
+ *     ],
+ *   }],
+ *   renderWidget: (widget, host) => { … },   // optional: your charts
+ * });
+ * render(SPEC, host);
+ * ```
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO: pick a charting library. `renderWidget` is
+ * the seam — the kit hands you the widget and a raw HTML host (the renderer's
+ * custom-node path, which unlike `metadata.html` is not sanitised, so real
+ * `<svg>`/`<canvas>` is fine). Omit it and `defaultWidgetRenderer` (widgets.ts)
+ * draws the declared `kind` from your own `data` with hand-rolled inline SVG —
+ * kpi / line / bar / donut / funnel / table, no dependency, no sample dataset —
+ * falling back to a titled frame for kinds it does not know, so a layout is
+ * testable before any chart exists.
+ *
+ * Cells are the truth and live in the existing `GridItemConfig`, so save/load
+ * round-trips with no extra work — same as every other kit.
+ */
+import { __awaiter } from "tslib";
+import { AddToGroupCommand, BatchCommand, BringNodeToFrontCommand, Command, GroupModel, NodeModel, RemoveFromGroupCommand, RemoveNodeCommand, SendNodeToBackCommand, } from '@grafloria/engine';
+import { bindDashboardGrid, } from './grid-binder';
+import { gridItemFromCell } from './grid-mapping';
+import { ensureDashboardKitStyles } from './styles';
+import { defaultWidgetRenderer } from './widgets';
+/**
+ * Add a widget node AND its board membership as ONE undoable step.
+ *
+ * A `BatchCommand([AddNodeCommand, AddToGroupCommand])` cannot express this:
+ * the manager validates the whole batch up front, and
+ * `AddToGroupCommand.canExecute` pre-gates on the node ALREADY being in the
+ * diagram — which it is not until the first command runs. Sequencing two
+ * commands works but costs two undo steps, so an interactive "add widget"
+ * would need two Ctrl-Z. This composite does both in its own execute(), and
+ * unwinds both in undo().
+ */
+class AddWidgetCommand extends Command {
+    constructor(node, groupId) {
+        super('Add widget');
+        this.node = node;
+        this.groupId = groupId;
+    }
+    execute(context) {
+        var _a;
+        const diagram = context.diagram;
+        if (!diagram)
+            return;
+        diagram.addNode(this.node);
+        (_a = diagram.getGroup(this.groupId)) === null || _a === void 0 ? void 0 : _a.addMember(this.node.id);
+    }
+    undo(context) {
+        var _a;
+        const diagram = context.diagram;
+        if (!diagram)
+            return;
+        (_a = diagram.getGroup(this.groupId)) === null || _a === void 0 ? void 0 : _a.removeMember(this.node.id);
+        diagram.removeNode(this.node.id);
+    }
+    serialize() {
+        return {
+            id: this.id,
+            name: this.name,
+            timestamp: this.timestamp,
+            data: { nodeId: this.node.id, groupId: this.groupId },
+        };
+    }
+}
+const DEFAULTS = { columns: 12, gap: 8, rowHeight: 130, width: 1180, height: 660 };
+const OFFSCREEN_X = -20000;
+let autoId = 0;
+/** The node a widget spec becomes — one place, so addWidget() and the initial
+ *  spec build can never drift apart on metadata. */
+function buildWidgetNode(w, rowHeight) {
+    var _a, _b, _c, _d, _e, _f;
+    const node = new NodeModel({
+        id: w.id,
+        type: 'widget',
+        position: { x: 0, y: 0 },
+        size: { width: 120, height: rowHeight, depth: 0 },
+    });
+    node.setMetadata('useHTMLLayer', true);
+    node.setMetadata('widgetKind', (_a = w.kind) !== null && _a !== void 0 ? _a : 'widget');
+    node.setMetadata('widgetSpec', (_b = w.data) !== null && _b !== void 0 ? _b : {});
+    // The TITLE was the one authored field that never reached the node — so a
+    // document-level reload rebuilt every card with `titleOf()` falling through to
+    // the kind, and a board of "Revenue vs target" / "Top reps by revenue" came
+    // back as "line" / "table". Only written when authored, so an untitled widget
+    // serialises exactly as it always did.
+    if (w.title !== undefined)
+        node.setMetadata('widgetTitle', w.title);
+    node.setMetadata('columnSpan', (_c = w.span) !== null && _c !== void 0 ? _c : 3);
+    node.setMetadata('rowSpan', (_d = w.rows) !== null && _d !== void 0 ? _d : 1);
+    if (w.x !== undefined && w.y !== undefined) {
+        node.setGridItem({
+            columnStart: w.x + 1,
+            columnEnd: w.x + 1 + ((_e = w.span) !== null && _e !== void 0 ? _e : 3),
+            rowStart: w.y + 1,
+            rowEnd: w.y + 1 + ((_f = w.rows) !== null && _f !== void 0 ? _f : 1),
+        });
+    }
+    // A dashboard widget is not a wiring endpoint: no ports, no hover glyphs.
+    node.setBehavior({ connectable: false });
+    for (const p of [...node.getPorts().values()])
+        node.removePort(p.id);
+    return node;
+}
+/** Flow widgets that declared no cell: left-to-right, wrapping at `columns`. */
+function assignCells(widgets, columns) {
+    var _a, _b;
+    let x = 0;
+    let y = 0;
+    let rowMax = 0;
+    for (const w of widgets) {
+        const span = Math.max(1, Math.min(columns, (_a = w.span) !== null && _a !== void 0 ? _a : 3));
+        const rows = Math.max(1, (_b = w.rows) !== null && _b !== void 0 ? _b : 1);
+        if (w.x === undefined || w.y === undefined) {
+            if (x + span > columns) {
+                x = 0;
+                y += rowMax || 1;
+                rowMax = 0;
+            }
+            w.x = x;
+            w.y = y;
+            x += span;
+            rowMax = Math.max(rowMax, rows);
+        }
+        w.span = span;
+        w.rows = rows;
+    }
+}
+/**
+ * Build THE `DashboardHandle` — the one and only implementation, shared by
+ * `dashboard()` and `fromDocument()`. Reads/writes the mutable `ctx.active` /
+ * `ctx.apiRef` cells so the caller's finalize can wire the API in afterwards.
+ */
+export function createDashboardHandle(ctx) {
+    const { views, groups, binders, specById, viewOfWidget } = ctx;
+    const hostOf = (id) => ctx.hosts.get(id);
+    const execCommand = (cmd) => {
+        var _a, _b, _c, _d;
+        try {
+            const r = (_c = (_b = (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.getEngine) === null || _b === void 0 ? void 0 : _b.call(_a)) === null || _c === void 0 ? void 0 : _c.commandManager.execute(cmd);
+            // Fire-and-forget like the binder's own commits, but never leave an
+            // unhandled rejection: a refused command is a no-op, not a crash.
+            (_d = r === null || r === void 0 ? void 0 : r.catch) === null || _d === void 0 ? void 0 : _d.call(r, () => undefined);
+        }
+        catch (_e) {
+            /* a refused command must not break the caller */
+        }
+    };
+    const handle = {
+        get views() {
+            return views.map((v) => v.id);
+        },
+        get activeView() {
+            return ctx.active;
+        },
+        showView(id) {
+            var _a, _b, _c, _d, _e, _f;
+            if (!groups.has(id))
+                return;
+            ctx.active = id;
+            for (const [vid, g] of groups) {
+                const x = vid === id ? 0 : OFFSCREEN_X;
+                const s = (_a = g.size) !== null && _a !== void 0 ? _a : { width: ctx.boardW, height: ctx.boardH };
+                if (g.position.x !== x)
+                    g.setFrame({ x, y: 0, width: s.width, height: s.height });
+            }
+            (_b = binders.get(id)) === null || _b === void 0 ? void 0 : _b.sync();
+            (_c = ctx.apiRef) === null || _c === void 0 ? void 0 : _c.renderNow();
+            const g = groups.get(id);
+            const gs = (_d = g.size) !== null && _d !== void 0 ? _d : { width: ctx.boardW, height: ctx.boardH };
+            (_f = (_e = ctx.apiRef) === null || _e === void 0 ? void 0 : _e.viewport) === null || _f === void 0 ? void 0 : _f.fitToBounds({ x: g.position.x, y: g.position.y, width: gs.width, height: gs.height }, 26, { maxZoom: 1 });
+        },
+        widget(id) {
+            return makeWidgetHandle(id);
+        },
+        widgetsOf(viewId) {
+            var _a;
+            const v = views.find((x) => x.id === (viewId !== null && viewId !== void 0 ? viewId : ctx.active));
+            return ((_a = v === null || v === void 0 ? void 0 : v.widgets) !== null && _a !== void 0 ? _a : []).map((w) => makeWidgetHandle(w.id)).filter(Boolean);
+        },
+        setSizing(mode) {
+            var _a;
+            for (const b of binders.values())
+                b.setSizing(mode);
+            (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+        },
+        getSizing: () => { var _a, _b, _c; return (_b = (_a = binders.get(ctx.active)) === null || _a === void 0 ? void 0 : _a.getSizing()) !== null && _b !== void 0 ? _b : ((_c = ctx.optionsBase.sizing) !== null && _c !== void 0 ? _c : 'fit'); },
+        setFloat(on) {
+            var _a;
+            for (const b of binders.values())
+                b.setFloat(on);
+            (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+        },
+        getFloat: () => { var _a, _b, _c; return (_b = (_a = binders.get(ctx.active)) === null || _a === void 0 ? void 0 : _a.getFloat()) !== null && _b !== void 0 ? _b : ((_c = ctx.optionsBase.float) !== null && _c !== void 0 ? _c : false); },
+        setColumns(n, layout, viewId) {
+            var _a;
+            const targets = viewId ? [binders.get(viewId)] : [...binders.values()];
+            for (const b of targets)
+                b === null || b === void 0 ? void 0 : b.setColumns(n, layout);
+            (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+        },
+        getColumns: (viewId) => { var _a, _b; return (_b = (_a = binders.get(viewId !== null && viewId !== void 0 ? viewId : ctx.active)) === null || _a === void 0 ? void 0 : _a.getColumns()) !== null && _b !== void 0 ? _b : ctx.columns; },
+        setRtl(on) {
+            var _a;
+            for (const b of binders.values())
+                b.setRtl(on);
+            (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+        },
+        getRtl: () => { var _a, _b, _c; return (_b = (_a = binders.get(ctx.active)) === null || _a === void 0 ? void 0 : _a.getRtl()) !== null && _b !== void 0 ? _b : ((_c = ctx.optionsBase.rtl) !== null && _c !== void 0 ? _c : false); },
+        addWidget(spec, viewId) {
+            var _a, _b, _c, _d, _e;
+            const vid = viewId !== null && viewId !== void 0 ? viewId : ctx.active;
+            const v = views.find((x) => x.id === vid);
+            const model = (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.getModel();
+            const group = groups.get(vid);
+            if (!v || !model || !group)
+                return undefined;
+            const w = Object.assign(Object.assign({}, spec), { id: spec.id || `w-${++autoId}`, span: (_b = spec.span) !== null && _b !== void 0 ? _b : 3, rows: (_c = spec.rows) !== null && _c !== void 0 ? _c : 1 });
+            // REGISTER FIRST: a custom node mounts exactly once, and the painter
+            // returns early for an id the spec does not know — so the widget must be
+            // known before the node reaches the model, or it paints blank forever.
+            v.widgets.push(w);
+            specById.set(w.id, w);
+            viewOfWidget.set(w.id, vid);
+            const existing = model.getNode(w.id);
+            const node = existing !== null && existing !== void 0 ? existing : buildWidgetNode(w, ctx.rowHeight);
+            if (w.pinned)
+                node.setState({ locked: true });
+            // ONE undoable step (see AddWidgetCommand for why this cannot be a batch).
+            execCommand(existing ? new AddToGroupCommand(group.id, w.id) : new AddWidgetCommand(node, group.id));
+            (_d = binders.get(vid)) === null || _d === void 0 ? void 0 : _d.sync();
+            (_e = ctx.apiRef) === null || _e === void 0 ? void 0 : _e.renderNow();
+            return makeWidgetHandle(w.id);
+        },
+        refresh() {
+            var _a;
+            for (const b of binders.values())
+                b.sync();
+            (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+        },
+        fit(viewId) {
+            var _a, _b, _c;
+            const g = groups.get(viewId !== null && viewId !== void 0 ? viewId : ctx.active);
+            if (!g)
+                return;
+            const gs = (_a = g.size) !== null && _a !== void 0 ? _a : { width: ctx.boardW, height: ctx.boardH };
+            (_c = (_b = ctx.apiRef) === null || _b === void 0 ? void 0 : _b.viewport) === null || _c === void 0 ? void 0 : _c.fitToBounds({ x: g.position.x, y: g.position.y, width: gs.width, height: gs.height }, 26, { maxZoom: 1 });
+        },
+        metrics(viewId) {
+            var _a;
+            return (_a = binders.get(viewId !== null && viewId !== void 0 ? viewId : ctx.active)) === null || _a === void 0 ? void 0 : _a.metrics();
+        },
+        binderOf(viewId) {
+            return binders.get(viewId !== null && viewId !== void 0 ? viewId : ctx.active);
+        },
+        exportIds(viewId) {
+            var _a, _b;
+            const id = viewId !== null && viewId !== void 0 ? viewId : ctx.active;
+            const ids = new Set();
+            // A view with no group is a view that was never finalized — an empty set
+            // is the honest answer, and scoping an export to nothing is a visible
+            // failure rather than a silently enormous document.
+            if (!groups.has(id))
+                return ids;
+            ids.add(id);
+            // Read the SPEC, not the group's member Set: membership is maintained by
+            // commands and an in-flight drag can have a widget momentarily reparented.
+            // The spec is what the view IS.
+            for (const w of (_b = (_a = views.find((v) => v.id === id)) === null || _a === void 0 ? void 0 : _a.widgets) !== null && _b !== void 0 ? _b : [])
+                ids.add(w.id);
+            return ids;
+        },
+        toJSON() {
+            // SAVING ON A PHONE SAVES THE DESKTOP LAYOUT. The binder serialises from
+            // the engine's LARGEST cached column count (gridstack's `save()`), so a
+            // board currently squeezed to 1 column still writes out the 12-column
+            // layout its user authored — and the view's `columns` is that count, so
+            // feeding this straight back into dashboard() rebuilds the wide board.
+            const savedViews = views.map((v) => {
+                var _a;
+                const saved = (_a = binders.get(v.id)) === null || _a === void 0 ? void 0 : _a.saveLayout();
+                return Object.assign(Object.assign(Object.assign({}, v), (saved ? { columns: saved.columns } : {})), { widgets: v.widgets.map((w) => {
+                        var _a, _b;
+                        const cell = (_a = saved === null || saved === void 0 ? void 0 : saved.cells.get(w.id)) !== null && _a !== void 0 ? _a : (_b = binders.get(v.id)) === null || _b === void 0 ? void 0 : _b.cellOf(w.id);
+                        return cell ? Object.assign(Object.assign({}, w), { x: cell.x, y: cell.y, span: cell.w, rows: cell.h }) : Object.assign({}, w);
+                    }) });
+            });
+            // Board options come off the LIVE board wherever the handle can see it —
+            // `sizing` and `float` are the two a user changes from the toolbar, and
+            // reading them from the authored literal would restore the board they
+            // started with rather than the one they are looking at.
+            return Object.assign(Object.assign({}, ctx.optionsBase), { renderWidget: undefined, onLayoutChange: undefined, columns: ctx.columns, gap: ctx.gap, rowHeight: ctx.rowHeight, sizing: handle.getSizing(), float: handle.getFloat(), rtl: handle.getRtl(), views: savedViews });
+        },
+        dispose() {
+            var _a, _b;
+            for (const b of binders.values())
+                b.dispose();
+            binders.clear();
+            // The groups finalize() created are ours to clean up — leaving them
+            // behind made a rebuild stack a second set of boards on the first.
+            const model = (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.getModel();
+            for (const id of groups.keys())
+                (_b = model === null || model === void 0 ? void 0 : model.removeGroup) === null || _b === void 0 ? void 0 : _b.call(model, id);
+            groups.clear();
+            ctx.hosts.clear();
+        },
+    };
+    function makeWidgetHandle(id) {
+        const spec = specById.get(id);
+        const viewId = viewOfWidget.get(id);
+        if (!spec || !viewId)
+            return undefined;
+        const binder = () => binders.get(viewId);
+        const node = () => { var _a; return (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.getModel().getNode(id); };
+        return {
+            id,
+            viewId,
+            get node() {
+                return node();
+            },
+            get spec() {
+                return spec;
+            },
+            get cell() {
+                var _a;
+                return (_a = binder()) === null || _a === void 0 ? void 0 : _a.cellOf(id);
+            },
+            get rect() {
+                var _a;
+                return (_a = binder()) === null || _a === void 0 ? void 0 : _a.cellRectOf(id);
+            },
+            get pinned() {
+                var _a, _b;
+                return ((_b = (_a = node()) === null || _a === void 0 ? void 0 : _a.state) === null || _b === void 0 ? void 0 : _b.locked) === true;
+            },
+            resize(span, rows) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    return (_b = (yield ((_a = binder()) === null || _a === void 0 ? void 0 : _a.resizeTo(id, span, rows)))) !== null && _b !== void 0 ? _b : false;
+                });
+            },
+            moveTo(x, y) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a, _b;
+                    return (_b = (yield ((_a = binder()) === null || _a === void 0 ? void 0 : _a.moveTo(id, x, y)))) !== null && _b !== void 0 ? _b : false;
+                });
+            },
+            pin(on) {
+                var _a, _b, _c;
+                const n = node();
+                if (!n)
+                    return;
+                n.setState({ locked: on !== null && on !== void 0 ? on : !(((_a = n.state) === null || _a === void 0 ? void 0 : _a.locked) === true) });
+                // Re-sync so the ENGINE's locked flag (never pushed, drags refused)
+                // and the hidden corner handle take effect on this frame, not the next
+                // gesture.
+                (_b = binder()) === null || _b === void 0 ? void 0 : _b.sync();
+                (_c = ctx.apiRef) === null || _c === void 0 ? void 0 : _c.renderNow();
+            },
+            bringToFront() {
+                var _a;
+                execCommand(new BringNodeToFrontCommand(id));
+                (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+            },
+            sendToBack() {
+                var _a;
+                execCommand(new SendNodeToBackCommand(id));
+                (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
+            },
+            update(patch) {
+                if (patch.data !== undefined)
+                    spec.data = patch.data;
+                if (patch.title !== undefined)
+                    spec.title = patch.title;
+                if (patch.kind !== undefined)
+                    spec.kind = patch.kind;
+                const host = hostOf(id);
+                if (host)
+                    ctx.renderWidget(spec, host);
+            },
+            remove(displaced) {
+                var _a, _b;
+                const n = node();
+                const group = groups.get(viewId);
+                const b = binder();
+                if (!n || !group || !b)
+                    return;
+                // ONE undoable step, survivors' re-pack folded in — the same atomic
+                // shape the kit's own drag-out-to-remove uses. A gesture that ALREADY
+                // computed the survivors passes them in: after a drag-out the tile is
+                // gone from the engine, so planRemoval() would return [] and the
+                // survivors' cells would never commit.
+                const survivors = (_a = displaced) !== null && _a !== void 0 ? _a : b.planRemoval(id);
+                const cmds = [...survivors, new RemoveFromGroupCommand(group.id, id), new RemoveNodeCommand(id)];
+                void execCommand(new BatchCommand('Remove widget', cmds));
+                const v = views.find((x) => x.id === viewId);
+                if (v)
+                    v.widgets = v.widgets.filter((w) => w.id !== id);
+                specById.delete(id);
+                viewOfWidget.delete(id);
+                b.sync();
+                (_b = ctx.apiRef) === null || _b === void 0 ? void 0 : _b.renderNow();
+            },
+            repaint() {
+                const host = hostOf(id);
+                if (host)
+                    ctx.renderWidget(spec, host);
+            },
+            // (hosts are captured in renderCustomNode, so repaint works for every
+            //  widget the renderer has mounted — including after a rebuild.)
+        };
+    }
+    return handle;
+}
+export function dashboard(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    ensureDashboardKitStyles();
+    const columns = (_a = options.columns) !== null && _a !== void 0 ? _a : DEFAULTS.columns;
+    const gap = (_b = options.gap) !== null && _b !== void 0 ? _b : DEFAULTS.gap;
+    const rowHeight = (_c = options.rowHeight) !== null && _c !== void 0 ? _c : DEFAULTS.rowHeight;
+    const boardW = (_d = options.width) !== null && _d !== void 0 ? _d : DEFAULTS.width;
+    const boardH = (_e = options.height) !== null && _e !== void 0 ? _e : DEFAULTS.height;
+    const views = options.views
+        ? options.views.map((v) => (Object.assign(Object.assign({}, v), { widgets: v.widgets.map((w) => (Object.assign({}, w))) })))
+        : [{ id: 'main', widgets: ((_f = options.widgets) !== null && _f !== void 0 ? _f : []).map((w) => (Object.assign({}, w))) }];
+    for (const v of views)
+        assignCells(v.widgets, (_g = v.columns) !== null && _g !== void 0 ? _g : columns);
+    // -- the render spec: one custom-HTML node per widget ----------------------
+    const nodes = [];
+    const specById = new Map();
+    const viewOfWidget = new Map();
+    for (const v of views) {
+        for (const w of v.widgets) {
+            specById.set(w.id, w);
+            viewOfWidget.set(w.id, v.id);
+            nodes.push({
+                id: w.id,
+                type: 'widget',
+                position: { x: 0, y: 0 },
+                size: { width: 100, height: rowHeight },
+                custom: true,
+                metadata: Object.assign(Object.assign({ useHTMLLayer: true, widgetKind: (_h = w.kind) !== null && _h !== void 0 ? _h : 'widget', widgetSpec: (_j = w.data) !== null && _j !== void 0 ? _j : {} }, (w.title !== undefined ? { widgetTitle: w.title } : {})), { columnSpan: w.span, rowSpan: w.rows, gridItem: { columnStart: w.x + 1, columnEnd: w.x + 1 + w.span, rowStart: w.y + 1, rowEnd: w.y + 1 + w.rows } }),
+            });
+        }
+    }
+    // No renderWidget → the built-in renderers draw the declared `kind` from the
+    // developer's own `data` (widgets.ts), unknown kinds landing on the titled
+    // frame they always did.
+    const renderWidget = (_k = options.renderWidget) !== null && _k !== void 0 ? _k : defaultWidgetRenderer;
+    // -- runtime: ONE shared handle over a boxed context -----------------------
+    // The two MUTABLE cells the handle used to close over as free `let`s —
+    // `active` (showView reassigns it) and `apiRef` (finalize sets it) — are boxed
+    // on `ctx`, so the SAME builder that fromDocument() calls reads and writes
+    // them. Everything else is the stable state; the handle is identical to what
+    // was inline here, moved verbatim into createDashboardHandle().
+    const ctx = {
+        views,
+        groups: new Map(),
+        binders: new Map(),
+        specById,
+        viewOfWidget,
+        hosts: new Map(),
+        renderWidget,
+        columns,
+        gap,
+        rowHeight,
+        boardW,
+        boardH,
+        optionsBase: options,
+        active: (_m = (_l = views[0]) === null || _l === void 0 ? void 0 : _l.id) !== null && _m !== void 0 ? _m : 'main',
+        apiRef: null,
+    };
+    const { binders, groups } = ctx;
+    const handle = createDashboardHandle(ctx);
+    return {
+        nodes,
+        edges: [],
+        renderCustomNode: (node, host) => {
+            const n = node;
+            const spec = specById.get(n.id);
+            if (!spec)
+                return;
+            ctx.hosts.set(n.id, host);
+            renderWidget(spec, host);
+        },
+        get handle() {
+            return handle;
+        },
+        finalize: (api) => {
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+            const a = api;
+            if (!a)
+                return;
+            ctx.apiRef = a;
+            const model = a.getModel();
+            for (const v of views) {
+                // One board per view; the group is a pure LAYOUT CONTAINER, so its
+                // chrome is suppressed (frameChrome) exactly as a dashboard needs.
+                const g = new GroupModel({ id: v.id, name: (_a = v.name) !== null && _a !== void 0 ? _a : v.id });
+                model.addGroup(g);
+                g.setMetadata('frameChrome', 'none');
+                // THE BOARD'S GEOMETRY, PERSISTED. Cells alone do not describe a board:
+                // the column count, gap and sizing mode are what turn them into pixels,
+                // and they live only in the `dashboard()` call. Without them a reloaded
+                // document could paint the widgets but never rebind the grid — the
+                // reload would be a picture of a dashboard rather than a dashboard.
+                // Serializable values only: the binder's callbacks belong to the app.
+                g.setMetadata('dashboardBoard', {
+                    columns: (_b = v.columns) !== null && _b !== void 0 ? _b : columns,
+                    gap,
+                    padding: gap,
+                    sizing: (_c = options.sizing) !== null && _c !== void 0 ? _c : 'fit',
+                    baseRowHeight: rowHeight,
+                    designHeight: (_d = v.height) !== null && _d !== void 0 ? _d : boardH,
+                    float: (_e = options.float) !== null && _e !== void 0 ? _e : false,
+                    rtl: (_f = options.rtl) !== null && _f !== void 0 ? _f : false,
+                });
+                g.size = { width: (_g = v.width) !== null && _g !== void 0 ? _g : boardW, height: (_h = v.height) !== null && _h !== void 0 ? _h : boardH, depth: 0 };
+                g.position = { x: v.id === ctx.active ? 0 : OFFSCREEN_X, y: 0 };
+                groups.set(v.id, g);
+                for (const w of v.widgets) {
+                    const n = model.getNode(w.id);
+                    if (!n)
+                        continue;
+                    // DECLARED CELLS ARE AUTHORITATIVE. `metadata.gridItem` on the node
+                    // SPEC is inert — the model's GridItemConfig is a real field
+                    // (`setGridItem`), and it is the only thing the binder reads. Without
+                    // this write the board silently auto-positioned instead, which
+                    // matched the declaration only while flow order happened to agree,
+                    // and made toJSON() → dashboard() NOT round-trip (a saved layout
+                    // rebuilt back into its declaration order rather than its cells).
+                    if (w.x !== undefined && w.y !== undefined) {
+                        n.setGridItem(gridItemFromCell({ x: w.x, y: w.y, w: (_j = w.span) !== null && _j !== void 0 ? _j : 3, h: (_k = w.rows) !== null && _k !== void 0 ? _k : 1 }));
+                    }
+                    if (w.pinned)
+                        n.setState({ locked: true });
+                    // A dashboard widget is not a wiring endpoint. This MUST happen here
+                    // rather than on the node spec: the render-input path IGNORES a
+                    // spec-level `behavior` (the same trap erDiagram documents for
+                    // `resizable`), so a DECLARED widget shipped connectable with four
+                    // default ports and sprouted glyphs on hover — while addWidget()'s
+                    // directly-built nodes were already correct. One path being right is
+                    // exactly what hid it, and why the tooth now covers both.
+                    n.setBehavior({ connectable: false });
+                    for (const p of [...n.getPorts().values()])
+                        n.removePort(p.id);
+                    g.addMember(w.id);
+                }
+                binders.set(v.id, bindDashboardGrid(a, g, Object.assign(Object.assign(Object.assign({ columns: (_l = v.columns) !== null && _l !== void 0 ? _l : columns, gap, padding: gap, sizing: (_m = options.sizing) !== null && _m !== void 0 ? _m : 'fit', baseRowHeight: rowHeight, designHeight: (_o = v.height) !== null && _o !== void 0 ? _o : boardH, float: (_p = options.float) !== null && _p !== void 0 ? _p : false, rtl: (_q = options.rtl) !== null && _q !== void 0 ? _q : false }, (options.responsive ? { responsive: options.responsive } : {})), ((_r = options.binder) !== null && _r !== void 0 ? _r : {})), { onGesture: (e) => {
+                        var _a, _b;
+                        if (e.type === 'commit' && options.onLayoutChange) {
+                            const snapshot = handle.toJSON().views.find((x) => x.id === v.id);
+                            if (snapshot)
+                                options.onLayoutChange(v.id, snapshot.widgets);
+                        }
+                        (_b = (_a = options.binder) === null || _a === void 0 ? void 0 : _a.onGesture) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+                    } })));
+            }
+            handle.showView(ctx.active);
+        },
+    };
+}
+//# sourceMappingURL=dashboard.js.map