@genome-spy/core 0.66.1 → 0.68.0

package/dist/src/scales/scaleResolution.js

@@ -13,7 +13,7 @@ import { configureDomain } from "../scale/scale.js";
 
 import ScaleInstanceManager from "./scaleInstanceManager.js";
 import { resolveScalePropsBase } from "./scalePropsResolver.js";
-import ScaleDomainAggregator from "./scaleDomainAggregator.js";
+import DomainPlanner from "./domainPlanner.js";
 import ScaleInteractionController from "./scaleInteractionController.js";
 import {
     INDEX,
@@ -23,9 +23,11 @@ import {
     QUANTITATIVE,
 } from "./scaleResolutionConstants.js";
 
+import { getAccessorDomainKey } from "../encoder/accessor.js";
 import { isSecondaryChannel } from "../encoder/encoder.js";
 import { NominalDomain } from "../utils/domainArray.js";
-import { asArray, shallowArrayEquals } from "../utils/arrayUtils.js";
+import { shallowArrayEquals } from "../utils/arrayUtils.js";
+import createIndexer from "../utils/indexer.js";
 
 // Register scaleLocus to Vega-Scale.
 // Loci are discrete but the scale's domain can be adjusted in a continuous manner.
@@ -42,7 +44,7 @@ export { INDEX, LOCUS, NOMINAL, ORDINAL, QUANTITATIVE };
  * @prop {import("../view/unitView.js").default} view TODO: Get rid of the view reference
  * @prop {T} channel
  * @prop {import("../spec/channel.js").ChannelDefWithScale} channelDef
- * @prop {(channel: ChannelWithScale, type: import("../spec/channel.js").Type) => DomainArray} dataDomainSource
+ * @prop {boolean} contributesToDomain
  */
 /**
  * Resolves a shared scale for a channel by merging scale properties and domains
@@ -51,6 +53,16 @@ export { INDEX, LOCUS, NOMINAL, ORDINAL, QUANTITATIVE };
  * notifications, while delegating domain aggregation, scale instance setup, and
  * interaction logic to focused helpers.
  *
+ * Documentation overview of current concerns this class (and its helpers) deal with:
+ * - Resolution membership and rules (shared/independent/forced/excluded, visibility, registration).
+ * - Scale property aggregation (merge props, channel overrides, unique scale names).
+ * - Domain computation and caching (configured/data unions, defaults, indexer stability, subscriptions).
+ * - Scale instance lifecycle (create, reconfigure props, apply domains, notify changes).
+ * - Interaction and zoom (zoom/pan/reset coordination, snapshots, zoom extents).
+ * - Rendering integration (range textures, axis sizing/positioning).
+ * - Locus-specific conversions (complex intervals, genome extent bindings).
+ * - Diagnostics and edge cases (ordinal unknown, nice/zero/padding, log warnings).
+ *
  * @implements {ScaleResolutionApi}
  */
 export default class ScaleResolution {
@@ -74,6 +86,9 @@ export default class ScaleResolution {
     /** @type {Set<ScaleResolutionMember>} The involved views */
     #members = new Set();
 
+    /** @type {Set<ScaleResolutionMember>} */
+    #dataDomainMembers = new Set();
+
     /**
      * @type {Record<ScaleResolutionEventType, Set<ScaleResolutionListener>>}
      */
@@ -85,12 +100,17 @@ export default class ScaleResolution {
     /** @type {ScaleInstanceManager} */
     #scaleManager;
 
-    /** @type {ScaleDomainAggregator} */
+    /** @type {DomainPlanner} */
     #domainAggregator;
 
     /** @type {ScaleInteractionController} */
     #interactionController;
 
+    /** @type {ReturnType<typeof createIndexer> | undefined} */
+    #categoricalIndexer;
+
+    #categoricalIndexerExplicit = false;
+
     /**
      * @param {Channel} channel
      */
@@ -102,8 +122,10 @@ export default class ScaleResolution {
         /** @type {string} An optional unique identifier for the scale */
         this.name = undefined;
 
-        this.#domainAggregator = new ScaleDomainAggregator({
-            getMembers: () => this.#members,
+        this.#domainAggregator = new DomainPlanner({
+            getMembers: () => this.#getActiveMembers(),
+            getDataMembers: () =>
+                this.#getActiveMembers(this.#dataDomainMembers),
             getType: () => this.type,
             getLocusExtent: () => this.#getLocusExtent(),
             fromComplexInterval: this.fromComplexInterval.bind(this),
@@ -139,6 +161,29 @@ export default class ScaleResolution {
         return first.view;
     }
 
+    /**
+     * @param {Set<ScaleResolutionMember>} [members]
+     */
+    #getActiveMembers(members = this.#members) {
+        /** @type {Set<ScaleResolutionMember>} */
+        const active = new Set();
+        for (const member of members) {
+            const view = member.view;
+            if (!view.isConfiguredVisible()) {
+                continue;
+            }
+            if (
+                !view.isDataInitialized() &&
+                !member.channelDef?.scale?.domain
+            ) {
+                // Explicit domains should be honored even before data init.
+                continue;
+            }
+            active.add(member);
+        }
+        return active;
+    }
+
     get #viewContext() {
         return this.#firstMemberView.context;
     }
@@ -262,6 +307,10 @@ export default class ScaleResolution {
         }
 
         this.#members.add(newMember);
+        if (newMember.contributesToDomain) {
+            this.#dataDomainMembers.add(newMember);
+        }
+        this.#domainAggregator.invalidateConfiguredDomain();
     }
 
     /**
@@ -272,10 +321,62 @@ export default class ScaleResolution {
         this.#addMember(member);
         return () => {
             const removed = this.#members.delete(member);
+            if (removed) {
+                this.#dataDomainMembers.delete(member);
+                this.#domainAggregator.invalidateConfiguredDomain();
+            }
             return removed && this.#members.size === 0;
         };
     }
 
+    #hasRenderedMember() {
+        for (const member of this.#members) {
+            if (member.view.hasRendered()) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * @param {import("../data/collector.js").default} collector
+     * @param {Iterable<import("../types/encoder.js").ScaleAccessor>} accessors
+     * @returns {() => void}
+     */
+    registerCollectorSubscriptions(collector, accessors) {
+        /** @type {Set<string>} */
+        const domainKeys = new Set();
+
+        for (const accessor of accessors) {
+            if (accessor.channelDef.domainInert) {
+                continue;
+            }
+            domainKeys.add(getAccessorDomainKey(accessor, this.type));
+        }
+
+        if (domainKeys.size === 0) {
+            return () => undefined;
+        }
+
+        const listener = () => {
+            this.reconfigureDomain();
+        };
+
+        /** @type {(() => void)[]} */
+        const unregisters = [];
+        for (const domainKey of domainKeys) {
+            unregisters.push(
+                collector.subscribeDomainChanges(domainKey, listener)
+            );
+        }
+
+        return () => {
+            for (const unregister of unregisters) {
+                unregister();
+            }
+        };
+    }
+
     /**
      * Returns true if the domain has been defined explicitly, i.e. not extracted from the data.
      */
@@ -337,10 +438,42 @@ export default class ScaleResolution {
                 extractDataDomain
             );
 
-        if (domain && domain.length > 0) {
+        if (isDiscrete(props.type)) {
+            const isExplicit = this.#isExplicitDomain();
+            const indexer = this.#getCategoricalIndexer(isExplicit);
+            if (domain != null) {
+                if (
+                    isExplicit &&
+                    indexer.domain().length > 0 &&
+                    !shallowArrayEquals(indexer.domain(), domain)
+                ) {
+                    this.#categoricalIndexer = undefined;
+                    return this.#getScaleProps(extractDataDomain);
+                }
+                indexer.addAll(domain);
+                const active = new Set(domain);
+                const indexedDomain = indexer
+                    .domain()
+                    .filter((value) => active.has(value));
+                props.domain =
+                    indexedDomain.length > 0
+                        ? /** @type {import("../spec/scale.js").ScalarDomain} */ (
+                              indexedDomain
+                          )
+                        : new NominalDomain();
+            } else {
+                const indexedDomain = indexer.domain();
+                props.domain =
+                    indexedDomain.length > 0
+                        ? /** @type {import("../spec/scale.js").ScalarDomain} */ (
+                              indexedDomain
+                          )
+                        : new NominalDomain();
+            }
+            // Scale props are spec-shaped; keep the indexer off the public type.
+            /** @type {any} */ (props).domainIndexer = indexer;
+        } else if (domain && domain.length > 0) {
             props.domain = domain;
-        } else if (isDiscrete(props.type)) {
-            props.domain = new NominalDomain();
         }
 
         if (!props.domain && props.domainMid !== undefined) {
@@ -352,6 +485,20 @@ export default class ScaleResolution {
         return props;
     }
 
+    /**
+     * @param {boolean} isExplicit
+     */
+    #getCategoricalIndexer(isExplicit) {
+        if (
+            !this.#categoricalIndexer ||
+            this.#categoricalIndexerExplicit !== isExplicit
+        ) {
+            this.#categoricalIndexer = createIndexer();
+            this.#categoricalIndexerExplicit = isExplicit;
+        }
+        return this.#categoricalIndexer;
+    }
+
     /**
      * Reconfigures the scale: updates domain and other settings.
      *
@@ -359,36 +506,108 @@ export default class ScaleResolution {
      * or when scale properties are otherwise re-resolved from the view hierarchy.
      */
     reconfigure() {
-        const props = this.#getScaleProps(true);
-        this.#reconfigureWith(() => this.#scaleManager.reconfigureScale(props));
+        this.#domainAggregator.invalidateConfiguredDomain();
+        const state = this.#computeScaleState(true);
+        if (!state) {
+            return;
+        }
+        this.#applyReconfigure(state, (scale, props) =>
+            this.#scaleManager.reconfigureScale(props)
+        );
+        this.#finalizeReconfigure(state);
     }
 
     /**
      * Reconfigures only the effective domain (configured + data-derived).
      *
      * Use this when data changes but the scale membership and properties are stable.
+     *
      */
     reconfigureDomain() {
-        const props = this.#getScaleProps(true);
-        this.#reconfigureWith(() => {
-            configureDomain(this.#scaleManager.scale, props);
-        });
+        const state = this.#computeScaleState(true, true);
+        if (!state) {
+            return;
+        }
+        const { domainConfig, targetDomain } = state;
+        const domainMatches =
+            targetDomain != null &&
+            shallowArrayEquals(targetDomain, state.scale.domain());
+
+        if (targetDomain != null && !domainMatches) {
+            this.#applyReconfigure(state, (scale) => {
+                scale.domain(targetDomain);
+                if (domainConfig.applyOrdinalUnknown) {
+                    // Keep ordinal unknown handling close to the domain write so
+                    // domainImplicit semantics stay aligned with the applied domain.
+                    /** @type {any} */ (scale).unknown(
+                        domainConfig.ordinalUnknown
+                    );
+                }
+            });
+        }
+        this.#finalizeReconfigure(state);
     }
 
     /**
-     * @param {() => void} apply
+     * @param {boolean} extractDataDomain
+     * @param {boolean} [includeDomainConfig]
+     * @returns {{
+     *     scale: ScaleWithProps,
+     *     props: import("../spec/scale.js").Scale,
+     *     previousDomain: any[],
+     *     domainWasInitialized: boolean,
+     *     domainConfig?: ReturnType<typeof configureDomain>,
+     *     targetDomain?: any[] | null,
+     * } | undefined}
      */
-    #reconfigureWith(apply) {
+    #computeScaleState(extractDataDomain, includeDomainConfig = false) {
         const scale = this.#scaleManager.scale;
 
         if (!scale || scale.type == "null") {
             return;
         }
 
-        const domainWasInitialized = this.#isDomainInitialized();
-        const previousDomain = scale.domain();
+        const state = {
+            scale,
+            props: this.#getScaleProps(extractDataDomain),
+            previousDomain: scale.domain(),
+            domainWasInitialized: this.#isDomainInitialized(),
+        };
+
+        if (includeDomainConfig) {
+            const domainConfig = configureDomain(scale, state.props);
+            return {
+                ...state,
+                domainConfig,
+                targetDomain: domainConfig.domain,
+            };
+        }
+
+        return state;
+    }
 
-        this.#scaleManager.withDomainNotificationsSuppressed(apply);
+    /**
+     * @param {{
+     *     scale: ScaleWithProps,
+     *     props: import("../spec/scale.js").Scale,
+     * }} inputs
+     * @param {(scale: ScaleWithProps, props: import("../spec/scale.js").Scale) => void} apply
+     */
+    #applyReconfigure(inputs, apply) {
+        this.#scaleManager.withDomainNotificationsSuppressed(() => {
+            apply(inputs.scale, inputs.props);
+        });
+    }
+
+    /**
+     * @param {{
+     *     scale: ScaleWithProps,
+     *     previousDomain: any[],
+     *     domainWasInitialized: boolean,
+     * }} inputs
+     */
+    #finalizeReconfigure(inputs) {
+        const { scale, previousDomain, domainWasInitialized } = inputs;
 
         if (
             this.#domainAggregator.captureInitialDomain(
@@ -402,13 +621,18 @@ export default class ScaleResolution {
         }
 
         const newDomain = scale.domain();
-        if (!shallowArrayEquals(newDomain, previousDomain)) {
-            if (this.isZoomable()) {
-                // Don't mess with zoomed views, restore the previous domain
-                this.#scaleManager.withDomainNotificationsSuppressed(() => {
-                    scale.domain(previousDomain);
-                });
-            } else if (this.#interactionController.isZoomingSupported()) {
+        const action = this.#interactionController.getDomainChangeAction(
+            previousDomain,
+            newDomain
+        );
+
+        if (action === "restore") {
+            // Don't mess with zoomed views, restore the previous domain
+            this.#scaleManager.withDomainNotificationsSuppressed(() => {
+                scale.domain(previousDomain);
+            });
+        } else if (action === "animate") {
+            if (this.#hasRenderedMember()) {
                 // It can be zoomed, so lets make a smooth transition.
                 // Restore the previous domain and zoom smoothly to the new domain.
                 this.#scaleManager.withDomainNotificationsSuppressed(() => {
@@ -416,10 +640,12 @@ export default class ScaleResolution {
                 });
                 this.zoomTo(newDomain, 500); // TODO: Configurable duration
             } else {
-                // Update immediately if the previous domain was the initial domain [0, 0]
-                // Notifications were suppressed during reconfigure; notify explicitly.
                 this.#notifyListeners("domain");
             }
+        } else if (action === "notify") {
+            // Update immediately if the previous domain was the initial domain [0, 0]
+            // Notifications were suppressed during reconfigure; notify explicitly.
+            this.#notifyListeners("domain");
         }
     }
 
@@ -615,44 +841,3 @@ export default class ScaleResolution {
         return /** @type {number[]} */ (interval);
     }
 }
-
-/**
- * Reconfigures scale domains, starting from the given view.
- *
- * Use this for data-driven updates where only domains need refreshing.
- *
- * TODO: This should be made unnecessary. Collectors should trigger the reconfiguration
- * for those views that get their data from the collector.
- *
- * TODO: This may reconfigure channels that are not affected by the change.
- * Causes performance issues with domains that are extracted from data.
- *
- * @param {import("../view/view.js").default | import("../view/view.js").default[]} fromViews
- */
-export function reconfigureScaleDomains(fromViews) {
-    /** @type {Set<ScaleResolution>} */
-    const uniqueResolutions = new Set();
-
-    /** @param {import("../view/view.js").default} view */
-    function collectResolutions(view) {
-        for (const resolution of Object.values(view.resolutions.scale)) {
-            uniqueResolutions.add(resolution);
-        }
-    }
-
-    for (const fromView of asArray(fromViews)) {
-        // Descendants
-        fromView.visit(collectResolutions);
-
-        // Ancestors
-        for (const view of fromView.getDataAncestors()) {
-            // Skip axis views etc. They should not mess with the domains.
-            if (!view.options.contributesToScaleDomain) {
-                break;
-            }
-            collectResolutions(view);
-        }
-    }
-
-    uniqueResolutions.forEach((resolution) => resolution.reconfigureDomain());
-}

package/dist/src/scales/scaleResolution.test.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaleResolution.test.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleResolution.test.js"],"names":[],"mappings":"sBAYa,OAAO,oBAAoB,EAAE,OAAO"}
+{"version":3,"file":"scaleResolution.test.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleResolution.test.js"],"names":[],"mappings":"sBAWa,OAAO,oBAAoB,EAAE,OAAO"}

package/dist/src/selection/selection.d.ts

@@ -8,6 +8,27 @@ export function createSinglePointSelection(datum: import("../data/flowNode.js").
  * @returns {import("../types/selectionTypes.js").MultiPointSelection}
  */
 export function createMultiPointSelection(data?: import("../data/flowNode.js").Datum[]): import("../types/selectionTypes.js").MultiPointSelection;
+/**
+ * Returns key tuples for a point selection.
+ *
+ * @param {import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection} selection
+ * @param {string[]} keyFields
+ * @returns {import("../spec/channel.js").Scalar[][] | undefined}
+ */
+export function getPointSelectionKeyTuples(selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, keyFields: string[]): import("../spec/channel.js").Scalar[][] | undefined;
+/**
+ * Resolves key tuples to a point selection value object.
+ *
+ * @param {"single" | "multi"} type
+ * @param {string[]} keyFields
+ * @param {import("../spec/channel.js").Scalar[][]} keyTuples
+ * @param {(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined} resolveDatum
+ * @returns {{ selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, unresolved: import("../spec/channel.js").Scalar[][] } | undefined}
+ */
+export function resolvePointSelectionFromKeyTuples(type: "single" | "multi", keyFields: string[], keyTuples: import("../spec/channel.js").Scalar[][], resolveDatum: (keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined): {
+    selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection;
+    unresolved: import("../spec/channel.js").Scalar[][];
+} | undefined;
 /**
  *
  * @param {import("../spec/channel.js").ChannelWithScale[]} channels

package/dist/src/selection/selection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/selection/selection.js"],"names":[],"mappings":"AAOA;;;GAGG;AACH,kDAHW,OAAO,qBAAqB,EAAE,KAAK,GACjC,OAAO,4BAA4B,EAAE,oBAAoB,CAQrE;AAED;;;GAGG;AACH,iDAHW,OAAO,qBAAqB,EAAE,KAAK,EAAE,GACnC,OAAO,4BAA4B,EAAE,mBAAmB,CAQpE;AAED;;;;GAIG;AACH,kDAHW,OAAO,oBAAoB,EAAE,gBAAgB,EAAE,GAC7C,OAAO,4BAA4B,EAAE,iBAAiB,CASlE;AAED;;;;;;;GAOG;AACH,qDAJW,OAAO,4BAA4B,EAAE,mBAAmB,2BACxD,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC,OAAO,qBAAqB,EAAE,KAAK,CAAC,CAAC,CAAC,GACzF,OAAO,4BAA4B,EAAE,mBAAmB,CA2BpE;AAED;;;;;GAKG;AACH,oDAHW,OAAO,sBAAsB,EAAE,qBAAqB,aACpD,OAAO,4BAA4B,EAAE,SAAS,UAgExD;AAED;;;GAGG;AACH,+CAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,iBAAiB,CAI/E;AAED;;;GAGG;AACH,kDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,oBAAoB,CAIlF;AAED;;;GAGG;AACH,iDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,mBAAmB,CAIjF;AAED;;;GAGG;AACH,gDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,kBAAkB,CAIhF;AAED;;;GAGG;AACH,gDAHW,OAAO,sBAAsB,EAAE,qBAAqB,GAClD,OAAO,sBAAsB,EAAE,eAAe,CA4B1D;AAED;;;GAGG;AACH,+CAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,oBAAoB,CAIzE;AAED;;;;GAIG;AACH,kDAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,uBAAuB,CAI5E;AAED;;GAEG;AACH,qDAFW,OAAO,4BAA4B,EAAE,iBAAiB,WAMhE;AAED;;;;;GAKG;AACH,kDAHW,iBAAiB,SACjB,aAAa,WAUvB;AAED;;;GAGG;AACH,yCAHW,OAAO,sBAAsB,EAAE,eAAe,CAAC,IAAI,CAAC,GAClD,OAAO,sBAAsB,EAAE,WAAW,CAsBtD;gCAvCY,OAAO,4BAA4B,EAAE,iBAAiB;4BACtD,OAAO,CAAC,MAAM,CAAC,MAAM,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC"}
+{"version":3,"file":"selection.d.ts","sourceRoot":"","sources":["../../../src/selection/selection.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,kDAHW,OAAO,qBAAqB,EAAE,KAAK,GACjC,OAAO,4BAA4B,EAAE,oBAAoB,CAQrE;AAED;;;GAGG;AACH,iDAHW,OAAO,qBAAqB,EAAE,KAAK,EAAE,GACnC,OAAO,4BAA4B,EAAE,mBAAmB,CAQpE;AAED;;;;;;GAMG;AACH,sDAJW,OAAO,4BAA4B,EAAE,oBAAoB,GAAG,OAAO,4BAA4B,EAAE,mBAAmB,aACpH,MAAM,EAAE,GACN,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,GAAG,SAAS,CA2B/D;AAED;;;;;;;;GAQG;AACH,yDANW,QAAQ,GAAG,OAAO,aAClB,MAAM,EAAE,aACR,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,gBACvC,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,OAAO,oBAAoB,EAAE,MAAM,EAAE,KAAK,OAAO,qBAAqB,EAAE,KAAK,GAAG,SAAS,GACvH;IAAE,SAAS,EAAE,OAAO,4BAA4B,EAAE,oBAAoB,GAAG,OAAO,4BAA4B,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,OAAO,oBAAoB,EAAE,MAAM,EAAE,EAAE,CAAA;CAAE,GAAG,SAAS,CAsChN;AAED;;;;GAIG;AACH,kDAHW,OAAO,oBAAoB,EAAE,gBAAgB,EAAE,GAC7C,OAAO,4BAA4B,EAAE,iBAAiB,CASlE;AAED;;;;;;;GAOG;AACH,qDAJW,OAAO,4BAA4B,EAAE,mBAAmB,2BACxD,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAAE,QAAQ,CAAC,OAAO,qBAAqB,EAAE,KAAK,CAAC,CAAC,CAAC,GACzF,OAAO,4BAA4B,EAAE,mBAAmB,CA2BpE;AAED;;;;;GAKG;AACH,oDAHW,OAAO,sBAAsB,EAAE,qBAAqB,aACpD,OAAO,4BAA4B,EAAE,SAAS,UAgExD;AAED;;;GAGG;AACH,+CAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,iBAAiB,CAI/E;AAED;;;GAGG;AACH,kDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,oBAAoB,CAIlF;AAED;;;GAGG;AACH,iDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,mBAAmB,CAIjF;AAED;;;GAGG;AACH,gDAHW,OAAO,4BAA4B,EAAE,SAAS,GAC5C,SAAS,IAAI,OAAO,4BAA4B,EAAE,kBAAkB,CAIhF;AAED;;;GAGG;AACH,gDAHW,OAAO,sBAAsB,EAAE,qBAAqB,GAClD,OAAO,sBAAsB,EAAE,eAAe,CA4B1D;AAED;;;GAGG;AACH,+CAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,oBAAoB,CAIzE;AAED;;;;GAIG;AACH,kDAHW,OAAO,sBAAsB,EAAE,eAAe,GAC5C,MAAM,IAAI,OAAO,sBAAsB,EAAE,uBAAuB,CAI5E;AAED;;GAEG;AACH,qDAFW,OAAO,4BAA4B,EAAE,iBAAiB,WAMhE;AAED;;;;;GAKG;AACH,kDAHW,iBAAiB,SACjB,aAAa,WAUvB;AAED;;;GAGG;AACH,yCAHW,OAAO,sBAAsB,EAAE,eAAe,CAAC,IAAI,CAAC,GAClD,OAAO,sBAAsB,EAAE,WAAW,CAsBtD;gCAvCY,OAAO,4BAA4B,EAAE,iBAAiB;4BACtD,OAAO,CAAC,MAAM,CAAC,MAAM,iBAAiB,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC"}

package/dist/src/selection/selection.js

@@ -4,6 +4,7 @@ import {
     isPrimaryPositionalChannel,
 } from "../encoder/encoder.js";
 import { validateParameterName } from "../view/paramMediator.js";
+import { field } from "../utils/field.js";
 
 /**
  * @param {import("../data/flowNode.js").Datum} datum
@@ -29,6 +30,87 @@ export function createMultiPointSelection(data) {
     };
 }
 
+/**
+ * Returns key tuples for a point selection.
+ *
+ * @param {import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection} selection
+ * @param {string[]} keyFields
+ * @returns {import("../spec/channel.js").Scalar[][] | undefined}
+ */
+export function getPointSelectionKeyTuples(selection, keyFields) {
+    if (!keyFields || keyFields.length === 0) {
+        return;
+    }
+
+    const accessors = keyFields.map((fieldName) => field(fieldName));
+    const toTuple = (
+        /** @type {import("../data/flowNode.js").Datum} */ datum
+    ) => accessors.map((accessor) => accessor(datum));
+
+    if (isSinglePointSelection(selection)) {
+        if (!selection.datum) {
+            return [];
+        }
+
+        return [toTuple(selection.datum)];
+    }
+
+    if (isMultiPointSelection(selection)) {
+        return [...selection.data.values()].map(toTuple);
+    }
+
+    throw new Error(
+        `Expected a point selection, got: ${JSON.stringify(selection)}`
+    );
+}
+
+/**
+ * Resolves key tuples to a point selection value object.
+ *
+ * @param {"single" | "multi"} type
+ * @param {string[]} keyFields
+ * @param {import("../spec/channel.js").Scalar[][]} keyTuples
+ * @param {(keyFields: string[], keyTuple: import("../spec/channel.js").Scalar[]) => import("../data/flowNode.js").Datum | undefined} resolveDatum
+ * @returns {{ selection: import("../types/selectionTypes.js").SinglePointSelection | import("../types/selectionTypes.js").MultiPointSelection, unresolved: import("../spec/channel.js").Scalar[][] } | undefined}
+ */
+export function resolvePointSelectionFromKeyTuples(
+    type,
+    keyFields,
+    keyTuples,
+    resolveDatum
+) {
+    if (!keyFields || keyFields.length === 0) {
+        return;
+    }
+
+    if (type === "single" && keyTuples.length > 1) {
+        throw new Error(
+            "Single point selections expect at most one key tuple."
+        );
+    }
+
+    /** @type {import("../data/flowNode.js").Datum[]} */
+    const datums = [];
+    /** @type {import("../spec/channel.js").Scalar[][]} */
+    const unresolved = [];
+
+    for (const tuple of keyTuples) {
+        const datum = resolveDatum(keyFields, tuple);
+        if (datum) {
+            datums.push(datum);
+        } else {
+            unresolved.push(tuple);
+        }
+    }
+
+    const selection =
+        type === "single"
+            ? createSinglePointSelection(datums[0] ?? null)
+            : createMultiPointSelection(datums);
+
+    return { selection, unresolved };
+}
+
 /**
  *
  * @param {import("../spec/channel.js").ChannelWithScale[]} channels