@genome-spy/core 0.29.0 → 0.30.2

package/src/view/view.js

@@ -1,612 +0,0 @@
-import {
-    parseSizeDef,
-    FlexDimensions,
-    ZERO_FLEXDIMENSIONS,
-} from "../utils/layout/flexLayout";
-import Padding from "../utils/layout/padding";
-import {
-    getCachedOrCall,
-    initPropertyCache,
-    invalidatePrefix,
-} from "../utils/propertyCacher";
-import { isNumber, isString, span } from "vega-util";
-import { scaleLog } from "d3-scale";
-import { isFieldDef, getPrimaryChannel } from "../encoder/encoder";
-import { appendToBaseUrl } from "../utils/url";
-import { isDiscrete, bandSpace } from "vega-scale";
-import { peek } from "../utils/arrayUtils";
-
-// TODO: View classes have too many responsibilities. Come up with a way
-// to separate the concerns. However, most concerns are tightly tied to
-// the hierarchy, which makes the separation quite tricky.
-// Separation of concerns would also make the code more easily testable.
-
-/** Skip children */
-export const VISIT_SKIP = "VISIT_SKIP";
-/** Stop further visits */
-export const VISIT_STOP = "VISIT_STOP";
-
-/** @type {function(number):number} */
-const defaultOpacityFunction = (parentOpacity) => parentOpacity;
-
-/**
- * @typedef {import("../spec/channel").Channel} Channel
- * @typedef {import("../spec/channel").ChannelDef} ChannelDef
- * @typedef {import("../spec/view").ViewSpec} ViewSpec
- * @typedef {import("./viewUtils").ViewContext} ViewContext
- * @typedef {import("../utils/layout/flexLayout").SizeDef} SizeDef
- * @typedef {import("../utils/layout/flexLayout").LocSize} LocSize
- *
- * @typedef {import("../spec/view").ResolutionTarget} ResolutionTarget
- * @typedef {import("./scaleResolution").default} ScaleResolution
- * @typedef {import("./axisResolution").default} AxisResolution
- *
- * @typedef {VISIT_SKIP|VISIT_STOP|void} VisitResult
- *
- * @callback VisitorCallback
- * @param {View} view
- * @returns {VisitResult}
- *
- * @typedef {VisitorCallback & {
- *      postOrder?: function(View):void,
- *      beforeChildren?: function(View):void,
- *      afterChildren?: function(View):void}
- * } Visitor
- *
- * @typedef {object} BroadcastMessage
- * @prop {string} type Broadcast type
- * @prop {any} [payload] Anything
- *
- * @typedef {import("./rendering").RenderingOptions} RenderingOptions
- *
- * @callback InteractionEventListener
- * @param {import("../utils/layout/rectangle").default} coords
- *      Coordinates of the view
- * @param {import("../utils/interactionEvent").default} event
- */
-export default class View {
-    /**
-     *
-     * @param {ViewSpec} spec
-     * @param {ViewContext} context
-     * @param {import("./containerView").default} parent
-     * @param {string} name
-     */
-    constructor(spec, context, parent, name) {
-        this.context = context;
-        this.parent = parent;
-        this.name = spec.name || name;
-        this.spec = spec;
-
-        this.resolutions = {
-            /**
-             * Channel-specific scale resolutions
-             * @type {Partial<Record<Channel, import("./scaleResolution").default>>}
-             */
-            scale: {},
-            /**
-             * Channel-specific axis resolutions
-             * @type {Partial<Record<import("../spec/channel").PrimaryPositionalChannel, import("./axisResolution").default>>}
-             */
-            axis: {},
-        };
-
-        /** @type {Record<string, (function(BroadcastMessage):void)[]>} */
-        this._broadcastHandlers = {};
-
-        /** @type {Record<string, InteractionEventListener[]>} */
-        this._capturingInteractionEventListeners = {};
-        /** @type {Record<string, InteractionEventListener[]>} */
-        this._nonCapturingInteractionEventListeners = {};
-
-        initPropertyCache(this);
-
-        /** @type {function(number):number} */
-        this.opacityFunction = defaultOpacityFunction;
-
-        /**
-         * Don't inherit encodings from parent.
-         * TODO: Make configurable through spec. Allow more fine-grained control.
-         */
-        this.blockEncodingInheritance = false;
-    }
-
-    getPadding() {
-        return this._cache("size/padding", () =>
-            Padding.createFromConfig(this.spec.padding)
-        );
-    }
-
-    /**
-     * Returns a padding that indicates how much axes and titles extend over the plot area.
-     *
-     * @returns {Padding}
-     */
-    getOverhang() {
-        return Padding.zero();
-    }
-
-    /**
-     * Returns the configured size, if present. Otherwise a computed or default
-     * height is returned.
-     *
-     * @returns {FlexDimensions}
-     */
-    getSize() {
-        return this._cache("size/size", () =>
-            this.isVisible()
-                ? this.getSizeFromSpec().addPadding(this.getPadding())
-                : ZERO_FLEXDIMENSIONS
-        );
-    }
-
-    /**
-     * @return {FlexDimensions}
-     */
-    getSizeFromSpec() {
-        /**
-         * @param {"width" | "height"} dimension
-         * @return {SizeDef}
-         */
-        const handleSize = (dimension) => {
-            let value = this.spec[dimension];
-
-            if (isStepSize(value)) {
-                const stepSize = value.step;
-
-                const scale = this.getScaleResolution(
-                    dimension == "width" ? "x" : "y"
-                )?.getScale();
-
-                if (scale) {
-                    // Note: this and all ancestral views need to be refreshed when the domain is changed.
-                    let steps = 0;
-                    if (isDiscrete(scale.type)) {
-                        steps = scale.domain().length;
-                    } else if (["locus", "index"].includes(scale.type)) {
-                        const domain = scale.domain();
-                        steps = peek(domain) - domain[0];
-                    } else {
-                        throw new Error(
-                            `Cannot use step-based size with "${scale.type}" scale!`
-                        );
-                    }
-
-                    // TODO: Type guards maybe?
-                    const _scale =
-                        /** @type {import("d3-scale").ScaleBand<any> | import("../genome/scaleLocus").ScaleLocus | import("../genome/scaleIndex").ScaleIndex} */ (
-                            scale
-                        );
-
-                    steps = bandSpace(
-                        steps,
-                        _scale.paddingInner(),
-                        _scale.paddingOuter()
-                    );
-
-                    return { px: steps * stepSize, grow: 0 };
-                } else {
-                    throw new Error(
-                        "Cannot use 'step' size with missing scale!"
-                    );
-                }
-            } else {
-                return (value && parseSizeDef(value)) ?? { px: 0, grow: 1 };
-            }
-        };
-
-        return this._cache(
-            "size/sizeFromSpec",
-            () => new FlexDimensions(handleSize("width"), handleSize("height"))
-        );
-    }
-
-    isVisible() {
-        return this.context.isViewVisible(this);
-    }
-
-    isVisibleInSpec() {
-        return this.spec.visible ?? true;
-    }
-
-    /**
-     * Returns the effective opacity of this view, e.g., view's opacity multiplied
-     * by opacities of its ancestors.
-     *
-     * TODO: This methods makes sense only in Unit and Layer views.
-     *
-     * @returns {number}
-     */
-    getEffectiveOpacity() {
-        return this.opacityFunction(this.parent?.getEffectiveOpacity() ?? 1.0);
-    }
-
-    getPathString() {
-        return [...this.getAncestors()]
-            .map((v) => v.name)
-            .reverse()
-            .join("/");
-    }
-
-    *getAncestors() {
-        // eslint-disable-next-line consistent-this
-        let view = /** @type {View} */ (this);
-        do {
-            yield view;
-            view = view.parent;
-        } while (view);
-    }
-
-    /**
-     * Handles a broadcast message that is intended for the whole view hierarchy.
-     *
-     * @param {BroadcastMessage} message
-     */
-    handleBroadcast(message) {
-        // TODO: message types should be constants
-        for (const handler of this._broadcastHandlers[message.type] || []) {
-            handler(message);
-        }
-    }
-
-    /**
-     *
-     * @param {string} type
-     * @param {function(BroadcastMessage):void} handler
-     */
-    _addBroadcastHandler(type, handler) {
-        let handlers = this._broadcastHandlers[type];
-        if (!handlers) {
-            handlers = [];
-            this._broadcastHandlers[type] = handlers;
-        }
-        handlers.push(handler);
-    }
-
-    /**
-     * Handles an interactionEvent
-     *
-     * @param {import("../utils/layout/rectangle").default} coords
-     *      Coordinates of the view
-     * @param {import("../utils/interactionEvent").default} event
-     * @param {boolean} capturing
-     */
-    handleInteractionEvent(coords, event, capturing) {
-        const listenersByType = capturing
-            ? this._capturingInteractionEventListeners
-            : this._nonCapturingInteractionEventListeners;
-        for (const listener of listenersByType[event.type] || []) {
-            listener(coords, event);
-        }
-    }
-
-    /**
-     * Add an "interaction" event listener that mimics DOM's event model inside
-     * the view hierarchy.
-     *
-     * This is intended for GenomeSpy's internal use. It allows the views to handle
-     * low level interactions such as dragging, wheeling, etc.
-     *
-     * @param {string} type
-     * @param {InteractionEventListener} listener
-     * @param {boolean} [useCapture]
-     */
-    addInteractionEventListener(type, listener, useCapture) {
-        const listenersByType = useCapture
-            ? this._capturingInteractionEventListeners
-            : this._nonCapturingInteractionEventListeners;
-        let listeners = listenersByType[type];
-        if (!listeners) {
-            listeners = [];
-            listenersByType[type] = listeners;
-        }
-
-        listeners.push(listener);
-    }
-
-    /**
-     * Visits child views in depth-first order. Visitor's return value
-     * controls the traversal.
-     *
-     * @param {Visitor} visitor
-     * @returns {VisitResult}
-     *
-     */
-    visit(visitor) {
-        try {
-            const result = visitor(this);
-
-            if (visitor.postOrder) {
-                visitor.postOrder(this);
-            }
-
-            if (result !== VISIT_STOP) {
-                return result;
-            }
-        } catch (e) {
-            // Augment the exception with the view
-            e.view = this;
-            throw e;
-        }
-    }
-
-    /**
-     * Called after all scales in the view hierarchy have been resolved.
-     */
-    onScalesResolved() {
-        // Only set the opacity function once. The idea is to allow custom functions
-        // and prevent accidental overwrites.
-        if (
-            !this.opacityFunction ||
-            this.opacityFunction === defaultOpacityFunction
-        ) {
-            this.opacityFunction = createViewOpacityFunction(this);
-        }
-    }
-
-    /**
-     * ViewRenderingContext calls this method once for each view during each rendering
-     * pass. The order is depth first, pre order.
-     */
-    onBeforeRender() {
-        //
-    }
-
-    /**
-     * Recursively traverses the view hierarchy, computes the view coordinates,
-     * and coordinates the mark rendering.
-     *
-     * @param {import("./renderingContext/viewRenderingContext").default} context
-     * @param {import("../utils/layout/rectangle").default} coords The coordinate rectangle that the parent computed
-     *      for the child that is being visited.
-     * @param {RenderingOptions} [options]
-     */
-    render(context, coords, options = {}) {
-        // override
-    }
-
-    /**
-     * Returns the encodings specified in this view combined with the inherited
-     * encodings. However, this does not contain any defaults or inferred/adjusted/fixed
-     * encodings. Those are available in Mark's encoding property.
-     *
-     * @return {import("../spec/channel").Encoding}
-     */
-    getEncoding() {
-        const pe =
-            this.parent && !this.blockEncodingInheritance
-                ? this.parent.getEncoding()
-                : {};
-        const te = this.spec.encoding || {};
-
-        /** @type {import("../spec/channel").Encoding} */
-        const combined = {
-            ...pe,
-            ...te,
-        };
-
-        for (const [channel, channelDef] of Object.entries(combined)) {
-            if (channelDef === null) {
-                // Prevent propagation
-                delete combined[channel];
-            }
-        }
-
-        return combined;
-    }
-
-    /**
-     * @param {View} [whoIsAsking] Passed to the immediate parent. Allows for
-     *      selectively breaking the inheritance.
-     * @return {function(object):any}
-     */
-    getFacetAccessor(whoIsAsking) {
-        if (this.parent) {
-            return this.parent.getFacetAccessor(this);
-        }
-    }
-
-    /**
-     * Returns the fields that should be used for partitioning the data for facets.
-     *
-     * @param {View} [whoIsAsking]
-     * @returns {string[]}
-     */
-    getFacetFields(whoIsAsking) {
-        const sampleFieldDef = this.getEncoding().sample;
-        if (isFieldDef(sampleFieldDef)) {
-            return [sampleFieldDef.field];
-        } else {
-            return this.parent?.getFacetFields(this);
-        }
-    }
-
-    /**
-     * Returns a texture that has a mapping for the sample locations. This is implemented
-     * only in the SampleView of GenomeSpy App.
-     *
-     * @returns {WebGLTexture}
-     */
-    getSampleFacetTexture() {
-        return undefined;
-    }
-
-    /**
-     *
-     * @param {Channel} channel
-     * @param {ResolutionTarget} type
-     * @returns {ScaleResolution | AxisResolution}
-     */
-    _getResolution(channel, type) {
-        channel = getPrimaryChannel(channel);
-
-        /** @type {import("./view").default } */
-        // eslint-disable-next-line consistent-this
-        let view = this;
-        do {
-            const resolution = view.resolutions[type][channel];
-            if (resolution) {
-                return resolution;
-            }
-            view = view.parent;
-        } while (view);
-    }
-
-    /**
-     * @param {Channel} channel
-     */
-    getScaleResolution(channel) {
-        return /** @type {ScaleResolution} */ (
-            this._getResolution(channel, "scale")
-        );
-    }
-
-    /**
-     * @param {Channel} channel
-     */
-    getAxisResolution(channel) {
-        return /** @type {AxisResolution} */ (
-            this._getResolution(channel, "axis")
-        );
-    }
-
-    /**
-     * @returns {string}
-     */
-    getBaseUrl() {
-        return appendToBaseUrl(
-            () => this.parent?.getBaseUrl(),
-            this.spec.baseUrl
-        );
-    }
-
-    /**
-     * @returns {import("../data/sources/dataSource").default}
-     */
-    getDynamicDataSource() {
-        throw new Error("The view does not provide dynamic data!");
-    }
-
-    /**
-     * Returns `true` if this view and its children supports picking.
-     */
-    isPickingSupported() {
-        return true;
-    }
-
-    getTitleText() {
-        const title = this.spec.title;
-        if (title) {
-            return isString(title) ? title : title.text;
-        }
-    }
-
-    /**
-     * @param {any} key string
-     * @param {function(key?):T} callable A function that produces a value to be cached
-     * @returns {T}
-     * @template T
-     */
-    _cache(key, callable) {
-        return getCachedOrCall(this, key, callable);
-    }
-
-    /**
-     *
-     * @param {string} key
-     * @param {"self" | "progeny" | "ancestors"} [direction]
-     */
-    _invalidateCacheByPrefix(key, direction = "self") {
-        switch (direction) {
-            case "self":
-                invalidatePrefix(this, key);
-                break;
-            case "ancestors":
-                for (const view of this.getAncestors()) {
-                    invalidatePrefix(view, key);
-                }
-                break;
-            case "progeny":
-                this.visit((view) => invalidatePrefix(view, key));
-                break;
-            default:
-        }
-    }
-
-    invalidateSizeCache() {
-        this._invalidateCacheByPrefix("size/", "ancestors");
-    }
-
-    /**
-     * Broadcasts a message to views that include the given (x, y) point.
-     * This is mainly intended for mouse events.
-     *
-     * @param {import("../utils/interactionEvent").default} event
-     */
-    propagateInteractionEvent(event) {
-        // Subclasses must implement proper handling
-    }
-}
-
-/**
- *
- * @param {any} opacity
- * @returns {opacity is import("../spec/view").DynamicOpacity}
- */
-function isDynamicOpacity(opacity) {
-    return "unitsPerPixel" in opacity;
-}
-
-/**
- *
- * @param {View} view
- * @returns {function(number):number}
- */
-function createViewOpacityFunction(view) {
-    const opacityDef = view.spec.opacity;
-
-    if (opacityDef !== undefined) {
-        if (isNumber(opacityDef)) {
-            return (parentOpacity) => parentOpacity * opacityDef;
-        } else if (isDynamicOpacity(opacityDef)) {
-            /** @type {function(Channel):any} */
-            const getScale = (channel) => {
-                const scale = view.getScaleResolution(channel)?.getScale();
-                // Only works on linear scales
-                if (["linear", "index", "locus"].includes(scale?.type)) {
-                    return scale;
-                }
-            };
-
-            const scale = opacityDef.channel
-                ? getScale(opacityDef.channel)
-                : getScale("x") || getScale("y");
-
-            if (!scale) {
-                throw new Error(
-                    "Cannot find a resolved quantitative scale for dynamic opacity!"
-                );
-            }
-
-            const interpolate = scaleLog()
-                .domain(opacityDef.unitsPerPixel)
-                .range(opacityDef.values)
-                .clamp(true);
-
-            return (parentOpacity) => {
-                const rangeSpan = 1000; //TODO: span(scale.range());
-                const unitsPerPixel = span(scale.domain()) / rangeSpan;
-
-                return interpolate(unitsPerPixel) * parentOpacity;
-            };
-        }
-    }
-    return (parentOpacity) => parentOpacity;
-}
-
-/**
- *
- * @param {any} size
- * @return {size is import("../spec/view").Step}
- */
-export const isStepSize = (size) => !!size?.step;