@genome-spy/core 0.64.0 → 0.66.1

package/dist/src/scales/scaleInteractionController.js

@@ -0,0 +1,336 @@
+import {
+    clampRange,
+    isArray,
+    isBoolean,
+    isObject,
+    panLinear,
+    panLog,
+    panPow,
+    span,
+    zoomLinear,
+    zoomLog,
+    zoomPow,
+} from "vega-util";
+import { isContinuous } from "vega-scale";
+import { easeCubicInOut } from "d3-ease";
+
+import eerp from "../utils/eerp.js";
+import { shallowArrayEquals } from "../utils/arrayUtils.js";
+
+/**
+ * @typedef {import("../spec/scale.js").NumericDomain} NumericDomain
+ * @typedef {import("../spec/scale.js").ScalarDomain} ScalarDomain
+ * @typedef {import("../spec/scale.js").ComplexDomain} ComplexDomain
+ * @typedef {import("../spec/scale.js").ZoomParams} ZoomParams
+ * @typedef {import("../types/encoder.js").VegaScale} VegaScale
+ * @typedef {VegaScale & { props: import("../spec/scale.js").Scale }} ScaleWithProps
+ */
+
+export default class ScaleInteractionController {
+    /** @type {() => ScaleWithProps} */
+    #getScale;
+
+    /** @type {() => import("../utils/animator.js").default} */
+    #getAnimator;
+
+    /** @type {() => number[]} */
+    #getInitialDomainSnapshot;
+
+    /** @type {() => number[]} */
+    #getResetDomain;
+
+    /** @type {(domain: ScalarDomain | ComplexDomain) => number[]} */
+    #fromComplexInterval;
+
+    /** @type {() => number[]} */
+    #getGenomeExtent;
+
+    /**
+     * @param {object} options
+     * @param {() => ScaleWithProps} options.getScale
+     * @param {() => import("../utils/animator.js").default} options.getAnimator
+     * @param {() => number[]} options.getInitialDomainSnapshot
+     * @param {() => number[]} options.getResetDomain
+     * @param {(domain: ScalarDomain | ComplexDomain) => number[]} options.fromComplexInterval
+     * @param {() => number[]} options.getGenomeExtent
+     */
+    constructor({
+        getScale,
+        getAnimator,
+        getInitialDomainSnapshot,
+        getResetDomain,
+        fromComplexInterval,
+        getGenomeExtent,
+    }) {
+        this.#getScale = getScale;
+        this.#getAnimator = getAnimator;
+        this.#getInitialDomainSnapshot = getInitialDomainSnapshot;
+        this.#getResetDomain = getResetDomain;
+        this.#fromComplexInterval = fromComplexInterval;
+        this.#getGenomeExtent = getGenomeExtent;
+    }
+
+    getZoomExtent() {
+        const scale = this.#getScale();
+        const zoom = scale.props.zoom;
+        return resolveZoomExtent(
+            scale,
+            zoom,
+            this.#fromComplexInterval,
+            this.#getGenomeExtent,
+            this.#getInitialDomainSnapshot
+        );
+    }
+
+    isZoomable() {
+        return this.isZoomingSupported() && !!this.#getScale().props.zoom;
+    }
+
+    isZoomingSupported() {
+        return isContinuous(this.#getScale().type);
+    }
+
+    /**
+     * Return true if the scale is zoomable and the current domain differs from the initial domain.
+     *
+     * @returns true if zoomed
+     */
+    isZoomed() {
+        return (
+            this.isZoomingSupported() &&
+            shallowArrayEquals(
+                this.#getResetDomain(),
+                this.#getScale().domain()
+            )
+        );
+    }
+
+    /**
+     * Pans (translates) and zooms using a specified scale factor.
+     *
+     * @param {number} scaleFactor
+     * @param {number} scaleAnchor
+     * @param {number} pan
+     * @returns {boolean} true if the scale was zoomed
+     */
+    zoom(scaleFactor, scaleAnchor, pan) {
+        if (!this.isZoomingSupported()) {
+            return false;
+        }
+
+        const scale = this.#getScale();
+        const oldDomain = scale.domain();
+        let newDomain = applyZoomTransform(
+            scale,
+            oldDomain,
+            scaleFactor,
+            scaleAnchor,
+            pan
+        );
+
+        // TODO: Use the zoomTo method. Move clamping etc there.
+        const zoomExtent = this.getZoomExtent();
+        newDomain = clampRange(newDomain, zoomExtent[0], zoomExtent[1]);
+
+        if ([0, 1].some((i) => newDomain[i] != oldDomain[i])) {
+            scale.domain(newDomain);
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Immediately zooms to the given interval.
+     *
+     * @param {NumericDomain | ComplexDomain} domain
+     * @param {boolean | number} [duration] an approximate duration for transition.
+     *      Zero duration zooms immediately. Boolean `true` indicates a default duration.
+     */
+    async zoomTo(domain, duration = false) {
+        if (isBoolean(duration)) {
+            duration = duration ? 700 : 0;
+        }
+
+        if (!this.isZoomingSupported()) {
+            throw new Error("Not a zoomable scale!");
+        }
+
+        const to = this.#fromComplexInterval(domain);
+
+        // TODO: Intersect the domain with zoom extent
+
+        const animator = this.#getAnimator();
+
+        const scale = this.#getScale();
+        const from = /** @type {number[]} */ (scale.domain());
+
+        if (duration > 0 && from.length == 2) {
+            // Spans
+            const fw = from[1] - from[0];
+            const tw = to[1] - to[0];
+
+            // Centers
+            const fc = from[0] + fw / 2;
+            const tc = to[0] + tw / 2;
+
+            // Constant endpoints. Skip calculation to maintain precision.
+            const ac = from[0] == to[0];
+            const bc = from[1] == to[1];
+
+            // TODO: Abort possible previous transition
+            await animator.transition({
+                duration,
+                easingFunction: easeCubicInOut,
+                onUpdate: (t) => {
+                    const w = eerp(fw, tw, t);
+                    const wt = fw == tw ? t : (fw - w) / (fw - tw);
+                    const c = wt * tc + (1 - wt) * fc;
+                    const newDomain = [
+                        ac ? from[0] : c - w / 2,
+                        bc ? from[1] : c + w / 2,
+                    ];
+                    scale.domain(newDomain);
+                },
+            });
+
+            scale.domain(to);
+        } else {
+            scale.domain(to);
+            animator?.requestRender();
+        }
+    }
+
+    /**
+     * Resets the current domain to the initial one
+     *
+     * @returns true if the domain was changed
+     */
+    resetZoom() {
+        if (!this.isZoomingSupported()) {
+            throw new Error("Not a zoomable scale!");
+        }
+
+        const scale = this.#getScale();
+        const oldDomain = scale.domain();
+        const newDomain = this.#getResetDomain();
+
+        if ([0, 1].some((i) => newDomain[i] != oldDomain[i])) {
+            scale.domain(newDomain);
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Returns the zoom level with respect to the reference domain span (the original domain).
+     */
+    getZoomLevel() {
+        // Zoom level makes sense only for user-zoomable scales where zoom extent is defined
+        if (this.isZoomable()) {
+            return span(this.getZoomExtent()) / span(this.#getScale().domain());
+        }
+
+        return 1.0;
+    }
+}
+
+/**
+ * @param {ScaleWithProps} scale
+ * @param {ZoomParams | boolean | undefined} zoom
+ * @param {(interval: ScalarDomain | ComplexDomain) => number[]} fromComplexInterval
+ * @param {() => number[]} getGenomeExtent
+ * @param {() => number[]} getInitialDomainSnapshot
+ * @returns {number[]}
+ */
+function resolveZoomExtent(
+    scale,
+    zoom,
+    fromComplexInterval,
+    getGenomeExtent,
+    getInitialDomainSnapshot
+) {
+    if (isZoomParams(zoom)) {
+        if (isArray(zoom.extent)) {
+            return fromComplexInterval(zoom.extent);
+        }
+    }
+
+    if (zoom && scale.props.type == "locus") {
+        return getGenomeExtent();
+    }
+
+    // TODO: Perhaps this should be "domain" for index scale and nothing for quantitative.
+    // Would behave similarly to Vega-Lite, which doesn't have constraints.
+    return getInitialDomainSnapshot();
+}
+
+/**
+ * @param {ScaleWithProps} scale
+ * @param {number[]} domain
+ * @param {number} scaleFactor
+ * @param {number} scaleAnchor
+ * @param {number} pan
+ * @returns {number[]}
+ */
+function applyZoomTransform(scale, domain, scaleFactor, scaleAnchor, pan) {
+    let newDomain = [...domain];
+
+    /** @type {number} */
+    // @ts-ignore
+    let anchor = scale.invert(scaleAnchor);
+
+    if (scale.props.reverse) {
+        pan = -pan;
+    }
+
+    if ("align" in scale) {
+        anchor += scale.align();
+    }
+
+    // TODO: symlog
+    switch (scale.type) {
+        case "linear":
+        case "index":
+        case "locus":
+            newDomain = panLinear(newDomain, pan || 0);
+            newDomain = zoomLinear(newDomain, anchor, scaleFactor);
+            break;
+        case "log":
+            newDomain = panLog(newDomain, pan || 0);
+            newDomain = zoomLog(newDomain, anchor, scaleFactor);
+            break;
+        case "pow":
+        case "sqrt": {
+            const powScale =
+                /** @type {import("d3-scale").ScalePower<number, number>} */ (
+                    scale
+                );
+            newDomain = panPow(newDomain, pan || 0, powScale.exponent());
+            newDomain = zoomPow(
+                newDomain,
+                anchor,
+                scaleFactor,
+                powScale.exponent()
+            );
+            break;
+        }
+        default:
+            throw new Error("Zooming is not implemented for: " + scale.type);
+    }
+
+    return newDomain;
+}
+
+/**
+ * @param {boolean | ZoomParams} zoom
+ * @returns {zoom is ZoomParams}
+ */
+function isZoomParams(zoom) {
+    return isObject(zoom);
+}
+
+/**
+ * @param {any[]} a
+ * @param {any[]} b
+ */

package/dist/src/scales/scaleInteractionController.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scaleInteractionController.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaleInteractionController.test.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleInteractionController.test.js"],"names":[],"mappings":""}

package/dist/src/scales/scalePropsResolver.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @typedef {import("../spec/channel.js").Channel} Channel
+ * @typedef {import("../spec/scale.js").Scale} Scale
+ * @typedef {import("./scaleResolution.js").ScaleResolutionMember} ScaleResolutionMember
+ */
+/**
+ * @param {object} options
+ * @param {Channel} options.channel
+ * @param {import("../spec/channel.js").Type} options.dataType
+ * @param {Set<ScaleResolutionMember>} options.members
+ * @param {boolean} options.isExplicitDomain
+ * @returns {Scale}
+ */
+export function resolveScalePropsBase({ channel, dataType, members, isExplicitDomain, }: {
+    channel: Channel;
+    dataType: import("../spec/channel.js").Type;
+    members: Set<ScaleResolutionMember>;
+    isExplicitDomain: boolean;
+}): Scale;
+export type Channel = import("../spec/channel.js").Channel;
+export type Scale = import("../spec/scale.js").Scale;
+export type ScaleResolutionMember = import("./scaleResolution.js").ScaleResolutionMember;
+//# sourceMappingURL=scalePropsResolver.d.ts.map

package/dist/src/scales/scalePropsResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scalePropsResolver.d.ts","sourceRoot":"","sources":["../../../src/scales/scalePropsResolver.js"],"names":[],"mappings":"AAOA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,yFANG;IAAyB,OAAO,EAAxB,OAAO;IACoC,QAAQ,EAAnD,OAAO,oBAAoB,EAAE,IAAI;IACG,OAAO,EAA3C,GAAG,CAAC,qBAAqB,CAAC;IACT,gBAAgB,EAAjC,OAAO;CACf,GAAU,KAAK,CAiDjB;sBA5DY,OAAO,oBAAoB,EAAE,OAAO;oBACpC,OAAO,kBAAkB,EAAE,KAAK;oCAChC,OAAO,sBAAsB,EAAE,qBAAqB"}

package/dist/src/scales/scalePropsResolver.js

@@ -0,0 +1,74 @@
+import { isDiscrete } from "vega-scale";
+
+import mergeObjects from "../utils/mergeObjects.js";
+import { getDefaultScaleProperties } from "../config/scaleDefaults.js";
+import { applyLockedProperties, getDefaultScaleType } from "./scaleRules.js";
+import { INDEX, LOCUS } from "./scaleResolutionConstants.js";
+
+/**
+ * @typedef {import("../spec/channel.js").Channel} Channel
+ * @typedef {import("../spec/scale.js").Scale} Scale
+ * @typedef {import("./scaleResolution.js").ScaleResolutionMember} ScaleResolutionMember
+ */
+
+/**
+ * @param {object} options
+ * @param {Channel} options.channel
+ * @param {import("../spec/channel.js").Type} options.dataType
+ * @param {Set<ScaleResolutionMember>} options.members
+ * @param {boolean} options.isExplicitDomain
+ * @returns {Scale}
+ */
+export function resolveScalePropsBase({
+    channel,
+    dataType,
+    members,
+    isExplicitDomain,
+}) {
+    const propArray = Array.from(members)
+        .map((member) => member.channelDef.scale)
+        .filter((props) => props !== undefined);
+
+    // TODO: Disabled scale: https://vega.github.io/vega-lite/docs/scale.html#disable
+    const mergedProps = mergeObjects(propArray, "scale", ["domain"]);
+    if (mergedProps === null || mergedProps.type == "null") {
+        return /** @type {Scale} */ ({ type: "null" });
+    }
+
+    const props = {
+        ...getDefaultScaleProperties(channel, dataType, isExplicitDomain),
+        ...mergedProps,
+    };
+
+    if (!props.type) {
+        props.type = getDefaultScaleType(channel, dataType);
+    }
+
+    // Reverse discrete y axis
+    if (
+        channel == "y" &&
+        isDiscrete(props.type) &&
+        props.reverse == undefined
+    ) {
+        props.reverse = true;
+    }
+
+    if (props.range && props.scheme) {
+        delete props.scheme;
+        // TODO: Props should be set more intelligently
+    }
+
+    // By default, index and locus scales are zoomable, others are not
+    if (!("zoom" in props) && [INDEX, LOCUS].includes(props.type)) {
+        props.zoom = true;
+    }
+
+    applyLockedProperties(props, channel);
+
+    return props;
+}
+
+/**
+ * @param {Scale} props
+ * @param {Channel} channel
+ */

package/dist/src/{view → scales}/scaleResolution.d.ts

@@ -1,5 +1,7 @@
 /**
- * Reconfigures scales, starting from the given view.
+ * 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.
@@ -7,28 +9,24 @@
  * 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.js").default | import("./view.js").default[]} fromViews
+ * @param {import("../view/view.js").default | import("../view/view.js").default[]} fromViews
  */
-export function reconfigureScales(fromViews: import("./view.js").default | import("./view.js").default[]): void;
-export const QUANTITATIVE: "quantitative";
-export const ORDINAL: "ordinal";
-export const NOMINAL: "nominal";
-export const LOCUS: "locus";
-export const INDEX: "index";
+export function reconfigureScaleDomains(fromViews: import("../view/view.js").default | import("../view/view.js").default[]): void;
 /**
  * @template {ChannelWithScale}[T=ChannelWithScale]
  *
  * @typedef {object} ScaleResolutionMember
- * @prop {import("./unitView.js").default} view TODO: Get rid of the view reference
+ * @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
  */
 /**
- * Resolution takes care of merging domains and scales from multiple views.
- * This class also provides some utility methods for zooming the scales etc..
- *
- * TODO: This has grown a bit too fat. Consider splitting.
+ * Resolves a shared scale for a channel by merging scale properties and domains
+ * across participating views, then coordinating range updates and zoom/pan
+ * interactions. It is the central wiring point for scale-related state and
+ * notifications, while delegating domain aggregation, scale instance setup, and
+ * interaction logic to focused helpers.
  *
  * @implements {ScaleResolutionApi}
  */
@@ -38,8 +36,6 @@ export default class ScaleResolution implements ScaleResolutionApi {
      */
     constructor(channel: import("../spec/channel.js").Channel);
     channel: import("../spec/channel.js").Channel;
-    /** @type {ScaleResolutionMember[]} The involved views */
-    members: ScaleResolutionMember[];
     /** @type {import("../spec/channel.js").Type} Data type (quantitative, nominal, etc...) */
     type: import("../spec/channel.js").Type;
     /** @type {string} An optional unique identifier for the scale */
@@ -60,29 +56,54 @@ export default class ScaleResolution implements ScaleResolutionApi {
      */
     removeEventListener(type: import("../types/scaleResolutionApi.js").ScaleResolutionEventType, listener: import("../types/scaleResolutionApi.js").ScaleResolutionListener): void;
     /**
-     * Add a view to this resolution.
-     * N.B. This is expected to be called in depth-first order
-     *
-     * @param {ScaleResolutionMember} newMember
+     * @param {ScaleResolutionMember} member
+     * @returns {() => boolean}
      */
-    addMember(newMember: ScaleResolutionMember): void;
+    registerMember(member: ScaleResolutionMember): () => boolean;
     /**
-     * Extracts and unions the data domains of all participating views.
+     * Reconfigures the scale: updates domain and other settings.
      *
-     * @return { DomainArray }
+     * Use this when the set of participating members changes (views added or removed),
+     * or when scale properties are otherwise re-resolved from the view hierarchy.
      */
-    getDataDomain(): import("../utils/domainArray.js").DomainArray;
+    reconfigure(): void;
     /**
-     * Reconfigures the scale: updates domain and other settings
+     * Reconfigures only the effective domain (configured + data-derived).
+     *
+     * Use this when data changes but the scale membership and properties are stable.
      */
-    reconfigure(): void;
+    reconfigureDomain(): void;
     /**
      * @returns {ScaleWithProps}
      */
     get scale(): import("../types/encoder.js").VegaScale & {
         props: import("../spec/scale.js").Scale;
     };
+    /**
+     * Returns the scale instance, creating it if needed.
+     *
+     * Use this from call sites that may run before explicit initialization.
+     *
+     * @returns {ScaleWithProps}
+     */
+    getScale(): import("../types/encoder.js").VegaScale & {
+        props: import("../spec/scale.js").Scale;
+    };
+    /**
+     * Initializes the scale instance once resolution has stabilized.
+     *
+     * @returns {ScaleWithProps}
+     */
+    initializeScale(): import("../types/encoder.js").VegaScale & {
+        props: import("../spec/scale.js").Scale;
+    };
     getDomain(): any[];
+    /**
+     * Extracts and unions the data domains of all participating views.
+     *
+     * @return { DomainArray }
+     */
+    getDataDomain(): import("../utils/domainArray.js").DomainArray;
     /**
      * @returns {NumericDomain | ComplexDomain}
      */
@@ -136,11 +157,6 @@ export default class ScaleResolution implements ScaleResolutionApi {
      * be configured as pixels, but that is yet to be materialized.
      */
     getAxisLength(): number;
-    /**
-     *
-     * @returns {import("../genome/genome.js").default}
-     */
-    getGenome(): import("../genome/genome.js").default;
     /**
      * Inverts a value in range to a value on domain. Returns an object in
      * case of locus scale.
@@ -168,9 +184,15 @@ export type ScaleResolutionMember<T extends import("../spec/channel.js").Channel
     /**
      * TODO: Get rid of the view reference
      */
-    view: import("./unitView.js").default;
+    view: import("../view/unitView.js").default;
     channel: T;
     channelDef: import("../spec/channel.js").ChannelDefWithScale;
     dataDomainSource: (channel: import("../spec/channel.js").ChannelWithScale, type: import("../spec/channel.js").Type) => import("../utils/domainArray.js").DomainArray;
 };
+import { INDEX } from "./scaleResolutionConstants.js";
+import { LOCUS } from "./scaleResolutionConstants.js";
+import { NOMINAL } from "./scaleResolutionConstants.js";
+import { ORDINAL } from "./scaleResolutionConstants.js";
+import { QUANTITATIVE } from "./scaleResolutionConstants.js";
+export { INDEX, LOCUS, NOMINAL, ORDINAL, QUANTITATIVE };
 //# sourceMappingURL=scaleResolution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scaleResolution.d.ts","sourceRoot":"","sources":["../../../src/scales/scaleResolution.js"],"names":[],"mappings":"AA0mBA;;;;;;;;;;;;GAYG;AACH,mDAFW,OAAO,iBAAiB,EAAE,OAAO,GAAG,OAAO,iBAAiB,EAAE,OAAO,EAAE,QA4BjF;AA5mBD;;;;;;;;GAQG;AACH;;;;;;;;GAQG;AACH;IAsCI;;OAEG;IACH,2DAgCC;IA/BG,8CAAsB;IACtB,0FAA0F;IAC1F,MADW,OAAO,oBAAoB,EAAE,IAAI,CAC5B;IAEhB,iEAAiE;IACjE,MADW,MAAM,CACI;IA2CzB,2BASC;IAqBD;;;;;;;OAOG;IACH,4KAEC;IAED;;;OAGG;IACH,+KAEC;IAyED;;;OAGG;IACH,uBAHW,qBAAqB,GACnB,MAAM,OAAO,CAQzB;IA8ED;;;;;OAKG;IACH,oBAGC;IAED;;;;OAIG;IACH,0BAKC;IAkDD;;OAEG;IACH;eAtWkC,OAAO,kBAAkB,EAAE,KAAK;MA6WjE;IAED;;;;;;OAMG;IACH;eAtXkC,OAAO,kBAAkB,EAAE,KAAK;MAwXjE;IAED;;;;OAIG;IACH;eA/XkC,OAAO,kBAAkB,EAAE,KAAK;MAwYjE;IAED,mBAEC;IAED;;;;OAIG;IACH,+DAEC;IAED;;OAEG;IACH,oBAFa,mFAA6B,CAMzC;IAED;;;;OAIG;IACH,oBAEC;IAED;;OAEG;IACH,sBAGC;IAED;;;;;;;OAOG;IACH,kBALW,MAAM,eACN,MAAM,OACN,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,eAJW,mFAA6B,aAC7B,OAAO,GAAG,MAAM,iBAK1B;IAED;;;;OAIG;IACH,qBAEC;IAED;;;;;OAKG;IACH,uBAEC;IAED;;;;;;;OAOG;IACH,wBAoBC;IAED;;;;;OAKG;IACH,uBAFW,MAAM,yDAUhB;IAED;;OAEG;IACH,iBAFW,MAAM,yDAIhB;IAED;;;OAGG;IACH,qBAHW,MAAM,+CAAmB,GACvB,MAAM,CAIlB;IAED;;;OAGG;IACH,8BAHW,kFAA4B,GAC1B,MAAM,EAAE,CAOpB;;CACJ;kCAlkB+B,CAAC,SAApB,6CAAkB;;;;UAGrB,OAAO,qBAAqB,EAAE,OAAO;aACrC,CAAC;gBACD,OAAO,oBAAoB,EAAE,mBAAmB;sBAChD,CAAC,OAAO,+CAAkB,EAAE,IAAI,EAAE,OAAO,oBAAoB,EAAE,IAAI,kDAAgB;;sBArBtF,+BAA+B;sBAA/B,+BAA+B;wBAA/B,+BAA+B;wBAA/B,+BAA+B;6BAA/B,+BAA+B"}