@grafloria/element 0.4.52 → 0.4.54

package/package.json

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

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

@@ -0,0 +1,82 @@
+/**
+ * THE COMMIT (tile first, step 4a) — what a gesture writes into history.
+ *
+ * Every gesture ends the same way: each board it touched reports the tiles
+ * whose cells or pixels differ from the snapshot taken when the gesture
+ * entered it, and those deltas become commands. A widget's cell is on its
+ * node (`SetGridItemCommand`, then the pixel move and resize the projection
+ * derived); a container's cell is on its GROUP, together with the frame the
+ * projection wrote. Both come out of ONE function here. Before this the node
+ * path skipped groups "by design" and every site that could have displaced
+ * a section rebuilt the group command by hand — six of them — and the one
+ * that did not (the cross-board drop) dropped the target board's pushed
+ * sections on the floor: the drop drew the push and never persisted it.
+ */
+import { Command } from '@grafloria/engine';
+import { type CellRect, type TileDelta, type WorldRect } from './grid-mapping.js';
+/**
+ * A CONTAINER's cell lives in its group's metadata and its frame is what the
+ * projection wrote for that cell: one command sets both, and undo puts both
+ * back. (A node's cell rides on the node itself — see `buildCommitCommands`.)
+ */
+export declare class SetGroupCellCommand extends Command {
+    private groupId;
+    private cellBefore;
+    private cellAfter;
+    private frameBefore;
+    private frameAfter;
+    constructor(groupId: string, cellBefore: CellRect, cellAfter: CellRect, frameBefore: WorldRect, frameAfter: WorldRect);
+    private apply;
+    execute(context: {
+        diagram?: unknown;
+    }): void;
+    undo(context: {
+        diagram?: unknown;
+    }): void;
+    serialize(): {
+        id: string;
+        name: string;
+        timestamp: number;
+        data: {
+            groupId: string;
+            cellBefore: CellRect;
+            cellAfter: CellRect;
+            frameBefore: WorldRect;
+            frameAfter: WorldRect;
+        };
+    };
+}
+/**
+ * Steps that depend on each other's RESULT — create a group, then move a page
+ * into it, then place the group on the board; or remove a member and then the
+ * group it emptied — run as one history step. A batch checks every member's
+ * `canExecute` before running any of them and every member's `canUndo` before
+ * undoing any, and a membership command's precondition (its group exists) is
+ * exactly what a neighbouring step creates or removes. This runs the chain in
+ * order and reverses it on undo, judging nothing up front.
+ */
+export declare class SequenceCommand extends Command {
+    private steps;
+    constructor(name: string, steps: Command[]);
+    execute(context: Parameters<Command['execute']>[0]): void;
+    undo(context: Parameters<Command['undo']>[0]): void;
+    canExecute(): boolean;
+    canUndo(): boolean;
+    serialize(): {
+        id: string;
+        name: string;
+        timestamp: number;
+        data: {
+            steps: import("@grafloria/engine").SerializedCommand[];
+        };
+    };
+}
+/**
+ * The commands for every tile a board's deltas say moved — nodes AND groups,
+ * in the deltas' order. A node's commands are its cell then its pixels; a
+ * group's is one cell-and-frame command. A delta whose cell did not change
+ * contributes nothing for a group (its frame follows its cell), and only the
+ * pixel commands for a node (a fit board re-projects every tile when a row
+ * comes or goes: the cells stand, the pixels move).
+ */
+export declare function tileCommands(deltas: TileDelta[]): Command[];

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

@@ -0,0 +1,121 @@
+/**
+ * THE COMMIT (tile first, step 4a) — what a gesture writes into history.
+ *
+ * Every gesture ends the same way: each board it touched reports the tiles
+ * whose cells or pixels differ from the snapshot taken when the gesture
+ * entered it, and those deltas become commands. A widget's cell is on its
+ * node (`SetGridItemCommand`, then the pixel move and resize the projection
+ * derived); a container's cell is on its GROUP, together with the frame the
+ * projection wrote. Both come out of ONE function here. Before this the node
+ * path skipped groups "by design" and every site that could have displaced
+ * a section rebuilt the group command by hand — six of them — and the one
+ * that did not (the cross-board drop) dropped the target board's pushed
+ * sections on the floor: the drop drew the push and never persisted it.
+ */
+import { Command } from '@grafloria/engine';
+import { buildCommitCommands, gridItemFromCell } from './grid-mapping.js';
+/**
+ * A CONTAINER's cell lives in its group's metadata and its frame is what the
+ * projection wrote for that cell: one command sets both, and undo puts both
+ * back. (A node's cell rides on the node itself — see `buildCommitCommands`.)
+ */
+export class SetGroupCellCommand extends Command {
+    constructor(groupId, cellBefore, cellAfter, frameBefore, frameAfter) {
+        super('Resize section');
+        this.groupId = groupId;
+        this.cellBefore = cellBefore;
+        this.cellAfter = cellAfter;
+        this.frameBefore = frameBefore;
+        this.frameAfter = frameAfter;
+    }
+    apply(context, cell, frame) {
+        const diagram = context.diagram;
+        const grp = diagram === null || diagram === void 0 ? void 0 : diagram.getGroup(this.groupId);
+        if (!grp)
+            return;
+        grp.setMetadata('gridItem', gridItemFromCell(cell));
+        grp.setFrame(Object.assign({}, frame));
+    }
+    execute(context) {
+        this.apply(context, this.cellAfter, this.frameAfter);
+    }
+    undo(context) {
+        this.apply(context, this.cellBefore, this.frameBefore);
+    }
+    serialize() {
+        return {
+            id: this.id,
+            name: this.name,
+            timestamp: this.timestamp,
+            data: {
+                groupId: this.groupId,
+                cellBefore: this.cellBefore,
+                cellAfter: this.cellAfter,
+                frameBefore: this.frameBefore,
+                frameAfter: this.frameAfter,
+            },
+        };
+    }
+}
+/**
+ * Steps that depend on each other's RESULT — create a group, then move a page
+ * into it, then place the group on the board; or remove a member and then the
+ * group it emptied — run as one history step. A batch checks every member's
+ * `canExecute` before running any of them and every member's `canUndo` before
+ * undoing any, and a membership command's precondition (its group exists) is
+ * exactly what a neighbouring step creates or removes. This runs the chain in
+ * order and reverses it on undo, judging nothing up front.
+ */
+export class SequenceCommand extends Command {
+    constructor(name, steps) {
+        super(name);
+        this.steps = steps;
+    }
+    execute(context) {
+        for (const c of this.steps)
+            c.execute(context);
+    }
+    undo(context) {
+        for (let i = this.steps.length - 1; i >= 0; i--)
+            this.steps[i].undo(context);
+    }
+    canExecute() {
+        return true;
+    }
+    canUndo() {
+        return true;
+    }
+    serialize() {
+        return { id: this.id, name: this.name, timestamp: this.timestamp, data: { steps: this.steps.map((c) => c.serialize()) } };
+    }
+}
+const sameCell = (a, b) => a.x === b.x && a.y === b.y && a.w === b.w && a.h === b.h;
+/** The frame a delta's pixels describe — a group's frame is its position and size in the model. */
+const frameOf = (pos, size) => ({
+    x: pos.x,
+    y: pos.y,
+    width: size.width,
+    height: size.height,
+});
+/**
+ * The commands for every tile a board's deltas say moved — nodes AND groups,
+ * in the deltas' order. A node's commands are its cell then its pixels; a
+ * group's is one cell-and-frame command. A delta whose cell did not change
+ * contributes nothing for a group (its frame follows its cell), and only the
+ * pixel commands for a node (a fit board re-projects every tile when a row
+ * comes or goes: the cells stand, the pixels move).
+ */
+export function tileCommands(deltas) {
+    const out = [];
+    for (const d of deltas) {
+        if (d.isGroup) {
+            if (sameCell(d.cellBefore, d.cellAfter))
+                continue;
+            out.push(new SetGroupCellCommand(d.id, d.cellBefore, d.cellAfter, frameOf(d.posBefore, d.sizeBefore), frameOf(d.posAfter, d.sizeAfter)));
+            continue;
+        }
+        out.push(...buildCommitCommands([d]));
+    }
+    return out;
+}
+//# sourceMappingURL=commit.js.map

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

@@ -411,9 +411,17 @@ export interface DashboardHandle {
     /**
      * Add a widget to a view. CREATES the node (you do not pre-build one), wires
      * its metadata, and commits node + membership as ONE undoable step.
-     * Auto-positions when the spec names no cell.
-     */
-    addWidget(spec: DashboardWidgetSpec, viewId?: string): WidgetHandle | undefined;
+     * Auto-positions when the spec names no cell. `opts.displaced`: the
+     * commands a palette drop handed `onDropIn` for the tiles the placeholder
+     * pushed aside — folded into the same step, so the widget lands on the cell
+     * the drop showed and undo puts the pushed tiles back with it. Left out,
+     * the board is re-read from the model and the push is forgotten: the new
+     * widget then auto-positions into whatever hole is left (Quantia's "lands
+     * on the cell it was aimed at", element 0.4.54).
+     */
+    addWidget(spec: DashboardWidgetSpec, viewId?: string, opts?: {
+        displaced?: Command[];
+    }): WidgetHandle | undefined;
     /**
      * Re-read every board from the model — call after undo/redo, or any
      * out-of-band mutation, so the grid and the projection agree again.

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

@@ -1575,8 +1575,8 @@ export function createDashboardHandle(ctx) {
             (_a = ctx.apiRef) === null || _a === void 0 ? void 0 : _a.renderNow();
         },
         getDragHandle: () => { var _a, _b, _c; return (_b = (_a = binders.get(ctx.active)) === null || _a === void 0 ? void 0 : _a.getDragHandle()) !== null && _b !== void 0 ? _b : ((_c = ctx.optionsBase.dragHandle) !== null && _c !== void 0 ? _c : false); },
-        addWidget(spec, viewId) {
-            var _a, _b, _c, _d, _e, _f;
+        addWidget(spec, viewId, opts) {
+            var _a, _b, _c, _d, _e, _f, _g;
             const vid = viewId !== null && viewId !== void 0 ? viewId : ctx.active;
             // `vid` may name a view OR a container — both are boards with a group,
             // a binder and an authored array.
@@ -1601,10 +1601,15 @@ export function createDashboardHandle(ctx) {
             const node = existing !== null && existing !== void 0 ? existing : buildWidgetNode(w, ctx.rowHeight);
             if (w.pinned)
                 node.setState({ locked: true });
-            // ONE undoable step, registration included (see AddWidgetCommand).
-            execCommand(new AddWidgetCommand(node, group.id, registry, !!existing));
-            (_e = binders.get(vid)) === null || _e === void 0 ? void 0 : _e.sync();
-            (_f = ctx.apiRef) === null || _f === void 0 ? void 0 : _f.renderNow();
+            // ONE undoable step, registration included (see AddWidgetCommand). The
+            // tiles a drop pushed aside ride in front of it, in a SEQUENCE: a batch
+            // runs its members across awaits, and the board is re-read right after
+            // this call — the pushed cells must be in the model by then.
+            const add = new AddWidgetCommand(node, group.id, registry, !!existing);
+            const displaced = (_e = opts === null || opts === void 0 ? void 0 : opts.displaced) !== null && _e !== void 0 ? _e : [];
+            execCommand(displaced.length > 0 ? new SequenceCommand('Add widget', [...displaced, add]) : add);
+            (_f = binders.get(vid)) === null || _f === void 0 ? void 0 : _f.sync();
+            (_g = ctx.apiRef) === null || _g === void 0 ? void 0 : _g.renderNow();
             return makeWidgetHandle(w.id);
         },
         refresh() {

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

@@ -52,6 +52,8 @@
 import { Command, type DiagramModel, type GridColumnLayout, type GroupModel, type NodeModel } from '@grafloria/engine';
 import { type ToolPointerEvent } from '@grafloria/renderer';
 import { type CellRect, type WorldRect } from './grid-mapping.js';
+import { type BesideSide } from './zones.js';
+export { SequenceCommand, SetGroupCellCommand } from './commit.js';
 /** The slice of a DiagramInstance the binder needs (structural, test-friendly). */
 export interface DashboardGridApi {
     getModel(): DiagramModel;
@@ -184,10 +186,13 @@ export interface DashboardGridOptions {
     onRemoveRequest?: (nodeId: string, displaced: Command[]) => void | Promise<void>;
     /**
      * Page hook for palette drag-in release: add `node` (already carrying
-     * `cell` in its gridItem, already placed in the engine) through the page's
-     * command path, folding `displaced` into the same batch.
+     * `cell` in its gridItem) to `target.boardId` — this view, or a page or
+     * section the chip was dropped into (tile first, step 4a) — through the
+     * page's command path, folding `displaced` into the same batch.
      */
-    onDropIn?: (node: NodeModel, cell: CellRect, displaced: Command[]) => void | Promise<void>;
+    onDropIn?: (node: NodeModel, cell: CellRect, displaced: Command[], target: {
+        boardId: string;
+    }) => void | Promise<void>;
     /**
      * A member is about to LEAVE this board through a gesture (moved into
      * another board, made a tab of its own). Answers the commands that follow
@@ -595,31 +600,6 @@ export interface TearOutPlan {
 }
 /** A torn-out page never arrives shorter than this: a strip with no room under it is not a group. */
 export declare const TEAR_OUT_MIN_ROWS = 2;
-/**
- * Steps that depend on each other's RESULT — create a group, then move a page
- * into it, then place the group on the board; or remove a member and then the
- * group it emptied — run as one history step. A batch checks every member's
- * `canExecute` before running any of them and every member's `canUndo` before
- * undoing any, and a membership command's precondition (its group exists) is
- * exactly what a neighbouring step creates or removes. This runs the chain in
- * order and reverses it on undo, judging nothing up front.
- */
-export declare class SequenceCommand extends Command {
-    private steps;
-    constructor(name: string, steps: Command[]);
-    execute(context: Parameters<Command['execute']>[0]): void;
-    undo(context: Parameters<Command['undo']>[0]): void;
-    canExecute(): boolean;
-    canUndo(): boolean;
-    serialize(): {
-        id: string;
-        name: string;
-        timestamp: number;
-        data: {
-            steps: import("@grafloria/engine").SerializedCommand[];
-        };
-    };
-}
 /**
  * A WIDGET dropped on a tab strip becomes a new tab there (a tab dropped on
  * one joins; a widget wraps into a page of its own first). The dashboard
@@ -646,14 +626,35 @@ interface AdoptOptions {
     fit?: 'shrink';
     /** Anchor the tile's TOP edge at the pointer instead of centring it (the pointer holds a tab, the page hangs below it). */
     anchor?: 'top';
+    /** Enter WITH INTENT: the tile takes the cell under the hand and pushes the solid tiles there (D2 — a section this board holds refused it). */
+    push?: boolean;
+    /** Enter BESIDE a container of this board: the container gives way, the tile takes the band's side at the pointer's row. */
+    beside?: {
+        containerId: string;
+        side: BesideSide;
+    };
 }
 interface AdoptedLeg {
     groupId: string;
-    /** Drive the target engine from the source binder's pointer stream. */
+    /** Drive the target engine from the source binder's pointer stream. `push`: the tile means it — solid tiles under the wanted cell are pushed (D2). */
     move(world: {
         x: number;
         y: number;
+    }, opts?: {
+        push?: boolean;
+    }): void;
+    /** Put the tile BESIDE `containerId` on this board, at the row under `world` — the container shifts or the tiles behind it are pushed; a repeat at the same row is a no-op. */
+    beside(containerId: string, side: BesideSide, world: {
+        x: number;
+        y: number;
     }): void;
+    /** The beside this board holds for the tile, for the zone resolve's stickiness: the container's frame at rest and the cell the tile took — null when none. */
+    besideState(): {
+        containerId: string;
+        side: BesideSide;
+        frame0: WorldRect;
+        vacated: WorldRect;
+    } | null;
     /**
      * Take the tile OFF the board while the pointer is somewhere the board is
      * not the target (over a group the page will join instead); the tiles it
@@ -680,22 +681,14 @@ interface AdoptedLeg {
     /** Undo the adoption: target board back to its pre-entry layout. */
     abort(): void;
     /**
-     * Close the leg for commit: returns the target-side displaced commands, the
-     * tile's final cell and its projected rect — and the member GROUPS the
-     * adoption moved (the node commands skip groups; a dock that pushed sections
-     * commits them through these). Null when the tile is somehow gone.
+     * Close the leg for commit: the target board's displaced commands (widgets
+     * and sections alike), the tile's final cell and its projected rect. Null
+     * when the tile is somehow gone.
      */
     finalize(): {
         commands: Command[];
         cell: CellRect;
         rect: WorldRect;
-        groups: Array<{
-            id: string;
-            cellBefore: CellRect;
-            cellAfter: CellRect;
-            frameBefore: WorldRect;
-            frameAfter: WorldRect;
-        }>;
     } | null;
 }
 /**