@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -0,0 +1,112 @@
+/**
+ * A searchable list of the node types a graph can hold — what an author picks from to add a node.
+ *
+ * It knows nothing about what the nodes are for. Everything specific to a graph's domain arrives as
+ * a callback: which types to offer, what to call the group each belongs in, what one line of help to
+ * show, and what to do when one is picked. A host that wants categories gets them; one that does not
+ * gets a flat list.
+ *
+ * Filtering matches the type's name, the label it is shown under and its category,
+ * case-insensitively, on every keystroke. The
+ * list is rebuilt rather than hidden per row: the registries this is pointed at hold tens of types,
+ * not thousands, and a rebuild keeps "which row is highlighted" from having to survive a filter.
+ *
+ * On top of what is typed, a host may narrow the library itself — see {@link #setPredicate}. That is
+ * a different kind of filter and is kept separate on purpose: what an author types is theirs to
+ * clear, and what the situation allows is not. A wire dropped on open canvas can only be finished by
+ * a type that has a port to take it, and no amount of backspacing makes the others eligible.
+ *
+ * Keyboard: type to filter, up/down to move the highlight, Enter to pick the highlighted type,
+ * Escape to clear the filter — or whatever the host does with it instead.
+ * The list is scrolled to follow the highlight.
+ */
+export class NodeGraphPaletteView extends View {
+    /**
+     * @param {object} options
+     * @param {NodeDescription[]|function():NodeDescription[]} options.descriptions the types to
+     *        offer; a function is called on every rebuild, so a changing library stays in step
+     * @param {function(NodeDescription)} options.onPick invoked with the type the author chose
+     * @param {function(NodeDescription):string} [options.categoryOf] group heading for a type;
+     *        types come back in the order given, grouped by the first appearance of each heading
+     * @param {function(NodeDescription):string} [options.describe] one line of help for a type
+     * @param {string} [options.placeholder] search-field placeholder
+     * @param {string} [options.emptyLabel] what to say when nothing matches
+     * @param {function()} [options.onEscape] what Escape does; clearing the filter by default, and
+     *        for a host that opened this as a menu, closing it
+     */
+    constructor({ descriptions, onPick, categoryOf, describe, placeholder, emptyLabel, onEscape }: {
+        descriptions: NodeDescription[] | (() => NodeDescription[]);
+        onPick: (arg0: NodeDescription) => any;
+        categoryOf?: (arg0: NodeDescription) => string;
+        describe?: (arg0: NodeDescription) => string;
+        placeholder?: string;
+        emptyLabel?: string;
+        onEscape?: () => any;
+    });
+    /**
+     * @type {string}
+     */
+    emptyLabel: string;
+    /**
+     * @type {function()}
+     */
+    onEscape: () => any;
+    el: HTMLDivElement;
+    /**
+     * @type {function():NodeDescription[]}
+     */
+    descriptions: () => NodeDescription[];
+    /**
+     * @type {function(NodeDescription)}
+     */
+    onPick: (arg0: NodeDescription) => any;
+    /**
+     * @type {function(NodeDescription):string}
+     */
+    categoryOf: (arg0: NodeDescription) => string;
+    /**
+     * @type {function(NodeDescription):string}
+     */
+    describe: (arg0: NodeDescription) => string;
+    /**
+     * The current filter. Public so a host can drive it — a canvas gesture that opens the
+     * palette pre-filtered, say.
+     * @type {ObservedString}
+     */
+    filter: ObservedString;
+    /**
+     * Put the caret in the search field. A palette that opens without focus makes the author click
+     * once before they can type.
+     */
+    focusSearch(): void;
+    /**
+     * Narrow the library itself: only types this accepts are offered, whatever is typed.
+     *
+     * For a host that opens this in a situation where most of the library cannot apply — a wire
+     * dropped on open canvas, which only a type with a port to take it can finish. Rebuilds, so the
+     * list and the highlight are correct on return.
+     *
+     * @param {function(NodeDescription):boolean} predicate
+     */
+    setPredicate(predicate: (arg0: NodeDescription) => boolean): void;
+    /**
+     * The types currently offered, in the order shown. What Enter would pick is the first of them
+     * unless the highlight has been moved.
+     *
+     * @returns {NodeDescription[]}
+     */
+    matches(): NodeDescription[];
+    /**
+     * Rebuild the list from the current type set and filter.
+     */
+    rebuild(): void;
+    /**
+     * Choose a type, as though the author had clicked it.
+     * @param {NodeDescription} description
+     */
+    pick(description: NodeDescription): void;
+    #private;
+}
+import View from "../../../src/view/View.js";
+import ObservedString from "../../../src/core/model/ObservedString.js";
+//# sourceMappingURL=NodeGraphPaletteView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphPaletteView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphPaletteView.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA6BI;;;;;;;;;;;;OAYG;IACH;QAXmE,YAAY,EAApE,iBAAiB,UAAY,iBAAiB,CAAA;QAEX,MAAM;QACE,UAAU,8BAA3B,MAAM;QAEW,QAAQ,8BAAzB,MAAM;QACf,WAAW,GAA5B,MAAM;QACW,UAAU,GAA3B,MAAM;QACe,QAAQ;OAkFvC;IApEG;;OAEG;IACH,YAFU,MAAM,CAEY;IAE5B;;OAEG;IACH,oBAAuD;IAEvD,mBAAuC;IAIvC;;OAEG;IACH,oBAFqB,iBAAiB,CAEoD;IAE1F;;OAEG;IACH,uCAAoB;IAEpB;;OAEG;IACH,uCAFoC,MAAM,CAEd;IAE5B;;OAEG;IACH,qCAFoC,MAAM,CAElB;IAExB;;;;OAIG;IACH,QAFU,cAAc,CAEY;IA+BxC;;;OAGG;IACH,oBAGC;IAED;;;;;;;;OAQG;IACH,mDAFqC,OAAO,QAM3C;IAED;;;;;OAKG;IACH,WAFa,iBAAiB,CAI7B;IAED;;OAEG;IACH,gBA4CC;IAgDD;;;OAGG;IACH,yCAEC;;CAgEJ;iBA3VgB,2BAA2B;2BAHjB,2CAA2C"}

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

@@ -0,0 +1,352 @@
+import { noop } from "../../../src/core/function/noop.js";
+import ObservedString from "../../../src/core/model/ObservedString.js";
+import LabelView from "../../../src/view/common/LabelView.js";
+import EmptyView from "../../../src/view/elements/EmptyView.js";
+import View from "../../../src/view/View.js";
+import { NodeIconView } from "./NodeIconView.js";
+
+/**
+ * A searchable list of the node types a graph can hold — what an author picks from to add a node.
+ *
+ * It knows nothing about what the nodes are for. Everything specific to a graph's domain arrives as
+ * a callback: which types to offer, what to call the group each belongs in, what one line of help to
+ * show, and what to do when one is picked. A host that wants categories gets them; one that does not
+ * gets a flat list.
+ *
+ * Filtering matches the type's name, the label it is shown under and its category,
+ * case-insensitively, on every keystroke. The
+ * list is rebuilt rather than hidden per row: the registries this is pointed at hold tens of types,
+ * not thousands, and a rebuild keeps "which row is highlighted" from having to survive a filter.
+ *
+ * On top of what is typed, a host may narrow the library itself — see {@link #setPredicate}. That is
+ * a different kind of filter and is kept separate on purpose: what an author types is theirs to
+ * clear, and what the situation allows is not. A wire dropped on open canvas can only be finished by
+ * a type that has a port to take it, and no amount of backspacing makes the others eligible.
+ *
+ * Keyboard: type to filter, up/down to move the highlight, Enter to pick the highlighted type,
+ * Escape to clear the filter — or whatever the host does with it instead.
+ * The list is scrolled to follow the highlight.
+ */
+export class NodeGraphPaletteView extends View {
+    /**
+     * The types currently passing the filter, in the order shown.
+     * @type {NodeDescription[]}
+     */
+    #matches = [];
+
+    /**
+     * Index into {@link #matches}, or -1 when nothing is highlighted.
+     * @type {number}
+     */
+    #highlight = -1;
+
+    /**
+     * @type {EmptyView}
+     */
+    #list;
+
+    /**
+     * @type {HTMLInputElement}
+     */
+    #search;
+
+    /**
+     * What the situation allows, on top of what is typed. See {@link #setPredicate}.
+     * @type {function(NodeDescription):boolean}
+     */
+    #predicate = () => true;
+
+    /**
+     * @param {object} options
+     * @param {NodeDescription[]|function():NodeDescription[]} options.descriptions the types to
+     *        offer; a function is called on every rebuild, so a changing library stays in step
+     * @param {function(NodeDescription)} options.onPick invoked with the type the author chose
+     * @param {function(NodeDescription):string} [options.categoryOf] group heading for a type;
+     *        types come back in the order given, grouped by the first appearance of each heading
+     * @param {function(NodeDescription):string} [options.describe] one line of help for a type
+     * @param {string} [options.placeholder] search-field placeholder
+     * @param {string} [options.emptyLabel] what to say when nothing matches
+     * @param {function()} [options.onEscape] what Escape does; clearing the filter by default, and
+     *        for a host that opened this as a menu, closing it
+     */
+    constructor({
+                    descriptions,
+                    onPick,
+                    categoryOf = noop,
+                    describe = noop,
+                    placeholder = "Search nodes…",
+                    emptyLabel = "no matching nodes",
+                    onEscape = undefined
+                }) {
+        super();
+
+        /**
+         * @type {string}
+         */
+        this.emptyLabel = emptyLabel;
+
+        /**
+         * @type {function()}
+         */
+        this.onEscape = onEscape ?? (() => this.filter.set(""));
+
+        this.el = document.createElement('div');
+
+        this.addClass('ui-node-graph-palette-view');
+
+        /**
+         * @type {function():NodeDescription[]}
+         */
+        this.descriptions = typeof descriptions === "function" ? descriptions : () => descriptions;
+
+        /**
+         * @type {function(NodeDescription)}
+         */
+        this.onPick = onPick;
+
+        /**
+         * @type {function(NodeDescription):string}
+         */
+        this.categoryOf = categoryOf;
+
+        /**
+         * @type {function(NodeDescription):string}
+         */
+        this.describe = describe;
+
+        /**
+         * The current filter. Public so a host can drive it — a canvas gesture that opens the
+         * palette pre-filtered, say.
+         * @type {ObservedString}
+         */
+        this.filter = new ObservedString("");
+
+        const search = document.createElement('input');
+
+        search.setAttribute('type', 'text');
+        search.setAttribute('spellcheck', 'false');
+        search.setAttribute('placeholder', placeholder);
+        search.classList.add('search');
+
+        this.#search = search;
+
+        search.addEventListener('input', () => this.filter.set(search.value));
+        search.addEventListener('keydown', event => this.#handleKey(event));
+
+        this.el.appendChild(search);
+
+        this.#list = new EmptyView({ classList: ['entries'] });
+
+        this.addChild(this.#list);
+
+        this.bindSignal(this.filter.onChanged, () => {
+            if (search.value !== this.filter.getValue()) {
+                search.value = this.filter.getValue();
+            }
+
+            this.rebuild();
+        });
+
+        this.on.linked.add(this.rebuild, this);
+    }
+
+    /**
+     * Put the caret in the search field. A palette that opens without focus makes the author click
+     * once before they can type.
+     */
+    focusSearch() {
+        this.#search.focus();
+        this.#search.select();
+    }
+
+    /**
+     * Narrow the library itself: only types this accepts are offered, whatever is typed.
+     *
+     * For a host that opens this in a situation where most of the library cannot apply — a wire
+     * dropped on open canvas, which only a type with a port to take it can finish. Rebuilds, so the
+     * list and the highlight are correct on return.
+     *
+     * @param {function(NodeDescription):boolean} predicate
+     */
+    setPredicate(predicate) {
+        this.#predicate = predicate;
+
+        this.rebuild();
+    }
+
+    /**
+     * The types currently offered, in the order shown. What Enter would pick is the first of them
+     * unless the highlight has been moved.
+     *
+     * @returns {NodeDescription[]}
+     */
+    matches() {
+        return this.#matches.slice();
+    }
+
+    /**
+     * Rebuild the list from the current type set and filter.
+     */
+    rebuild() {
+        const needle = this.filter.getValue().trim().toLowerCase();
+
+        this.#matches = this.descriptions().filter(description => {
+            if (!this.#predicate(description)) {
+                return false;
+            }
+
+            if (needle === "") {
+                return true;
+            }
+
+            const category = this.categoryOf(description);
+
+            // the label as well as the name: an author looking for "divide" is not looking for
+            // the mnemonic they would have had to know already
+            return description.name.toLowerCase().includes(needle)
+                || description.getDisplayLabel().toLowerCase().includes(needle)
+                || (typeof category === "string" && category.toLowerCase().includes(needle));
+        });
+
+        this.#highlight = this.#matches.length > 0 ? 0 : -1;
+
+        this.#list.removeAllChildren();
+
+        let open_category;
+
+        this.#matches.forEach((description, index) => {
+            const category = this.categoryOf(description);
+
+            if (typeof category === "string" && category !== open_category) {
+                open_category = category;
+
+                this.#list.addChild(new LabelView(category, { classList: ['category'] }));
+            }
+
+            this.#list.addChild(this.#buildEntry(description, index));
+        });
+
+        if (this.#matches.length === 0) {
+            this.#list.addChild(new LabelView(this.emptyLabel, { classList: ['empty'] }));
+        }
+
+        this.#writeHighlight();
+    }
+
+    /**
+     * @param {NodeDescription} description
+     * @param {number} index
+     * @returns {View}
+     */
+    #buildEntry(description, index) {
+        const entry = new EmptyView({ classList: ['entry'] });
+
+        if (description.icon !== "") {
+            entry.addChild(new NodeIconView(description.icon, { classList: ['icon'] }));
+        }
+
+        const vText = new EmptyView({ classList: ['text'] });
+
+        // the same label the node itself carries, so what is picked here and what lands on the
+        // canvas are recognisably the same thing
+        vText.addChild(new LabelView(description.getDisplayLabel(), { classList: ['name'] }));
+
+        const help = this.describe(description);
+
+        if (typeof help === "string" && help !== "") {
+            vText.addChild(new LabelView(help, { classList: ['description'] }));
+        }
+
+        entry.addChild(vText);
+
+        // pointerdown rather than click: the palette usually lives next to something focusable, and
+        // a click that first moves focus loses the author a keystroke
+        entry.el.addEventListener('pointerdown', event => {
+            event.preventDefault();
+            event.stopPropagation();
+
+            this.#highlight = index;
+            this.#writeHighlight();
+
+            this.pick(description);
+        });
+
+        entry.el.addEventListener('pointerenter', () => {
+            this.#highlight = index;
+            this.#writeHighlight();
+        });
+
+        return entry;
+    }
+
+    /**
+     * Choose a type, as though the author had clicked it.
+     * @param {NodeDescription} description
+     */
+    pick(description) {
+        this.onPick(description);
+    }
+
+    /**
+     * @param {KeyboardEvent} event
+     */
+    #handleKey(event) {
+        if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+            event.preventDefault();
+
+            if (this.#matches.length === 0) {
+                return;
+            }
+
+            const step = event.key === "ArrowDown" ? 1 : -1;
+            const count = this.#matches.length;
+
+            this.#highlight = (this.#highlight + step + count) % count;
+
+            this.#writeHighlight();
+
+            return;
+        }
+
+        if (event.key === "Enter") {
+            event.preventDefault();
+
+            const description = this.#matches[this.#highlight];
+
+            if (description !== undefined) {
+                this.pick(description);
+            }
+
+            return;
+        }
+
+        if (event.key === "Escape") {
+            event.preventDefault();
+
+            this.onEscape();
+        }
+    }
+
+    /**
+     * Reflect the highlight onto the rows, and scroll it into view.
+     */
+    #writeHighlight() {
+        let index = -1;
+
+        for (const child of this.#list.children) {
+            if (!child.el.classList.contains('entry')) {
+                continue;
+            }
+
+            index++;
+
+            const selected = index === this.#highlight;
+
+            child.setClass('highlighted', selected);
+
+            if (selected && typeof child.el.scrollIntoView === "function") {
+                child.el.scrollIntoView({ block: "nearest" });
+            }
+        }
+    }
+}

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

@@ -0,0 +1,76 @@
+/**
+ * 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 {
+    /**
+     * @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 }: {
+        descriptions: NodeDescription[] | (() => NodeDescription[]);
+        categoryOf?: (arg0: NodeDescription) => string;
+        describe?: (arg0: NodeDescription) => string;
+        placeholder?: string;
+    });
+    /**
+     * @readonly
+     */
+    readonly on: any;
+    el: HTMLDivElement;
+    /**
+     * @returns {boolean}
+     */
+    get isOpen(): boolean;
+    /**
+     * The list itself, for a host that wants to drive it — a test, most of all.
+     * @returns {NodeGraphPaletteView}
+     */
+    palette(): NodeGraphPaletteView;
+    /**
+     * 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, heading }: {
+        x: number;
+        y: number;
+        onPick: (arg0: NodeDescription) => void;
+        predicate?: (arg0: NodeDescription) => boolean;
+        heading?: string;
+    }): void;
+    /**
+     * 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?: NodeDescription | null): void;
+    #private;
+}
+import View from "../../../src/view/View.js";
+import { NodeGraphPaletteView } from "./NodeGraphPaletteView.js";
+//# sourceMappingURL=NodeGraphSearchMenuView.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphSearchMenuView.d.ts","sourceRoot":"","sources":["../../../../editor/view/node-graph/NodeGraphSearchMenuView.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAuCI;;;;;;OAMG;IACH;QALmE,YAAY,EAApE,iBAAiB,UAAY,iBAAiB,CAAA;QACH,UAAU,8BAA3B,MAAM;QACW,QAAQ,8BAAzB,MAAM;QACf,WAAW,GAA5B,MAAM;OAiDhB;IA5FD;;OAEG;IACH,iBAWE;IAkCE,mBAAuC;IA8C3C;;OAEG;IACH,sBAEC;IAED;;;OAGG;IACH,WAFa,oBAAoB,CAIhC;IAED;;;;;;;;;OASG;IACH;QAN2B,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACkC,MAAM,6BAApB,IAAI;QACc,SAAS,8BAA3B,OAAO;QAChB,OAAO,GAAxB,MAAM;aAsBhB;IAiCD;;;;;OAKG;IACH,eAFW,kBAAgB,IAAI,QAc9B;;CA+BJ;iBApPgB,2BAA2B;qCACP,2BAA2B"}