@genome-spy/core 0.73.0 → 0.75.0

package/dist/src/scales/scaleResolution.js

@@ -28,15 +28,19 @@ import {
     isPrimaryPositionalChannel,
     isSecondaryChannel,
 } from "../encoder/encoder.js";
+import { isExprRef } from "../paramRuntime/paramUtils.js";
 import { NominalDomain } from "../utils/domainArray.js";
 import { shallowArrayEquals } from "../utils/arrayUtils.js";
 import createIndexer from "../utils/indexer.js";
+import { getCachedOrCall, invalidate } from "../utils/propertyCacher.js";
 import { resolveUrl } from "../utils/url.js";
+import { orderResolutionMembers } from "./resolutionMemberOrder.js";
 import {
+    findIntervalSelectionBindingOwners,
     normalizeIntervalForSelection,
     requireIntervalSelection,
-    requireParamRuntime,
 } from "./selectionDomainUtils.js";
+import { toExternalIndexLikeInterval } from "./indexLikeDomainUtils.js";
 
 // Register scaleLocus to Vega-Scale.
 // Loci are discrete but the scale's domain can be adjusted in a continuous manner.
@@ -98,6 +102,9 @@ export default class ScaleResolution {
     /** @type {Set<ScaleResolutionMember>} */
     #dataDomainMembers = new Set();
 
+    /** @type {ScaleResolutionMember[] | undefined} */
+    #orderedMembers;
+
     /**
      * @type {Record<ScaleResolutionEventType, Set<ScaleResolutionListener>>}
      */
@@ -125,10 +132,28 @@ export default class ScaleResolution {
 
     #selectionReverseSyncSuppressionDepth = 0;
 
+    /** @type {(() => void)[]} */
+    #configuredDomainExprUnsubscribers = [];
+
+    #ignoreSelectionInitial = false;
+
+    /** @type {[number, number] | null | undefined} */
+    #lastLinkedSelectionInterval = undefined;
+
+    /** @type {import("../view/view.js").default | undefined} */
+    #hostView;
+
+    #resolvingScaleProps = 0;
+
+    #memberRegistrationBatchDepth = 0;
+
+    #membersDirty = false;
+
     /**
      * @param {Channel} channel
+     * @param {import("../view/view.js").default} [hostView]
      */
-    constructor(channel) {
+    constructor(channel, hostView) {
         this.channel = channel;
         /** @type {import("../spec/channel.js").Type} Data type (quantitative, nominal, etc...) */
         this.type = null;
@@ -136,8 +161,11 @@ export default class ScaleResolution {
         /** @type {string} An optional unique identifier for the scale */
         this.name = undefined;
 
+        this.#hostView = hostView;
+
         this.#domainAggregator = new DomainPlanner({
-            getMembers: () => this.#getActiveMembers(),
+            getActiveMembers: () => this.#getActiveMembers(),
+            getAllMembers: () => this.#members,
             getDataMembers: () =>
                 this.#getActiveMembers(this.#dataDomainMembers),
             getType: () => this.type,
@@ -146,7 +174,7 @@ export default class ScaleResolution {
         });
 
         this.#scaleManager = new ScaleInstanceManager({
-            getParamRuntime: () => this.#firstMemberView.paramRuntime,
+            getParamRuntime: () => this.#resolutionView.paramRuntime,
             onRangeChange: () => this.#notifyListeners("range"),
             onDomainChange: () => this.#notifyListeners("domain"),
             getGenomeStore: () => this.#viewContext.genomeStore,
@@ -157,8 +185,7 @@ export default class ScaleResolution {
             getAnimator: () => this.#viewContext.animator,
             getInitialDomainSnapshot: () =>
                 this.#domainAggregator.initialDomainSnapshot,
-            getResetDomain: () =>
-                this.#domainAggregator.getConfiguredOrDefaultDomain(),
+            getResetDomain: () => this.#getConfiguredOrDefaultDomain(),
             fromComplexInterval: this.fromComplexInterval.bind(this),
             getGenomeExtent: () => this.#getLocusExtent(),
         });
@@ -175,6 +202,10 @@ export default class ScaleResolution {
         return first.view;
     }
 
+    get #resolutionView() {
+        return this.#hostView ?? this.#firstMemberView;
+    }
+
     /**
      * @param {Set<ScaleResolutionMember>} [members]
      */
@@ -199,7 +230,7 @@ export default class ScaleResolution {
     }
 
     get #viewContext() {
-        return this.#firstMemberView.context;
+        return this.#resolutionView.context;
     }
 
     get zoomExtent() {
@@ -263,7 +294,7 @@ export default class ScaleResolution {
             type === "domain" &&
             this.#selectionReverseSyncSuppressionDepth === 0
         ) {
-            this.#syncLinkedSelectionFromDomain();
+            this.syncLinkedSelectionFromDomain();
         }
 
         for (const listener of this.#listeners[type].values()) {
@@ -286,27 +317,15 @@ export default class ScaleResolution {
         }
     }
 
-    #syncLinkedSelectionFromDomain() {
+    syncLinkedSelectionFromDomain() {
         const linkInfo =
-            this.#domainAggregator.getSelectionConfiguredDomainInfo();
-        if (!linkInfo) {
-            return;
-        }
-
-        const shouldReverseSync =
-            linkInfo.sync === "twoWay" ||
-            (linkInfo.sync === "auto" && this.isZoomable());
-        if (!shouldReverseSync) {
+            this.#domainAggregator.getSelectionConfiguredDomainBindingInfo();
+        if (!linkInfo || !this.isZoomable()) {
             return;
         }
 
-        const runtime = requireParamRuntime(
-            this.#firstMemberView.paramRuntime,
-            linkInfo.param
-        );
-
         const selection = requireIntervalSelection(
-            runtime.getValue(linkInfo.param),
+            linkInfo.runtime.getValue(linkInfo.param),
             linkInfo.param
         );
 
@@ -332,7 +351,7 @@ export default class ScaleResolution {
             return;
         }
 
-        runtime.setValue(linkInfo.param, {
+        linkInfo.runtime.setValue(linkInfo.param, {
             ...selection,
             type: "interval",
             intervals: {
@@ -350,6 +369,71 @@ export default class ScaleResolution {
         return normalizeIntervalForSelection(domain, this.zoomExtent);
     }
 
+    #getLinkedSelectionInfo() {
+        return this.#domainAggregator.getSelectionConfiguredDomainBindingInfo();
+    }
+
+    #shouldIncludeSelectionInitial() {
+        return !this.#ignoreSelectionInitial;
+    }
+
+    /**
+     * @param {boolean} [extractDataDomain]
+     * @param {import("../spec/scale.js").Scale["assembly"]} [locusAssembly]
+     * @returns {any[]}
+     */
+    #getConfiguredOrDefaultDomain(extractDataDomain = false, locusAssembly) {
+        return this.#domainAggregator.getConfiguredOrDefaultDomain(
+            extractDataDomain,
+            locusAssembly,
+            {
+                includeSelectionInitial: this.#shouldIncludeSelectionInitial(),
+            }
+        );
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    #hasConfiguredDomain() {
+        for (const member of this.#members) {
+            if (
+                member.contributesToDomain &&
+                member.channelDef.scale?.domain !== undefined
+            ) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * @param {import("./domainPlanner.js").SelectionDomainLinkInfo} linkInfo
+     * @returns {[number, number] | null}
+     */
+    #getCurrentLinkedSelectionInterval(linkInfo) {
+        const selection = requireIntervalSelection(
+            linkInfo.runtime.getValue(linkInfo.param),
+            linkInfo.param
+        );
+        const interval = selection.intervals[linkInfo.encoding];
+        return interval && interval.length === 2
+            ? /** @type {[number, number]} */ (interval)
+            : null;
+    }
+
+    /**
+     * @param {[number, number] | null} previousInterval
+     * @param {[number, number] | null} nextInterval
+     */
+    #updateSelectionInitialBypass(previousInterval, nextInterval) {
+        if (nextInterval) {
+            this.#ignoreSelectionInitial = false;
+        } else if (previousInterval) {
+            this.#ignoreSelectionInitial = true;
+        }
+    }
+
     /**
      * Add a view to this resolution.
      * N.B. This is expected to be called in depth-first order
@@ -413,12 +497,16 @@ export default class ScaleResolution {
             if (!this.type) {
                 this.type = type;
             } else if (type !== this.type && !isSecondaryChannel(channel)) {
+                // TODO: Revisit shared discrete positional scales when
+                // implementing Vega-Lite-like band-vs-point inference.
+                // Nominal/ordinal members should be able to share a scale even
+                // if one member wants "point" and another wants "band"; the
+                // merged result should resolve to "band". Explicit
+                // user-specified incompatible scale types should still error.
                 // TODO: Include a reference to the layer
                 throw new Error(
                     `Can not use shared scale for different data types: ${this.type} vs. ${type}. Use "resolve: independent" for channel ${this.channel}`
                 );
-                // Actually, point scale could be changed into band scale
-                // TODO: Use the same merging logic as in: https://github.com/vega/vega-lite/blob/master/src/scale.ts
             }
         }
 
@@ -426,23 +514,67 @@ export default class ScaleResolution {
         if (member.contributesToDomain) {
             this.#dataDomainMembers.add(member);
         }
-        this.#domainAggregator.invalidateConfiguredDomain();
-        this.#refreshSelectionDomainParamSubscriptions();
         return member;
     }
 
+    #syncMembers() {
+        this.#membersDirty = false;
+        this.#invalidateOrderedMembers();
+        this.#invalidateConfiguredDomain();
+        this.#refreshSelectionDomainParamSubscriptions();
+        this.#refreshConfiguredDomainExprSubscriptions();
+    }
+
+    #markMembersDirty() {
+        if (this.#memberRegistrationBatchDepth > 0) {
+            this.#membersDirty = true;
+        } else {
+            this.#syncMembers();
+        }
+    }
+
+    /**
+     * Executes a group of member registrations without refreshing derived
+     * membership state until the callback completes.
+     *
+     * @template T
+     * @param {Iterable<ScaleResolution>} resolutions
+     * @param {() => T} callback
+     * @returns {T}
+     */
+    static registerInBatch(resolutions, callback) {
+        const batchedResolutions = Array.from(resolutions);
+        for (const resolution of batchedResolutions) {
+            resolution.#memberRegistrationBatchDepth++;
+        }
+
+        try {
+            return callback();
+        } finally {
+            for (const resolution of batchedResolutions) {
+                resolution.#memberRegistrationBatchDepth--;
+                if (
+                    resolution.#memberRegistrationBatchDepth === 0 &&
+                    resolution.#membersDirty
+                ) {
+                    resolution.#syncMembers();
+                }
+            }
+        }
+    }
+
     /**
      * @param {ScaleResolutionMember} member
      * @returns {() => boolean}
      */
     registerMember(member) {
         const registeredMember = this.#addMember(member);
+        this.#markMembersDirty();
         return () => {
             const removed = this.#members.delete(registeredMember);
             if (removed) {
                 this.#dataDomainMembers.delete(registeredMember);
-                this.#domainAggregator.invalidateConfiguredDomain();
-                this.#refreshSelectionDomainParamSubscriptions();
+                this.#markMembersDirty();
             }
             return removed && this.#members.size === 0;
         };
@@ -450,6 +582,7 @@ export default class ScaleResolution {
 
     dispose() {
         this.#clearSelectionDomainParamSubscriptions();
+        this.#clearConfiguredDomainExprSubscriptions();
         this.#listeners.domain.clear();
         this.#listeners.range.clear();
         this.#scaleManager.dispose();
@@ -460,6 +593,14 @@ export default class ScaleResolution {
             unsubscribe();
         }
         this.#selectionDomainParamUnsubscribers = [];
+        this.#lastLinkedSelectionInterval = undefined;
+    }
+
+    #clearConfiguredDomainExprSubscriptions() {
+        for (const unsubscribe of this.#configuredDomainExprUnsubscribers) {
+            unsubscribe();
+        }
+        this.#configuredDomainExprUnsubscribers = [];
     }
 
     #refreshSelectionDomainParamSubscriptions() {
@@ -469,25 +610,57 @@ export default class ScaleResolution {
             return;
         }
 
-        const linkInfo =
-            this.#domainAggregator.getSelectionConfiguredDomainInfo();
+        const linkInfo = this.#getLinkedSelectionInfo();
         if (!linkInfo) {
             return;
         }
 
-        const runtime = requireParamRuntime(
-            this.#firstMemberView.paramRuntime,
-            linkInfo.param
-        );
+        this.#lastLinkedSelectionInterval =
+            this.#getCurrentLinkedSelectionInterval(linkInfo);
 
         this.#selectionDomainParamUnsubscribers.push(
-            runtime.subscribe(linkInfo.param, () => {
-                this.#domainAggregator.invalidateConfiguredDomain();
+            linkInfo.runtime.subscribe(linkInfo.param, () => {
+                const previousInterval = this.#lastLinkedSelectionInterval;
+                const currentInterval =
+                    this.#getCurrentLinkedSelectionInterval(linkInfo);
+                this.#updateSelectionInitialBypass(
+                    previousInterval,
+                    currentInterval
+                );
+                this.#lastLinkedSelectionInterval = currentInterval;
+                this.#invalidateConfiguredDomain();
                 this.reconfigureDomain();
             })
         );
     }
 
+    #refreshConfiguredDomainExprSubscriptions() {
+        this.#clearConfiguredDomainExprSubscriptions();
+
+        if (this.#members.size === 0) {
+            return;
+        }
+
+        const listener = () => {
+            this.#invalidateConfiguredDomain();
+            this.reconfigureDomain();
+        };
+
+        for (const member of this.#members) {
+            if (!member.contributesToDomain) {
+                continue;
+            }
+            const domain = member.channelDef.scale?.domain;
+            if (!isExprRef(domain)) {
+                continue;
+            }
+
+            const expr = member.view.paramRuntime.createExpression(domain.expr);
+            const unsubscribe = expr.subscribe(listener);
+            this.#configuredDomainExprUnsubscribers.push(unsubscribe);
+        }
+    }
+
     #hasRenderedMember() {
         for (const member of this.#members) {
             if (member.view.hasRendered()) {
@@ -539,11 +712,11 @@ export default class ScaleResolution {
     /**
      * Returns true if the domain has been defined explicitly, i.e. not extracted from the data.
      */
-    #isExplicitDomain() {
-        return this.#domainAggregator.hasConfiguredDomain();
+    isDomainDefinedExplicitly() {
+        return this.#hasConfiguredDomain();
     }
 
-    #isDomainInitialized() {
+    isDomainInitialized() {
         const s = this.#scaleManager.scale;
         if (!s) {
             return false;
@@ -569,14 +742,68 @@ export default class ScaleResolution {
      * @returns {import("../spec/scale.js").Scale}
      */
     #getMergedScaleProps() {
-        return resolveScalePropsBase({
-            channel: this.channel,
-            dataType: this.type,
-            members: this.#members,
-            isExplicitDomain: this.#isExplicitDomain(),
+        return getCachedOrCall(this, "mergedScaleProps", () => {
+            const props = resolveScalePropsBase({
+                channel: this.channel,
+                dataType: this.type,
+                orderedMembers: this.#getOrderedMembers(),
+                isExplicitDomain: this.isDomainDefinedExplicitly(),
+                configScopes: this.#resolutionView.getConfigScopes(),
+            });
+            this.#validateLinkedSelectionConfiguration(props);
+            return props;
         });
     }
 
+    #invalidateMergedScaleProps() {
+        invalidate(this, "mergedScaleProps");
+    }
+
+    #invalidateOrderedMembers() {
+        this.#orderedMembers = undefined;
+    }
+
+    /**
+     * Returns the participating members in a stable order.
+     *
+     * The membership set changes rarely, so cache the sorted order separately
+     * from merged scale props. That keeps parameter-driven domain updates from
+     * re-running the same path-based sort work.
+     *
+     * @returns {ScaleResolutionMember[]}
+     */
+    #getOrderedMembers() {
+        if (!this.#orderedMembers) {
+            this.#orderedMembers = orderResolutionMembers(this.#members);
+        }
+        return this.#orderedMembers;
+    }
+
+    #invalidateConfiguredDomain() {
+        this.#domainAggregator.invalidateConfiguredDomain();
+        this.#invalidateMergedScaleProps();
+    }
+
+    /**
+     * @param {import("../spec/scale.js").Scale} props
+     */
+    #validateLinkedSelectionConfiguration(props) {
+        const linkInfo = this.#getLinkedSelectionInfo();
+        if (!linkInfo || props === null || props.type === "null") {
+            return;
+        }
+
+        const isZoomable =
+            isContinuous(props.type) && !isDiscrete(props.type) && !!props.zoom;
+
+        if (linkInfo.hasInitial && !isZoomable) {
+            throw new Error(
+                `Selection domain reference "${linkInfo.param}.${linkInfo.encoding}" cannot use "initial" with a non-zoomable ${this.channel} scale. ` +
+                    `Enable zoom on the linked scale or remove "initial".`
+            );
+        }
+    }
+
     /**
      * Returns locus assembly requirements without initializing the scale.
      *
@@ -604,6 +831,23 @@ export default class ScaleResolution {
         };
     }
 
+    /**
+     * Returns the resolved scale type without instantiating the scale.
+     *
+     * Useful during view construction, before assembly preflight has loaded
+     * URL-backed locus genomes.
+     *
+     * @returns {import("../spec/scale.js").Scale["type"] | undefined}
+     */
+    getResolvedScaleType() {
+        const props = this.#getMergedScaleProps();
+        if (props === null || props.type === "null") {
+            return undefined;
+        }
+
+        return props.type;
+    }
+
     /**
      * Returns the merged scale properties supplemented with inferred properties
      * and domain.
@@ -619,13 +863,23 @@ export default class ScaleResolution {
             return { type: "null" };
         }
 
-        const domain = this.#domainAggregator.getConfiguredOrDefaultDomain(
-            extractDataDomain,
-            props.type === LOCUS ? props.assembly : undefined
-        );
+        const resolvedProps = { ...props };
+
+        this.#resolvingScaleProps += 1;
+        let domain;
+        try {
+            domain = this.#getConfiguredOrDefaultDomain(
+                extractDataDomain,
+                resolvedProps.type === LOCUS
+                    ? resolvedProps.assembly
+                    : undefined
+            );
+        } finally {
+            this.#resolvingScaleProps -= 1;
+        }
 
-        if (isDiscrete(props.type)) {
-            const isExplicit = this.#isExplicitDomain();
+        if (isDiscrete(resolvedProps.type)) {
+            const isExplicit = this.isDomainDefinedExplicitly();
             const indexer = this.#getCategoricalIndexer(isExplicit);
             if (domain != null) {
                 if (
@@ -641,7 +895,7 @@ export default class ScaleResolution {
                 const indexedDomain = indexer
                     .domain()
                     .filter((value) => active.has(value));
-                props.domain =
+                resolvedProps.domain =
                     indexedDomain.length > 0
                         ? /** @type {import("../spec/scale.js").ScalarDomain} */ (
                               indexedDomain
@@ -649,7 +903,7 @@ export default class ScaleResolution {
                         : new NominalDomain();
             } else {
                 const indexedDomain = indexer.domain();
-                props.domain =
+                resolvedProps.domain =
                     indexedDomain.length > 0
                         ? /** @type {import("../spec/scale.js").ScalarDomain} */ (
                               indexedDomain
@@ -657,18 +911,21 @@ export default class ScaleResolution {
                         : new NominalDomain();
             }
             // Scale props are spec-shaped; keep the indexer off the public type.
-            /** @type {any} */ (props).domainIndexer = indexer;
+            /** @type {any} */ (resolvedProps).domainIndexer = indexer;
         } else if (domain && domain.length > 0) {
-            props.domain = domain;
+            resolvedProps.domain = domain;
         }
 
-        if (!props.domain && props.domainMid !== undefined) {
+        if (!resolvedProps.domain && resolvedProps.domainMid !== undefined) {
             // Initialize with a bogus domain so that scale.js can inject the domainMid.
             // The number of domain elements must be know before the glsl scale is generated.
-            props.domain = [props.domainMin ?? 0, props.domainMax ?? 1];
+            resolvedProps.domain = [
+                resolvedProps.domainMin ?? 0,
+                resolvedProps.domainMax ?? 1,
+            ];
         }
 
-        return props;
+        return resolvedProps;
     }
 
     /**
@@ -693,7 +950,7 @@ export default class ScaleResolution {
      */
     reconfigure() {
         this.#withSelectionReverseSyncSuppressed(() => {
-            this.#domainAggregator.invalidateConfiguredDomain();
+            this.#invalidateConfiguredDomain();
             const state = this.#computeScaleState(true);
             if (!state) {
                 return;
@@ -735,6 +992,7 @@ export default class ScaleResolution {
                 });
             }
             this.#finalizeReconfigure(state);
+            this.syncLinkedSelectionFromDomain();
         });
     }
 
@@ -762,7 +1020,7 @@ export default class ScaleResolution {
             scale,
             props: this.#getScaleProps(extractDataDomain),
             previousDomain: scale.domain(),
-            domainWasInitialized: this.#isDomainInitialized(),
+            domainWasInitialized: this.isDomainInitialized(),
             hasSelectionConfiguredDomain:
                 this.#domainAggregator.hasSelectionConfiguredDomain(),
         };
@@ -808,10 +1066,15 @@ export default class ScaleResolution {
             hasSelectionConfiguredDomain,
         } = inputs;
 
+        const initialDomainSnapshot = hasSelectionConfiguredDomain
+            ? this.#domainAggregator.getDefaultDomain(true)
+            : undefined;
+
         if (
             this.#domainAggregator.captureInitialDomain(
                 scale,
-                domainWasInitialized
+                domainWasInitialized,
+                initialDomainSnapshot
             )
         ) {
             // Domain changes were suppressed during reconfigure; notify explicitly.
@@ -819,6 +1082,11 @@ export default class ScaleResolution {
             return;
         }
 
+        if (scale.props.domainTransition === false) {
+            this.#notifyListeners("domain");
+            return;
+        }
+
         const newDomain = scale.domain();
         const action = this.#interactionController.getDomainChangeAction(
             previousDomain,
@@ -878,6 +1146,11 @@ export default class ScaleResolution {
      * @returns {ScaleWithProps}
      */
     getScale() {
+        if (this.#resolvingScaleProps > 0) {
+            throw new Error(
+                `Scale resolution for channel "${this.channel}" cannot read its own scale while its domain is being resolved.`
+            );
+        }
         return this.#scaleManager.scale ?? this.initializeScale();
     }
 
@@ -898,6 +1171,13 @@ export default class ScaleResolution {
     }
 
     getDomain() {
+        if (this.#resolvingScaleProps > 0) {
+            throw new Error(
+                `Scale resolution for channel "${this.channel}" cannot read its own domain while its domain is being resolved.`
+            );
+        }
+        // The underlying scale getter returns a fresh array. Treat this as a
+        // read-only snapshot rather than a mutable backing store.
         return this.getScale().domain();
     }
 
@@ -915,10 +1195,39 @@ export default class ScaleResolution {
      */
     getComplexDomain() {
         return /** @type {NumericDomain | ComplexDomain} */ (
-            toComplexInterval(this.#getGenomeSource(), this.getDomain())
+            toComplexInterval(
+                this.#getGenomeSource(),
+                toExternalIndexLikeInterval(this.type, this.getDomain())
+            )
         );
     }
 
+    /**
+     * Returns metadata about a selection-linked domain, if present.
+     */
+    getLinkedSelectionDomainInfo() {
+        const linkInfo = this.#getLinkedSelectionInfo();
+        if (!linkInfo) {
+            return;
+        }
+
+        const root = this.#resolutionView.getLayoutAncestors().at(-1);
+        const persist = root
+            ? findIntervalSelectionBindingOwners(
+                  root,
+                  linkInfo.runtime,
+                  linkInfo.param,
+                  linkInfo.encoding
+              ).some((owner) => owner.param.persist !== false)
+            : false;
+
+        return {
+            param: linkInfo.param,
+            encoding: linkInfo.encoding,
+            persist,
+        };
+    }
+
     /**
      * Return true if the scale is zoomable and the current domain differs from the initial domain.
      *
@@ -932,8 +1241,14 @@ export default class ScaleResolution {
      * Returns true if zooming is supported and allowed in view spec.
      */
     isZoomable() {
-        // Check explicit configuration
-        return this.#interactionController.isZoomable();
+        const props = this.#getMergedScaleProps();
+        if (props === null || props.type === "null") {
+            return false;
+        }
+
+        return (
+            isContinuous(props.type) && !isDiscrete(props.type) && !!props.zoom
+        );
     }
 
     /**