plexora 0.0.1__py3-none-any.whl

plexora/client/src/js/views/colorSwatchPicker.js

@@ -0,0 +1,202 @@
+/**
+ * @class ColorSwatchPicker - one-click curated color palette popover, with a
+ * native <input type="color"> escape hatch for exact/custom hex values.
+ */
+class ColorSwatchPicker {
+    constructor(mount, options = {}) {
+        this.mount = mount;
+        this.value = options.value || "#2388ff";
+        this.presets = options.presets || ColorSwatchPicker.DEFAULT_PRESETS;
+        this.title = options.title || "Channel color";
+        this.onChange = options.onChange || (() => {});
+        this.isOpen = false;
+        this.render();
+        this.bindDismissHandlers();
+    }
+
+    render() {
+        this.mount.innerHTML = "";
+        this.mount.classList.add("color-swatch-mount");
+
+        this.button = document.createElement("button");
+        this.button.type = "button";
+        this.button.className = "channel-color-swatch";
+        this.button.title = this.title;
+        this.button.setAttribute("aria-label", this.title);
+        this.button.style.setProperty("--swatch-color", this.value);
+        this.button.setAttribute("aria-haspopup", "true");
+        this.button.setAttribute("aria-expanded", "false");
+        this.button.addEventListener("click", (event) => {
+            event.stopPropagation();
+            this.toggle();
+        });
+        this.mount.appendChild(this.button);
+
+        this.popover = document.createElement("div");
+        this.popover.className = "color-swatch-popover";
+        this.popover.hidden = true;
+        this.popover.addEventListener("click", (event) => event.stopPropagation());
+
+        const grid = document.createElement("div");
+        grid.className = "color-swatch-grid";
+        this.presets.forEach((preset) => {
+            const swatch = document.createElement("button");
+            swatch.type = "button";
+            swatch.className = "color-swatch-option";
+            swatch.title = preset.label;
+            swatch.style.setProperty("--swatch-color", preset.hex);
+            swatch.classList.toggle("is-selected", preset.hex.toLowerCase() === this.value.toLowerCase());
+            swatch.addEventListener("click", () => this.selectColor(preset.hex));
+            grid.appendChild(swatch);
+        });
+        this.popover.appendChild(grid);
+
+        const customRow = document.createElement("label");
+        customRow.className = "color-swatch-custom-row";
+        const customLabel = document.createElement("span");
+        customLabel.textContent = "Custom";
+        customRow.appendChild(customLabel);
+        this.customInput = document.createElement("input");
+        this.customInput.type = "color";
+        this.customInput.value = this.value;
+        this.customInput.addEventListener("input", (event) => this.selectColor(event.target.value, { keepOpen: true }));
+        customRow.appendChild(this.customInput);
+        this.popover.appendChild(customRow);
+
+        // Appended to <body> (a positioning "portal"), not this.mount: a disabled/dimmed
+        // ancestor row has opacity < 1, which creates its own CSS stacking context and
+        // would trap this popover's z-index behind the *next* row otherwise.
+        document.body.appendChild(this.popover);
+    }
+
+    toggle() {
+        if (this.isOpen) {
+            this.close();
+        } else {
+            this.open();
+        }
+    }
+
+    open() {
+        if (ColorSwatchPicker.activeInstance && ColorSwatchPicker.activeInstance !== this) {
+            ColorSwatchPicker.activeInstance.close();
+        }
+        ColorSwatchPicker.activeInstance = this;
+        this.isOpen = true;
+        this.positionPopover();
+        this.popover.hidden = false;
+        requestAnimationFrame(() => this.popover.classList.add("is-open"));
+        this.button.setAttribute("aria-expanded", "true");
+        this.bindDismissListeners();
+    }
+
+    positionPopover() {
+        const rect = this.button.getBoundingClientRect();
+        this.popover.style.left = `${rect.left}px`;
+        this.popover.style.top = `${rect.bottom + 6}px`;
+    }
+
+    close() {
+        this.isOpen = false;
+        if (!this.popover) return;
+        this.popover.classList.remove("is-open");
+        this.button.setAttribute("aria-expanded", "false");
+        window.setTimeout(() => {
+            // The popover may have been destroyed inside this delay -- closing
+            // is the first thing destroy() does.
+            if (!this.isOpen && this.popover) this.popover.hidden = true;
+        }, 150);
+        if (ColorSwatchPicker.activeInstance === this) {
+            ColorSwatchPicker.activeInstance = null;
+        }
+        this.unbindDismissListeners();
+    }
+
+    bindDismissListeners() {
+        if (this._dismissScroll) return;
+        this._dismissScroll = (event) => {
+            if (event.target === this.popover || this.popover.contains(event.target)) return;
+            this.close();
+        };
+        this._dismissResize = () => this.close();
+        window.addEventListener("scroll", this._dismissScroll, true);
+        window.addEventListener("resize", this._dismissResize);
+    }
+
+    unbindDismissListeners() {
+        if (!this._dismissScroll) return;
+        window.removeEventListener("scroll", this._dismissScroll, true);
+        window.removeEventListener("resize", this._dismissResize);
+        this._dismissScroll = null;
+        this._dismissResize = null;
+    }
+
+    selectColor(hex, opts = {}) {
+        this.setValue(hex);
+        this.onChange(hex);
+        if (!opts.keepOpen) this.close();
+    }
+
+    setValue(hex) {
+        this.value = hex;
+        this.button.style.setProperty("--swatch-color", hex);
+        this.customInput.value = hex;
+        this.popover.querySelectorAll(".color-swatch-option").forEach((el) => {
+            el.classList.toggle("is-selected", el.style.getPropertyValue("--swatch-color").toLowerCase() === hex.toLowerCase());
+        });
+    }
+
+    bindDismissHandlers() {
+        // Kept on the instance so destroy() can take them off again. Anonymous
+        // handlers here meant every picker ever built stayed subscribed to
+        // document for the life of the page, which is invisible while pickers
+        // are per-channel and created once, and is not once a list rebuilds a
+        // row of them on every keystroke.
+        this._documentClick = (event) => {
+            if (this.isOpen && !this.mount.contains(event.target) && !this.popover.contains(event.target)) {
+                this.close();
+            }
+        };
+        this._documentKeydown = (event) => {
+            if (event.key === "Escape" && this.isOpen) {
+                this.close();
+            }
+        };
+        document.addEventListener("click", this._documentClick);
+        document.addEventListener("keydown", this._documentKeydown);
+    }
+
+    /**
+     * Take this picker off the page for good.
+     *
+     * The popover lives on <body> rather than inside the mount (see render), so
+     * removing the row that owns it leaves the popover behind. Callers that
+     * rebuild their rows must call this, or the orphans accumulate.
+     */
+    destroy() {
+        this.close();
+        this.unbindDismissListeners();
+        document.removeEventListener("click", this._documentClick);
+        document.removeEventListener("keydown", this._documentKeydown);
+        this.popover?.remove();
+        this.popover = null;
+        if (ColorSwatchPicker.activeInstance === this) {
+            ColorSwatchPicker.activeInstance = null;
+        }
+    }
+}
+
+ColorSwatchPicker.DEFAULT_PRESETS = [
+    { label: "Blue", hex: "#2388ff" },
+    { label: "Red", hex: "#ff2d2d" },
+    { label: "Green", hex: "#2bd46f" },
+    { label: "White", hex: "#ffffff" },
+    { label: "Yellow", hex: "#ffd60a" },
+    { label: "Magenta", hex: "#ec4899" },
+    { label: "Cyan", hex: "#22e6e6" },
+    { label: "Orange", hex: "#f97316" },
+    { label: "Violet", hex: "#a78bfa" },
+    { label: "Gray", hex: "#94a3b8" },
+];
+
+ColorSwatchPicker.activeInstance = null;

plexora/client/src/js/views/columnClassifier.js

@@ -0,0 +1,146 @@
+/**
+ * columnClassifier.js -- which columns are markers, and which are metadata.
+ *
+ * Two boxes side by side. The server predicts the split (adapters/classify.py)
+ * and the user corrects it by dragging; the metadata box additionally carries
+ * the role slots, because a role always names a metadata column -- the cell id
+ * and the coordinates are measurements *about* a cell, never markers measured
+ * on one.
+ *
+ * Mounted by three callers -- the CSV import step, the requirements modal, and
+ * the project edit page -- which is why it is a component rather than page
+ * code. All three are asking the same question and must store the same answer.
+ *
+ * Uses window.Sortable (vendored via webpack's vendor bundle, loaded by
+ * base.html on every page).
+ */
+window.PlexoraColumnClassifier = (function () {
+    /**
+     * @param mount        element to render into
+     * @param options.markers    predicted marker columns, in table order
+     * @param options.metadata   predicted metadata columns, in table order
+     * @param options.roles      role -> column name, as already recorded
+     * @param options.roleLabels role -> human label (from the server, so the
+     *                           wording matches the requirements modal)
+     * @param options.onChange   called after every edit
+     * @returns { value(), destroy() }
+     */
+    function mount(mount, options = {}) {
+        const roleLabels = options.roleLabels || {};
+        const roleNames = Object.keys(roleLabels);
+        const roles = { ...(options.roles || {}) };
+        let markers = [...(options.markers || [])];
+        let metadata = [...(options.metadata || [])];
+        const sortables = [];
+
+        mount.innerHTML = `
+            <div class="column-classifier">
+                <div class="column-box" data-group="metadata">
+                    <div class="column-box-head">
+                        <h2>Metadata</h2>
+                        <span class="field-hint">Identifiers, coordinates, morphology, annotations.</span>
+                    </div>
+                    <div class="column-roles"></div>
+                    <ul class="column-list" data-group="metadata"></ul>
+                </div>
+                <div class="column-box" data-group="markers">
+                    <div class="column-box-head">
+                        <h2>Markers</h2>
+                        <span class="field-hint">Per-cell intensities that can be plotted or thresholded.</span>
+                    </div>
+                    <ul class="column-list" data-group="markers"></ul>
+                </div>
+            </div>
+            <p class="column-classifier-hint">
+                Drag a column between the boxes to correct it.
+            </p>
+        `;
+
+        const lists = {
+            metadata: mount.querySelector('.column-list[data-group="metadata"]'),
+            markers: mount.querySelector('.column-list[data-group="markers"]'),
+        };
+        const rolesMount = mount.querySelector('.column-roles');
+
+        function item(name) {
+            const li = document.createElement('li');
+            li.className = 'column-chip';
+            li.dataset.column = name;
+            li.textContent = name;
+            return li;
+        }
+
+        function renderList(group, names) {
+            lists[group].replaceChildren(...names.map(item));
+        }
+
+        function renderRoles() {
+            // Rebuilt whenever the metadata box changes: a role can only name a
+            // column that is in it, and dragging a column out has to clear any
+            // role pointing at it rather than leave a dangling name.
+            rolesMount.replaceChildren(...roleNames.map((role) => {
+                const field = document.createElement('label');
+                field.className = 'column-role';
+                field.textContent = roleLabels[role];
+
+                const select = document.createElement('select');
+                select.className = 'form-select';
+                select.dataset.role = role;
+                select.append(new Option('—', ''));
+                metadata.forEach((name) => {
+                    select.append(new Option(name, name, false, roles[role] === name));
+                });
+                if (roles[role] && !metadata.includes(roles[role])) {
+                    roles[role] = null;
+                }
+                select.addEventListener('change', () => {
+                    roles[role] = select.value || null;
+                    options.onChange?.();
+                });
+                field.appendChild(select);
+                return field;
+            }));
+        }
+
+        function readLists() {
+            metadata = [...lists.metadata.children].map((li) => li.dataset.column);
+            markers = [...lists.markers.children].map((li) => li.dataset.column);
+            renderRoles();
+            options.onChange?.();
+        }
+
+        renderList('metadata', metadata);
+        renderList('markers', markers);
+        renderRoles();
+
+        // One shared group name is what makes the two lists exchange items;
+        // without it each list only reorders within itself.
+        Object.values(lists).forEach((list) => {
+            sortables.push(new Sortable(list, {
+                group: 'plexora-columns',
+                animation: 150,
+                ghostClass: 'column-chip-ghost',
+                onSort: readLists,
+            }));
+        });
+
+        return {
+            value() {
+                // Only the roles this instance actually drew. A caller that
+                // narrows `roleLabels` is saying "I am not the surface that
+                // asks about the rest" -- and echoing an unrendered role back
+                // would have the server record it as confirmed, retiring a
+                // question nobody was ever shown.
+                const answered = Object.fromEntries(
+                    roleNames.map((role) => [role, roles[role] ?? null]));
+                return { markers: [...markers], metadata: [...metadata], roles: answered };
+            },
+            destroy() {
+                sortables.forEach((s) => s.destroy());
+                mount.innerHTML = '';
+            },
+        };
+    }
+
+    return { mount };
+})();

plexora/client/src/js/views/coordinateField.js

@@ -0,0 +1,133 @@
+/**
+ * The "where are the cell coordinates" control.
+ *
+ * Shared by the requirements modal and the project edit page, the same way
+ * columnClassifier.js is -- both ask this question and neither should own a
+ * private version of the answer shape, which is a read spec the server has to
+ * be able to apply either way.
+ *
+ * Why it is one control rather than the two column selects it replaces:
+ *
+ *   A file can put a cell's position in either of two places. `obs` holds it as
+ *   a pair of columns, which two selects express fine. `obsm` holds it as one
+ *   (n, 2) array holding BOTH axes -- and "which column is X" has no answer for
+ *   that. So the obsm case could previously only appear as a blank option with
+ *   the detected key printed on it: visible, unpickable, never confirmed. The
+ *   source got decided by matching the key name against a hardcoded list.
+ *
+ *   That is not a safe way to decide it. A store routinely carries `spatial`
+ *   and `X_umap` as identically-shaped (n, 2) float32 arrays, so nothing about
+ *   the data separates a position from an embedding -- and a file whose UMAP
+ *   happens to be named `spatial` would have had every cell drawn in UMAP space
+ *   with nothing said. Hence: list every candidate with its shape, and let the
+ *   person who knows the file choose.
+ *
+ * mount() returns { value() }, where value() is the payload the server takes:
+ *
+ *     { source: "obsm", obsm_key: "spatial" }
+ *     { source: "obs", x_column: "X_centroid", y_column: "Y_centroid" }
+ *
+ * or null while the choice is incomplete, so a caller can tell "not answered
+ * yet" from "answered" without inspecting the controls.
+ */
+window.PlexoraCoordinateField = (function () {
+
+    function el(tag, className, text) {
+        const node = document.createElement(tag);
+        if (className) node.className = className;
+        if (text) node.textContent = text;
+        return node;
+    }
+
+    /** `obsm["spatial"] · 42609 × 2` -- the name, and the shape that is the
+     *  only other thing on offer to tell candidates apart. */
+    function describe(entry) {
+        const shape = (entry.shape || []).join(" × ");
+        return shape ? `obsm["${entry.name}"] · ${shape}` : `obsm["${entry.name}"]`;
+    }
+
+    /**
+     * @param container   element to render into
+     * @param options     { obsm: [{name, shape}], obs: [name], current: {...},
+     *                      name: unique radio-group name, onChange(value) }
+     */
+    function mount(container, options) {
+        const obsmEntries = options.obsm || [];
+        const obsColumns = options.obs || [];
+        const current = options.current || {};
+        const onChange = options.onChange || function () {};
+        const groupName = options.name || "coordinates";
+
+        const root = el("div", "coordinate-field");
+
+        const obsmSelect = el("select", "form-select");
+        obsmSelect.append(new Option("Choose an array…", ""));
+        obsmEntries.forEach((entry) => {
+            obsmSelect.append(new Option(describe(entry), entry.name));
+        });
+
+        const obsRow = el("div", "coordinate-field-pair");
+        const xSelect = el("select", "form-select");
+        const ySelect = el("select", "form-select");
+        [[xSelect, "X column…"], [ySelect, "Y column…"]].forEach(([select, blank]) => {
+            select.append(new Option(blank, ""));
+            obsColumns.forEach((name) => select.append(new Option(name, name)));
+            obsRow.appendChild(select);
+        });
+
+        let source = current.source === "obs" ? "obs" : "obsm";
+
+        function value() {
+            if (source === "obsm") {
+                return obsmSelect.value
+                    ? { source: "obsm", obsm_key: obsmSelect.value } : null;
+            }
+            return (xSelect.value && ySelect.value)
+                ? { source: "obs", x_column: xSelect.value, y_column: ySelect.value }
+                : null;
+        }
+
+        function show(next) {
+            source = next;
+            obsmSelect.hidden = next !== "obsm";
+            obsRow.hidden = next !== "obs";
+            onChange(value());
+        }
+
+        // A radio rather than a third dropdown: the choice changes what the
+        // control below it is asking, and the user has to see both places at
+        // once to know the other one exists.
+        const radios = el("div", "coordinate-field-source");
+        [["obsm", ".obsm"], ["obs", ".obs"]].forEach(([choice, label]) => {
+            const wrapper = el("label", "coordinate-field-radio");
+            const input = document.createElement("input");
+            input.type = "radio";
+            input.name = groupName;
+            input.value = choice;
+            input.checked = choice === source;
+            input.addEventListener("change", () => {
+                if (input.checked) show(choice);
+            });
+            wrapper.appendChild(input);
+            wrapper.appendChild(el("span", null, label));
+            radios.appendChild(wrapper);
+        });
+
+        if (current.obsm_key) obsmSelect.value = current.obsm_key;
+        if (current.x_column) xSelect.value = current.x_column;
+        if (current.y_column) ySelect.value = current.y_column;
+        [obsmSelect, xSelect, ySelect].forEach((select) => {
+            select.addEventListener("change", () => onChange(value()));
+        });
+
+        root.appendChild(radios);
+        root.appendChild(obsmSelect);
+        root.appendChild(obsRow);
+        container.appendChild(root);
+
+        show(source);
+        return { value };
+    }
+
+    return { mount };
+}());