plexora 0.0.1__py3-none-any.whl

plexora/plugins/figure_builder/static/figureContextMenu.js

@@ -0,0 +1,253 @@
+/**
+ * FigureContextMenu - the right-click, on the page and in the tray.
+ *
+ * The third level of the interface. Level 1 is the tool rail and the topbar
+ * (always visible), level 2 is the floating bar (visible while something is
+ * selected), and this is everything else: the actions that are worth having and
+ * are not worth a permanent button, which is most of them.
+ *
+ * Having it is what lets the rest of the interface stay small. Bring to front,
+ * Replace image, Copy, Delete from figure and the rest are all one click away
+ * from the thing they act on, and none of them costs a pixel of chrome.
+ *
+ * ## Two deletes, and they are not the same delete
+ *
+ * "Remove from page" unplaces a panel: it goes back to the tray with its
+ * captured scene intact. "Delete from figure" destroys it. The distinction is
+ * load-bearing -- a captured scene can be the only record of a view somebody
+ * spent an hour finding -- so the destructive one is further away, worded as
+ * what it does, and asks first.
+ */
+class FigureContextMenu {
+
+    constructor(options) {
+        this.state = options.state;
+        this.canvas = options.canvas;
+        this.handlers = options.handlers || {};
+        this.el = null;
+        //: Where the menu was opened, in page millimetres. Paste puts things
+        //: where the user right-clicked, which is the only place they could
+        //: have meant.
+        this.point = null;
+    }
+
+    setup(surfaceEl, trayEl) {
+        this._onSurface = (event) => this.openForCanvas(event);
+        surfaceEl?.addEventListener("contextmenu", this._onSurface);
+        this._onTray = (event) => this.openForTray(event);
+        trayEl?.addEventListener("contextmenu", this._onTray);
+
+        this._onDismiss = (event) => {
+            if (this.el && !this.el.contains(event.target)) this.close();
+        };
+        document.addEventListener("pointerdown", this._onDismiss, true);
+        this._onScroll = () => this.close();
+        window.addEventListener("scroll", this._onScroll, true);
+    }
+
+    destroy() {
+        document.removeEventListener("pointerdown", this._onDismiss, true);
+        window.removeEventListener("scroll", this._onScroll, true);
+        this.close();
+    }
+
+    // -- opening -----------------------------------------------------------
+
+    openForCanvas(event) {
+        event.preventDefault();
+        this.point = this.canvas.surfacePoint(event);
+
+        const panelEl = event.target.closest?.(".fb-panel");
+        const annotationEl = event.target.closest?.(".fb-annotation");
+        const id = panelEl ? panelEl.dataset.panelId
+            : annotationEl ? annotationEl.dataset.annotationId : null;
+
+        // Right-clicking something that is not in the selection selects it
+        // first. A menu that acted on a selection somewhere else on the page is
+        // the classic way to delete the wrong thing.
+        if (id && !this.canvas.selection.has(id)) this.canvas.select([id], false);
+        if (!id) this.canvas.select([], false);
+
+        const ids = Array.from(this.canvas.selection);
+        this.open(event.clientX, event.clientY,
+                  ids.length ? this.selectionEntries(ids) : this.pageEntries());
+    }
+
+    openForTray(event) {
+        const item = event.target.closest?.(".fb-tray-item");
+        if (!item) return;
+        event.preventDefault();
+        this.point = null;
+        this.handlers.onTrayContext?.(item.dataset.panelId);
+        this.open(event.clientX, event.clientY,
+                  this.trayEntries(this.handlers.traySelection?.() || [item.dataset.panelId]));
+    }
+
+    // -- what each menu holds ------------------------------------------------
+
+    /**
+     * The right-click rows, from the same registry the floating bar reads.
+     *
+     * It was a separate hand-built list, and the two had already drifted: this
+     * one honestly disabled "Bring to front" when nothing could be reordered
+     * while the bar offered it live on a text box, where it did nothing.
+     */
+    selectionEntries(ids) {
+        const context = {
+            ids: ids,
+            sel: FigureSelection.describe(ids, this.state, this.canvas),
+            canvas: this.canvas,
+            state: this.state,
+            handlers: this.handlers,
+        };
+        const entries = [];
+        let generic = null;
+        for (const action of FigureActions.forSurface("menu", context.sel, context)) {
+            if (generic !== null && Boolean(action.generic) !== generic) {
+                entries.push({ separator: true });
+            }
+            generic = Boolean(action.generic);
+            entries.push({ act: action.id, label: action.label,
+                           icon: action.icon, shortcut: action.shortcut,
+                           disabled: !action.isEnabled, danger: action.danger });
+        }
+        return entries;
+    }
+
+    pageEntries() {
+        return [
+            { act: "paste", label: "Paste", disabled: !FigureClipboard.hasContent() },
+            { separator: true },
+            { act: "select_all", label: "Select everything on this page" },
+            { separator: true },
+            { act: "page_background", label: "Page background…" },
+            { act: "page_duplicate", label: "Duplicate this page" },
+        ];
+    }
+
+    trayEntries(ids) {
+        return [
+            { act: "tray_place", label: ids.length > 1 ? "Place all on this page" : "Place on this page" },
+            { act: "tray_duplicate", label: "Duplicate" },
+            { separator: true },
+            { act: "tray_delete", label: "Delete from figure", danger: true },
+        ];
+    }
+
+    // -- the menu itself -----------------------------------------------------
+
+    open(clientX, clientY, entries) {
+        this.close();
+        this.el = document.createElement("div");
+        this.el.className = "fb-menu";
+        // The icon gutter is drawn only when SOME row in this menu has an icon.
+        // A fixed gutter is what stops a half-iconed list having a ragged left
+        // edge; in a list where no row has one at all -- the page menu, the tray
+        // menu -- it is fourteen pixels of indent that says nothing.
+        const gutter = entries.some((entry) => entry.icon);
+        this.el.innerHTML = entries.map((entry) => entry.separator
+            ? '<span class="fb-menu-separator"></span>'
+            : `<button type="button" class="fb-menu-item${entry.danger ? " is-danger" : ""}"
+                       data-act="${entry.act}" ${entry.disabled ? "disabled" : ""}>${gutter
+                       ? `<span class="fb-menu-icon" aria-hidden="true">${entry.icon
+                           ? `<span class="fas fa-${entry.icon}"></span>` : ""}</span>` : ""}
+                   <span class="fb-menu-text">${FigureSchema.escapeHtml(entry.label)}</span>${
+                   entry.shortcut
+                       ? `<span class="fb-menu-key" aria-hidden="true">${
+                           FigureSchema.escapeHtml(entry.shortcut)}</span>` : ""}</button>`
+        ).join("");
+        document.body.appendChild(this.el);
+
+        // Flipped rather than clipped: a menu opened near the bottom right of
+        // the window has to open up and to the left, or its last item -- which
+        // is the destructive one -- is off screen.
+        // offsetWidth/Height and not getBoundingClientRect: the card animates
+        // in with a `scale(0.97)`, and a client rect is the TRANSFORMED box.
+        // Measuring it mid-animation would under-report the size by a few
+        // pixels and decide "does this fit below?" from a number that stops
+        // being true 120ms later. The offset pair is the layout box, which the
+        // animation never touches.
+        const size = { width: this.el.offsetWidth, height: this.el.offsetHeight };
+        const left = clientX + size.width > window.innerWidth - 8
+            ? Math.max(8, clientX - size.width) : clientX;
+        const top = clientY + size.height > window.innerHeight - 8
+            ? Math.max(8, clientY - size.height) : clientY;
+        this.el.style.left = Math.round(left) + "px";
+        this.el.style.top = Math.round(top) + "px";
+
+        this.el.addEventListener("click", (event) => {
+            const item = event.target.closest("[data-act]");
+            if (!item || item.disabled) return;
+            const act = item.dataset.act;
+            this.close();
+            this.run(act);
+        });
+    }
+
+    close() {
+        this.el?.remove();
+        this.el = null;
+    }
+
+    run(act) {
+        const ids = Array.from(this.canvas.selection);
+        const handlers = this.handlers;
+
+        // A selection action runs from the registry. Only the entries that are
+        // about the PAGE or the TRAY rather than about the selection are
+        // dispatched here, because those have no selection to describe.
+        const action = FigureActions.byId(act);
+        if (action && action.run) {
+            action.run({ ids: ids,
+                         sel: FigureSelection.describe(ids, this.state, this.canvas),
+                         canvas: this.canvas, state: this.state,
+                         handlers: handlers });
+            return;
+        }
+        ({
+            paste: () => this.canvas.paste(this.point),
+            select_all: () => this.canvas.selectAllOnPage(),
+            page_background: () => handlers.onPageBackground?.(),
+            page_duplicate: () => handlers.onDuplicatePage?.(),
+            tray_place: () => handlers.onPlaceFromTray?.(),
+            tray_duplicate: () => handlers.onDuplicateTray?.(),
+            tray_delete: () => handlers.onDeleteTray?.(),
+        }[act] || (() => {}))();
+    }
+}
+
+
+/**
+ * The clipboard, for this tab.
+ *
+ * A module singleton rather than the OS clipboard. What is copied here is a
+ * captured SCENE -- a source id, a region in image pixels, a set of channels
+ * and windows -- and none of that means anything in another application, or in
+ * another figure that does not reference the same image. Writing it to the
+ * system clipboard would offer a paste everywhere that can only fail almost
+ * everywhere.
+ *
+ * Cross-tab paste is deliberately not built either: two tabs on one figure is
+ * the case the whole revision system exists to keep honest, and a paste that
+ * crossed between them would arrive against a revision it was not copied from.
+ */
+const FigureClipboard = {
+    panels: [],
+    annotations: [],
+
+    hasContent() {
+        return this.panels.length > 0 || this.annotations.length > 0;
+    },
+
+    put(panels, annotations) {
+        this.panels = JSON.parse(JSON.stringify(panels || []));
+        this.annotations = JSON.parse(JSON.stringify(annotations || []));
+    },
+
+    take() {
+        return {
+            panels: JSON.parse(JSON.stringify(this.panels)),
+            annotations: JSON.parse(JSON.stringify(this.annotations)),
+        };
+    },
+};

plexora/plugins/figure_builder/static/figureDocumentState.js

@@ -0,0 +1,275 @@
+/**
+ * FigureDocumentState - the open figure, and everything about saving it.
+ *
+ * One object owns the document, the revision, the save queue and the undo
+ * stack, because all four are the same question asked from different angles and
+ * splitting them is how a client ends up saving a revision it no longer holds.
+ *
+ * Three decisions worth stating:
+ *
+ * **The server is the only interpreter of operations.** This side edits its own
+ * copy directly and sends the equivalent operation list; it does not reimplement
+ * `operations.py`. Two implementations of "what does add_panel mean" is two
+ * implementations that can disagree, and the disagreement would be invisible
+ * until a figure was reopened. If the server rejects a batch, the local copy is
+ * rolled back to the last confirmed one -- so the two can never drift, because
+ * only agreement survives.
+ *
+ * **Saves are chained, never concurrent**, and each reads the revision at the
+ * moment it is SENT rather than the moment the edit was made. Those two moments
+ * are not the same one: a commit made while an earlier save is still in flight
+ * would otherwise carry a revision the server has already moved past, and be
+ * answered with a 409 that no other session had anything to do with. Reading it
+ * late is safe precisely because the chain means nothing else can have written
+ * in between. Chaining also makes the outcome deterministic: without it, a slow
+ * earlier save can land after a newer one and quietly reinstate what the newer
+ * one changed.
+ *
+ * **Undo is a snapshot, not an inverse.** A figure document is a few hundred
+ * kilobytes at worst -- it holds references and geometry, never pixels -- so
+ * keeping N of them costs nothing next to writing and maintaining an inverse
+ * for every operation, and an inverse that is subtly wrong corrupts a figure
+ * silently. Undo is sent as a whole-document replace, which is a new revision:
+ * revisions only ever go forwards, and the conflict check depends on that.
+ */
+class FigureDocumentState {
+
+    /** How many undo steps are kept. Past this, the oldest is dropped. */
+    static get HISTORY_LIMIT() { return 50; }
+
+    constructor(options) {
+        this.api = options.api;
+        this.figureId = options.figureId;
+
+        this.document = null;
+        this.sourceStatus = {};
+        /** "loading" | "saved" | "saving" | "unsaved" | "failed" | "conflict" | "unreadable" */
+        this.status = "loading";
+        this.statusDetail = "";
+
+        this._listeners = { change: [], status: [] };
+        this._chain = Promise.resolve();
+        this._undo = [];
+        this._redo = [];
+
+        ["change", "status"].forEach((name) => {
+            if (typeof options["on" + name.charAt(0).toUpperCase() + name.slice(1)] === "function") {
+                this._listeners[name].push(options["on" + name.charAt(0).toUpperCase() + name.slice(1)]);
+            }
+        });
+    }
+
+    on(event, handler) {
+        if (this._listeners[event]) this._listeners[event].push(handler);
+        return this;
+    }
+
+    _emit(event, payload) {
+        (this._listeners[event] || []).forEach((handler) => {
+            try {
+                handler(payload, this);
+            } catch (error) {
+                // One broken listener must not stop the others, and must not
+                // abort a save that has already happened.
+                console.error("figure_builder: listener failed", error);
+            }
+        });
+    }
+
+    _setStatus(status, detail) {
+        this.status = status;
+        this.statusDetail = detail || "";
+        this._emit("status", { status: status, detail: this.statusDetail });
+    }
+
+    get revision() {
+        return this.document ? this.document.revision : 0;
+    }
+
+    get canUndo() { return this._undo.length > 0; }
+    get canRedo() { return this._redo.length > 0; }
+
+    async load() {
+        const result = await this.api.getFigure(this.figureId);
+        if (result.status === 422) {
+            this._setStatus("unreadable", result.data.detail || result.data.error || "");
+            return false;
+        }
+        if (!result.ok) {
+            this._setStatus("failed", result.status === 404
+                ? "This figure no longer exists."
+                : "Could not open this figure.");
+            return false;
+        }
+        this.document = result.data.document;
+        this.sourceStatus = result.data.source_status || {};
+        this._undo = [];
+        this._redo = [];
+        this._setStatus("saved");
+        this._emit("change", this.document);
+        return true;
+    }
+
+    /**
+     * Change the figure and save the change.
+     *
+     * `mutate(draft)` applies the edit to a copy of the document for immediate
+     * display; `operations` is the same edit expressed for the server. They
+     * describe one action, which is why they are passed together -- and one
+     * call here is one undo step, whatever it contains, because that is what
+     * makes a five-panel split undo as a split rather than as five deletions.
+     *
+     * Returns a promise for `true` if it was stored.
+     */
+    commit(operations, mutate) {
+        if (!this.document) return Promise.resolve(false);
+
+        const before = this._snapshot();
+        const draft = this._snapshot();
+        try {
+            if (typeof mutate === "function") mutate(draft);
+        } catch (error) {
+            console.error("figure_builder: local edit failed", error);
+            return Promise.resolve(false);
+        }
+
+        this.document = draft;
+        this._undo.push(before);
+        if (this._undo.length > FigureDocumentState.HISTORY_LIMIT) this._undo.shift();
+        // A new edit is a new branch: whatever was undone is no longer
+        // reachable, and offering a redo that would reinstate a state the user
+        // has since edited past is offering an action nobody can predict.
+        this._redo = [];
+        this._setStatus("unsaved");
+        this._emit("change", this.document);
+
+        return this._enqueue(async () => {
+            // Read HERE, not where the commit was made. The queue serialises
+            // saves, so an earlier one may have moved the figure on between the
+            // two moments -- and `before.revision` is then a revision the server
+            // has already superseded, which it answers with a 409 that has
+            // nothing to do with another session. Placing a text box and pressing
+            // Escape was enough: the add and the remove are two commits in the
+            // same breath, and the second carried the revision from before the
+            // first.
+            //
+            // Basing the operations on the latest CONFIRMED revision is exactly
+            // what the chain exists to make safe: nothing else can have written
+            // in between, because nothing else is allowed to be in flight.
+            const baseRevision = this.revision;
+            this._setStatus("saving");
+            let result;
+            try {
+                result = await this.api.patchFigure(this.figureId, baseRevision, operations);
+            } catch (error) {
+                // Never discard local state after a failed save: the network is
+                // the thing that failed, and the user's work is still here.
+                this._setStatus("failed", "Could not reach the server. Your changes are still here.");
+                return false;
+            }
+            return this._settle(result, before);
+        });
+    }
+
+    /** Roll back one committed action. */
+    undo() {
+        if (!this._undo.length) return Promise.resolve(false);
+        const target = this._undo.pop();
+        this._redo.push(this._snapshot());
+        return this._replaceWith(target);
+    }
+
+    redo() {
+        if (!this._redo.length) return Promise.resolve(false);
+        const target = this._redo.pop();
+        this._undo.push(this._snapshot());
+        return this._replaceWith(target);
+    }
+
+    _replaceWith(target) {
+        const current = this.document;
+        const draft = JSON.parse(JSON.stringify(target));
+        // The revision is the CURRENT one, not the one the snapshot was taken
+        // at: going back to an earlier state is a new edit, and rewinding the
+        // number would make every other tab's next save look valid when it is
+        // not.
+        draft.revision = current.revision;
+        this.document = draft;
+        this._setStatus("unsaved");
+        this._emit("change", this.document);
+
+        return this._enqueue(async () => {
+            // Same as `commit`: the revision is whatever is confirmed when the
+            // request goes out, not what was current when undo was pressed. Two
+            // undos in a row is the case that broke.
+            const baseRevision = this.revision;
+            draft.revision = baseRevision;
+            this._setStatus("saving");
+            let result;
+            try {
+                result = await this.api.replaceFigure(this.figureId, baseRevision, draft);
+            } catch (error) {
+                this._setStatus("failed", "Could not reach the server. Your changes are still here.");
+                return false;
+            }
+            return this._settle(result, current);
+        });
+    }
+
+    _settle(result, before) {
+        if (result.ok) {
+            this.document.revision = result.data.revision;
+            this._setStatus("saved");
+            return true;
+        }
+        if (result.status === 409) {
+            // Both sides have work. Nothing is discarded here -- the banner
+            // asks, and reloading is the user's decision.
+            this._setStatus("conflict", "This figure was modified in another session.");
+            return false;
+        }
+        if (result.status === 422) {
+            this._setStatus("unreadable", result.data.detail || "");
+            return false;
+        }
+        // The server refused the edit itself. The local copy is now describing
+        // something that was never stored, so it goes back to what was
+        // confirmed -- otherwise the next save would be built on a state the
+        // server has never seen.
+        this.document = before;
+        this._undo.pop();
+        this._setStatus("failed", result.data.error || "That change could not be saved.");
+        this._emit("change", this.document);
+        return false;
+    }
+
+    _enqueue(task) {
+        this._chain = this._chain.then(task, task);
+        return this._chain;
+    }
+
+    _snapshot() {
+        return JSON.parse(JSON.stringify(this.document));
+    }
+
+    // -- convenience readers, so callers do not reach into the shape ------
+
+    get title() { return this.document ? this.document.title : ""; }
+
+    get pages() { return this.document ? this.document.pages : []; }
+
+    panel(panelId) {
+        return (this.document && this.document.panels[panelId]) || null;
+    }
+
+    source(sourceId) {
+        return (this.document && this.document.sources[sourceId]) || null;
+    }
+
+    /** The source registered for a datasource, or null if it is not one yet. */
+    sourceForDatasource(datasource) {
+        if (!this.document) return null;
+        return Object.values(this.document.sources).find(
+            (source) => source.kind === "plexora_project" && source.datasource === datasource) || null;
+    }
+}