@woosh/meep-engine 3.15.0 → 3.16.0

package/editor/view/node-graph/NodeGraphSearchMenuView.js

@@ -0,0 +1,247 @@
+import Signal from "../../../src/core/events/signal/Signal.js";
+import EmptyView from "../../../src/view/elements/EmptyView.js";
+import View from "../../../src/view/View.js";
+import { NodeGraphPaletteView } from "./NodeGraphPaletteView.js";
+
+/**
+ * The node library as a menu, opened at a point on the canvas.
+ *
+ * The same searchable list a docked {@link NodeGraphPaletteView} shows, put where the author is
+ * looking instead of down the side of the window. Right-click the canvas and it opens under the
+ * cursor with the caret already in the search field, the first match already highlighted, and Enter
+ * placing that type at the point that was clicked — so adding a node is type-and-Enter rather than
+ * cross the window, click, cross back.
+ *
+ * It is also what finishes a wire dropped on open canvas. In that case the host narrows the library
+ * to the types that could actually take the wire (see {@link NodeGraphPaletteView#setPredicate}) and
+ * says so in the menu's heading, so what is on offer and why are the same thing.
+ *
+ * ## Where it closes
+ *
+ * Escape, a pick, or a pointer press anywhere outside it. The outside press is watched on the window
+ * during capture, so a menu cannot be left open by a click that some other view stops on the way up
+ * — a canvas that pans on pointerdown, most of all.
+ */
+export class NodeGraphSearchMenuView extends View {
+    /**
+     * @readonly
+     */
+    on = {
+        ...this.on,
+
+        /**
+         * The menu has closed, whether by a pick, Escape, or a press outside it. Carries the type
+         * that was picked, or `null`.
+         *
+         * @readonly
+         * @type {Signal<NodeDescription|null>}
+         */
+        closed: new Signal()
+    };
+
+    /**
+     * @type {NodeGraphPaletteView}
+     */
+    #palette;
+
+    /**
+     * @type {EmptyView}
+     */
+    #heading;
+
+    /**
+     * What to do with the type the author picks, for the gesture the menu is currently open for.
+     * @type {function(NodeDescription):void}
+     */
+    #onPick = () => undefined;
+
+    /**
+     * Watches for a press outside the menu while it is open; `null` while it is not.
+     * @type {function(PointerEvent):void|null}
+     */
+    #outside = null;
+
+    /**
+     * @param {object} options
+     * @param {NodeDescription[]|function():NodeDescription[]} options.descriptions the library
+     * @param {function(NodeDescription):string} [options.categoryOf] see {@link NodeGraphPaletteView}
+     * @param {function(NodeDescription):string} [options.describe] see {@link NodeGraphPaletteView}
+     * @param {string} [options.placeholder] search-field placeholder
+     */
+    constructor({ descriptions, categoryOf, describe, placeholder = "add node…" }) {
+        super();
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-node-graph-search-menu');
+
+        this.#heading = new EmptyView({ classList: ['heading'] });
+
+        // The heading only ever says something for a wire-drop; an empty one would be a bar of
+        // padding above the search field on every ordinary right-click.
+        this.#heading.visible = false;
+
+        this.addChild(this.#heading);
+
+        this.#palette = new NodeGraphPaletteView({
+            descriptions,
+            categoryOf,
+            describe,
+            placeholder,
+            emptyLabel: "nothing here fits",
+            onEscape: () => this.close(),
+            onPick: description => {
+                const handle = this.#onPick;
+
+                // closed before the callback runs: adding a node moves focus and rebuilds views,
+                // and a menu still on screen through that is a menu that flickers away afterwards
+                this.close(description);
+
+                handle(description);
+            },
+        });
+
+        this.addChild(this.#palette);
+
+        this.visible = false;
+
+        // a press inside the menu is the menu's own business, and must not read as a press outside
+        this.el.addEventListener('pointerdown', event => event.stopPropagation());
+
+        // right-clicking the menu is not another request to open one
+        this.el.addEventListener('contextmenu', event => {
+            event.preventDefault();
+            event.stopPropagation();
+        });
+
+        this.on.unlinked.add(this.close, this);
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    get isOpen() {
+        return this.visible;
+    }
+
+    /**
+     * The list itself, for a host that wants to drive it — a test, most of all.
+     * @returns {NodeGraphPaletteView}
+     */
+    palette() {
+        return this.#palette;
+    }
+
+    /**
+     * Open the menu at a point in this view's parent's coordinates.
+     *
+     * @param {object} options
+     * @param {number} options.x
+     * @param {number} options.y
+     * @param {function(NodeDescription):void} options.onPick what to do with the chosen type
+     * @param {function(NodeDescription):boolean} [options.predicate] which types apply here
+     * @param {string} [options.heading] one line saying what the menu is for, shown above the search
+     */
+    open({ x, y, onPick, predicate = () => true, heading = "" }) {
+        this.#onPick = onPick;
+
+        this.#heading.el.textContent = heading;
+        this.#heading.visible = heading !== "";
+
+        this.position.set(x, y);
+
+        this.visible = true;
+
+        this.#palette.filter.set("");
+
+        // rebuilds, which is also what gets the list built for a menu opening for the first time
+        this.#palette.setPredicate(predicate);
+
+        this.#keepInside();
+
+        this.#palette.focusSearch();
+
+        this.#watchOutside();
+    }
+
+    /**
+     * Pull the menu back inside its host if opening it where it was asked would hang it over an edge.
+     *
+     * The canvas clips what leaves it, so a right-click near the right edge would otherwise open a
+     * menu with half its rows cut off — and the search field, which is the whole point of the
+     * gesture, is one of the halves that goes.
+     *
+     * Measured rather than computed from the stylesheet, because the menu's size is the stylesheet's
+     * to decide. Where there is no layout to measure — an environment with no layout engine at all —
+     * there is nothing hanging over anything, and the point stands as asked for.
+     */
+    #keepInside() {
+        const host = this.el.parentElement;
+
+        if (host === null) {
+            return;
+        }
+
+        const width = this.el.offsetWidth;
+        const height = this.el.offsetHeight;
+
+        if (width === 0 || height === 0 || host.clientWidth === 0 || host.clientHeight === 0) {
+            return;
+        }
+
+        this.position.set(
+            Math.max(0, Math.min(this.position.x, host.clientWidth - width)),
+            Math.max(0, Math.min(this.position.y, host.clientHeight - height))
+        );
+    }
+
+    /**
+     * Close the menu. Harmless when it is already closed, which is what lets every path out of it —
+     * Escape, a pick, a press outside, the view being unlinked — call this without checking.
+     *
+     * @param {NodeDescription|null} [picked] the type the author chose, if that is why it closed
+     */
+    close(picked = null) {
+        this.#unwatchOutside();
+
+        if (!this.visible) {
+            return;
+        }
+
+        this.visible = false;
+
+        this.#onPick = () => undefined;
+
+        this.on.closed.send1(picked);
+    }
+
+    #watchOutside() {
+        if (this.#outside !== null) {
+            return;
+        }
+
+        // Capture, because a canvas that swallows pointerdown to start a pan would otherwise keep
+        // the menu open under the gesture that was meant to dismiss it. Which means this runs before
+        // the menu's own handlers, so "inside" is decided by where the press landed rather than by
+        // anything the menu is given a chance to say about it.
+        this.#outside = event => {
+            if (this.el.contains(event.target)) {
+                return;
+            }
+
+            this.close();
+        };
+
+        window.addEventListener('pointerdown', this.#outside, true);
+    }
+
+    #unwatchOutside() {
+        if (this.#outside === null) {
+            return;
+        }
+
+        window.removeEventListener('pointerdown', this.#outside, true);
+
+        this.#outside = null;
+    }
+}

package/editor/view/node-graph/NodeGraphView.d.ts

@@ -8,9 +8,46 @@ export class NodeGraphView extends View {
      * @param {NodeDescriptionVisualRegistry} nodeVisualRegistry
      * @param {ActionProcessor} [actionProcessor] timeline that all graph edits are routed through
      * @param {NodeGraphSelection} [selection]
+     * @param {function({node: NodeInstance, commit: function(string, *)}):View|null} [parameterViewFactory]
+     *        see {@link NodeView}; passed through unchanged, so a host's controls reach every node
+     * @param {function(NodeInstancePortReference):DataType} [portDataType]
+     *        the type a port carries on a particular node instance, which is what its marker is
+     *        coloured by and what a wire out of it is drawn in. The declared type by default. A
+     *        host whose ports are typed by what is wired into them — where an `add` is as wide as
+     *        its inputs — supplies one, and calls {@link #refreshPortTypes} when its answers change.
+     * @param {boolean} [readOnly] show the graph without offering to change it: no wiring, no
+     *        dragging, no parameter edits. What a host drilling into a graph it does not own — a
+     *        locked node group — shows. Selection and the camera still work, because looking around
+     *        is not editing.
      */
-    constructor({ graph, visual, camera, nodeVisualRegistry, actionProcessor, selection }: NodeGraph);
+    constructor({ graph, visual, camera, nodeVisualRegistry, actionProcessor, selection, parameterViewFactory, portDataType, readOnly }: NodeGraph);
     el: HTMLDivElement;
+    /**
+     * The view of each node currently on the canvas, by node id.
+     *
+     * A host that wants to decorate a node — mark it as carrying an error, flash it, badge it —
+     * needs to find its view, and reaching into the child list to do it depends on how this view
+     * happens to be assembled. Kept in step with the node list rather than rebuilt on demand.
+     *
+     * @readonly
+     * @type {Map<number, NodeView>}
+     */
+    readonly nodeViews: Map<number, NodeView>;
+    /**
+     * The type a port carries on a particular node instance. See the constructor.
+     * @type {function(NodeInstancePortReference):DataType}
+     */
+    portDataType: (arg0: NodeInstancePortReference) => DataType;
+    /**
+     * @readonly
+     */
+    readonly on: any;
+    /**
+     * Whether the graph can be edited through this view. See the constructor.
+     * @readonly
+     * @type {boolean}
+     */
+    readonly readOnly: boolean;
     /**
      *
      * @type {ActionProcessor}
@@ -36,7 +73,98 @@ export class NodeGraphView extends View {
      * @type {NodeGraphSelection}
      */
     selection: NodeGraphSelection;
+    /**
+     * Ask every port what it carries now, and draw the wires again in the answer's colours.
+     *
+     * For a host that resolves port types per node instance (see `portDataType` in the
+     * constructor): a graph whose types follow its wiring changes its mind about ports far from the
+     * edit — a literal made narrower retypes everything downstream of it — so the host says when,
+     * and every port is asked rather than the ones it can think of.
+     *
+     * @returns {void}
+     */
+    refreshPortTypes(): void;
+    /**
+     * Have every node on the canvas record where the browser has put it.
+     *
+     * The nodes measure themselves as their content changes, so this is not the usual path — it is
+     * how the canvas gets its first measurement, at the one moment it is known that every node is
+     * in the document and none of them has been asked yet.
+     *
+     * @returns {void}
+     */
+    measureNodes(): void;
+    /**
+     * Whether the visual data describes the graph as drawn, rather than as the visual registry
+     * estimated it.
+     *
+     * False while the canvas is not on screen at all: an unlinked view has drawn nothing, and a
+     * node's size is not knowable without drawing it.
+     *
+     * @returns {boolean}
+     */
+    isMeasured(): boolean;
+    /**
+     * Wire up what the canvas background does with the pointer.
+     *
+     * Three gestures want that background — moving the view, pulling a selection box across it, and
+     * asking for the add-node menu — and a canvas that guessed between them would keep getting it
+     * wrong. They are told apart by which button began the gesture, the way graph editors of this
+     * kind have long settled it (Unreal's Blueprint canvas among them):
+     *
+     * | gesture                  | what it does                                          |
+     * |--------------------------|-------------------------------------------------------|
+     * | drag with the left       | pull a selection box; SHIFT adds, CTRL toggles        |
+     * | drag with right, middle  | pan                                                   |
+     * | click with the left      | select what is under the cursor, or clear the selection |
+     * | click with the right     | ask the host for the add-node menu                    |
+     * | wheel                    | zoom about the cursor                                 |
+     *
+     * A click and a drag are the same two events with a different amount of travel in between, so
+     * one tolerance decides which a gesture was — see {@link CANVAS_CLICK_TOLERANCE_PX}. That is how
+     * the right button both pans and opens a menu without ever doing one when the other was meant.
+     *
+     * A press over a node or a port never arrives here: those run pointer devices of their own and
+     * stop it where it is raised, so everything below is about open canvas.
+     *
+     * @returns {void}
+     */
     initializeNavigationControls(): void;
+    /**
+     * The nodes a graph-space box touches.
+     *
+     * Touches rather than encloses: a box that has to go around whole nodes is a box drawn wider
+     * than the graph, and every editor that offers the gesture takes overlap for that reason.
+     *
+     * @param {AABB2} region graph-space box
+     * @returns {number[]} node ids
+     */
+    findNodesInRegion(region: AABB2): number[];
+    /**
+     * The wires a graph-space box holds whole.
+     *
+     * Whole, unlike the nodes, and for the same reason they are not: a box around a few nodes cuts
+     * across every wire leaving them for elsewhere, and taking those would turn a gesture aimed at
+     * four nodes into half the graph highlighted. A wire the box holds is one whose ports are both
+     * inside it — so its nodes are in the selection too, and the box selects what it looks like it
+     * selects.
+     *
+     * @param {AABB2} region graph-space box
+     * @returns {number[]} connection ids
+     */
+    findConnectionsInRegion(region: AABB2): number[];
+    /**
+     * Apply a rubber-band gesture: what the box went around, met with the selection already there
+     * the way the modifier keys ask — plain replaces, SHIFT adds, CTRL toggles.
+     *
+     * The same three {@link #applySelectionClick} offers, because they are one question asked of
+     * more than one element at a time.
+     *
+     * @param {AABB2} region graph-space box
+     * @param {MouseEvent|PointerEvent} event source of modifier key state
+     * @returns {void}
+     */
+    applySelectionRegion(region: AABB2, event: MouseEvent | PointerEvent): void;
     /**
      * Find the connection nearest to a graph-space point, within hit tolerance
      * @param {Vector2} point graph-space point
@@ -61,15 +189,25 @@ export class NodeGraphView extends View {
      * @returns {boolean}
      */
     isGraphAABBVisible(x0: any, y0: any, x1: any, y1: any): boolean;
+    /**
+     * The path a connection is drawn along — its route while that route still meets its ports, and
+     * a plain curve between them otherwise. See {@link wire_resolve_path}.
+     *
+     * The fallback is a shared scratch object, so the result is only valid until this is called
+     * again.
+     *
+     * @param {Connection} connection
+     * @returns {ConnectionVisualData}
+     */
+    resolveConnectionPath(connection: Connection): ConnectionVisualData;
     /**
      *
      * @param {CanvasRenderingContext2D} ctx
-     * @param {Vector2} source
-     * @param {Vector2} target
+     * @param {ConnectionVisualData} path
      * @param {DataType} dataType
      * @param {boolean} [selected] selected wires are drawn with a highlight halo
      */
-    drawConnection(ctx: CanvasRenderingContext2D, source: Vector2, target: Vector2, dataType: DataType, selected?: boolean): void;
+    drawConnection(ctx: CanvasRenderingContext2D, path: ConnectionVisualData, dataType: DataType, selected?: boolean): void;
     /**
      *
      * @param {NodeInstancePortReference} endpoint
@@ -88,11 +226,15 @@ export class NodeGraphView extends View {
      * @param {Vector2} output
      */
     transformPointCanvas2Graph(input: Vector2, output: Vector2): void;
+    #private;
 }
 import View from "../../../src/view/View.js";
+import { NodeView } from "./NodeView.js";
+import { NodeInstancePortReference } from "../../../src/core/model/node-graph/node/NodeInstancePortReference.js";
 import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
 import { NodeGraphCamera } from "./NodeGraphCamera.js";
 import { NodeGraphSelection } from "./NodeGraphSelection.js";
+import AABB2 from "../../../src/core/geom/2d/aabb/AABB2.js";
 import Vector2 from "../../../src/core/geom/Vector2.js";
-import { NodeInstancePortReference } from "../../../src/core/model/node-graph/node/NodeInstancePortReference.js";
+import { ConnectionVisualData } from "../../../src/core/model/node-graph/visual/ConnectionVisualData.js";
 //# sourceMappingURL=NodeGraphView.d.ts.map

package/editor/view/node-graph/NodeGraphView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphView.js"],"names":[],"mappings":";AAqDA;IAGI;;;;;;;;OAQG;IACH,kGA8UC;IAzVD,mBAAmC;IAqB/B;;;OAGG;IACH,2CAAsC;IAEtC;;;OAGG;IACH,QAFU,eAAe,CAEL;IAEpB;;;OAGG;IACH,iBAAkB;IAElB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,WAFU,kBAAkB,CAEF;IA0S9B,qCA0CC;IAED;;;;OAIG;IACH,wBAHW,OAAO,GACL,aAAW,IAAI,CAsC3B;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,IAAI,gBACX,MAAM,GAAC,IAAI,SACX,UAAU,GAAC,YAAY,QA8CjC;IAGD;;;;;;;OAOG;IACH,wDAFa,OAAO,CAcnB;IAED;;;;;;;OAOG;IACH,oBANW,wBAAwB,UACxB,OAAO,UACP,OAAO,iCAEP,OAAO,QAqDjB;IAED;;;;OAIG;IACH,mCAHW,yBAAyB,UACzB,OAAO,QAiBjB;IAED;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;IAED;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;CACJ;iBAvpBgB,2BAA2B;gCASZ,mDAAmD;gCACnD,sBAAsB;mCACnB,yBAAyB;oBATxC,mCAAmC;0CAMb,sEAAsE"}
+{"version":3,"file":"NodeGraphView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphView.js"],"names":[],"mappings":";AAyGA;IA4GI;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gJA8cC;IA7kBD,mBAAmC;IAEnC;;;;;;;;;OASG;IACH,oBAFU,IAAI,MAAM,EAAE,QAAQ,CAAC,CAET;IAmBtB;;;OAGG;IACH,qBAFmB,yBAAyB,cAE/B;IAEb;;OAEG;IACH,iBA0DE;IAEF;;;;OAIG;IACH,mBAFU,OAAO,CAEA;IAmCb;;;OAGG;IACH,2CAAsC;IAMtC;;;OAGG;IACH,QAFU,eAAe,CAEL;IAEpB;;;OAGG;IACH,iBAAkB;IAElB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,WAFU,kBAAkB,CAEF;IAma9B;;;;;;;;;OASG;IACH,oBAFa,IAAI,CAgBhB;IAED;;;;;;;;OAQG;IACH,gBAFa,IAAI,CAMhB;IAED;;;;;;;;OAQG;IACH,cAFa,OAAO,CAInB;IAgBD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,gCAFa,IAAI,CA+NhB;IAED;;;;;;;;OAQG;IACH,0BAHW,KAAK,GACH,MAAM,EAAE,CAwBpB;IAED;;;;;;;;;;;OAWG;IACH,gCAHW,KAAK,GACH,MAAM,EAAE,CAsBpB;IAED;;;;;;;;;;OAUG;IACH,6BAJW,KAAK,SACL,UAAU,GAAC,YAAY,GACrB,IAAI,CAgDhB;IAED;;;;OAIG;IACH,wBAHW,OAAO,GACL,aAAW,IAAI,CAiC3B;IAED;;;;;;;OAOG;IACH,4BAJW,MAAM,GAAC,IAAI,gBACX,MAAM,GAAC,IAAI,SACX,UAAU,GAAC,YAAY,QA8CjC;IAGD;;;;;;;OAOG;IACH,wDAFa,OAAO,CAcnB;IAED;;;;;;;;;OASG;IACH,+CAFa,oBAAoB,CAYhC;IAED;;;;;;OAMG;IACH,oBALW,wBAAwB,QACxB,oBAAoB,iCAEpB,OAAO,QA+DjB;IAED;;;;OAIG;IACH,mCAHW,yBAAyB,UACzB,OAAO,QAiBjB;IAeD;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;IAED;;;;OAIG;IACH,kCAHW,OAAO,UACP,OAAO,QAIjB;;CACJ;iBAn3CgB,2BAA2B;yBAInB,eAAe;0CAIE,sEAAsE;gCAChF,mDAAmD;gCACnD,sBAAsB;mCACnB,yBAAyB;kBAQ1C,yCAAyC;oBAjBvC,mCAAmC;qCAgBlB,mEAAmE"}