@genome-spy/core 0.73.0 → 0.75.0

package/dist/src/scales/domainPlanner.js

@@ -1,72 +1,124 @@
 import { span } from "vega-util";
 import { isContinuous } from "vega-scale";
 
-import { LOCUS } from "./scaleResolutionConstants.js";
-import { requireIntervalSelection } from "./selectionDomainUtils.js";
+import { INDEX, LOCUS } from "./scaleResolutionConstants.js";
+import {
+    toInternalIndexLikeDataDomain,
+    toInternalIndexLikeInterval,
+} from "./indexLikeDomainUtils.js";
+import {
+    hasIntervalSelectionBindingInScope,
+    resolveIntervalSelectionBinding,
+} from "./selectionDomainUtils.js";
 import createDomain from "../utils/domainArray.js";
+import { isExprRef } from "../paramRuntime/paramUtils.js";
 import { getAccessorDomainKey, isScaleAccessor } from "../encoder/accessor.js";
-import { getPrimaryChannel } from "../encoder/encoder.js";
+import { getEncoderAccessors, getPrimaryChannel } from "../encoder/encoder.js";
+import {
+    hasExplicitLocusUpperBound,
+    isChromosomalLocusInterval,
+} from "../genome/genome.js";
+
+/*
+ * Domain planning decides what domain a shared scale should use before the
+ * scale instance is configured.
+ *
+ * "Planning" means collecting the participating members, separating literal
+ * configured domains from selection-driven domains, validating that the shared
+ * scale is not asked to mix incompatible sources, and producing the final union
+ * that will be applied to the scale.
+ */
 
 /**
  * @typedef {import("../utils/domainArray.js").DomainArray} DomainArray
  * @typedef {import("../spec/scale.js").ComplexDomain} ComplexDomain
  * @typedef {import("../spec/scale.js").ScalarDomain} ScalarDomain
  * @typedef {import("../spec/scale.js").SelectionDomainRef} SelectionDomainRef
+ * @typedef {import("../spec/parameter.js").ExprRef} ExprRef
  * @typedef {import("./scaleResolution.js").ScaleResolutionMember} ScaleResolutionMember
+ * @typedef {() => Set<ScaleResolutionMember>} ScaleMembersGetter
+ * @typedef {(interval: ScalarDomain | ComplexDomain) => number[]} FromComplexInterval
+ * @typedef {(assembly: import("../spec/scale.js").Scale["assembly"] | undefined) => number[]} GetLocusExtent
+ * @typedef {{
+ *   domains: DomainArray[],
+ *   selectionRef: SelectionDomainLinkInfo | undefined,
+ *   selectionRuntime: any,
+ *   selectionDescription: string | undefined,
+ *   hasLiteralDomain: boolean,
+ * }} ConfiguredDomainResolutionState
+ * @typedef {{
+ *   kind: "literal",
+ *   domain: DomainArray,
+ * } | {
+ *   kind: "selection",
+ *   domain: DomainArray | undefined,
+ *   description: string,
+ *   param: string,
+ *   encoding: "x" | "y",
+ *   hasInitial: boolean,
+ *   runtime: any,
+ * }} ConfiguredDomainMemberResolution
  * @typedef {{
  *   param: string,
  *   encoding: "x" | "y",
- *   sync: "auto" | "oneWay" | "twoWay",
+ *   hasInitial: boolean,
+ *   runtime: any,
  * }} SelectionDomainLinkInfo
  */
 
 export default class DomainPlanner {
-    /** @type {() => Set<ScaleResolutionMember>} */
-    #getMembers;
+    /** @type {ScaleMembersGetter} */
+    #getActiveMembers;
+
+    /** @type {ScaleMembersGetter} */
+    #getAllMembers;
 
-    /** @type {() => Set<ScaleResolutionMember>} */
+    /** @type {ScaleMembersGetter} */
     #getDataMembers;
 
     /** @type {() => import("../spec/channel.js").Type} */
     #getType;
 
-    /** @type {(assembly: import("../spec/scale.js").Scale["assembly"] | undefined) => number[]} */
+    /** @type {GetLocusExtent} */
     #getLocusExtent;
 
-    /** @type {(interval: ScalarDomain | ComplexDomain) => number[]} */
+    /** @type {FromComplexInterval} */
     #fromComplexInterval;
 
     /** @type {any[]} */
     #initialDomain;
 
-    /** @type {DomainArray | undefined} */
-    #configuredDomain;
-
     /** @type {SelectionDomainLinkInfo | undefined} */
     #selectionDomainLinkInfo = undefined;
 
     #configuredDomainDirty = true;
 
+    /** @type {Map<boolean, DomainArray | undefined>} */
+    #configuredDomainsByInitialMode = new Map();
+
     /** @type {WeakMap<ScaleResolutionMember, import("../types/encoder.js").ScaleAccessor[]>} */
     #accessorsByMember = new WeakMap();
 
     /**
      * @param {object} options
-     * @param {() => Set<ScaleResolutionMember>} options.getMembers
-     * @param {() => Set<ScaleResolutionMember>} [options.getDataMembers]
+     * @param {ScaleMembersGetter} options.getActiveMembers Active shared-scale members used for configured domain planning.
+     * @param {ScaleMembersGetter} [options.getAllMembers] All members, including inactive ones, used for conflict validation.
+     * @param {ScaleMembersGetter} [options.getDataMembers] Members used for data-domain extraction; defaults to `getActiveMembers`.
      * @param {() => import("../spec/channel.js").Type} options.getType
-     * @param {(assembly: import("../spec/scale.js").Scale["assembly"] | undefined) => number[]} options.getLocusExtent
-     * @param {(interval: ScalarDomain | ComplexDomain) => number[]} options.fromComplexInterval
+     * @param {GetLocusExtent} options.getLocusExtent
+     * @param {FromComplexInterval} options.fromComplexInterval
      */
     constructor({
-        getMembers,
+        getActiveMembers,
+        getAllMembers,
         getDataMembers,
         getType,
         getLocusExtent,
         fromComplexInterval,
     }) {
-        this.#getMembers = getMembers;
-        this.#getDataMembers = getDataMembers ?? getMembers;
+        this.#getActiveMembers = getActiveMembers;
+        this.#getAllMembers = getAllMembers ?? getActiveMembers;
+        this.#getDataMembers = getDataMembers ?? getActiveMembers;
         this.#getType = getType;
         this.#getLocusExtent = getLocusExtent;
         this.#fromComplexInterval = fromComplexInterval;
@@ -79,25 +131,46 @@ export default class DomainPlanner {
         return this.#initialDomain;
     }
 
-    hasConfiguredDomain() {
-        return !!this.getConfiguredDomain();
+    /**
+     * @param {{ includeSelectionInitial?: boolean }} [options]
+     */
+    hasConfiguredDomain(options = {}) {
+        return !!this.getConfiguredDomain(options);
     }
 
     hasSelectionConfiguredDomain() {
-        this.getConfiguredDomain();
+        this.getSelectionConfiguredDomainBindingInfo();
         return !!this.#selectionDomainLinkInfo;
     }
 
     /**
      * @returns {SelectionDomainLinkInfo | undefined}
      */
-    getSelectionConfiguredDomainInfo() {
+    getSelectionConfiguredDomainBindingInfo() {
+        if (this.#selectionDomainLinkInfo || !this.#configuredDomainDirty) {
+            return this.#selectionDomainLinkInfo;
+        }
+
         this.getConfiguredDomain();
         return this.#selectionDomainLinkInfo;
     }
 
+    getSelectionConfiguredDomainInfo() {
+        const bindingInfo = this.getSelectionConfiguredDomainBindingInfo();
+        if (!bindingInfo) {
+            return;
+        }
+
+        return {
+            param: bindingInfo.param,
+            encoding: bindingInfo.encoding,
+        };
+    }
+
     invalidateConfiguredDomain() {
         this.#configuredDomainDirty = true;
+        this.#selectionDomainLinkInfo = undefined;
+        this.#configuredDomainsByInitialMode.clear();
     }
 
     /**
@@ -108,10 +181,13 @@ export default class DomainPlanner {
      * @returns {any[]}
      */
     getDefaultDomain(extractDataDomain = false, locusAssembly) {
+        const type = this.#getType();
         return resolveDefaultDomain(
-            this.#getType(),
+            type,
             this.#getLocusExtent,
-            extractDataDomain ? this.getDataDomain() : undefined,
+            extractDataDomain && type !== LOCUS
+                ? this.getDataDomain()
+                : undefined,
             locusAssembly
         );
     }
@@ -121,12 +197,17 @@ export default class DomainPlanner {
      *
      * @param {boolean} [extractDataDomain]
      * @param {import("../spec/scale.js").Scale["assembly"]} [locusAssembly]
+     * @param {{ includeSelectionInitial?: boolean }} [options]
      * @returns {any[]}
      */
-    getConfiguredOrDefaultDomain(extractDataDomain = false, locusAssembly) {
+    getConfiguredOrDefaultDomain(
+        extractDataDomain = false,
+        locusAssembly,
+        options = {}
+    ) {
         // TODO: intersect the domain with zoom extent (if it's defined)
         return (
-            this.getConfiguredDomain() ??
+            this.getConfiguredDomain(options) ??
             this.getDefaultDomain(extractDataDomain, locusAssembly)
         );
     }
@@ -134,19 +215,35 @@ export default class DomainPlanner {
     /**
      * Unions the configured domains of all participating views.
      *
+     * @param {{ includeSelectionInitial?: boolean }} [options]
      * @return {DomainArray}
      */
-    getConfiguredDomain() {
-        if (!this.#configuredDomainDirty) {
-            return this.#configuredDomain;
+    getConfiguredDomain(options = {}) {
+        const includeSelectionInitial = options.includeSelectionInitial ?? true;
+
+        if (
+            !this.#configuredDomainDirty &&
+            this.#configuredDomainsByInitialMode.has(includeSelectionInitial)
+        ) {
+            return this.#configuredDomainsByInitialMode.get(
+                includeSelectionInitial
+            );
         }
 
         const configuredDomain = resolveConfiguredDomain(
-            this.#getMembers(),
-            this.#fromComplexInterval
+            this.#getActiveMembers(),
+            this.#fromComplexInterval,
+            includeSelectionInitial
+        );
+        validateSharedSelectionDomain(
+            this.#getAllMembers(),
+            configuredDomain.selectionRef
         );
-        this.#configuredDomain = configuredDomain.domain;
         this.#selectionDomainLinkInfo = configuredDomain.selectionRef;
+        this.#configuredDomainsByInitialMode.set(
+            includeSelectionInitial,
+            configuredDomain.domain
+        );
         this.#configuredDomainDirty = false;
         return configuredDomain.domain;
     }
@@ -167,18 +264,19 @@ export default class DomainPlanner {
     /**
      * @param {import("../types/encoder.js").VegaScale} scale
      * @param {boolean} domainWasInitialized
+     * @param {any[]} [snapshotDomain]
      * @returns {boolean} true if listeners should be notified immediately
      */
-    captureInitialDomain(scale, domainWasInitialized) {
+    captureInitialDomain(scale, domainWasInitialized, snapshotDomain) {
         if (!this.#initialDomain && isContinuous(scale.type)) {
-            const domain = scale.domain();
+            const domain = snapshotDomain ?? scale.domain();
             if (span(domain) > 0) {
                 this.#initialDomain = domain;
             }
         }
 
         if (!domainWasInitialized) {
-            this.#initialDomain = scale.domain();
+            this.#initialDomain = snapshotDomain ?? scale.domain();
             return true;
         }
 
@@ -205,7 +303,7 @@ export default class DomainPlanner {
             return [];
         }
 
-        const accessors = encoder.accessors ?? [];
+        const accessors = getEncoderAccessors(encoder);
         if (accessors.length === 0) {
             return [];
         }
@@ -222,107 +320,168 @@ export default class DomainPlanner {
 /**
  * @param {Set<ScaleResolutionMember>} members
  * @param {(interval: ScalarDomain | ComplexDomain) => number[]} fromComplexInterval
+ * @param {boolean} includeSelectionInitial
  * @returns {{
  *   domain: DomainArray | undefined,
  *   selectionRef: SelectionDomainLinkInfo | undefined,
  * }}
  */
-function resolveConfiguredDomain(members, fromComplexInterval) {
+function resolveConfiguredDomain(
+    members,
+    fromComplexInterval,
+    includeSelectionInitial
+) {
     const domainMembers = Array.from(members)
         .filter((member) => member.contributesToDomain)
         .filter((member) => member.channelDef.scale?.domain);
 
-    /** @type {DomainArray[]} */
-    const domains = [];
-
-    /** @type {string | undefined} */
-    let selectionRefKey = undefined;
-    /** @type {string | undefined} */
-    let selectionRefDescription = undefined;
-    /** @type {"auto" | "oneWay" | "twoWay" | undefined} */
-    let selectionRefSync = undefined;
-    /** @type {SelectionDomainLinkInfo | undefined} */
-    let selectionRef = undefined;
-    let hasLiteralDomain = false;
+    /** @type {ConfiguredDomainResolutionState} */
+    const state = {
+        domains: [],
+        selectionRef: undefined,
+        selectionRuntime: undefined,
+        selectionDescription: undefined,
+        hasLiteralDomain: false,
+    };
 
     for (const member of domainMembers) {
-        const domainDef = member.channelDef.scale.domain;
-        if (isSelectionDomainRef(domainDef)) {
-            if (hasLiteralDomain) {
-                throw new Error(
-                    "Cannot mix selection-driven and literal configured domains on a shared scale."
-                );
-            }
+        const resolved = resolveConfiguredDomainMember(
+            member,
+            fromComplexInterval,
+            includeSelectionInitial
+        );
+
+        if (resolved.kind === "selection") {
+            mergeSelectionConfiguredDomain(state, resolved);
+            continue;
+        }
 
-            const resolved = resolveSelectionDomain(
+        mergeLiteralConfiguredDomain(state, resolved);
+    }
+
+    return finishConfiguredDomainResolution(state);
+}
+
+/**
+ * @param {ScaleResolutionMember} member
+ * @param {(interval: ScalarDomain | ComplexDomain) => number[]} fromComplexInterval
+ * @param {boolean} includeSelectionInitial
+ * @returns {ConfiguredDomainMemberResolution}
+ */
+function resolveConfiguredDomainMember(
+    member,
+    fromComplexInterval,
+    includeSelectionInitial
+) {
+    const domainDef = member.channelDef.scale.domain;
+    if (isSelectionDomainRef(domainDef)) {
+        return {
+            kind: "selection",
+            ...resolveSelectionDomain(
                 member,
                 domainDef,
+                fromComplexInterval,
+                includeSelectionInitial
+            ),
+        };
+    }
+
+    if (isExprRef(domainDef)) {
+        return {
+            kind: "literal",
+            domain: resolveConfiguredIntervalDomain(
+                member.channelDef.type,
+                member.view.paramRuntime.createExpression(domainDef.expr)(),
                 fromComplexInterval
-            );
+            ),
+        };
+    }
 
-            if (selectionRefKey && selectionRefKey !== resolved.key) {
-                throw new Error(
-                    "Conflicting selection domain references on a shared scale: " +
-                        selectionRefDescription +
-                        " vs " +
-                        resolved.description +
-                        "."
-                );
-            }
+    return {
+        kind: "literal",
+        domain: resolveConfiguredIntervalDomain(
+            member.channelDef.type,
+            domainDef,
+            fromComplexInterval
+        ),
+    };
+}
 
-            if (!selectionRefSync) {
-                selectionRefSync = resolved.sync;
-            } else if (selectionRefSync === "auto") {
-                selectionRefSync = resolved.sync;
-            } else if (resolved.sync !== "auto") {
-                if (selectionRefSync !== resolved.sync) {
-                    throw new Error(
-                        "Conflicting selection domain sync modes on a shared scale: " +
-                            selectionRefSync +
-                            " vs " +
-                            resolved.sync +
-                            "."
-                    );
-                }
-            }
+/**
+ * @param {ConfiguredDomainResolutionState} state
+ * @param {Extract<ConfiguredDomainMemberResolution, { kind: "selection" }>} resolved
+ */
+function mergeSelectionConfiguredDomain(state, resolved) {
+    if (state.hasLiteralDomain) {
+        throw new Error(
+            "Cannot mix selection-driven and literal configured domains on a shared scale."
+        );
+    }
 
-            selectionRefKey = resolved.key;
-            selectionRefDescription = resolved.description;
-            selectionRef = {
-                param: resolved.param,
-                encoding: resolved.encoding,
-                sync: selectionRefSync,
-            };
+    if (
+        state.selectionRef &&
+        (state.selectionRef.runtime !== resolved.runtime ||
+            state.selectionRef.param !== resolved.param ||
+            state.selectionRef.encoding !== resolved.encoding)
+    ) {
+        throw new Error(
+            "Conflicting selection domain references on a shared scale: " +
+                state.selectionDescription +
+                " vs " +
+                resolved.description +
+                "."
+        );
+    }
 
-            if (resolved.domain) {
-                domains.push(resolved.domain);
-            }
-            continue;
-        }
+    state.selectionRuntime = resolved.runtime;
+    state.selectionDescription = resolved.description;
+    state.selectionRef = {
+        param: resolved.param,
+        encoding: resolved.encoding,
+        hasInitial:
+            (state.selectionRef?.hasInitial ?? false) || resolved.hasInitial,
+        runtime: resolved.runtime,
+    };
 
-        if (selectionRefKey) {
-            throw new Error(
-                "Cannot mix literal configured domains with selection-driven domains on a shared scale."
-            );
-        }
+    if (resolved.domain) {
+        state.domains.push(resolved.domain);
+    }
+}
 
-        hasLiteralDomain = true;
-        domains.push(
-            createDomain(member.channelDef.type, fromComplexInterval(domainDef))
+/**
+ * @param {ConfiguredDomainResolutionState} state
+ * @param {Extract<ConfiguredDomainMemberResolution, { kind: "literal" }>} resolved
+ */
+function mergeLiteralConfiguredDomain(state, resolved) {
+    if (state.selectionRuntime) {
+        throw new Error(
+            "Cannot mix literal configured domains with selection-driven domains on a shared scale."
         );
     }
 
-    if (domains.length > 0) {
+    state.hasLiteralDomain = true;
+    state.domains.push(resolved.domain);
+}
+
+/**
+ * @param {ConfiguredDomainResolutionState} state
+ * @returns {{
+ *   domain: DomainArray | undefined,
+ *   selectionRef: SelectionDomainLinkInfo | undefined,
+ * }}
+ */
+function finishConfiguredDomainResolution(state) {
+    if (state.domains.length > 0) {
         return {
-            domain: domains.reduce((acc, curr) => acc.extendAll(curr)),
-            selectionRef,
+            domain: state.domains.reduce((acc, curr) => acc.extendAll(curr)),
+            selectionRef: state.selectionRef,
         };
     }
 
-    if (selectionRefKey) {
+    if (state.selectionRuntime) {
         // Selection refs are still the source of truth even when the
         // selection interval currently resolves to no domain.
-        return { domain: undefined, selectionRef };
+        return { domain: undefined, selectionRef: state.selectionRef };
     }
 
     return { domain: undefined, selectionRef: undefined };
@@ -332,24 +491,23 @@ function resolveConfiguredDomain(members, fromComplexInterval) {
  * @param {ScaleResolutionMember} member
  * @param {SelectionDomainRef} domainRef
  * @param {(interval: ScalarDomain | ComplexDomain) => number[]} fromComplexInterval
+ * @param {boolean} includeSelectionInitial
  * @returns {{
  *   domain: DomainArray | undefined,
- *   key: string,
  *   description: string,
  *   param: string,
  *   encoding: "x" | "y",
- *   sync: "auto" | "oneWay" | "twoWay",
+ *   hasInitial: boolean,
+ *   runtime: any,
  * }}
  */
-function resolveSelectionDomain(member, domainRef, fromComplexInterval) {
+function resolveSelectionDomain(
+    member,
+    domainRef,
+    fromComplexInterval,
+    includeSelectionInitial
+) {
     const paramName = domainRef.param;
-    const syncMode = domainRef.sync ?? "auto";
-
-    if (syncMode !== "auto" && syncMode !== "oneWay" && syncMode !== "twoWay") {
-        throw new Error(
-            `Invalid selection domain sync mode "${syncMode}" for parameter "${paramName}".`
-        );
-    }
 
     const resolvedChannel = resolveSelectionDomainChannel(
         member.channel,
@@ -357,40 +515,112 @@ function resolveSelectionDomain(member, domainRef, fromComplexInterval) {
         paramName
     );
 
-    const paramRuntime = member.view.paramRuntime;
-    const selection = requireIntervalSelection(
-        paramRuntime?.findValue(paramName),
-        paramName
+    const binding = resolveIntervalSelectionBinding(
+        member.view,
+        paramName,
+        resolvedChannel
     );
-
-    const interval = selection.intervals[resolvedChannel];
-    const key = [paramName, resolvedChannel].join("|");
+    const hasInitial = domainRef.initial !== undefined;
+    const interval = binding.selection.intervals[resolvedChannel];
     const description = paramName + "." + resolvedChannel;
-
     if (!interval || interval.length !== 2) {
+        const initialDomain = includeSelectionInitial
+            ? domainRef.initial
+                ? resolveConfiguredIntervalDomain(
+                      member.channelDef.type,
+                      domainRef.initial,
+                      fromComplexInterval
+                  )
+                : undefined
+            : undefined;
         return {
-            domain: undefined,
-            key,
+            domain: initialDomain,
             description,
             param: paramName,
             encoding: resolvedChannel,
-            sync: syncMode,
+            hasInitial,
+            runtime: binding.runtime,
         };
     }
 
     return {
+        // Selection intervals already use internal scale-domain coordinates.
         domain: createDomain(
             member.channelDef.type,
             fromComplexInterval(interval)
         ),
-        key,
         description,
         param: paramName,
         encoding: resolvedChannel,
-        sync: syncMode,
+        hasInitial,
+        runtime: binding.runtime,
     };
 }
 
+/**
+ * @param {import("../spec/channel.js").Type} type
+ * @param {ScalarDomain | ComplexDomain} interval
+ * @param {(interval: ScalarDomain | ComplexDomain) => number[]} fromComplexInterval
+ * @returns {DomainArray}
+ */
+function resolveConfiguredIntervalDomain(type, interval, fromComplexInterval) {
+    const numericDomain = fromComplexInterval(interval);
+    const internalDomain =
+        type === LOCUS &&
+        isChromosomalLocusInterval(interval) &&
+        !hasExplicitLocusUpperBound(interval)
+            ? numericDomain
+            : toInternalIndexLikeInterval(type, numericDomain);
+
+    return createDomain(type, internalDomain);
+}
+
+/**
+ * Fails fast when a selection-driven scale domain ends up sharing the same
+ * scale resolution as the interval selection that drives it. This typically
+ * happens when an overview/detail spec forgets to make the linked positional
+ * scale independent.
+ *
+ * @param {Set<ScaleResolutionMember>} members
+ * @param {SelectionDomainLinkInfo | undefined} selectionRef
+ */
+function validateSharedSelectionDomain(members, selectionRef) {
+    if (
+        !selectionRef ||
+        members.size < 2 ||
+        !Array.from(members).some((member) =>
+            hasIntervalSelectionBindingInScope(
+                member.view,
+                selectionRef.runtime,
+                selectionRef.param,
+                selectionRef.encoding
+            )
+        )
+    ) {
+        return;
+    }
+
+    const viewPaths = Array.from(
+        new Set(
+            Array.from(members)
+                .filter((member) => member.contributesToDomain)
+                .map(
+                    (member) =>
+                        member.view.getPathString?.() ??
+                        member.view.name ??
+                        "(unknown)"
+                )
+        )
+    );
+
+    throw new Error(
+        `Selection domain reference "${selectionRef.param}.${selectionRef.encoding}" cannot use a shared ${selectionRef.encoding} scale when the same interval selection is defined in that shared view group (${viewPaths.join(", ")}). ` +
+            `This creates a feedback loop between brushing and the scale domain. ` +
+            `Make the linked ${selectionRef.encoding} scale independent, for example with ` +
+            `"resolve": { "scale": { "${selectionRef.encoding}": "independent" } } on the common ancestor.`
+    );
+}
+
 /**
  * @param {import("../spec/channel.js").ChannelWithScale} channel
  * @param {SelectionDomainRef} domainRef
@@ -502,5 +732,8 @@ function resolveDefaultDomain(type, getLocusExtent, dataDomain, locusAssembly) {
     if (type == LOCUS) {
         return getLocusExtent(locusAssembly);
     }
+    if (type == INDEX) {
+        return toInternalIndexLikeDataDomain(type, dataDomain) ?? [];
+    }
     return dataDomain ?? [];
 }