@genome-spy/core 0.43.3 → 0.44.0

package/dist/src/paramBroker.js

@@ -12,6 +12,8 @@ import createFunction from "./utils/expression.js";
  * - Calling observers when a parameter changes
  * - Somehow saving parameter "state" (in bookmarks)
  * - Maybe something else
+ *
+ * @typedef {import("./utils/expression.js").ExpressionFunction & { addListener: (listener: () => void) => void, invalidate: () => void}} ExprRefFunction
  */
 export default class ParamBroker {
     /** @type {Map<string, any>} */
@@ -72,7 +74,7 @@ export default class ParamBroker {
      * @param {string} expr
      */
     createExpression(expr) {
-        /** @type {import("./utils/expression.js").ExpressionFunction & { addListener: (listener: () => void) => void}} */
+        /** @type {ExprRefFunction} */
         const fn = /** @type {any} */ (createFunction(expr, this.#proxy));
 
         for (const g of fn.globals) {
@@ -83,6 +85,9 @@ export default class ParamBroker {
             }
         }
 
+        // Keep track of them so that they can be detached later
+        const myListeners = new Set();
+
         /**
          *
          * @param {() => void} listener
@@ -92,10 +97,21 @@ export default class ParamBroker {
                 const listeners = this.#paramListeners.get(g) ?? new Set();
                 this.#paramListeners.set(g, listeners);
                 listeners.add(listener);
+                myListeners.add(listener);
             }
         };
 
-        // TODO: remove listener
+        /**
+         * Detach listeners. This must be called if the expression is no longer used.
+         */
+        fn.invalidate = () => {
+            for (const g of fn.globals) {
+                const listeners = this.#paramListeners.get(g);
+                for (const listener of myListeners) {
+                    listeners.delete(listener);
+                }
+            }
+        };
 
         return fn;
     }

package/dist/src/spec/channel.d.ts

@@ -8,11 +8,12 @@
  * BSD-3-Clause License: https://github.com/vega/vega-lite/blob/master/LICENSE
  */
 
+import { ExprRef } from "./parameter.js";
 import { Scale } from "./scale.js";
 import { GenomeAxis } from "./axis.js";
 
 export type Scalar = string | number | boolean;
-export type Value = Scalar | null;
+export type Value = Scalar | ExprRef | null;
 
 export type FieldName = string;
 export type Field = FieldName;
@@ -149,7 +150,7 @@ export interface ValueDefBase<V extends Value = Scalar> {
     /**
      * A constant value in visual domain (e.g., `"red"` / `"#0099ff"`, values between `0` to `1` for opacity).
      */
-    value: V;
+    value: V | ExprRef;
 }
 
 export type ValueDef<V extends Value = Scalar> = ValueDefBase<V> & TitleMixins;
@@ -158,7 +159,7 @@ export interface DatumDefBase {
     /**
      * A constant value in data domain.
      */
-    datum?: Scalar;
+    datum?: Scalar | ExprRef;
 }
 
 export type DatumDef = DatumDefBase & TitleMixins;

package/dist/src/spec/mark.d.ts

@@ -1,35 +1,27 @@
 import { Scalar } from "./channel.js";
+import { ExprRef } from "./parameter.js";
 import { Align, Baseline, FontStyle, FontWeight } from "./font.js";
 import { Tooltip } from "./tooltip.js";
 
-// TODO: This may not be the best place for this type.
-// Also, this is now similar to the ExprDef type in channel.d.ts
-export interface ExprRef {
-    /**
-     * The expression string.
-     */
-    expr: string;
-}
-
 export type MarkType = "rect" | "point" | "rule" | "text" | "link";
 
 export interface FillAndStrokeProps {
     /** The fill color */
-    fill?: string;
+    fill?: string | ExprRef;
 
     /** The fill opacity. Value between [0, 1]. */
-    fillOpacity?: number;
+    fillOpacity?: number | ExprRef;
 
     /** The stroke color */
-    stroke?: string;
+    stroke?: string | ExprRef;
 
     /** The stroke opacity. Value between [0, 1]. */
-    strokeOpacity?: number;
+    strokeOpacity?: number | ExprRef;
 }
 
 export interface SecondaryPositionProps {
-    x2?: number;
-    y2?: number;
+    x2?: number | ExprRef;
+    y2?: number | ExprRef;
 }
 
 export interface AngleProps {
@@ -38,7 +30,7 @@ export interface AngleProps {
      *
      * **Default value:** `0`
      */
-    angle?: number;
+    angle?: number | ExprRef;
 }
 
 /**
@@ -177,7 +169,7 @@ export interface TextProps
      *
      * **Default value:** `11`
      */
-    size?: number;
+    size?: number | ExprRef;
 
     /**
      * The font typeface. GenomeSpy uses [SDF](https://github.com/Chlumsky/msdfgen)
@@ -414,7 +406,7 @@ export interface LinkProps extends SecondaryPositionProps {
 }
 
 // TODO: Mark-specific configs
-export interface MarkConfig
+export interface MarkProps
     extends PointProps,
         RectProps,
         TextProps,
@@ -422,11 +414,11 @@ export interface MarkConfig
         LinkProps,
         FillAndStrokeProps {
     // Channels.
-    x?: number;
-    y?: number;
-    color?: string;
-    opacity?: number;
-    size?: number;
+    x?: number | ExprRef;
+    y?: number | ExprRef;
+    color?: string | ExprRef;
+    opacity?: number | ExprRef;
+    size?: number | ExprRef;
 
     /**
      * Whether the `color` represents the `fill` color (`true`) or the `stroke` color (`false`).
@@ -463,7 +455,7 @@ export interface MarkConfig
     /**
      * The stroke width in pixels.
      */
-    strokeWidth?: number;
+    strokeWidth?: number | ExprRef;
 
     /**
      * Minimum size for WebGL buffers (number of data items).
@@ -474,6 +466,6 @@ export interface MarkConfig
     minBufferSize?: number;
 }
 
-export interface MarkConfigAndType extends MarkConfig {
+export interface MarkConfigAndType extends MarkProps {
     type: MarkType;
 }

package/dist/src/spec/parameter.d.ts

@@ -0,0 +1,123 @@
+export interface ExprRef {
+    /**
+     * The expression string.
+     */
+    expr: string;
+}
+
+// Adapted from: https://github.com/vega/vega-lite/blob/main/src/parameter.ts
+
+export interface VariableParameter {
+    /**
+     * A unique name for the variable parameter. Parameter names should be valid
+     * JavaScript identifiers: they should contain only alphanumeric characters
+     * (or "$", or "_") and may not start with a digit. Reserved keywords that
+     * may not be used as parameter names are: "datum".
+     */
+    name: string;
+
+    /**
+     * The [initial value](http://vega.github.io/vega-lite/docs/value.html) of the parameter.
+     *
+     * __Default value:__ `undefined`
+     */
+    value?: any;
+
+    /**
+     * Binds the parameter to an external input element such as a slider, selection list or radio button group.
+     */
+    bind?: Binding;
+}
+
+// ----------------------------------------------------------------------------
+// Adapted from: https://github.com/vega/vega/blob/main/packages/vega-typings/types/spec/bind.d.ts
+
+export type Element = string;
+
+export interface BindBase {
+    /**
+     * An optional CSS selector string indicating the parent element to which
+     * the input element should be added. By default, all input elements are
+     * added within the parent container of the Vega view.
+     */
+    element?: Element;
+
+    /**
+     * If defined, delays event handling until the specified milliseconds have
+     * elapsed since the last event was fired.
+     */
+    debounce?: number;
+
+    /**
+     * By default, the parameter name is used to label input elements.
+     * This `name` property can be used instead to specify a custom
+     * label for the bound parameter.
+     */
+    name?: string;
+}
+
+export interface BindCheckbox extends BindBase {
+    input: "checkbox";
+}
+
+export interface BindRadioSelect extends BindBase {
+    input: "radio" | "select";
+    /**
+     * An array of options to select from.
+     */
+    options: any[];
+
+    /**
+     * An array of label strings to represent the `options` values. If
+     * unspecified, the `options` value will be coerced to a string and
+     * used as the label.
+     */
+    labels?: string[];
+}
+
+export interface BindRange extends BindBase {
+    input: "range";
+
+    /**
+     * Sets the minimum slider value. Defaults to the smaller of the signal value and `0`.
+     */
+    min?: number;
+
+    /**
+     * Sets the maximum slider value. Defaults to the larger of the signal value and `100`.
+     */
+    max?: number;
+
+    /**
+     * Sets the minimum slider increment. If undefined, the step size will be
+     * automatically determined based on the `min` and `max` values.
+     */
+    step?: number;
+}
+
+export interface BindDirect {
+    /**
+     * An input element that exposes a _value_ property and supports the
+     * [EventTarget](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget)
+     * interface, or a CSS selector string to such an element. When the element
+     * updates and dispatches an event, the _value_ property will be used as the
+     * new, bound signal value. When the signal updates independent of the
+     * element, the _value_ property will be set to the signal value and a new
+     * event will be dispatched on the element.
+     */
+    element: Element | EventTarget;
+
+    /**
+     * The event (default `"input"`) to listen for to track changes on the
+     * external element.
+     */
+    event?: string;
+
+    /**
+     * If defined, delays event handling until the specified milliseconds have
+     * elapsed since the last event was fired.
+     */
+    debounce?: number;
+}
+
+export type Binding = BindCheckbox | BindRadioSelect | BindRange;

package/dist/src/spec/root.d.ts

@@ -1,4 +1,5 @@
 import { GenomeConfig } from "./genome.js";
+import { VariableParameter } from "./parameter.js";
 import { ViewSpec } from "./view.js";
 
 interface RootConfig {
@@ -13,6 +14,14 @@ interface RootConfig {
      */
     background?: string;
 
+    /**
+     * Dynamic variables that parameterize a visualization.
+     *
+     * For now, these are only supported in mark properties, i.e.,
+     * they are not supported in the filter and formula transforms (yet).
+     */
+    params?: VariableParameter[];
+
     /**
      * https://vega.github.io/vega-lite/docs/data.html#datasets
      */

package/dist/src/spec/scale.d.ts

@@ -9,6 +9,7 @@
  */
 
 import { ChromosomalLocus } from "./genome.js";
+import { ExprRef } from "./parameter.js";
 
 export type ScaleType =
     | "null"
@@ -94,7 +95,7 @@ export interface Scale {
      *
      * 2) Any directly specified `range` for `x` and `y` channels will be ignored. Range can be customized via the view's corresponding [size](https://vega.github.io/vega-lite/docs/size.html) (`width` and `height`).
      */
-    range?: number[] | string[] | string;
+    range?: number[] | string[] | string | ExprRef[];
 
     // ordinal
 

package/dist/src/spec/view.d.ts

@@ -7,12 +7,12 @@ import {
     PrimaryPositionalChannel,
 } from "./channel.js";
 import {
-    ExprRef,
     FillAndStrokeProps,
     MarkConfigAndType,
     MarkType,
     RectProps,
 } from "./mark.js";
+import { ExprRef } from "./parameter.js";
 import { Title } from "./title.js";
 import { SampleSpec } from "./sampleView.js";
 

package/dist/src/types/scaleResolutionApi.d.ts

@@ -1,8 +1,9 @@
 import { ComplexDomain, NumericDomain } from "../spec/scale.js";
 import ScaleResolution from "../view/scaleResolution.js";
 
+export type ScaleResolutionEventType = "domain" | "range";
 export interface ScaleResolutionEvent {
-    type: "domain";
+    type: ScaleResolutionEventType;
 
     scaleResolution: ScaleResolution;
 }
@@ -13,10 +14,13 @@ export type ScaleResolutionListener = (event: ScaleResolutionEvent) => void;
  * A public API for ScaleResolution
  */
 export interface ScaleResolutionApi {
-    addEventListener(type: "domain", listener: ScaleResolutionListener): void;
+    addEventListener(
+        type: ScaleResolutionEventType,
+        listener: ScaleResolutionListener
+    ): void;
 
     removeEventListener(
-        type: "domain",
+        type: ScaleResolutionEventType,
         listener: ScaleResolutionListener
     ): void;
 

package/dist/src/utils/expression.d.ts

@@ -4,7 +4,7 @@
  * @prop { string[] } globals
  * @prop { string } code
  *
- * @typedef { ((x: object) => any) & ExpressionProps } ExpressionFunction
+ * @typedef { ((datum: object) => any) & ExpressionProps } ExpressionFunction
  *
  * @param {string} expr
  * @returns {ExpressionFunction}
@@ -15,5 +15,5 @@ export type ExpressionProps = {
     globals: string[];
     code: string;
 };
-export type ExpressionFunction = ((x: object) => any) & ExpressionProps;
+export type ExpressionFunction = ((datum: object) => any) & ExpressionProps;
 //# sourceMappingURL=expression.d.ts.map

package/dist/src/utils/expression.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../../src/utils/expression.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;GAUG;AACH,6CAHW,MAAM,sBACJ,kBAAkB,CAyB9B;;YAhCU,MAAM,EAAE;aACR,MAAM,EAAE;UACR,MAAM;;sCAEE,MAAM,KAAK,GAAG"}
+{"version":3,"file":"expression.d.ts","sourceRoot":"","sources":["../../../src/utils/expression.js"],"names":[],"mappings":"AAyDA;;;;;;;;;;GAUG;AACH,6CAHW,MAAM,sBACJ,kBAAkB,CAyB9B;;YAhCU,MAAM,EAAE;aACR,MAAM,EAAE;UACR,MAAM;;0CAEM,MAAM,KAAK,GAAG"}

package/dist/src/utils/expression.js

@@ -61,7 +61,7 @@ const cg = codegenExpression({
  * @prop { string[] } globals
  * @prop { string } code
  *
- * @typedef { ((x: object) => any) & ExpressionProps } ExpressionFunction
+ * @typedef { ((datum: object) => any) & ExpressionProps } ExpressionFunction
  *
  * @param {string} expr
  * @returns {ExpressionFunction}
@@ -79,8 +79,8 @@ export default function createFunction(expr, globalObject = {}) {
         ).bind(functionContext);
 
         /** @type { ExpressionFunction } */
-        const exprFunction = /** @param {object} x */ (x) =>
-            fn(x, globalObject);
+        const exprFunction = /** @param {object} datum */ (datum) =>
+            fn(datum, globalObject);
         exprFunction.fields = generatedCode.fields;
         exprFunction.globals = generatedCode.globals;
         exprFunction.code = generatedCode.code;

package/dist/src/view/axisView.js

@@ -459,7 +459,7 @@ export function createGenomeAxis(axisProps, type) {
      * @return {import("../spec/view.js").UnitSpec}
      */
     const createChromosomeLabels = () => {
-        /** @type {Partial<import("../spec/mark.js").MarkConfig>} */
+        /** @type {Partial<import("../spec/mark.js").MarkProps>} */
         let chromLabelMarkProps;
         switch (ap.orient) {
             case "top":
@@ -594,7 +594,7 @@ export function createGenomeAxis(axisProps, type) {
         if (axisProps.chromLabels) {
             chromLayerSpec.layer.push(createChromosomeLabels());
 
-            /** @type {import("../spec/mark.js").MarkConfig} */
+            /** @type {import("../spec/mark.js").MarkProps} */
             let labelMarkSpec;
 
             // TODO: Simplify the following mess
@@ -608,7 +608,7 @@ export function createGenomeAxis(axisProps, type) {
                                 /** @type {import("../spec/view.js").UnitSpec} */ view
                             ) => {
                                 labelMarkSpec =
-                                    /** @type {import("../spec/mark.js").MarkConfig} */ (
+                                    /** @type {import("../spec/mark.js").MarkProps} */ (
                                         view.mark
                                     );
                             }

package/dist/src/view/scaleResolution.d.ts

@@ -45,15 +45,15 @@ export default class ScaleResolution implements ScaleResolutionApi {
      * e.g., zoomed. The call is synchronous and happens before the views
      * are rendered.
      *
-     * @param {"domain"} type
+     * @param {ScaleResolutionEventType} type
      * @param {ScaleResolutionListener} listener function
      */
-    addEventListener(type: "domain", listener: import("../types/scaleResolutionApi.js").ScaleResolutionListener): void;
+    addEventListener(type: import("../types/scaleResolutionApi.js").ScaleResolutionEventType, listener: import("../types/scaleResolutionApi.js").ScaleResolutionListener): void;
     /**
-     * @param {"domain"} type
+     * @param {ScaleResolutionEventType} type
      * @param {ScaleResolutionListener} listener function
      */
-    removeEventListener(type: "domain", listener: import("../types/scaleResolutionApi.js").ScaleResolutionListener): void;
+    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
@@ -62,18 +62,6 @@ export default class ScaleResolution implements ScaleResolutionApi {
      * @param {ChannelWithScale} channel
      */
     pushUnitView(view: import("./unitView.js").default, channel: import("../spec/channel.js").ChannelWithScale): void;
-    /**
-     * Returns true if the domain has been defined explicitly, i.e. not extracted from the data.
-     */
-    isExplicitDomain(): boolean;
-    isDomainInitialized(): boolean;
-    /**
-     * Returns the merged scale properties supplemented with inferred properties
-     * and domain.
-     *
-     * @returns {import("../spec/scale.js").Scale}
-     */
-    getScaleProps(): import("../spec/scale.js").Scale;
     /**
      * Unions the configured domains of all participating views.
      *
@@ -91,9 +79,11 @@ export default class ScaleResolution implements ScaleResolutionApi {
      */
     reconfigure(): void;
     /**
-     * @returns {VegaScale}
+     * @returns {ScaleWithProps}
      */
-    getScale(): import("../types/encoder.js").VegaScale;
+    get scale(): import("../types/encoder.js").VegaScale & {
+        props: import("../spec/scale.js").Scale;
+    };
     getDomain(): any[];
     /**
      * @returns {NumericDomain | ComplexDomain}

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

@@ -1 +1 @@
-{"version":3,"file":"scaleResolution.d.ts","sourceRoot":"","sources":["../../../src/view/scaleResolution.js"],"names":[],"mappings":"AA20BA;;;;;;;;;;GAUG;AACH,6CAFW,OAAO,WAAW,EAAE,OAAO,GAAG,OAAO,WAAW,EAAE,OAAO,EAAE,QA4BrE;AAl0BD,0CAA2C;AAC3C,gCAAiC;AACjC,gCAAiC;AACjC,4BAA6B;AAC7B,4BAA6B;AAE7B;;;;GAIG;AACH;;;;;;;GAOG;AACH;IAyBI;;OAEG;IACH,2DASC;IARG,8CAAsB;IACtB,oDAAoD;IACpD,SADW,gBAAgB,EAAE,CACZ;IACjB,+DAA+D;IAC/D,MADW,MAAM,CACD;IAEhB,iEAAiE;IACjE,MADW,MAAM,CACI;IAGzB;;;;;;;OAOG;IACH,uBAHW,QAAQ,oFAQlB;IAED;;;OAGG;IACH,0BAHW,QAAQ,oFAQlB;IAWD;;;;;;OAMG;IACH,kHA0BC;IAED;;OAEG;IACH,4BAEC;IAED,+BAiBC;IAuBD;;;;;OAKG;IACH,iBAFa,OAAO,kBAAkB,EAAE,KAAK,CA+D5C;IAYD;;;;OAIG;IACH,qEAMC;IAED;;;;OAIG;IACH,+DAQC;IAED;;OAEG;IACH,oBAkCC;IAED;;OAEG;IACH,oDAmBC;IAED,mBAEC;IAED;;OAEG;IACH,oBAFa,mFAA6B,CAOzC;IAED;;;;OAIG;IACH,oBAKC;IAED;;OAEG;IACH,sBAGC;IAUD;;;;;;;OAOG;IACH,kBALW,MAAM,eACN,MAAM,OACN,MAAM,GACJ,OAAO,CAwEnB;IAED;;;;;;OAMG;IACH,eAJW,mFAA6B,aAC7B,OAAO,GAAG,MAAM,iBAgD1B;IAED;;;;OAIG;IACH,qBAcC;IAED;;;;;OAKG;IACH,uBAOC;IA8DD;;;OAGG;IACH,aAFa,OAAO,qBAAqB,EAAE,OAAO,CAajD;IAID;;;;;OAKG;IACH,uBAFW,MAAM,yDAUhB;IAED;;OAEG;IACH,iBAFW,MAAM,yDAKhB;IAED;;;OAGG;IACH,6EAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,mHAFa,MAAM,EAAE,CAOpB;;CA6BJ;wIA9rBY;IAAC,IAAI,EAAE,OAAO,eAAe,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAC"}
+{"version":3,"file":"scaleResolution.d.ts","sourceRoot":"","sources":["../../../src/view/scaleResolution.js"],"names":[],"mappings":"AAy6BA;;;;;;;;;;GAUG;AACH,6CAFW,OAAO,WAAW,EAAE,OAAO,GAAG,OAAO,WAAW,EAAE,OAAO,EAAE,QA4BrE;AAh6BD,0CAA2C;AAC3C,gCAAiC;AACjC,gCAAiC;AACjC,4BAA6B;AAC7B,4BAA6B;AAE7B;;;;GAIG;AACH;;;;;;;GAOG;AACH;IAyCI;;OAEG;IACH,2DASC;IARG,8CAAsB;IACtB,oDAAoD;IACpD,SADW,gBAAgB,EAAE,CACZ;IACjB,+DAA+D;IAC/D,MADW,MAAM,CACD;IAEhB,iEAAiE;IACjE,MADW,MAAM,CACI;IAOzB;;;;;;;OAOG;IACH,4KAEC;IAED;;;OAGG;IACH,+KAEC;IAcD;;;;;;OAMG;IACH,kHA0BC;IAkLD;;;;OAIG;IACH,qEAMC;IAED;;;;OAIG;IACH,+DAQC;IAED;;OAEG;IACH,oBAyCC;IAED;;OAEG;IACH;eA3WkC,OAAO,kBAAkB,EAAE,KAAK;MAkZjE;IAED,mBAEC;IAED;;OAEG;IACH,oBAFa,mFAA6B,CAOzC;IAED;;;;OAIG;IACH,oBAKC;IAED;;OAEG;IACH,sBAGC;IAUD;;;;;;;OAOG;IACH,kBALW,MAAM,eACN,MAAM,OACN,MAAM,GACJ,OAAO,CAwEnB;IAED;;;;;;OAMG;IACH,eAJW,mFAA6B,aAC7B,OAAO,GAAG,MAAM,iBAgD1B;IAED;;;;OAIG;IACH,qBAcC;IAED;;;;;OAKG;IACH,uBAOC;IA8DD;;;OAGG;IACH,aAFa,OAAO,qBAAqB,EAAE,OAAO,CAajD;IAID;;;;;OAKG;IACH,uBAFW,MAAM,yDAUhB;IAED;;OAEG;IACH,iBAFW,MAAM,yDAKhB;IAED;;;OAGG;IACH,6EAFa,MAAM,CAQlB;IAED;;;OAGG;IACH,mHAFa,MAAM,EAAE,CAOpB;;CA6BJ;wIA5xBY;IAAC,IAAI,EAAE,OAAO,eAAe,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,CAAC,CAAA;CAAC"}