higlass 1.13.0 → 1.13.1

package/app/scripts/PixiTrack.js

@@ -1,3 +1,4 @@
+// @ts-check
 import { formatPrefix, precisionPrefix } from 'd3-format';
 import slugid from 'slugid';
 
@@ -7,14 +8,18 @@ import { colorToHex } from './utils';
 
 // Configs
 import { GLOBALS } from './configs';
+import {
+  isResolutionsTilesetInfo,
+  isLegacyTilesetInfo,
+} from './utils/type-guards';
 
 /**
  * Format a resolution relative to the highest possible resolution.
  *
  * The highest possible resolution determines the granularity of the
  * formatting (e.g. 20K vs 20000)
- * @param {int} resolution The resolution to format (e.g. 30000)
- * @param {int} maxResolutionSize The maximum possible resolution (e.g. 1000)
+ * @param {number} resolution The resolution to format (e.g. 30000)
+ * @param {number} maxResolutionSize The maximum possible resolution (e.g. 1000)
  *
  * @returns {string} A formatted resolution string (e.g. "30K")
  */
@@ -30,11 +35,10 @@ function formatResolutionText(resolution, maxResolutionSize) {
  * Get a text description of a resolution based on a zoom level
  * and a list of resolutions
  *
- * @param {list} resolutions: A list of resolutions (e.g. [1000,2000,3000])
- * @param {int} zoomLevel: The current zoom level (e.g. 4)
+ * @param {Array<number>} resolutions: A list of resolutions (e.g. [1000,2000,3000])
+ * @param {number} zoomLevel: The current zoom level (e.g. 4)
  *
- * @returns {string} A formatted string representation of the zoom level
- *   (e.g. "30K")
+ * @returns {string} A formatted string representation of the zoom level (e.g. "30K")
  */
 function getResolutionBasedResolutionText(resolutions, zoomLevel) {
   const sortedResolutions = resolutions.map((x) => +x).sort((a, b) => b - a);
@@ -46,18 +50,14 @@ function getResolutionBasedResolutionText(resolutions, zoomLevel) {
 
 /**
  * Get a text description of the resolution based on the zoom level
- * max width of the dataset, the bins per dimension and the maximum
- * zoom.
+ * max width of the dataset, the bins per dimension and the maximum zoom.
  *
- * @param {int} zoomLevel The current zoomLevel (e.g. 0)
- * @param {int} max_width The max width
- *   (e.g. 2 ** maxZoom * highestResolution * binsPerDimension)
- * @param {int} bins_per_dimension The number of bins per tile dimension
- *   (e.g. 256)
- * @param {int} maxZoom The maximum zoom level for this tileset
+ * @param {number} zoomLevel - The current zoomLevel (e.g. 0)
+ * @param {number} maxWidth - The max width (e.g. 2 ** maxZoom * highestResolution * binsPerDimension)
+ * @param {number} binsPerDimension - The number of bins per tile dimension (e.g. 256)
+ * @param {number} maxZoom - The maximum zoom level for this tileset
  *
- * @returns {string} A formatted string representation of the zoom level
- *   (e.g. "30K")
+ * @returns {string} A formatted string representation of the zoom level (e.g. "30K")
  */
 function getWidthBasedResolutionText(
   zoomLevel,
@@ -84,14 +84,35 @@ function getWidthBasedResolutionText(
   return '';
 }
 
+/**
+ * @typedef PixiTrackOptions
+ * @property {string} labelPosition - If the label is to be drawn, where should it be drawn?
+ * @property {string} labelText - What should be drawn in the label.
+ * If either labelPosition or labelText are false, no label will be drawn.
+ * @property {number=} trackBorderWidth
+ * @property {string=} trackBorderColor
+ * @property {string=} backgroundColor
+ * @property {string=} labelColor
+ * @property {string=} lineStrokeColor
+ * @property {string=} barFillColor
+ * @property {string=} name
+ * @property {number=} labelTextOpacity
+ * @property {string=} labelBackgroundColor
+ * @property {number=} labelLeftMargin
+ * @property {number=} labelRightMargin
+ * @property {number=} labelTopMargin
+ * @property {number=} labelBottomMargin
+ * @property {number=} labelBackgroundOpacity
+ * @property {boolean=} labelShowAssembly
+ * @property {boolean=} labelShowResolution
+ * @property {string=} dataTransform
+ */
+
+/** @extends {Track<PixiTrackOptions>} */
 class PixiTrack extends Track {
   /**
-   * @param scene: A PIXI.js scene to draw everything to.
-   * @param options: A set of options that describe how this track is rendered.
-    this.pMain.position.x = this.position[0];
-   *          - labelPosition: If the label is to be drawn, where should it be drawn?
-   *          - labelText: What should be drawn in the label. If either labelPosition
-   *                  or labelText are false, no label will be drawn.
+   * @param {import('./Track').ExtendedTrackContext<{ scene: import('pixi.js').Container}>} context - Includes the PIXI.js scene to draw to.
+   * @param {PixiTrackOptions} options - The options for this track.
    */
   constructor(context, options) {
     super(context, options);
@@ -99,27 +120,39 @@ class PixiTrack extends Track {
 
     // the PIXI drawing areas
     // pMain will have transforms applied to it as users scroll to and fro
+    /** @type {import('pixi.js').Container} */
     this.scene = scene;
 
     // this option is used to temporarily prevent drawing so that
     // updates can be batched (e.g. zoomed and options changed)
+    /** @type {boolean} */
     this.delayDrawing = false;
 
+    /** @type {import('pixi.js').Graphics} */
     this.pBase = new GLOBALS.PIXI.Graphics();
-
+    /** @type {import('pixi.js').Graphics} */
     this.pMasked = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pMask = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pMain = new GLOBALS.PIXI.Graphics();
 
     // for drawing the track label (often its name)
+    /** @type {import('pixi.js').Graphics} */
     this.pBorder = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pBackground = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pForeground = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pLabel = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pMobile = new GLOBALS.PIXI.Graphics();
+    /** @type {import('pixi.js').Graphics} */
     this.pAxis = new GLOBALS.PIXI.Graphics();
 
     // for drawing information on mouseover events
+    /** @type {import('pixi.js').Graphics} */
     this.pMouseOver = new GLOBALS.PIXI.Graphics();
 
     this.scene.addChild(this.pBase);
@@ -138,20 +171,28 @@ class PixiTrack extends Track {
 
     this.pMasked.mask = this.pMask;
 
+    /** @type {string} */
     this.prevOptions = '';
 
     // pMobile will be a graphics object that is moved around
     // tracks that wish to use it will replace this.pMain with it
 
+    /** @type {PixiTrackOptions} */
     this.options = Object.assign(this.options, options);
 
+    /** @type {string} */
     const labelTextText = this.getName();
-
+    /** @type {string} */
     this.labelTextFontFamily = 'Arial';
+    /** @type {number} */
     this.labelTextFontSize = 12;
-    // Used to avoid label/colormap clashes
+    /**
+     * Used to avoid label/colormap clashes
+     * @type {number}
+     */
     this.labelXOffset = 0;
 
+    /** @type {import('pixi.js').Text} */
     this.labelText = new GLOBALS.PIXI.Text(labelTextText, {
       fontSize: `${this.labelTextFontSize}px`,
       fontFamily: this.labelTextFontFamily,
@@ -159,6 +200,7 @@ class PixiTrack extends Track {
     });
     this.pLabel.addChild(this.labelText);
 
+    /** @type {import('pixi.js').Text} */
     this.errorText = new GLOBALS.PIXI.Text('', {
       fontSize: '12px',
       fontFamily: 'Arial',
@@ -167,12 +209,19 @@ class PixiTrack extends Track {
     this.errorText.anchor.x = 0.5;
     this.errorText.anchor.y = 0.5;
     this.pLabel.addChild(this.errorText);
+    /** @type {string} */
+    this.errorTextText = '';
+    /** @type {boolean} */
+    this.flipText = false;
+    /** @type {import('./types').TilesetInfo | undefined} */
+    this.tilesetInfo = undefined;
   }
 
   setLabelText() {
     // will be drawn in draw() anyway
   }
 
+  /** @param {[number, number]} newPosition */
   setPosition(newPosition) {
     this.position = newPosition;
 
@@ -183,6 +232,7 @@ class PixiTrack extends Track {
     this.setForeground();
   }
 
+  /** @param {[number, number]} newDimensions */
   setDimensions(newDimensions) {
     super.setDimensions(newDimensions);
 
@@ -193,6 +243,10 @@ class PixiTrack extends Track {
     this.setForeground();
   }
 
+  /**
+   * @param {[number, number]} position
+   * @param {[number, number]} dimensions
+   */
   setMask(position, dimensions) {
     this.pMask.clear();
     this.pMask.beginFill();
@@ -320,6 +374,8 @@ class PixiTrack extends Track {
 
     graphics.clear();
 
+    // TODO(Trevor): I don't think this can ever be true. Options are always defined,
+    // and options.labelPosition can't be defined if this.options is undefined.
     if (
       !this.options ||
       !this.options.labelPosition ||
@@ -330,11 +386,11 @@ class PixiTrack extends Track {
       return;
     }
 
+    const { labelBackgroundColor = 'white', labelBackgroundOpacity = 0.5 } =
+      this.options;
     graphics.beginFill(
-      colorToHex(this.options.labelBackgroundColor || 'white'),
-      +this.options.labelBackgroundOpacity >= 0
-        ? +this.options.labelBackgroundOpacity
-        : 0.5,
+      colorToHex(labelBackgroundColor),
+      +labelBackgroundOpacity,
     );
 
     const fontColor = colorToHex(this.getLabelColor());
@@ -356,8 +412,7 @@ class PixiTrack extends Track {
 
     if (
       this.options.labelShowResolution &&
-      this.tilesetInfo &&
-      this.tilesetInfo.max_width &&
+      isLegacyTilesetInfo(this.tilesetInfo) &&
       this.tilesetInfo.bins_per_dimension
     ) {
       const formattedResolution = getWidthBasedResolutionText(
@@ -370,8 +425,7 @@ class PixiTrack extends Track {
       labelTextText += `\n[Current data resolution: ${formattedResolution}]`;
     } else if (
       this.options.labelShowResolution &&
-      this.tilesetInfo &&
-      this.tilesetInfo.resolutions
+      isResolutionsTilesetInfo(this.tilesetInfo)
     ) {
       const formattedResolution = getResolutionBasedResolutionText(
         this.tilesetInfo.resolutions,
@@ -418,10 +472,12 @@ class PixiTrack extends Track {
       this.labelText.scale.x = -1;
     }
 
-    const labelLeftMargin = +this.options.labelLeftMargin || 0;
-    const labelRightMargin = +this.options.labelRightMargin || 0;
-    const labelTopMargin = +this.options.labelTopMargin || 0;
-    const labelBottomMargin = +this.options.labelBottomMargin || 0;
+    const {
+      labelLeftMargin = 0,
+      labelRightMargin = 0,
+      labelTopMargin = 0,
+      labelBottomMargin = 0,
+    } = this.options;
 
     if (this.options.labelPosition === 'topLeft') {
       this.labelText.x = this.position[0] + labelLeftMargin + this.labelXOffset;
@@ -575,6 +631,7 @@ class PixiTrack extends Track {
     }
   }
 
+  /** @param {PixiTrackOptions} options */
   rerender(options) {
     this.options = options;
 
@@ -598,8 +655,8 @@ class PixiTrack extends Track {
   /**
    * Export an SVG representation of this track
    *
-   * @returns {Array} The two returned DOM nodes are both SVG
-   * elements [base,track]. Base is a parent which contains track as a
+   * @returns {[HTMLElement, HTMLElement]} The two returned DOM nodes are both SVG
+   * elements [base, track]. Base is a parent which contains track as a
    * child. Track is clipped with a clipping rectangle contained in base.
    *
    */
@@ -693,15 +750,15 @@ class PixiTrack extends Track {
         this.options.labelPosition === 'topRight'
       ) {
         const dy = ddy + (i + 1) * (this.labelTextFontSize + 2);
-        text.setAttribute('dy', dy);
+        text.setAttribute('dy', String(dy));
       } else if (
         this.options.labelPosition === 'bottomLeft' ||
         this.options.labelPosition === 'bottomRight'
       ) {
-        text.setAttribute('dy', ddy + i * (this.labelTextFontSize + 2));
+        text.setAttribute('dy', String(ddy + i * (this.labelTextFontSize + 2)));
       }
 
-      text.setAttribute('fill', this.options.labelColor);
+      text.setAttribute('fill', this.options.labelColor ?? '');
 
       if (this.labelText.anchor.x === 0.5) {
         text.setAttribute('text-anchor', 'middle');
@@ -721,6 +778,13 @@ class PixiTrack extends Track {
     // contents
     return [gBase, gTrack];
   }
+
+  /**
+   * @returns {number}
+   */
+  calculateZoomLevel() {
+    throw new Error('Must be implemented by subclass');
+  }
 }
 
 export default PixiTrack;

package/app/scripts/Track.js

@@ -1,41 +1,62 @@
+// @ts-check
 import { scaleLinear } from 'd3-scale';
 import { fake as fakePubSub } from './hocs/with-pub-sub';
 
 // Services
 import { isWithin } from './utils';
 
+/**
+ * @typedef TrackContext
+ * @property {string} id - The track ID.
+ * @property {import('pub-sub-es').PubSub & { __fake__?: boolean }} [pubSub] - The pub-sub channel.
+ * @property {() => import('./types').Theme} [getTheme] - A function that returns the current theme.
+ */
+
+/**
+ * @template T
+ * @typedef {T & TrackContext} ExtendedTrackContext
+ */
+
+/** @template Options */
 class Track {
-  constructor(context) {
+  /**
+   * @param {TrackContext} context
+   * @param {Options} options
+   */
+  constructor(context, options) {
     this.context = context;
 
     const { id, pubSub, getTheme } = context;
-    if (pubSub) {
-      this.pubSub = pubSub;
-    } else {
-      this.pubSub = fakePubSub;
-    }
+    /** @type {import('pub-sub-es').PubSub} */
+    this.pubSub = pubSub ?? fakePubSub;
 
+    /** @type {string} */
     this.id = id;
+    /** @type {import('./types').Scale} */
     this._xScale = scaleLinear();
+    /** @type {import('./types').Scale} */
     this._yScale = scaleLinear();
 
     // reference scales used for tracks that can translate and scale
     // their graphics
     // They will draw their graphics on the reference scales and then translate
     // and pan them as needed
+    /** @type {import('./types').Scale} */
     this._refXScale = scaleLinear();
+    /** @type {import('./types').Scale} */
     this._refYScale = scaleLinear();
 
+    /** @type {[number, number]} */
     this.position = [0, 0];
+    /** @type {[number, number]} */
     this.dimensions = [1, 1];
-    this.options = {};
+    /** @type {Options} */
+    this.options = options;
+    /** @type {Array<import('pub-sub-es').Subscription>} */
     this.pubSubs = [];
 
-    if (getTheme) {
-      this.getTheme = getTheme;
-    } else {
-      this.getTheme = () => {};
-    }
+    /** @type {() => (import('./types').Theme | undefined)} */
+    this.getTheme = getTheme ?? (() => undefined);
 
     this.pubSubs.push(
       this.pubSub.subscribe(
@@ -43,14 +64,16 @@ class Track {
         this.defaultMouseMoveHandler.bind(this),
       ),
     );
+
+    this.isLeftModified = false;
   }
 
   /**
    * Check if a 2d location (x, y) is within the bounds of this track.
    *
-   * @param {Number}  x  X position to be tested.
-   * @param {Number}  y  Y position to be tested.
-   * @return {Boolean}  If `true` location is within the track.
+   * @param {number} x - X position to be tested.
+   * @param {number} y - Y position to be tested.
+   * @return {boolean}  If `true` location is within the track.
    */
   isWithin(x, y) {
     let xx = x;
@@ -75,14 +98,26 @@ class Track {
     );
   }
 
+  /**
+   * Get a property from the track.
+   * @template {keyof this} T
+   * @param {T} prop - The property to get.
+   * @return {() => this[T]}
+   */
   getProp(prop) {
     return () => this[prop];
   }
 
   getData() {}
 
-  /** Capture click events. x and y are relative to the track
-   * position */
+  /**
+   * Capture click events. x and y are relative to the track position
+   * @template T
+   * @param {number} x - X position of the click event.
+   * @param {number} y - Y position of the click event.
+   * @param {T} evt - The event.
+   * @return {{ type: 'generic', event: T, payload: null }}
+   */
   click(x, y, evt) {
     return {
       type: 'generic',
@@ -94,10 +129,12 @@ class Track {
   /** There was a click event outside the track * */
   clickOutside() {}
 
+  /** @returns {[number, number]} */
   getDimensions() {
     return this.dimensions;
   }
 
+  /** @param {[number, number]} newDimensions */
   setDimensions(newDimensions) {
     this.dimensions = newDimensions;
 
@@ -105,82 +142,136 @@ class Track {
     this._yScale.range([0, this.dimensions[1]]);
   }
 
+  /**
+   * @overload
+   * @return {import('./types').Scale}
+   */
+  /**
+   * @overload
+   * @param {import('./types').Scale} scale
+   * @return {this}
+   */
   /**
    * Either get or set the reference xScale
+   *
+   * @param {import('./types').Scale=} scale
+   * @return {import('./types').Scale | this}
    */
-  refXScale(_) {
-    if (!arguments.length) return this._refXScale;
-
-    this._refXScale = _;
-
+  refXScale(scale) {
+    if (!scale) return this._refXScale;
+    this._refXScale = scale;
     return this;
   }
 
+  /**
+   * @overload
+   * @return {import('./types').Scale}
+   */
+  /**
+   * @overload
+   * @param {import('./types').Scale} scale
+   * @return {this}
+   */
   /**
    * Either get or set the reference yScale
+   *
+   * @param {import('./types').Scale=} scale
+   * @return {import('./types').Scale | this}
    */
-  refYScale(_) {
-    if (!arguments.length) return this._refYScale;
-
-    this._refYScale = _;
-
+  refYScale(scale) {
+    if (!scale) return this._refYScale;
+    this._refYScale = scale;
     return this;
   }
 
+  /**
+   * @overload
+   * @return {import('./types').Scale}
+   */
+  /**
+   * @overload
+   * @param {import('./types').Scale} scale
+   * @return {this}
+   */
   /**
    * Either get or set the xScale
+   *
+   * @param {import('./types').Scale=} scale
+   * @return {import('./types').Scale | this}
    */
-  xScale(_) {
-    if (!arguments.length) return this._xScale;
-
-    this._xScale = _;
-
+  xScale(scale) {
+    if (!scale) return this._xScale;
+    this._xScale = scale;
     return this;
   }
 
+  /**
+   * @overload
+   * @return {import('./types').Scale}
+   */
+  /**
+   * @overload
+   * @param {import('./types').Scale} scale
+   * @return {this}
+   */
   /**
    * Either get or set the yScale
+   *
+   * @param {import('./types').Scale=} scale
+   * @return {import('./types').Scale | this}
    */
-  yScale(_) {
-    if (!arguments.length) {
-      return this._yScale;
-    }
-
-    this._yScale = _;
-
+  yScale(scale) {
+    if (!scale) return this._yScale;
+    this._yScale = scale;
     return this;
   }
 
+  /**
+   * @param {import('./types').Scale} newXScale
+   * @param {import('./types').Scale} newYScale
+   * @returns {void}
+   */
   zoomed(newXScale, newYScale) {
     this.xScale(newXScale);
     this.yScale(newYScale);
   }
 
+  /**
+   * @param {import('./types').Scale} refXScale
+   * @param {import('./types').Scale} refYScale
+   * @returns {void}
+   */
   refScalesChanged(refXScale, refYScale) {
     this._refXScale = refXScale;
     this._refYScale = refYScale;
   }
 
+  /** @returns {void} */
   draw() {}
 
+  /** @returns {[number, number]} */
   getPosition() {
     return this.position;
   }
 
+  /**
+   * @param {[number, number]} newPosition
+   * @returns {void}
+   */
   setPosition(newPosition) {
     this.position = newPosition;
   }
 
-  /*
+  /**
    * A blank handler for MouseMove / Zoom events. Should be overriden
    * by individual tracks to provide
    *
-   * @param {obj} evt:
-   *
-   * @returns nothing
+   * @param {{}} evt
+   * @returns {void}
    */
   defaultMouseMoveHandler(evt) {}
 
+  /** @returns {void} */
   remove() {
     // Clear all pubSub subscriptions
     this.pubSubs.forEach((subscription) =>
@@ -189,19 +280,36 @@ class Track {
     this.pubSubs = [];
   }
 
-  rerender() {}
+  /**
+   * @param {Options} options
+   * @returns {void}
+   */
+  rerender(options) {}
 
-  /*
+  /**
    * This function is for seeing whether this track should respond
    * to events at this mouse position. The difference to `isWithin()` is that it
    * can be overwritten if a track is inactive for example.
+   *
+   * @param {number} x - X position to be tested.
+   * @param {number} y - Y position to be tested.
+   * @returns {boolean}
    */
   respondsToPosition(x, y) {
     return this.isWithin(x, y);
   }
 
+  /**
+   * @param {number} trackY
+   * @param {number} kMultiplier
+   * @returns {void}
+   */
   zoomedY(trackY, kMultiplier) {}
 
+  /**
+   * @param {number} dY
+   * @returns {void}
+   */
   movedY(dY) {}
 }