From 43d4a6cc593d841d9f02fad580f245bf69f224da Mon Sep 17 00:00:00 2001 From: ilan-gold Date: Mon, 5 Apr 2021 16:46:27 -0400 Subject: [PATCH] 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 | 2 + src/layers/BitmapLayer.js | 1 + src/layers/ImageLayer.js | 3 +- src/layers/OverviewLayer.js | 1 + src/viewers/PictureInPictureViewer.js | 8 ++-- src/viewers/SideBySideViewer.js | 3 +- src/viewers/VivViewer.js | 65 ++++++++++++++++++++------- src/views/DetailView.js | 6 --- src/views/SideBySideView.js | 15 ++++--- src/views/VivView.js | 14 +++--- src/views/utils.js | 2 +- 11 files changed, 81 insertions(+), 39 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 210019cb9..baa5855ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ ### Changed +- Fix `VivViewer` and `VivView` types. + ## 0.9.4 ### Added diff --git a/src/layers/BitmapLayer.js b/src/layers/BitmapLayer.js index 9100a4846..2e5fc9156 100644 --- a/src/layers/BitmapLayer.js +++ b/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[]) }} diff --git a/src/layers/ImageLayer.js b/src/layers/ImageLayer.js index cbc67b27d..19f126d9d 100644 --- a/src/layers/ImageLayer.js +++ b/src/layers/ImageLayer.js @@ -41,7 +41,7 @@ const defaultProps = { * @property {Array.>} colorValues List of [r, g, b] values for each channel. * @property {Array.>} 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.>=} domain Override for the possible max/min values (i.e something different than 65535 for uint16/'=} 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. */ /** diff --git a/src/viewers/PictureInPictureViewer.js b/src/viewers/PictureInPictureViewer.js index 789060fb0..763e55ccb 100644 --- a/src/viewers/PictureInPictureViewer.js +++ b/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, diff --git a/src/viewers/SideBySideViewer.js b/src/viewers/SideBySideViewer.js index 93d49f4d4..79b674d03 100644 --- a/src/viewers/SideBySideViewer.js +++ b/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. diff --git a/src/viewers/VivViewer.js b/src/viewers/VivViewer.js index c38715dd0..9726e8c67 100644 --- a/src/viewers/VivViewer.js +++ b/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.} 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.} props.views Various `VivView`s 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) + * @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 => ; +export default VivViewer; diff --git a/src/views/DetailView.js b/src/views/DetailView.js index f22008341..794c0dc77 100644 --- a/src/views/DetailView.js +++ b/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; diff --git a/src/views/SideBySideView.js b/src/views/SideBySideView.js index 6e0fb9d3a..c00d81e23 100644 --- a/src/views/SideBySideView.js +++ b/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} 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 = [], diff --git a/src/views/VivView.js b/src/views/VivView.js index 9aa263b00..6dda38847 100644 --- a/src/views/VivView.js +++ b/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} 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 diff --git a/src/views/utils.js b/src/views/utils.js index 6e37d7a46..99ecc6aff 100644 --- a/src/views/utils.js +++ b/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. */