@woosh/meep-engine 2.169.4 → 2.170.0

package/src/view/layout/DockLayoutView.js

@@ -0,0 +1,1193 @@
+import Signal from "../../core/events/signal/Signal.js";
+import { clamp } from "../../core/math/clamp.js";
+import { MouseEvents } from "../../engine/input/devices/events/MouseEvents.js";
+import { DraggableAspect } from "../../engine/ui/DraggableAspect.js";
+import LabelView from "../common/LabelView.js";
+import { TAB_STRIP_HEIGHT, TabDefinition } from "../common/TabbedView.js";
+import { CSS_ABSOLUTE_POSITIONING } from "../CSS_ABSOLUTE_POSITIONING.js";
+import EmptyView from "../elements/EmptyView.js";
+import View from "../View.js";
+import { DockDragOverlayView } from "./DockDragOverlayView.js";
+import { DockDropPlan } from "./DockDropPlan.js";
+import { DockGroupNode } from "./DockGroupNode.js";
+import { dock_side_direction, dock_side_half, dock_side_title, DOCK_SPLIT_SIDES, DockSide } from "./DockSide.js";
+import { DockSplitNode } from "./DockSplitNode.js";
+import { FloatingPanelView } from "./FloatingPanelView.js";
+import { show_popup_menu } from "./show_popup_menu.js";
+
+/**
+ * Size a panel's window takes the first time it floats, px
+ * @type {number}
+ */
+const FLOAT_DEFAULT_WIDTH = 360;
+
+/**
+ * @type {number}
+ */
+const FLOAT_DEFAULT_HEIGHT = 300;
+
+/**
+ * How much of a group's edge means "out of the layout" rather than "into this group", px.
+ *
+ * Without it the groups tile the dock and every point in it is a placement, which leaves
+ * an author who wants a panel out of the layout nowhere to let go of it. The seams between
+ * groups, and the outside edge of the dock, are where a drop floats instead.
+ * @type {number}
+ */
+const NEUTRAL_MARGIN = 26;
+
+/**
+ * The margin is capped at this share of a group's extent, so that a small group stays
+ * something that can be dropped into rather than a solid band of "no".
+ * @type {number}
+ */
+const NEUTRAL_MARGIN_MAX_FRACTION = 0.2;
+
+/**
+ * How near an edge of a group counts as asking to split it, as a share of the group's
+ * extent along that axis
+ * @type {number}
+ */
+const SPLIT_BAND_FRACTION = 0.3;
+
+/**
+ * Where the dock keeps a panel, and where it would put it if it floated.
+ *
+ * The two placements are exclusive: a panel has a tab in a group, or it stands in a
+ * window, never both. The float rectangle is carried either way, so a panel that is docked
+ * and floated again comes back the size it was.
+ */
+class DockPanelRecord {
+    /**
+     * The group holding the panel, null while it floats or is between placements
+     * @type {DockGroupNode|null}
+     */
+    group = null;
+
+    /**
+     * The panel's tab in that group, null while it floats
+     * @type {TabDefinition|null}
+     */
+    definition = null;
+
+    /**
+     * The window holding the panel, null while it is docked
+     * @type {FloatingPanelView|null}
+     */
+    window = null;
+
+    /**
+     * @type {number}
+     */
+    float_x = 0;
+
+    /**
+     * @type {number}
+     */
+    float_y = 0;
+
+    /**
+     * @type {number}
+     */
+    float_width = FLOAT_DEFAULT_WIDTH;
+
+    /**
+     * @type {number}
+     */
+    float_height = FLOAT_DEFAULT_HEIGHT;
+}
+
+/**
+ * A docking layout: a tree of tab groups divided by draggable splitters, with panels that
+ * can also stand outside the tree in windows of their own.
+ *
+ * There are no fixed zones. A panel dropped on the middle of a group, or on its tab strip,
+ * joins it as a tab; dropped near one of the group's four edges it splits the group and
+ * takes that side, which is how a layout grows a sidebar, a bottom drawer or a second
+ * editor column without any of those being built in. A group that loses its last panel is
+ * folded away and its other half takes the room back — except for the last group in the
+ * dock, which stays, so there is always somewhere to drop.
+ *
+ * Every group keeps a margin around it where a drop leaves the layout altogether and puts
+ * the panel in a window. A floating panel's title bar carries its tab: drag the tab and the
+ * panel docks the way it always did, drag the bar beside it and the window simply moves.
+ *
+ * Moving a panel is an unlink→relink cycle for its view — panel content must rebuild from
+ * its model on link, which is the framework-wide convention.
+ */
+export class DockLayoutView extends View {
+    /**
+     * @type {Map<DockPanel, DockPanelRecord>}
+     */
+    #panels = new Map();
+
+    /**
+     * @type {DockGroupNode|DockSplitNode}
+     */
+    #root;
+
+    /**
+     * Hosts the tree, under the floating windows
+     * @type {EmptyView}
+     */
+    #tree_host;
+
+    /**
+     * Hosts the windows of floating panels, above the tree and below the drag feedback
+     * @type {EmptyView}
+     */
+    #float_layer;
+
+    /**
+     * @type {DockDragOverlayView}
+     */
+    #drag_overlay;
+
+    /**
+     * Stacking order handed to the last window to come forward. Windows are stacked by
+     * this rather than by their order in the layer, so bringing one forward costs a style
+     * write instead of a re-parent — a re-parent would unlink and rebuild the panel inside.
+     * @type {number}
+     */
+    #float_order = 0;
+
+    el = document.createElement('div');
+
+    constructor() {
+        super();
+
+        this.addClass('meep-dock-layout');
+
+        this.#tree_host = new EmptyView({ classList: ['meep-dock-tree'] });
+        this.#tree_host.css(CSS_ABSOLUTE_POSITIONING);
+
+        // both layers cover the tree rather than following it, so they are taken out of the
+        // flow the splitters occupy
+        this.#float_layer = new EmptyView({ classList: ['meep-dock-float-layer'] });
+        this.#float_layer.css(CSS_ABSOLUTE_POSITIONING);
+
+        this.#drag_overlay = new DockDragOverlayView();
+        this.#drag_overlay.css(CSS_ABSOLUTE_POSITIONING);
+
+        this.addChild(this.#tree_host);
+        this.addChild(this.#float_layer);
+        this.addChild(this.#drag_overlay);
+
+        /**
+         * Raised whenever the user rearranges the layout — a panel moves, a divider is
+         * dragged, a window is moved or resized. A host that persists the arrangement saves
+         * on this; it deliberately does not fire for reflows, which happen constantly.
+         * @type {Signal}
+         */
+        this.on.rearranged = new Signal();
+
+        this.#root = new DockGroupNode();
+        this.#root.view.css(CSS_ABSOLUTE_POSITIONING);
+        this.#tree_host.addChild(this.#root.view);
+
+        this.layout();
+
+        this.bindSignal(this.size.onChanged, this.layout, this);
+        this.on.linked.add(this.layout, this);
+    }
+
+    /**
+     * Put a panel in the dock's first group — the one reached going down the a-side of the
+     * tree. This is how a host seeds a layout, and where a panel with nowhere else to be
+     * ends up.
+     *
+     * @param {DockPanel} panel
+     */
+    addPanel(panel) {
+        this.#placePanel(panel, this.#firstGroup(), DockSide.Center, 0);
+    }
+
+    /**
+     * Put a panel in the same group as one that is already docked, as another tab.
+     *
+     * @param {DockPanel} panel
+     * @param {DockPanel} neighbour
+     */
+    tabPanel(panel, neighbour) {
+        this.#placePanel(panel, this.#requireGroupOf(neighbour), DockSide.Center, 0);
+    }
+
+    /**
+     * Put a panel in a group of its own on one side of the group holding `neighbour`,
+     * splitting that group in two.
+     *
+     * @param {DockPanel} panel
+     * @param {DockPanel} neighbour
+     * @param {string} side one of {@link DOCK_SPLIT_SIDES}
+     * @param {number} extent extent of the new group along the split's axis, px
+     */
+    splitPanel(panel, neighbour, side, extent) {
+        if (!DOCK_SPLIT_SIDES.includes(side)) {
+            throw new Error(`Side '${side}' does not split anything, valid sides: ${DOCK_SPLIT_SIDES.join(', ')}`);
+        }
+
+        this.#placePanel(panel, this.#requireGroupOf(neighbour), side, extent);
+    }
+
+    /**
+     * Lift a panel out of the layout into a window of its own, or move the window it is
+     * already in. The rectangle is in the dock's own frame, px.
+     *
+     * @param {DockPanel} panel
+     * @param {number} x
+     * @param {number} y
+     * @param {number} width
+     * @param {number} height
+     */
+    floatPanel(panel, x, y, width, height) {
+        const record = this.#requireRecord(panel);
+
+        record.float_x = x;
+        record.float_y = y;
+        record.float_width = width;
+        record.float_height = height;
+
+        if (record.window !== null) {
+            // already out: this is the author moving or resizing the window they have
+            record.window.position.set(x, y);
+            record.window.size.set(width, height);
+
+            this.on.rearranged.send0();
+
+            return;
+        }
+
+        this.#detach(panel);
+
+        const window_view = new FloatingPanelView({
+            handle: this.#buildHandle(panel),
+            content: panel.view
+        });
+
+        record.window = window_view;
+
+        window_view.on.moved.add(() => {
+            record.float_x = window_view.position.x;
+            record.float_y = window_view.position.y;
+
+            this.on.rearranged.send0();
+        });
+
+        window_view.on.resized.add(() => {
+            record.float_width = window_view.size.x;
+            record.float_height = window_view.size.y;
+
+            this.on.rearranged.send0();
+        });
+
+        window_view.on.raiseRequested.add(() => this.#raiseWindow(window_view));
+
+        // a window the author has just put somewhere is a window they are looking at
+        this.#raiseWindow(window_view);
+
+        window_view.position.set(x, y);
+        window_view.size.set(width, height);
+
+        this.#float_layer.addChild(window_view);
+
+        this.on.rearranged.send0();
+    }
+
+    /**
+     * Take a panel out of the dock altogether.
+     *
+     * @param {DockPanel} panel
+     */
+    removePanel(panel) {
+        this.#detach(panel);
+
+        this.#panels.delete(panel);
+
+        this.on.rearranged.send0();
+    }
+
+    /**
+     *
+     * @param {DockPanel} panel
+     * @returns {boolean} whether the panel stands in a window of its own
+     */
+    isPanelFloating(panel) {
+        return this.#requireRecord(panel).window !== null;
+    }
+
+    /**
+     *
+     * @param {DockPanel} panel
+     * @returns {boolean} whether the dock holds this panel at all
+     */
+    hasPanel(panel) {
+        return this.#panels.has(panel);
+    }
+
+    /**
+     * Capture where the user put things, so a later session can put them back. Panels are
+     * recorded by {@link DockPanel#id} — the only thing about a panel that survives a
+     * reload; the views themselves are rebuilt by the host.
+     *
+     * @returns {{layout: Object, panels: {id: string, floating: boolean, float: {x: number, y: number, width: number, height: number}}[]}}
+     */
+    toJSON() {
+        const panels = [];
+
+        for (const [panel, record] of this.#panels) {
+            panels.push({
+                id: panel.id,
+                floating: record.window !== null,
+                float: {
+                    x: record.float_x,
+                    y: record.float_y,
+                    width: record.float_width,
+                    height: record.float_height
+                }
+            });
+        }
+
+        return {
+            layout: this.#nodeToJSON(this.#root),
+            panels
+        };
+    }
+
+    /**
+     * Restore a layout captured by {@link DockLayoutView#toJSON} onto a dock the host has
+     * already populated. Panels are matched by id and put back where they were; an id this
+     * build no longer has is skipped, and a panel this build has that the arrangement never
+     * mentioned lands in the first group, where it can be found and moved. Layouts outlive
+     * the code that wrote them, and a stale entry is not a reason to drop the whole thing.
+     *
+     * An arrangement written by a build whose layout had a different shape — one carrying no
+     * `layout` tree at all — is left alone rather than guessed at: the host's own defaults
+     * are a better answer than a mistranslation.
+     *
+     * @param {{layout: Object, panels: {id: string, floating: boolean, float: {x: number, y: number, width: number, height: number}}[]}} json
+     */
+    fromJSON(json) {
+        if (json.layout === undefined) {
+            return;
+        }
+
+        const by_id = new Map();
+
+        for (const panel of this.#panels.keys()) {
+            by_id.set(panel.id, panel);
+        }
+
+        for (const entry of json.panels) {
+            const panel = by_id.get(entry.id);
+
+            if (panel === undefined) {
+                continue;
+            }
+
+            const record = this.#panels.get(panel);
+
+            record.float_x = entry.float.x;
+            record.float_y = entry.float.y;
+            record.float_width = entry.float.width;
+            record.float_height = entry.float.height;
+        }
+
+        // a clean slate: every panel comes off, which folds the tree down to its last group
+        for (const panel of [...this.#panels.keys()]) {
+            this.#detach(panel);
+        }
+
+        this.#restoreInto(json.layout, by_id, this.#firstGroup());
+
+        for (const entry of json.panels) {
+            const panel = by_id.get(entry.id);
+
+            if (panel === undefined || !entry.floating) {
+                continue;
+            }
+
+            const record = this.#panels.get(panel);
+
+            this.floatPanel(panel, record.float_x, record.float_y, record.float_width, record.float_height);
+        }
+
+        // whatever the arrangement did not speak for is still the host's, and still has to be
+        // somewhere the author can reach it
+        for (const [panel, record] of this.#panels) {
+            if (record.group === null && record.window === null) {
+                this.#dockIntoGroup(panel, this.#firstGroup(), DockSide.Center, 0);
+            }
+        }
+
+        this.layout();
+    }
+
+    /**
+     * Carry out a placement and account for it: the panel is registered if it is new,
+     * brought to the front of its group if it was already somewhere (a panel arriving for
+     * the first time does not push aside what the host put there before it), and the
+     * rearrangement is announced once.
+     *
+     * @param {DockPanel} panel
+     * @param {DockGroupNode} group
+     * @param {string} side one of {@link DockSide}
+     * @param {number} extent extent of the new group along the split's axis, px
+     */
+    #placePanel(panel, group, side, extent) {
+        let record = this.#panels.get(panel);
+
+        if (record === undefined) {
+            record = new DockPanelRecord();
+
+            this.#panels.set(panel, record);
+        }
+
+        const was_placed = record.group !== null || record.window !== null;
+
+        if (record.group === group) {
+            // Landing back on its own group is a placement only when the panel leaves that
+            // group behind — and a panel that is the whole group cannot: taking it out folds
+            // the group away, target and all.
+            if (side === DockSide.Center || group.panels.length === 1) {
+                return;
+            }
+        }
+
+        this.#dockIntoGroup(panel, group, side, extent);
+
+        if (was_placed) {
+            record.group.view.activate(record.definition);
+        }
+
+        this.on.rearranged.send0();
+    }
+
+    /**
+     *
+     * @param {DockPanel} panel
+     * @returns {DockPanelRecord}
+     */
+    #requireRecord(panel) {
+        const record = this.#panels.get(panel);
+
+        if (record === undefined) {
+            throw new Error(`Panel '${panel.id}' is not docked`);
+        }
+
+        return record;
+    }
+
+    /**
+     *
+     * @param {DockPanel} panel
+     * @returns {DockGroupNode}
+     */
+    #requireGroupOf(panel) {
+        const record = this.#requireRecord(panel);
+
+        if (record.group === null) {
+            throw new Error(`Panel '${panel.id}' is floating, so there is no group to place anything beside it in`);
+        }
+
+        return record.group;
+    }
+
+    /**
+     * The group a panel with nowhere in particular to go belongs in: the first leaf of the
+     * tree, reading it from the root down its a-sides.
+     *
+     * @returns {DockGroupNode}
+     */
+    #firstGroup() {
+        let node = this.#root;
+
+        while (node instanceof DockSplitNode) {
+            node = node.a;
+        }
+
+        return node;
+    }
+
+    /**
+     *
+     * @param {DockGroupNode|DockSplitNode} node
+     * @param {DockGroupNode[]} result
+     */
+    #collectGroups(node, result) {
+        if (node instanceof DockSplitNode) {
+            this.#collectGroups(node.a, result);
+            this.#collectGroups(node.b, result);
+
+            return;
+        }
+
+        result.push(node);
+    }
+
+    /**
+     * @returns {DockGroupNode[]} every group in the layout, in tree order
+     */
+    #groups() {
+        const result = [];
+
+        this.#collectGroups(this.#root, result);
+
+        return result;
+    }
+
+    /**
+     * Take a panel out of wherever it currently is, leaving its view unlinked and
+     * parentless. A group emptied by this is folded away, so it must not be one the caller
+     * still means to place into.
+     *
+     * @param {DockPanel} panel
+     */
+    #detach(panel) {
+        const record = this.#requireRecord(panel);
+
+        if (record.window !== null) {
+            const window_view = record.window;
+
+            record.window = null;
+
+            // removal unlinks the frame and the panel view with it; the frame then lets go of
+            // the views it borrowed, so they can be re-parented
+            this.#float_layer.removeChild(window_view);
+            window_view.release();
+
+            return;
+        }
+
+        if (record.group === null) {
+            return;
+        }
+
+        const group = record.group;
+
+        const was_active = record.definition.active.getValue();
+
+        group.tabs.removeOneOf(record.definition);
+        group.panels.splice(group.panels.indexOf(panel), 1);
+
+        record.group = null;
+        record.definition = null;
+
+        if (was_active && group.tabs.length > 0) {
+            group.view.activate(group.tabs.get(0));
+        }
+
+        if (group.panels.length === 0) {
+            this.#collapseGroup(group);
+        }
+    }
+
+    /**
+     * Fold away a group that holds nothing: its other half takes the room back. The last
+     * group in the dock stays, empty — a layout with nowhere to drop into is a dead end.
+     *
+     * @param {DockGroupNode} group
+     */
+    #collapseGroup(group) {
+        const split = group.parent;
+
+        if (split === null) {
+            return;
+        }
+
+        const sibling = split.a === group ? split.b : split.a;
+
+        // hand the sibling back before the split it belonged to leaves the tree
+        split.view.removeChild(sibling.view);
+
+        this.#replaceNode(split, sibling);
+    }
+
+    /**
+     * Put a detached panel into a group, either alongside its panels or in a new group
+     * splitting it.
+     *
+     * @param {DockPanel} panel
+     * @param {DockGroupNode} group
+     * @param {string} side one of {@link DockSide}
+     * @param {number} extent extent of the new group along the split's axis, px
+     */
+    #dockIntoGroup(panel, group, side, extent) {
+        this.#detach(panel);
+
+        if (side === DockSide.Center) {
+            this.#addToGroup(panel, group);
+
+            return;
+        }
+
+        this.#addToGroup(panel, this.#splitGroup(group, side, extent, dock_side_half(side)));
+    }
+
+    /**
+     * Divide a group in two, returning the empty new half. The caller fills it; a half left
+     * empty would sit there for ever, since only losing a panel folds a group away.
+     *
+     * @param {DockGroupNode} group
+     * @param {string} side one of {@link DOCK_SPLIT_SIDES}, which half the new group takes
+     * @param {number} extent extent of the anchored half along the split's axis, px
+     * @param {'a'|'b'} anchor which half keeps that extent when the split is resized
+     * @returns {DockGroupNode}
+     */
+    #splitGroup(group, side, extent, anchor) {
+        const fresh = new DockGroupNode();
+
+        const split = new DockSplitNode(dock_side_direction(side), anchor, extent);
+
+        this.#replaceNode(group, split);
+
+        if (dock_side_half(side) === 'a') {
+            split.a = fresh;
+            split.b = group;
+        } else {
+            split.a = group;
+            split.b = fresh;
+        }
+
+        fresh.parent = split;
+        group.parent = split;
+
+        split.view.childA = split.a.view;
+        split.view.childB = split.b.view;
+
+        split.view.on.resized.add(applied => {
+            split.extent = applied;
+
+            this.on.rearranged.send0();
+        });
+
+        return fresh;
+    }
+
+    /**
+     * Give a detached panel a tab in a group.
+     *
+     * @param {DockPanel} panel
+     * @param {DockGroupNode} group
+     */
+    #addToGroup(panel, group) {
+        const record = this.#requireRecord(panel);
+
+        const handle = this.#buildHandle(panel);
+
+        const definition = TabDefinition.from({
+            toggle: handle,
+            panel: panel.view
+        });
+
+        const update_active_class = () => {
+            handle.setClass('meep-tab-active', definition.active.getValue());
+        };
+
+        handle.on.linked.add(update_active_class);
+        handle.bindSignal(definition.active.onChanged, update_active_class);
+
+        record.group = group;
+        record.definition = definition;
+
+        group.panels.push(panel);
+        group.tabs.add(definition);
+
+        if (group.view.getActiveTab() === undefined) {
+            group.view.activate(definition);
+        }
+    }
+
+    /**
+     * Swap one node of the tree for another, in the tree and in the views alike.
+     *
+     * @param {DockGroupNode|DockSplitNode} old_node
+     * @param {DockGroupNode|DockSplitNode} next
+     */
+    #replaceNode(old_node, next) {
+        const parent = old_node.parent;
+
+        old_node.parent = null;
+        next.parent = parent;
+
+        if (parent === null) {
+            this.#tree_host.removeChild(old_node.view);
+
+            next.view.css(CSS_ABSOLUTE_POSITIONING);
+            this.#tree_host.addChild(next.view);
+
+            this.#root = next;
+
+            this.layout();
+
+            return;
+        }
+
+        if (parent.a === old_node) {
+            parent.a = next;
+            parent.view.childA = next.view;
+        } else {
+            parent.b = next;
+            parent.view.childB = next.view;
+        }
+    }
+
+    /**
+     * The panel's handle: its title, a menu affordance, and the grip the whole placement
+     * gesture hangs off. The same view serves as the panel's tab while it is docked and as
+     * the tab on its window's title bar while it floats.
+     *
+     * @param {DockPanel} panel
+     * @returns {View}
+     */
+    #buildHandle(panel) {
+        const handle = new EmptyView({ classList: ['meep-tab'] });
+
+        handle.addChild(new LabelView(panel.title, { classList: ['meep-tab-title'] }));
+
+        const menu_button = new EmptyView({ tag: 'span', classList: ['meep-tab-menu'] });
+        menu_button.el.textContent = '▾';
+
+        menu_button.el.addEventListener(MouseEvents.Click, (event) => {
+            // the handle itself activates the tab on click; the menu click only opens the menu
+            event.stopPropagation();
+
+            show_popup_menu(this.#buildPlacementMenu(panel, handle), event.clientX, event.clientY);
+        });
+
+        handle.addChild(menu_button);
+
+        // Which tab is in front is part of the arrangement — it is in what toJSON writes —
+        // so bringing one forward is a rearrangement, even though it moves nothing. The tab
+        // itself is activated by the group; this only says that something happened.
+        handle.el.addEventListener(MouseEvents.Click, () => this.on.rearranged.send0());
+
+        // where inside the handle the author took hold of it, so a window it turns into lands
+        // under the cursor the way the handle itself sits under it
+        let grab_x = 0;
+        let grab_y = 0;
+
+        const drag = new DraggableAspect({
+            el: handle.el,
+            dragStart: (position) => {
+                grab_x = position.x;
+                grab_y = position.y;
+
+                this.setClass('meep-dock-dragging', true);
+                handle.addClass('meep-dock-handle-dragging');
+            },
+            drag: (position, origin, delta, event) => {
+                this.#drag_overlay.show(this.#planDrop(panel, event.clientX, event.clientY, grab_x, grab_y));
+            },
+            dragEnd: (position, origin, event) => {
+                const plan = this.#planDrop(panel, event.clientX, event.clientY, grab_x, grab_y);
+
+                this.#drag_overlay.hide();
+
+                handle.removeClass('meep-dock-handle-dragging');
+                this.setClass('meep-dock-dragging', false);
+
+                // the placement rebuilds this handle, and with it this aspect. Safe here: the
+                // gesture has already detached its own listeners before calling back.
+                this.#applyDropPlan(panel, plan);
+            }
+        });
+
+        handle.on.linked.add(drag.start, drag);
+        handle.on.unlinked.add(drag.stop, drag);
+
+        return handle;
+    }
+
+    /**
+     * Every placement the panel is not already in, for authors who would rather not drag.
+     *
+     * @param {DockPanel} panel
+     * @param {View} handle
+     * @returns {{label: string, action: function}[]}
+     */
+    #buildPlacementMenu(panel, handle) {
+        const record = this.#requireRecord(panel);
+
+        const items = [];
+
+        if (record.window === null) {
+            // splitting a group off a panel that is the whole group would put it back where it
+            // started, so that is not offered
+            if (record.group.panels.length > 1) {
+                for (const side of DOCK_SPLIT_SIDES) {
+                    items.push({
+                        label: `Split ${dock_side_title(side)}`,
+                        action: () => this.#placePanel(panel, record.group, side, this.#halfExtent(record.group, side))
+                    });
+                }
+            }
+
+            items.push({
+                label: 'Float',
+                action: () => {
+                    const bounds = this.el.getBoundingClientRect();
+                    const from = handle.el.getBoundingClientRect();
+
+                    // the window opens over the tab it came from, so it does not appear
+                    // somewhere the author was not looking
+                    this.floatPanel(
+                        panel,
+                        this.#clampFloatX(from.left - bounds.left, record.float_width),
+                        this.#clampFloatY(from.top - bounds.top, record.float_height),
+                        record.float_width,
+                        record.float_height
+                    );
+                }
+            });
+        } else {
+            items.push({
+                label: 'Dock',
+                action: () => this.addPanel(panel)
+            });
+        }
+
+        if (panel.closable) {
+            items.push({
+                label: 'Close',
+                action: () => this.removePanel(panel)
+            });
+        }
+
+        return items;
+    }
+
+    /**
+     * Half of a group's extent along the axis a side splits it on, px — what a group gives
+     * up when it is divided down the middle.
+     *
+     * @param {DockGroupNode} group
+     * @param {string} side
+     * @returns {number}
+     */
+    #halfExtent(group, side) {
+        const rect = group.view.el.getBoundingClientRect();
+
+        return Math.round((dock_side_direction(side) === 'x' ? rect.width : rect.height) / 2);
+    }
+
+    /**
+     * Carry out a plan. The extent comes off the plan's own rectangle rather than being
+     * measured again, so the panel lands at exactly the size the preview showed it at.
+     *
+     * Taking the panel out of where it was can move the target: a panel that was the whole
+     * of its group folds that group away, and the room goes back to whatever was beside it.
+     * The preview cannot show that — it is drawn while the panel is still in place — so the
+     * promise it makes is about the size, which is kept, and not about the position, which
+     * the reflow has the final say on. Any other reading would have the panel land at a size
+     * nobody was shown.
+     *
+     * @param {DockPanel} panel
+     * @param {DockDropPlan} plan
+     */
+    #applyDropPlan(panel, plan) {
+        if (plan.group === null) {
+            this.floatPanel(panel, plan.x, plan.y, plan.width, plan.height);
+
+            return;
+        }
+
+        const extent = dock_side_direction_of_plan(plan) === 'x' ? plan.width : plan.height;
+
+        this.#placePanel(panel, plan.group, plan.side, extent);
+    }
+
+    /**
+     * What releasing the panel at a point in client space would do with it.
+     *
+     * @param {DockPanel} panel
+     * @param {number} client_x
+     * @param {number} client_y
+     * @param {number} grab_x where in the handle the author took hold, px
+     * @param {number} grab_y
+     * @returns {DockDropPlan}
+     */
+    #planDrop(panel, client_x, client_y, grab_x, grab_y) {
+        const bounds = this.el.getBoundingClientRect();
+
+        const plan = new DockDropPlan();
+
+        const title = panel.title.getValue();
+
+        for (const group of this.#groups()) {
+            const rect = group.view.el.getBoundingClientRect();
+
+            if (client_x < rect.left || client_x > rect.right || client_y < rect.top || client_y > rect.bottom) {
+                continue;
+            }
+
+            const side = this.#sideAt(rect, client_x, client_y);
+
+            if (side === "") {
+                // in the margin the group keeps around itself: the groups tile the layout, so
+                // no other group holds this point either, and the panel is on its way out
+                break;
+            }
+
+            const half_width = Math.round(rect.width / 2);
+            const half_height = Math.round(rect.height / 2);
+
+            plan.group = group;
+            plan.side = side;
+            plan.x = rect.left - bounds.left + (side === DockSide.Right ? rect.width - half_width : 0);
+            plan.y = rect.top - bounds.top + (side === DockSide.Bottom ? rect.height - half_height : 0);
+            plan.width = side === DockSide.Left || side === DockSide.Right ? half_width : rect.width;
+            plan.height = side === DockSide.Top || side === DockSide.Bottom ? half_height : rect.height;
+            plan.label = side === DockSide.Center
+                ? `${title} → tab group`
+                : `${title} → split ${dock_side_title(side)}`;
+
+            return plan;
+        }
+
+        // over no group, or over the margin one keeps around itself: the panel leaves the
+        // layout and stands where it was dropped
+        const record = this.#requireRecord(panel);
+
+        plan.group = null;
+        plan.width = record.float_width;
+        plan.height = record.float_height;
+        plan.x = this.#clampFloatX(client_x - bounds.left - grab_x, plan.width);
+        plan.y = this.#clampFloatY(client_y - bounds.top - grab_y, plan.height);
+        plan.label = `${title} → floating window`;
+
+        return plan;
+    }
+
+    /**
+     * Which side of a group a point asks for: its tab strip and its middle mean the group
+     * itself, a band along each edge means splitting it, and the margin outside those means
+     * leaving the layout.
+     *
+     * @param {DOMRect} rect the group, in client space
+     * @param {number} x
+     * @param {number} y
+     * @returns {string} one of {@link DockSide}, or "" for the margin
+     */
+    #sideAt(rect, x, y) {
+        // the tab strip is where tabs live, so dropping a tab on it means exactly that,
+        // whatever the margins would otherwise have to say
+        if (y <= rect.top + TAB_STRIP_HEIGHT) {
+            return DockSide.Center;
+        }
+
+        const margin_x = Math.min(NEUTRAL_MARGIN, rect.width * NEUTRAL_MARGIN_MAX_FRACTION);
+        const margin_y = Math.min(NEUTRAL_MARGIN, rect.height * NEUTRAL_MARGIN_MAX_FRACTION);
+
+        const left = rect.left + margin_x;
+        const right = rect.right - margin_x;
+        const top = rect.top + margin_y;
+        const bottom = rect.bottom - margin_y;
+
+        if (x < left || x > right || y < top || y > bottom) {
+            return "";
+        }
+
+        const width = Math.max(1, right - left);
+        const height = Math.max(1, bottom - top);
+
+        // distance to each edge as a share of the extent it is measured along, so that a long
+        // thin group is judged the same way a square one is
+        const to_left = (x - left) / width;
+        const to_right = (right - x) / width;
+        const to_top = (y - top) / height;
+        const to_bottom = (bottom - y) / height;
+
+        const nearest = Math.min(to_left, to_right, to_top, to_bottom);
+
+        if (nearest >= SPLIT_BAND_FRACTION) {
+            return DockSide.Center;
+        }
+
+        if (nearest === to_left) {
+            return DockSide.Left;
+        }
+
+        if (nearest === to_right) {
+            return DockSide.Right;
+        }
+
+        if (nearest === to_top) {
+            return DockSide.Top;
+        }
+
+        return DockSide.Bottom;
+    }
+
+    /**
+     * Bring a window in front of the others.
+     *
+     * @param {FloatingPanelView} window_view
+     */
+    #raiseWindow(window_view) {
+        this.#float_order++;
+
+        window_view.css({ zIndex: this.#float_order });
+    }
+
+    /**
+     * A window is kept inside the dock: one dropped past the edge would be clipped by it,
+     * title bar and all, and could not be reached again.
+     *
+     * @param {number} x
+     * @param {number} width
+     * @returns {number}
+     */
+    #clampFloatX(x, width) {
+        return clamp(x, 0, Math.max(0, this.size.x - width));
+    }
+
+    /**
+     *
+     * @param {number} y
+     * @param {number} height
+     * @returns {number}
+     */
+    #clampFloatY(y, height) {
+        return clamp(y, 0, Math.max(0, this.size.y - height));
+    }
+
+    /**
+     *
+     * @param {DockGroupNode|DockSplitNode} node
+     * @returns {Object}
+     */
+    #nodeToJSON(node) {
+        if (node instanceof DockSplitNode) {
+            return {
+                type: 'split',
+                direction: node.direction,
+                anchor: node.anchor,
+                extent: node.extent,
+                a: this.#nodeToJSON(node.a),
+                b: this.#nodeToJSON(node.b)
+            };
+        }
+
+        const active = node.panels.find(panel => this.#panels.get(panel).definition.active.getValue());
+
+        return {
+            type: 'group',
+            panels: node.panels.map(panel => panel.id),
+            active: active === undefined ? "" : active.id
+        };
+    }
+
+    /**
+     * Rebuild a recorded subtree into the space a group currently holds, placing the panels
+     * it names as it goes. Every panel is expected to be detached.
+     *
+     * A half of a split whose panels this build no longer has is not built at all — the
+     * other half takes the whole space, which is what folding away an emptied group would
+     * have done anyway.
+     *
+     * @param {Object} json
+     * @param {Map<string, DockPanel>} by_id
+     * @param {DockGroupNode} group
+     */
+    #restoreInto(json, by_id, group) {
+        if (json.type !== 'split') {
+            for (const id of json.panels) {
+                const panel = by_id.get(id);
+
+                if (panel !== undefined) {
+                    this.#addToGroup(panel, group);
+                }
+            }
+
+            const active = by_id.get(json.active);
+
+            if (active !== undefined && this.#panels.get(active).group === group) {
+                group.view.activate(this.#panels.get(active).definition);
+            }
+
+            return;
+        }
+
+        const has_a = this.#restorablePanelCount(json.a, by_id) > 0;
+        const has_b = this.#restorablePanelCount(json.b, by_id) > 0;
+
+        if (!has_a) {
+            this.#restoreInto(json.b, by_id, group);
+
+            return;
+        }
+
+        if (!has_b) {
+            this.#restoreInto(json.a, by_id, group);
+
+            return;
+        }
+
+        // the a-half is split off the group, the b-half carries on in it; the recorded anchor
+        // rides along, since which half keeps its extent is the author's arrangement too
+        const side = json.direction === 'x' ? DockSide.Left : DockSide.Top;
+
+        const fresh = this.#splitGroup(group, side, json.extent, json.anchor);
+
+        this.#restoreInto(json.a, by_id, fresh);
+        this.#restoreInto(json.b, by_id, group);
+    }
+
+    /**
+     *
+     * @param {Object} json
+     * @param {Map<string, DockPanel>} by_id
+     * @returns {number} how many of a recorded subtree's panels this build still has
+     */
+    #restorablePanelCount(json, by_id) {
+        if (json.type === 'split') {
+            return this.#restorablePanelCount(json.a, by_id) + this.#restorablePanelCount(json.b, by_id);
+        }
+
+        return json.panels.filter(id => by_id.has(id)).length;
+    }
+
+    layout() {
+        this.#tree_host.position.set(0, 0);
+        this.#tree_host.size.copy(this.size);
+
+        this.#root.view.position.set(0, 0);
+        this.#root.view.size.copy(this.size);
+
+        this.#float_layer.position.set(0, 0);
+        this.#float_layer.size.copy(this.size);
+
+        this.#drag_overlay.position.set(0, 0);
+        this.#drag_overlay.size.copy(this.size);
+
+        if (this.size.x <= 0 || this.size.y <= 0) {
+            // nothing has been laid out against yet — a host sizes the dock after linking it,
+            // and a restored arrangement can land in between. There is no room here to hold a
+            // window inside of, and squaring it up against none would destroy where it goes.
+            return;
+        }
+
+        // a dock that shrank must not leave a window stranded outside itself
+        for (const record of this.#panels.values()) {
+            if (record.window === null) {
+                continue;
+            }
+
+            record.float_x = this.#clampFloatX(record.float_x, record.float_width);
+            record.float_y = this.#clampFloatY(record.float_y, record.float_height);
+
+            record.window.position.set(record.float_x, record.float_y);
+        }
+    }
+}
+
+/**
+ * The axis a plan's split runs on; a plan that docks as a tab has no axis and reports the
+ * one that leaves its extent unused.
+ *
+ * @param {DockDropPlan} plan
+ * @returns {'x'|'y'}
+ */
+function dock_side_direction_of_plan(plan) {
+    return plan.side === DockSide.Left || plan.side === DockSide.Right ? 'x' : 'y';
+}