@grafloria/element 0.4.0 → 0.4.2

package/README.md

@@ -44,6 +44,8 @@ Worst case, importing the **entire** public surface of `@grafloria/element`
 
 A real app importing only what it uses ships less. Reproduce it in two minutes:
 
+**Docs:** [JavaScript in 10 minutes](https://grafloria.com/learn/javascript/) · [guides & concepts](https://grafloria.com/learn/) · [111 live demos](https://grafloria.com/demos/)
+
 ```sh
 npm i -D esbuild @grafloria/element
 echo "export * from '@grafloria/element';" > entry.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grafloria/element",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",

package/src/lib/dashboard-kit/dashboard.d.ts

@@ -64,6 +64,30 @@ export interface DashboardWidgetSpec {
     data?: Record<string, unknown>;
     /** Optional title used by the built-in fallback renderer. */
     title?: string;
+    /**
+     * CONTAINMENT. A widget carrying `widgets` is a CONTAINER: it mounts as a
+     * member group (a locked slab in its parent's grid, exactly like a view's
+     * board one level down) with its own nested pack grid bound on it. Children
+     * lay out inside its frame; dragging a tile across the boundary adopts it
+     * live in either direction, and one undo restores the whole gesture.
+     * Containers may nest — tested to TWO levels; deeper is not exercised by
+     * the gates and rides at your own risk. A container renders no card of its
+     * own (`kind`/`data` are carried for your bookkeeping and serialization,
+     * not painted).
+     */
+    widgets?: DashboardWidgetSpec[];
+    /**
+     * Container only: column count of the INNER grid (default: the parent
+     * board's column count).
+     */
+    columns?: number;
+    /**
+     * Container only: the inner grid's designed row count. A child resized past
+     * it ESCALATES — the container's slab grows a row in the parent board (the
+     * ratchet), instead of the child overflowing the frame. Default: the row
+     * extent of the declared children.
+     */
+    maxRows?: number;
 }
 /** One board. Multiple views are the tab pattern: only one is on-camera. */
 export interface DashboardViewSpec {
@@ -316,7 +340,17 @@ export interface DashboardHandleContext {
     groups: Map<string, GroupModel>;
     binders: Map<string, DashboardGridHandle>;
     specById: Map<string, DashboardWidgetSpec>;
+    /** Widget id → the BOARD that owns it (a view id, or a container id). */
     viewOfWidget: Map<string, string>;
+    /** Every board group — the views PLUS every container. Views also live in
+     *  `groups` (the parking map showView drives); containers deliberately do
+     *  NOT — parking flings a group to OFFSCREEN_X, and a container must follow
+     *  its parent, not travel on its own. */
+    boardGroups: Map<string, GroupModel>;
+    /** Board id → its authored widgets array (views and containers alike). */
+    boardWidgets: Map<string, DashboardWidgetSpec[]>;
+    /** Board id → the VIEW it belongs to (identity for views). */
+    viewOfBoard: Map<string, string>;
     hosts: Map<string, HTMLElement>;
     renderWidget: (widget: DashboardWidgetSpec, host: HTMLElement) => void;
     columns: number;

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

@@ -129,6 +129,32 @@ function buildWidgetNode(w, rowHeight) {
         node.removePort(p.id);
     return node;
 }
+function cloneWidgets(ws) {
+    return ws.map((w) => (Object.assign(Object.assign({}, w), (w.widgets ? { widgets: cloneWidgets(w.widgets) } : {}))));
+}
+/** A container's inner column count: authored, else its own span — inner cells
+ *  then ride the parent's column rhythm, which is what a section reads as. */
+function innerColumnsOf(w) {
+    var _a, _b;
+    return Math.max(1, (_b = (_a = w.columns) !== null && _a !== void 0 ? _a : w.span) !== null && _b !== void 0 ? _b : 3);
+}
+/** The row extent of a laid-out widget list (the inner grid's design height). */
+function rowExtentOf(widgets) {
+    var _a, _b;
+    let max = 1;
+    for (const w of widgets)
+        max = Math.max(max, ((_a = w.y) !== null && _a !== void 0 ? _a : 0) + ((_b = w.rows) !== null && _b !== void 0 ? _b : 1));
+    return max;
+}
+/** Recursive `assignCells`: a container flows in its parent like any widget,
+ *  and its children flow inside its OWN column count. */
+function assignCellsDeep(widgets, columns) {
+    assignCells(widgets, columns);
+    for (const w of widgets) {
+        if (w.widgets)
+            assignCellsDeep(w.widgets, innerColumnsOf(w));
+    }
+}
 /** Flow widgets that declared no cell: left-to-right, wrapping at `columns`. */
 function assignCells(widgets, columns) {
     var _a, _b;
@@ -161,6 +187,38 @@ function assignCells(widgets, columns) {
 export function createDashboardHandle(ctx) {
     const { views, groups, binders, specById, viewOfWidget } = ctx;
     const hostOf = (id) => ctx.hosts.get(id);
+    /**
+     * A board's widgets as a NESTED tree, derived from LIVE membership — not the
+     * authored arrays. A cross-boundary drag moves membership through commands
+     * (and undo moves it back); the authored arrays do not follow. Deriving from
+     * the groups + engines is what makes toJSON() and onLayoutChange report a
+     * tile under the container it is actually in, in every one of those states.
+     */
+    const treeOf = (boardId) => {
+        var _a;
+        const g = ctx.boardGroups.get(boardId);
+        const b = binders.get(boardId);
+        if (!g)
+            return [];
+        // Cells from the binder's serialisation (largest cached layout — the
+        // saving-on-a-phone rule), falling back to the live engine cell.
+        const saved = b === null || b === void 0 ? void 0 : b.saveLayout();
+        const cellOf = (id) => { var _a; return (_a = saved === null || saved === void 0 ? void 0 : saved.cells.get(id)) !== null && _a !== void 0 ? _a : b === null || b === void 0 ? void 0 : b.cellOf(id); };
+        const entries = [];
+        for (const memberId of (_a = g.members) !== null && _a !== void 0 ? _a : []) {
+            const spec = specById.get(memberId);
+            const cell = cellOf(memberId);
+            const at = cell ? { x: cell.x, y: cell.y, span: cell.w, rows: cell.h } : {};
+            if (ctx.boardGroups.has(memberId)) {
+                entries.push(Object.assign(Object.assign(Object.assign({ id: memberId }, (spec !== null && spec !== void 0 ? spec : {})), at), { widgets: treeOf(memberId) }));
+            }
+            else if (spec) {
+                entries.push(Object.assign(Object.assign({}, spec), at));
+            }
+        }
+        entries.sort((p1, p2) => { var _a, _b, _c, _d; return ((_a = p1.y) !== null && _a !== void 0 ? _a : 0) - ((_b = p2.y) !== null && _b !== void 0 ? _b : 0) || ((_c = p1.x) !== null && _c !== void 0 ? _c : 0) - ((_d = p2.x) !== null && _d !== void 0 ? _d : 0); });
+        return entries;
+    };
     const execCommand = (cmd) => {
         var _a, _b, _c, _d;
         try {
@@ -237,16 +295,18 @@ export function createDashboardHandle(ctx) {
         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);
+            // `vid` may name a view OR a container — both are boards with a group,
+            // a binder and an authored array.
+            const arr = ctx.boardWidgets.get(vid);
             const model = (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.getModel();
-            const group = groups.get(vid);
-            if (!v || !model || !group)
+            const group = ctx.boardGroups.get(vid);
+            if (!arr || !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);
+            arr.push(w);
             specById.set(w.id, w);
             viewOfWidget.set(w.id, vid);
             const existing = model.getNode(w.id);
@@ -292,9 +352,16 @@ export function createDashboardHandle(ctx) {
             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);
+            // The spec is what the view IS. Containers add themselves AND their
+            // subtree — an exported container without its children is an empty frame.
+            const walk = (ws) => {
+                for (const w of ws) {
+                    ids.add(w.id);
+                    if (w.widgets)
+                        walk(w.widgets);
+                }
+            };
+            walk((_b = (_a = views.find((v) => v.id === id)) === null || _a === void 0 ? void 0 : _a.widgets) !== null && _b !== void 0 ? _b : []);
             return ids;
         },
         toJSON() {
@@ -304,13 +371,13 @@ export function createDashboardHandle(ctx) {
             // 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;
+                var _a, _b, _c, _d;
                 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);
-                    }) });
+                const live = treeOf(v.id);
+                return Object.assign(Object.assign(Object.assign({}, v), (saved ? { columns: saved.columns } : {})), { 
+                    // Live membership when the view is mounted; the authored tree before
+                    // finalize (a spec serialised without ever rendering keeps its shape).
+                    widgets: live.length > 0 || ((_d = (_c = (_b = ctx.boardGroups.get(v.id)) === null || _b === void 0 ? void 0 : _b.members) === null || _c === void 0 ? void 0 : _c.size) !== null && _d !== void 0 ? _d : 0) > 0 ? live : v.widgets.map((w) => (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
@@ -319,16 +386,21 @@ export function createDashboardHandle(ctx) {
             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;
+            var _a, _b, _c;
             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())
+            // Deepest first: a container group removed after its parent is an orphan
+            // the model never saw inside a board.
+            for (const id of [...ctx.boardGroups.keys()].reverse())
                 (_b = model === null || model === void 0 ? void 0 : model.removeGroup) === null || _b === void 0 ? void 0 : _b.call(model, id);
+            for (const id of groups.keys())
+                (_c = model === null || model === void 0 ? void 0 : model.removeGroup) === null || _c === void 0 ? void 0 : _c.call(model, id);
             groups.clear();
+            ctx.boardGroups.clear();
             ctx.hosts.clear();
         },
     };
@@ -407,8 +479,15 @@ export function createDashboardHandle(ctx) {
             },
             remove(displaced) {
                 var _a, _b;
+                if (spec.widgets) {
+                    // A container is a GROUP, not a node — RemoveNodeCommand would
+                    // silently no-op and strand the children. Container removal is not
+                    // supported through the widget handle (yet); say so loudly.
+                    console.warn('[dashboard] remove() on a container is not supported');
+                    return;
+                }
                 const n = node();
-                const group = groups.get(viewId);
+                const group = ctx.boardGroups.get(viewId);
                 const b = binder();
                 if (!n || !group || !b)
                     return;
@@ -420,9 +499,12 @@ export function createDashboardHandle(ctx) {
                 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);
+                const arr = ctx.boardWidgets.get(viewId);
+                if (arr) {
+                    const i = arr.findIndex((w) => w.id === id);
+                    if (i >= 0)
+                        arr.splice(i, 1);
+                }
                 specById.delete(id);
                 viewOfWidget.delete(id);
                 b.sync();
@@ -440,7 +522,7 @@ export function createDashboardHandle(ctx) {
     return handle;
 }
 export function dashboard(options) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     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;
@@ -448,32 +530,54 @@ export function dashboard(options) {
     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))) }];
+        ? options.views.map((v) => (Object.assign(Object.assign({}, v), { widgets: cloneWidgets(v.widgets) })))
+        : [{ id: 'main', widgets: cloneWidgets((_f = options.widgets) !== null && _f !== void 0 ? _f : []) }];
     for (const v of views)
-        assignCells(v.widgets, (_g = v.columns) !== null && _g !== void 0 ? _g : columns);
+        assignCellsDeep(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) {
+    const boardWidgets = new Map();
+    const viewOfBoard = new Map();
+    // Recursive walk: a CONTAINER contributes no node (it becomes a group in
+    // finalize) but registers like a widget, and its children flatten into the
+    // render spec with the container as their board.
+    const flatten = (boardId, viewId, widgets) => {
+        for (const w of widgets) {
             specById.set(w.id, w);
-            viewOfWidget.set(w.id, v.id);
+            viewOfWidget.set(w.id, boardId);
+            if (w.widgets) {
+                boardWidgets.set(w.id, w.widgets);
+                viewOfBoard.set(w.id, viewId);
+                flatten(w.id, viewId, w.widgets);
+                continue;
+            }
+            pushWidgetNode(w);
+        }
+    };
+    const pushWidgetNode = (w) => {
+        var _a, _b;
+        {
             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 } }),
+                metadata: Object.assign(Object.assign({ useHTMLLayer: true, widgetKind: (_a = w.kind) !== null && _a !== void 0 ? _a : 'widget', widgetSpec: (_b = w.data) !== null && _b !== void 0 ? _b : {} }, (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 } }),
             });
         }
+    };
+    for (const v of views) {
+        boardWidgets.set(v.id, v.widgets);
+        viewOfBoard.set(v.id, v.id);
+        flatten(v.id, v.id, v.widgets);
     }
     // 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;
+    const renderWidget = (_h = options.renderWidget) !== null && _h !== void 0 ? _h : 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
@@ -486,6 +590,9 @@ export function dashboard(options) {
         binders: new Map(),
         specById,
         viewOfWidget,
+        boardGroups: new Map(),
+        boardWidgets,
+        viewOfBoard,
         hosts: new Map(),
         renderWidget,
         columns,
@@ -494,7 +601,7 @@ export function dashboard(options) {
         boardW,
         boardH,
         optionsBase: options,
-        active: (_m = (_l = views[0]) === null || _l === void 0 ? void 0 : _l.id) !== null && _m !== void 0 ? _m : 'main',
+        active: (_k = (_j = views[0]) === null || _j === void 0 ? void 0 : _j.id) !== null && _k !== void 0 ? _k : 'main',
         apiRef: null,
     };
     const { binders, groups } = ctx;
@@ -514,7 +621,7 @@ export function dashboard(options) {
             return handle;
         },
         finalize: (api) => {
-            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+            var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
             const a = api;
             if (!a)
                 return;
@@ -545,7 +652,77 @@ export function dashboard(options) {
                 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) {
+                ctx.boardGroups.set(v.id, g);
+                mountBoard(v.id, v.id, v.widgets, g);
+                binders.set(v.id, bindDashboardGrid(a, g, Object.assign(Object.assign(Object.assign({ columns: (_j = v.columns) !== null && _j !== void 0 ? _j : columns, gap, padding: gap, sizing: (_k = options.sizing) !== null && _k !== void 0 ? _k : 'fit', baseRowHeight: rowHeight, designHeight: (_l = v.height) !== null && _l !== void 0 ? _l : boardH, float: (_m = options.float) !== null && _m !== void 0 ? _m : false, rtl: (_o = options.rtl) !== null && _o !== void 0 ? _o : false }, (options.responsive ? { responsive: options.responsive } : {})), ((_p = options.binder) !== null && _p !== void 0 ? _p : {})), { onGesture: (e) => {
+                        var _a, _b;
+                        if (e.type === 'commit')
+                            reportLayoutChange(v.id);
+                        (_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);
+            return;
+            /**
+             * Mount one board's widgets into its group — and recurse for CONTAINERS.
+             * A container is a view's construction one level down: a frameless
+             * member group with a slab cell in the PARENT's grid, its own
+             * `dashboardBoard` metadata (so `fromDocument()` rebinds it like any
+             * board), and a second `bindDashboardGrid` on the same canvas — which
+             * registers it as a BinderPeer, so cross-boundary drag, deepest-wins
+             * hit-testing and the height-escalation ratchet all apply unchanged.
+             */
+            function mountBoard(boardId, viewId, widgets, boardGroup) {
+                var _a, _b, _c, _d, _e, _f;
+                for (const w of widgets) {
+                    if (w.widgets) {
+                        const innerColumns = innerColumnsOf(w);
+                        const innerRows = (_a = w.maxRows) !== null && _a !== void 0 ? _a : rowExtentOf(w.widgets);
+                        const cg = new GroupModel({ id: w.id, name: (_b = w.title) !== null && _b !== void 0 ? _b : w.id });
+                        model.addGroup(cg);
+                        cg.setMetadata('frameChrome', 'none');
+                        // Slab cells live in GROUP metadata (groups carry no GridItemConfig).
+                        cg.setMetadata('gridItem', gridItemFromCell({ x: w.x, y: w.y, w: w.span, h: w.rows }));
+                        // The container's own spec fields, persisted ON the group — a
+                        // reloaded document has no authored literal to read them from.
+                        cg.setMetadata('containerWidget', Object.assign(Object.assign(Object.assign(Object.assign({}, (w.kind !== undefined ? { kind: w.kind } : {})), (w.title !== undefined ? { title: w.title } : {})), { columns: innerColumns, maxRows: innerRows }), (w.data !== undefined ? { data: w.data } : {})));
+                        cg.setMetadata('dashboardBoard', {
+                            columns: innerColumns,
+                            gap,
+                            padding: 0,
+                            sizing: 'fit',
+                            baseRowHeight: rowHeight,
+                            // The slab's height is the PARENT's business — 0 hands it over,
+                            // which is what makes escalation grow the slab instead of the
+                            // container fighting its own frame.
+                            designHeight: 0,
+                            maxRows: innerRows,
+                            float: false,
+                            rtl: (_c = options.rtl) !== null && _c !== void 0 ? _c : false,
+                        });
+                        cg.size = { width: 100, height: rowHeight, depth: 0 };
+                        boardGroup.addMember(w.id);
+                        ctx.boardGroups.set(w.id, cg);
+                        mountBoard(w.id, viewId, w.widgets, cg);
+                        binders.set(w.id, bindDashboardGrid(a, cg, {
+                            columns: innerColumns,
+                            gap,
+                            padding: 0,
+                            sizing: 'fit',
+                            baseRowHeight: rowHeight,
+                            designHeight: 0,
+                            maxRows: innerRows,
+                            float: false,
+                            rtl: (_d = options.rtl) !== null && _d !== void 0 ? _d : false,
+                            onGesture: (e) => {
+                                var _a, _b;
+                                if (e.type === 'commit')
+                                    reportLayoutChange(viewId);
+                                (_b = (_a = options.binder) === null || _a === void 0 ? void 0 : _a.onGesture) === null || _b === void 0 ? void 0 : _b.call(_a, e);
+                            },
+                        }));
+                        continue;
+                    }
                     const n = model.getNode(w.id);
                     if (!n)
                         continue;
@@ -557,7 +734,7 @@ export function dashboard(options) {
                     // 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 }));
+                        n.setGridItem(gridItemFromCell({ x: w.x, y: w.y, w: (_e = w.span) !== null && _e !== void 0 ? _e : 3, h: (_f = w.rows) !== null && _f !== void 0 ? _f : 1 }));
                     }
                     if (w.pinned)
                         n.setState({ locked: true });
@@ -571,19 +748,24 @@ export function dashboard(options) {
                     n.setBehavior({ connectable: false });
                     for (const p of [...n.getPorts().values()])
                         n.removePort(p.id);
-                    g.addMember(w.id);
+                    boardGroup.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);
+            /**
+             * One reporter for every binder on a view — the view's own and each
+             * container's. The payload is the view's FULL NESTED TREE derived from
+             * live membership (handle.toJSON()), so an inner commit reports the same
+             * truth an outer one does, and a tile that crossed a boundary shows up
+             * under its NEW parent. (The old per-view lookup found nothing for a
+             * container binder and silently reported nothing.)
+             */
+            function reportLayoutChange(viewId) {
+                if (!options.onLayoutChange)
+                    return;
+                const snapshot = handle.toJSON().views.find((x) => x.id === viewId);
+                if (snapshot)
+                    options.onLayoutChange(viewId, snapshot.widgets);
+            }
         },
     };
 }

package/src/lib/dashboard-kit/grid-binder.js

@@ -1240,13 +1240,27 @@ export function bindDashboardGrid(api, group, options = {}) {
         id: `dashboard-grid:${group.id}:${++binderSeq}`,
         priority: 2, // point-specific claim — outranks mode-style tools (see ext/tools.ts)
         hitTest(ev, hit) {
-            var _a;
+            var _a, _b;
             if (disposed)
                 return false;
             if (gesture)
                 return true; // own the rest of an in-flight gesture
-            if (hit.node)
-                return ((_a = group.members) !== null && _a !== void 0 ? _a : new Set()).has(hit.node.id);
+            if (hit.node) {
+                if (((_a = group.members) !== null && _a !== void 0 ? _a : new Set()).has(hit.node.id))
+                    return true;
+                // A press on a tile that belongs to a NESTED board must reach that
+                // board's tool. The dead-zone claim below deadens the slab's EMPTY
+                // band — claiming a peer's tile with it swallowed every resize inside
+                // an API-built container (which binds child-before-parent, so the
+                // parent's tool won the registration-order tie and the child's resize
+                // never armed; grid-options binds parent-first and worked by
+                // accident).
+                for (const p of (_b = BOARD_REGISTRY.get(api.container)) !== null && _b !== void 0 ? _b : []) {
+                    if (p !== selfPeer && p.hasItem(hit.node.id))
+                        return false;
+                }
+                return insideMemberGroupFrame(ev.world.x, ev.world.y);
+            }
             // Claim (and deaden) empty presses inside a member group's frame so the
             // built-in group-drag cannot fight the pack layout for the KPI slab.
             return insideMemberGroupFrame(ev.world.x, ev.world.y);

package/src/lib/load.js

@@ -67,6 +67,7 @@ import { bindRowInteractions } from './diagram-kit/rows.js';
 import { bindCardEditing } from './diagram-kit/editing.js';
 import { ensureDiagramKitStyles } from './diagram-kit/styles.js';
 import { bindDashboardGrid } from './dashboard-kit/grid-binder.js';
+import { cellFromGridItem } from './dashboard-kit/grid-mapping.js';
 import { ensureDashboardKitStyles } from './dashboard-kit/styles.js';
 import { defaultWidgetRenderer } from './dashboard-kit/widgets.js';
 import { createDashboardHandle, } from './dashboard-kit/dashboard.js';
@@ -100,7 +101,7 @@ function widgetSpecOf(node) {
  * 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;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
     const parsed = typeof document === 'string' ? parseDocument(document) : document;
     const model = new DiagramSerializer().deserialize(parsed);
     const nodes = model.getNodes();
@@ -124,40 +125,79 @@ export function fromDocument(document, options = {}) {
     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 boardWidgets = new Map();
+    const viewOfBoard = new Map();
+    const boardGroups = new Map(dashGroups.map((g) => [g.id, g]));
+    // A CONTAINER is a dashboard group that is itself a MEMBER of another
+    // dashboard group; the rest are views. This is the whole nesting test —
+    // containment IS membership.
+    const containerIds = new Set();
+    for (const g of dashGroups) {
+        for (const m of (_b = g.members) !== null && _b !== void 0 ? _b : [])
+            if (boardGroups.has(m))
+                containerIds.add(m);
+    }
+    const rebuildBoard = (g, viewId) => {
+        var _a, _b;
         const widgets = [];
         for (const memberId of (_a = g.members) !== null && _a !== void 0 ? _a : []) {
+            const childGroup = boardGroups.get(memberId);
+            if (childGroup) {
+                // A nested container: its spec fields ride on the group, its cell in
+                // the group's slab `gridItem`, its children in its own membership.
+                const meta = ((_b = childGroup.getMetadata('containerWidget')) !== null && _b !== void 0 ? _b : {});
+                const cell = cellFromGridItem(childGroup.getMetadata('gridItem'));
+                const ws = Object.assign(Object.assign(Object.assign({ id: childGroup.id }, meta), (cell ? { x: cell.x, y: cell.y, span: cell.w, rows: cell.h } : {})), { widgets: rebuildBoard(childGroup, viewId) });
+                specById.set(ws.id, ws);
+                viewOfWidget.set(ws.id, g.id);
+                boardWidgets.set(ws.id, ws.widgets);
+                viewOfBoard.set(ws.id, viewId);
+                widgets.push(ws);
+                continue;
+            }
             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
+                continue;
             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 };
+        return widgets;
+    };
+    const viewGroups = dashGroups.filter((g) => !containerIds.has(g.id));
+    const ctxViews = viewGroups.map((g) => {
+        var _a, _b;
+        const board = g.getMetadata('dashboardBoard');
+        const widgets = rebuildBoard(g, g.id);
+        boardWidgets.set(g.id, widgets);
+        viewOfBoard.set(g.id, g.id);
+        return { id: g.id, name: g.name, widgets, columns: board.columns, width: (_a = g.size) === null || _a === void 0 ? void 0 : _a.width, height: (_b = g.size) === null || _b === void 0 ? void 0 : _b.height };
     });
-    const firstBoard = (_b = dashGroups[0]) === null || _b === void 0 ? void 0 : _b.getMetadata('dashboardBoard');
+    const firstBoard = (_c = viewGroups[0]) === null || _c === void 0 ? void 0 : _c.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 activeGroup = (_d = viewGroups.find((g) => g.position.x > -1000)) !== null && _d !== void 0 ? _d : viewGroups[0];
     const ctx = {
         views: ctxViews,
-        groups: new Map(dashGroups.map((g) => [g.id, g])),
+        // PARKING map: views only. A container must follow its parent when a view
+        // parks, not travel to OFFSCREEN_X on its own.
+        groups: new Map(viewGroups.map((g) => [g.id, g])),
         // The SAME map the LoadedDiagramSpec exposes as `boards` — derived, not a copy.
         binders: boards,
         specById,
         viewOfWidget,
+        boardGroups,
+        boardWidgets,
+        viewOfBoard,
         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,
+        columns: (_e = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.columns) !== null && _e !== void 0 ? _e : 12,
+        gap: (_f = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.gap) !== null && _f !== void 0 ? _f : 8,
+        rowHeight: (_g = firstBoard === null || firstBoard === void 0 ? void 0 : firstBoard.baseRowHeight) !== null && _g !== void 0 ? _g : 130,
+        boardW: (_k = (_j = (_h = viewGroups[0]) === null || _h === void 0 ? void 0 : _h.size) === null || _j === void 0 ? void 0 : _j.width) !== null && _k !== void 0 ? _k : 1180,
+        boardH: (_o = (_m = (_l = viewGroups[0]) === null || _l === void 0 ? void 0 : _l.size) === null || _m === void 0 ? void 0 : _m.height) !== null && _o !== void 0 ? _o : 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
@@ -168,11 +208,11 @@ export function fromDocument(document, options = {}) {
                 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,
+                width: (_q = (_p = viewGroups[0]) === null || _p === void 0 ? void 0 : _p.size) === null || _q === void 0 ? void 0 : _q.width,
+                height: (_s = (_r = viewGroups[0]) === null || _r === void 0 ? void 0 : _r.size) === null || _s === void 0 ? void 0 : _s.height,
             }
             : {},
-        active: (_s = activeGroup === null || activeGroup === void 0 ? void 0 : activeGroup.id) !== null && _s !== void 0 ? _s : 'main',
+        active: (_t = activeGroup === null || activeGroup === void 0 ? void 0 : activeGroup.id) !== null && _t !== void 0 ? _t : 'main',
         apiRef: null,
     };
     const handle = createDashboardHandle(ctx);