@woosh/meep-engine 3.15.0 → 3.17.0

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

@@ -7,13 +7,59 @@ export class NodeGraphEditorView extends View {
      * @param {NodeGraphCamera} camera
      * @param {InterfaceCommand[]} [actions]
      * @param {ActionProcessor} [actionProcessor] timeline that all graph edits are routed through, supply a shared one to integrate with a host editor's UNDO/REDO
+     * @param {function({node: NodeInstance, commit: function(string, *)}):View|null} [parameterViewFactory]
+     *        supplies controls for node state the generic parameter mechanism cannot describe, see {@link NodeView}
+     * @param {function(NodeInstancePortReference):DataType} [portDataType]
+     *        the type a port carries on a particular node instance, for a host whose types are
+     *        resolved from the wiring rather than declared on the port; see {@link NodeGraphView}
+     * @param {boolean} [minimap] show the whole graph in a corner, see {@link NodeGraphMinimapView}.
+     *        On by default: a graph is bigger than its viewport almost as soon as it is worth
+     *        editing. Off for a host that puts one somewhere of its own, or has no room for one.
+     * @param {object} [library] the node library, as the canvas's own add-node menu needs it. With
+     *        one, right-clicking the canvas offers the types it names and a wire dropped on open
+     *        canvas offers the ones that could take it; without one, neither gesture does anything.
+     * @param {NodeDescription[]|function():NodeDescription[]} library.descriptions the types to offer
+     * @param {function(NodeDescription):string} [library.categoryOf] group heading for a type
+     * @param {function(NodeDescription):string} [library.describe] one line of help for a type
+     * @param {function(Port, DataType|null, NodeDescription):boolean} [library.accepts] whether a
+     *        port could take a value of a type. The same-type rule by default; a library whose ports
+     *        are typed by what is wired into them supplies its own.
+     * @param {function(NodeDescription):object} [library.parametersOf] starting parameters for a
+     *        type the menu places, so a node arrives ready to compile rather than to repair
+     * @param {boolean} [readOnly] show the graph without offering to change it; see
+     *        {@link NodeGraphView}. Turns off the add-node menu and the editing shortcuts too.
+     * @param {NodeGraphClipboard} [clipboard] what `Ctrl+C` writes and `Ctrl+V` reads. A host with
+     *        several canvases over one document passes one to all of them, so a copy taken in one
+     *        pastes in the next; on its own, a canvas gets one of its own and copies to itself.
+     * @param {function(NodeInstance):boolean} [copyable] whether a node may be had a second of, for
+     *        a host with types that exist once per graph. See
+     *        {@link node_graph_fragment_from_nodes}.
      */
-    constructor({ graph, nodeRegistry, visual, camera, actions, actionProcessor }: NodeGraph);
+    constructor({ graph, nodeRegistry, visual, camera, actions, actionProcessor, parameterViewFactory, portDataType, minimap, library, readOnly, clipboard, copyable }: NodeGraph);
+    /**
+     * @readonly
+     */
+    readonly on: any;
+    /**
+     * @type {boolean}
+     */
+    readOnly: boolean;
     /**
      *
      * @type {ActionProcessor}
      */
     actionProcessor: ActionProcessor<any, any>;
+    /**
+     * What a copy is written to and a paste read from. Shared with the host's other canvases
+     * when it supplied one.
+     *
+     * @type {NodeGraphClipboard}
+     */
+    clipboard: NodeGraphClipboard;
+    /**
+     * @type {function(NodeInstance):boolean}
+     */
+    copyable: (arg0: NodeInstance) => boolean;
     /**
      *
      * @type {NodeGraphSelection}
@@ -40,16 +86,169 @@ export class NodeGraphEditorView extends View {
      * @type {NodeDescriptionVisualRegistry}
      */
     visualRegistry: NodeDescriptionVisualRegistry;
+    /**
+     * @type {NodeGraphView}
+     */
+    graphView: NodeGraphView;
+    /**
+     * The map of the whole graph, where there is one.
+     *
+     * Composed rather than built in: it reads this editor's graph view and writes its camera,
+     * and nothing else here knows it exists. A host that wants one of its own docks a
+     * {@link NodeGraphMinimapView} elsewhere and turns this off.
+     *
+     * @type {NodeGraphMinimapView|null}
+     */
+    minimap: NodeGraphMinimapView | null;
+    /**
+     * The canvas's own add-node menu, where there is a library to fill it. See
+     * {@link NodeGraphSearchMenuView}.
+     *
+     * @type {NodeGraphSearchMenuView|null}
+     */
+    searchMenu: NodeGraphSearchMenuView | null;
+    /**
+     * The add the canvas menu last started, as a promise of the node it makes; `null` before the
+     * menu has been used.
+     *
+     * Adding a node goes through the {@link ActionProcessor}, which queues, so a node picked
+     * from the menu does not exist when the menu closes. A host that wants to do something with
+     * it — select it, put the camera on it, open its parameters — has to be able to wait for it,
+     * and so does anything testing the gesture.
+     *
+     * @type {Promise<NodeInstance>|null}
+     */
+    menuGesture: Promise<NodeInstance> | null;
+    /**
+     * Add a node and immediately wire one of its ports to an existing one, as a single undoable step.
+     *
+     * What finishes a wire dropped on open canvas. One step rather than two because it was one
+     * gesture: an undo that left a disconnected node behind would be undoing something the author
+     * never did on its own.
+     *
+     * @param {NodeDescription} description
+     * @param {object} options
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @param {NodeInstancePortReference} options.endpoint the port the wire came from
+     * @param {Port} options.port the port of the new node to wire it to
+     * @returns {Promise<NodeInstance>} the new node
+     */
+    addNodeWiredTo(description: NodeDescription, { x, y, parameters, endpoint, port }: {
+        x?: number;
+        y?: number;
+        parameters?: object;
+        endpoint: NodeInstancePortReference;
+        port: Port;
+    }): Promise<NodeInstance>;
+    /**
+     * Arrange the nodes and route the wires.
+     *
+     * An arrangement is only as good as the node sizes it is given, and those are facts about drawn
+     * nodes: how wide a host's own control is, how long the text in a picker runs. Until the graph
+     * has been on screen the only sizes anyone has are {@link NodeDescriptionVisualRegistry}'s
+     * estimates from port and parameter counts, which cannot know either.
+     *
+     * So a graph arranged before it has been drawn is arranged twice: once now, because a graph
+     * opened straight into this has to look like something, and once more when the views report
+     * what the browser actually made of them. {@link #on.arranged} says which of the two just
+     * happened.
+     */
     layout(): void;
+    /**
+     * Whether the arrangement in hand was made from estimated node sizes and is still to be redone
+     * from the drawn ones. See {@link #layout}.
+     *
+     * What to consult before doing anything that depends on where the nodes ended up — pointing a
+     * camera at them, most of all, since framing the provisional arrangement leaves it aimed at
+     * where the nodes were about to stop being.
+     *
+     * @returns {boolean}
+     */
+    isArrangementProvisional(): boolean;
+    /**
+     * Add a node of the given type to the graph, as one undoable step.
+     *
+     * With no position, the node lands in the middle of what the author is looking at — where they
+     * will see it — rather than at the graph origin, which may be off screen entirely.
+     *
+     * @param {NodeDescription} description
+     * @param {object} [options]
+     * @param {number} [options.x] graph-space position
+     * @param {number} [options.y] graph-space position
+     * @param {object} [options.parameters] starting parameter values
+     * @returns {Promise<NodeInstance>} the new node, once the timeline has applied the action —
+     *          {@link ActionProcessor} queues, so it does not exist on return
+     */
+    addNode(description: NodeDescription, { x, y, parameters }?: {
+        x?: number;
+        y?: number;
+        parameters?: object;
+    }): Promise<NodeInstance>;
+    /**
+     * Middle of the visible area, in graph space.
+     * @returns {Vector2}
+     */
+    viewCentreInGraphSpace(): Vector2;
     /**
      * Delete everything in the current selection as a single undoable group
+     *
+     * @returns {Promise} settles once the timeline has applied the deletion — {@link ActionProcessor}
+     *          queues, so nothing has been removed on return
+     */
+    deleteSelection(): Promise<any>;
+    /**
+     * Take a copy of the selected nodes, and of every wire they hold whole.
+     *
+     * Reading, not editing, so a read-only canvas offers it: opening one of a library's own groups
+     * to take a copy of what is inside it is the point of being able to open them.
+     *
+     * @returns {boolean} whether anything was copied. A selection with nothing copyable in it leaves
+     *          the clipboard alone rather than emptying it, which is the one outcome an author
+     *          asking for a copy certainly did not want.
+     */
+    copySelection(): boolean;
+    /**
+     * Put what was copied into this graph, in the middle of what the author is looking at.
+     *
+     * Where a paste lands is the one decision here. It goes to the middle of the view rather than
+     * back where it was copied from, for the same reason a node added from the menu with no position
+     * does: what arrives has to be somewhere the author can see it, and the place it was copied from
+     * may be a long way off screen — a copy taken in one phase and pasted in the other has no
+     * meaningful "back where it was" at all. The arrangement inside the fragment is kept exactly; it
+     * is the whole of it that moves. A repeat paste of the same content steps aside by
+     * {@link NODE_GRAPH_PASTE_STEP} so that copies do not hide each other.
+     *
+     * @returns {Promise<NodeInstance[]>} the nodes that landed, once the timeline has applied them;
+     *          empty when there was nothing on the clipboard
+     * @throws if this canvas is read-only
+     */
+    paste(): Promise<NodeInstance[]>;
+    /**
+     * A second of everything selected, beside the originals.
+     *
+     * Beside rather than in the middle of the view, which is where {@link #paste} puts things: a
+     * duplicate is a second of something the author is already looking at, and centring it would
+     * take it away from the thing it is a second of. The clipboard is not touched — `Ctrl+D` is not
+     * a copy, and it must not cost the author whatever they had copied earlier.
+     *
+     * @returns {Promise<NodeInstance[]>} the new nodes; empty when nothing selected could be had a
+     *          second of
+     * @throws if this canvas is read-only
      */
-    deleteSelection(): void;
+    duplicateSelection(): Promise<NodeInstance[]>;
     cameraContainAll(): void;
+    #private;
 }
 import View from "../../../src/view/View.js";
 import { ActionProcessor } from "../../../src/core/process/undo/ActionProcessor.js";
+import { NodeGraphClipboard } from "./NodeGraphClipboard.js";
 import { NodeGraphSelection } from "./NodeGraphSelection.js";
 import { NodeGraphCamera } from "./NodeGraphView.js";
 import { NodeDescriptionVisualRegistry } from "../../../src/core/model/node-graph/visual/NodeDescriptionVisualRegistry.js";
+import { NodeGraphView } from "./NodeGraphView.js";
+import { NodeGraphMinimapView } from "./NodeGraphMinimapView.js";
+import { NodeGraphSearchMenuView } from "./NodeGraphSearchMenuView.js";
+import Vector2 from "../../../src/core/geom/Vector2.js";
 //# sourceMappingURL=NodeGraphEditorView.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphEditorView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphEditorView.js"],"names":[],"mappings":"AAmBA;IACI;;;;;;;;OAQG;IACH,0FA8IC;IA3IG;;;OAGG;IACH,2CAAsC;IAEtC;;;OAGG;IACH,WAFU,kBAAkB,CAEa;IAEzC;;;OAGG;IACH,QAFU,eAAe,CAEL;IACpB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,iBAAkB;IAElB,mBAAuC;IAUvC;;;OAGG;IACH,gBAFU,6BAA6B,CAEH;IAkGxC,eAGC;IAED;;OAEG;IACH,wBA6BC;IAED,yBAuDC;CACJ;iBAvQgB,2BAA2B;gCAHZ,mDAAmD;mCAMhD,yBAAyB;gCADb,oBAAoB;8CAO5D,4EAA4E"}
+{"version":3,"file":"NodeGraphEditorView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphEditorView.js"],"names":[],"mappings":"AAmDA;IAyBI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,+KAiSC;IA7VD;;OAEG;IACH,iBAWE;IA+DE;;OAEG;IACH,UAFU,OAAO,CAEO;IAExB;;;OAGG;IACH,2CAAsC;IAEtC;;;;;OAKG;IACH,WAFU,kBAAkB,CAEF;IAE1B;;OAEG;IACH,kCAFiC,OAAO,CAEA;IAExC;;;OAGG;IACH,WAFU,kBAAkB,CAEa;IAEzC;;;OAGG;IACH,QAFU,eAAe,CAEL;IACpB;;;OAGG;IACH,4BAAoB;IAEpB;;;OAGG;IACH,iBAAkB;IAElB,mBAAuC;IAYvC;;;OAGG;IACH,gBAFU,6BAA6B,CAEH;IAepC;;OAEG;IACH,WAFU,aAAa,CAEG;IA4H1B;;;;;;;;OAQG;IACH,SAFU,oBAAoB,GAAC,IAAI,CAEhB;IA4BnB;;;;;OAKG;IACH,YAFU,uBAAuB,GAAC,IAAI,CAEhB;IAEtB;;;;;;;;;;OAUG;IACH,aAFU,qBAAqB,GAAC,IAAI,CAEb;IAgF3B;;;;;;;;;;;;;;;OAeG;IACH;QAP4B,CAAC,GAAlB,MAAM;QACW,CAAC,GAAlB,MAAM;QACW,UAAU,GAA3B,MAAM;QAC6B,QAAQ;QAC7B,IAAI;QAChB,qBAAqB,CAwBjC;IAED;;;;;;;;;;;;OAYG;IACH,eAWC;IAED;;;;;;;;;OASG;IACH,4BAFa,OAAO,CAInB;IAED;;;;;;;;;;;;;OAaG;IACH;QAN4B,CAAC,GAAlB,MAAM;QACW,CAAC,GAAlB,MAAM;QACW,UAAU,GAA3B,MAAM;QACJ,qBAAqB,CA6BjC;IAED;;;OAGG;IACH,0BAFa,OAAO,CAQnB;IAED;;;;;OAKG;IACH,gCA8BC;IAED;;;;;;;;;OASG;IACH,iBAJa,OAAO,CAmBnB;IAED;;;;;;;;;;;;;;OAcG;IACH,SAJa,QAAQ,cAAc,CAAC,CAiCnC;IAED;;;;;;;;;;;OAWG;IACH,sBAJa,QAAQ,cAAc,CAAC,CAqBnC;IA+DD,yBAuDC;;CACJ;iBAz1BgB,2BAA2B;gCAHZ,mDAAmD;mCA4B5E,yBAAyB;mCArBG,yBAAyB;gCAFb,oBAAoB;8CAS5D,4EAA4E;8BATpC,oBAAoB;qCAC9B,2BAA2B;wCAexB,8BAA8B;oBALlD,mCAAmC"}