Fix type/docs for VivViewer and VivView (and upstream users)

Author: ilan-gold

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### Changed
 
+- Fix `VivViewer` and `VivView` types.
+
 ## 0.9.4
 
 ### Added

src/viewers/PictureInPictureViewer.js

@@ -22,7 +22,7 @@ import { GLOBAL_SLIDER_DIMENSION_FIELDS } from '../constants';
  * @param {Object} props.overview Allows you to pass settings into the OverviewView: { scale, margin, position, minimumWidth, maximumWidth,
  * boundingBoxColor, boundingBoxOutlineWidth, viewportOutlineColor, viewportOutlineWidth}.  See http://viv.gehlenborglab.org/#overviewview for defaults.
  * @param {Boolean} props.overviewOn Whether or not to show the OverviewView.
- * @param {Object} [props.hoverHooks] Object including utility hooks - an object with key handleValue like { handleValue: (valueArray) => {}, handleCoordinate: (coordinate) => {} } where valueArray
+ * @param {import('./VivViewer').HoverHooks} [props.hoverHooks] Object including utility hooks - an object with key handleValue like { handleValue: (valueArray) => {}, handleCoordinate: (coordinate) => {} } where valueArray
  * has the pixel values for the image under the hover location and coordinate is the coordinate in the image from which the values are picked.
  * @param {Array} [props.viewStates] Array of objects like [{ target: [x, y, 0], zoom: -zoom, id: DETAIL_VIEW_ID }] for setting where the viewer looks (optional - this is inferred from height/width/loader
  * internally by default using getDefaultInitialViewState).
@@ -41,7 +41,7 @@ import { GLOBAL_SLIDER_DIMENSION_FIELDS } from '../constants';
  * @param {import('./VivViewer').ViewStateChange} [props.onViewStateChange] Callback that returns the deck.gl view state (https://deck.gl/docs/api-reference/core/deck#onviewstatechange).
  * @param {import('./VivViewer').Hover} [props.onHover] Callback that returns the picking info and the event (https://deck.gl/docs/api-reference/core/layer#onhover
  *     https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object)
- * @param {Array} [props.transitionFields] A string array indicating which fields require a transition: Default: ['t', 'z'].
+ * @param {Array} [props.transitionFields] A string array indicating which fields require a transition when making a new selection: Default: ['t', 'z'].
  */
 
 const PictureInPictureViewer = props => {
@@ -55,7 +55,7 @@ const PictureInPictureViewer = props => {
     overview,
     overviewOn,
     loaderSelection,
-    hoverHooks = {},
+    hoverHooks = { handleValue: () => {}, handleCoordinate: () => {} },
     height,
     width,
     isLensOn = false,

src/viewers/SideBySideViewer.js

@@ -23,6 +23,7 @@ import { GLOBAL_SLIDER_DIMENSION_FIELDS } from '../constants';
  * @param {number} [props.lensSelection] Numeric index of the channel to be focused on by the lens (default 0).
  * @param {Array} [props.lensBorderColor] RGB color of the border of the lens (default [255, 255, 255]).
  * @param {number} [props.lensBorderRadius] Percentage of the radius of the lens for a border (default 0.02).
+ * @param {number} [props.lensRadius] Pixel radius of the lens (default: 100).
  * @param {Array} [props.transparentColor] An RGB (0-255 range) color to be considered "transparent" if provided.
  * In other words, any fragment shader output equal transparentColor (before applying opacity) will have opacity 0.
  * This parameter only needs to be a truthy value when using colormaps because each colormap has its own transparent color that is calculated on the shader.

src/viewers/VivViewer.js

@@ -15,26 +15,56 @@ const areViewStatesEqual = (viewState, otherViewState) => {
 /**
  * @callback ViewStateChange
  * @param {Object} event
+ * @ignore
  */
 
 /**
  * @callback Hover
  * @param {Object} info
  * @param {Object} event
+ * @ignore
  */
 
 /**
- * This component handles rendering the various views within the DeckGL contenxt.
- * @param {Object} props
- * @param {Array} props.layerProps  Props for the layers in each view.
- * @param {Array} props.randomize Whether or not to randomize which view goes first (for dynamic rendering).
- * @param {VivView} props.views Various VivViews to render.
- * @param {Array} props.viewStates List of objects like [{ target: [x, y, 0], zoom: -zoom, id: 'left' }, { target: [x, y, 0], zoom: -zoom, id: 'right' }]
- * @param {ViewStateChange} [props.onViewStateChange] Callback that returns the deck.gl view state (https://deck.gl/docs/api-reference/core/deck#onviewstatechange).
- * @param {Hover} [props.onHover] Callback that returns the picking info and the event (https://deck.gl/docs/api-reference/core/layer#onhover
+ * @callback HandleValue
+ * @param {Array.<number>} valueArray pixel values for the image under the hover location
+ * @ignore
+ */
+
+/**
+ * @callback HandleCoordinate
+ * @param {Object} coordnate The coordinate in the image from which the values are picked.
+ * @ignore
+ */
+
+/**
+ * @typedef HoverHooks
+ * @type {object}
+ * @property {HandleValue} handleValue
+ * @property {HandleCoordinate} handleCoordinate
+ * @ignore
+ */
+
+/**
+ * @typedef LayerProps
+ * @type {object}
+ * @property {Array} layerProps  Props for the layers in each view.
+ * @property {boolean} [randomize] Whether or not to randomize which view goes first (for dynamic rendering of multiple linked views).
+ * @property {Array.<import('../views').VivView>} views Various `VivView`s to render.
+ * @property {Array.<object>} viewStates List of objects like [{ target: [x, y, 0], zoom: -zoom, id: 'left' }, { target: [x, y, 0], zoom: -zoom, id: 'right' }]
+ * @property {ViewStateChange} [onViewStateChange] Callback that returns the deck.gl view state (https://deck.gl/docs/api-reference/core/deck#onviewstatechange).
+ * @property {Hover} [onHover] Callback that returns the picking info and the event (https://deck.gl/docs/api-reference/core/layer#onhover
  *     https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object)
+ * @property {HoverHooks} [hoverHooks] Object including utility hooks - an object with key handleValue like { handleValue: (valueArray) => {}, handleCoordinate: (coordinate) => {} } where valueArray
+ * has the pixel values for the image under the hover location and coordinate is the coordinate in the image from which the values are picked.
  */
+
 export default class VivViewer extends PureComponent {
+  /**
+   * This component handles rendering the various views within the DeckGL contenxt.
+   * @param {LayerProps} props
+   */
+
   constructor(props) {
     super(props);
     this.state = {
@@ -56,8 +86,9 @@ export default class VivViewer extends PureComponent {
    * This prevents only the `draw` call of a layer from firing,
    * but not other layer lifecycle methods.  Nonetheless, it is
    * still useful.
-   * @param {Layer} layer Layer being updated.
-   * @param {Viewport} viewport Viewport being updated.
+   * @param {object} args
+   * @param {object} args.layer Layer being updated.
+   * @param {object} args.viewport Viewport being updated.
    * @returns {boolean} Whether or not this layer should be drawn in this viewport.
    */
   // eslint-disable-next-line class-methods-use-this

src/views/SideBySideView.js

@@ -9,17 +9,22 @@ import { getImageLayers, getVivId, makeBoundingBox } from './utils';
  * It is linked with its other views as controlled by `linkedIds`, `zoomLock`, and `panLock` parameters.
  * It takes the same arguments for its constructor as its base class VivView plus the following:
  * @param {Object} args
- * @param {Array} args.linkedIds Ids of the other views to which this could be locked via zoom/pan.
+ * @param {Array<String>} args.linkedIds Ids of the other views to which this could be locked via zoom/pan.
  * @param {Boolean} args.panLock Whether or not we lock pan.
  * @param {Boolean} args.zoomLock Whether or not we lock zoom.
- * @param {Array} args.viewportOutlineColor Outline color of the border (default [255, 255, 255])
- * @param {number} args.viewportOutlineWidth Default outline width (default 10)
+ * @param {Array=} args.viewportOutlineColor Outline color of the border (default [255, 255, 255])
+ * @param {number=} args.viewportOutlineWidth Default outline width (default 10)
+ * @param {number=} args.x X (top-left) location on the screen for the current view
+ * @param {number=} args.y Y (top-left) location on the screen for the current view
+ * @param {number} args.height Width of the view.
+ * @param {number} args.width Height of the view.
+ * @param {string} args.id id of the View
  * */
 export default class SideBySideView extends VivView {
   constructor({
     id,
-    x,
-    y,
+    x = 0,
+    y = 0,
     height,
     width,
     linkedIds = [],

src/views/VivView.js

@@ -7,8 +7,8 @@ import { OrthographicView } from '@deck.gl/core';
  * @param {Object} args.height Width of the view.
  * @param {Object} args.width Height of the view.
  * @param {string} args.id Id for the current view
- * @param {number} args.x X (top-left) location on the screen for the current view
- * @param {number} args.y Y (top-left) location on the screen for the current view
+ * @param {number=} args.x X (top-left) location on the screen for the current view
+ * @param {number=} args.y Y (top-left) location on the screen for the current view
  */
 export default class VivView {
   constructor({ id, x = 0, y = 0, height, width }) {