Fix type/docs for VivView(er) and Consumers. (#407)

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

* Use special jsdoc -> typescript syntax.

* Small Fixes

* Fix ImageLayer

* Try functional component

* Small fixes.

* Small fixes.

CHANGELOG.md

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

src/layers/BitmapLayer.js

@@ -124,6 +124,7 @@ class BitmapLayerWrapper extends BaseBitmapLayer {
  * 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.
  * Thus setting this to a truthy value (with a colormap set) indicates that the shader should make that color transparent.
+ * @property {String=} id Unique identifier for this layer.
  */
 /**
  * @type {{ new(...props: LayerProps[]) }}

src/layers/ImageLayer.js

@@ -41,7 +41,7 @@ const defaultProps = {
  * @property {Array.<Array.<number>>} colorValues List of [r, g, b] values for each channel.
  * @property {Array.<Array.<boolean>>} channelIsOn List of boolean values for each channel for whether or not it is visible.
  * @property {Array} loader PixelSource. Represents an N-dimensional image.
- * @property {Array} loader Selection to be used for fetching data.
+ * @property {Array} loaderSelection Selection to be used for fetching data.
  * @property {number=} opacity Opacity of the layer.
  * @property {string=} colormap String indicating a colormap (default: '').  The full list of options is here: https://github.com/glslify/glsl-colormap#glsl-colormap
  * @property {Array.<Array.<number>>=} domain Override for the possible max/min values (i.e something different than 65535 for uint16/'<u2').
@@ -59,6 +59,7 @@ const defaultProps = {
  * 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.
  * Thus setting this to a truthy value (with a colormap set) indicates that the shader should make that color transparent.
  * @property {function=} onViewportLoad Function that gets called when the data in the viewport loads.
+ * @property {String=} id Unique identifier for this layer.
  */
 
 /**

src/layers/OverviewLayer.js

@@ -50,6 +50,7 @@ const defaultProps = {
  * @property {number=} boundingBoxOutlineWidth Width of the bounding box in px (default: 1).
  * @property {Array.<number>=} viewportOutlineColor [r, g, b] color of the outline (default: [255, 190, 0]).
  * @property {number=} viewportOutlineWidth Viewport outline width in px (default: 2).
+ * @property {String=} id Unique identifier for this layer.
  */
 
 /**

src/viewers/PictureInPictureViewer.js

@@ -16,13 +16,13 @@ import { GLOBAL_SLIDER_DIMENSION_FIELDS } from '../constants';
  * @param {Array} props.sliderValues List of [begin, end] values to control each channel's ramp function.
  * @param {Array} props.colorValues List of [r, g, b] values for each channel.
  * @param {Array} props.channelIsOn List of boolean values for each channel for whether or not it is visible.
- * @param {string} props.colormap String indicating a colormap (default: '').  The full list of options is here: https://github.com/glslify/glsl-colormap#glsl-colormap
+ * @param {string} [props.colormap] String indicating a colormap (default: '').  The full list of options is here: https://github.com/glslify/glsl-colormap#glsl-colormap
  * @param {Array} props.loader The data source for the viewer, PixelSource[]. If loader.length > 1, data is assumed to be multiscale.
  * @param {Array} props.loaderSelection Selection to be used for fetching data.
  * @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

@@ -10,7 +10,7 @@ import { GLOBAL_SLIDER_DIMENSION_FIELDS } from '../constants';
  * @param {Array} props.sliderValues List of [begin, end] values to control each channel's ramp function.
  * @param {Array} props.colorValues List of [r, g, b] values for each channel.
  * @param {Array} props.channelIsOn List of boolean values for each channel for whether or not it is visible.
- * @param {string} props.colormap String indicating a colormap (default: '').  The full list of options is here: https://github.com/glslify/glsl-colormap#glsl-colormap
+ * @param {string} [props.colormap] String indicating a colormap (default: '').  The full list of options is here: https://github.com/glslify/glsl-colormap#glsl-colormap
  * @param {Array} props.loader This data source for the viewer. PixelSource[]. If loader.length > 1, data is assumed to be multiscale.
  * @param {Array} props.loaderSelection Selection to be used for fetching data.
  * @param {Boolean} props.zoomLock Whether or not lock the zooms of the two views.
@@ -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

@@ -12,29 +12,48 @@ const areViewStatesEqual = (viewState, otherViewState) => {
   );
 };
 
+/**
+ * @typedef viewStateChangeProps
+ * @type {object}
+ * @property {string} args.viewId
+ * @property {object} args.viewState
+ * @property {object} args.oldViewState
+ * @ignore
+ */
+
 /**
  * @callback ViewStateChange
- * @param {Object} event
+ * @param {viewStateChangeProps} args
+ * @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
- *     https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object)
+ * @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
  */
-export default class VivViewer extends PureComponent {
+
+/**
+ * @typedef HoverHooks
+ * @type {object}
+ * @property {HandleValue} handleValue
+ * @property {HandleCoordinate} handleCoordinate
+ * @ignore
+ */
+class VivViewerWrapper extends PureComponent {
   constructor(props) {
     super(props);
     this.state = {
@@ -56,8 +75,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
@@ -276,7 +296,22 @@ export default class VivViewer extends PureComponent {
         }}
       />
     );
-
-    /* eslint-disable react/destructuring-assignment */
   }
 }
+
+/**
+ * This component wraps the DeckGL component.
+ * @param {Object} props
+ * @param {Array} props.layerProps  Props for the layers in each view.
+ * @param {boolean} [props.randomize] Whether or not to randomize which view goes first (for dynamic rendering of multiple linked views).
+ * @param {Array.<import('../views').VivView>} props.views Various `VivView`s to render.
+ * @param {Array.<object>} 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
+ *     https://deck.gl/docs/developer-guide/interactivity#the-picking-info-object)
+ * @param {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.
+ */
+// eslint-disable-next-line react/jsx-props-no-spreading
+const VivViewer = props => <VivViewerWrapper {...props} />;
+export default VivViewer;

src/views/DetailView.js

@@ -33,12 +33,6 @@ export default class DetailView extends VivView {
     return layers;
   }
 
-  /**
-   * Create a viewState for this class, checking the id to make sure this class and viewState match.
-   * @param {Object} args
-   * @param {ViewState} args.ViewState ViewState object.
-   * @returns {ViewState} ViewState for this class (or null by default if the ids do not match).
-   */
   filterViewState({ viewState, currentViewState }) {
     if (viewState.id === OVERVIEW_VIEW_ID) {
       const { target } = viewState;

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 }) {
@@ -37,8 +37,10 @@ export default class VivView {
   /**
    * Create a viewState for this class, checking the id to make sure this class and veiwState match.
    * @param {Object} args
-   * @param {ViewState} args.ViewState ViewState object.
-   * @returns {ViewState} ViewState for this class (or null by default if the ids do not match).
+   * @param {object} [args.viewState] incoming ViewState object from deck.gl update.
+   * @param {object} [args.oldViewState] old ViewState object from deck.gl.
+   * @param {object} [args.currentViewState] current ViewState object in react state.
+   * @returns {?object} ViewState for this class (or null by default if the ids do not match).
    */
   filterViewState({ viewState }) {
     const { id, height, width } = this;
@@ -48,8 +50,8 @@ export default class VivView {
   /**
    * Create a layer for this instance.
    * @param {Object} args
-   * @param {ViewState} args.viewStates ViewStates for all current views.
-   * @param {number} args.props Props for this instance.
+   * @param {Object<string,Object>} args.viewStates ViewStates for all current views.
+   * @param {Object} args.props Props for this instance.
    * @returns {Layer} Instance of a layer.
    */
   // eslint-disable-next-line class-methods-use-this,no-unused-vars

src/views/utils.js

@@ -52,7 +52,7 @@ export function getDefaultInitialViewState(loader, viewSize, zoomBackOff = 0) {
 
 /**
  * Creates the layers for viewing an image in detail.
- * @param {string} id The identifier of the view.
+ * @param {String} id The identifier of the view.
  * @param {Object} props The layer properties.
  * @returns {Array} An array of layers.
  */