From fe354cccbb67e1cbfc752305fce1fc0468433344 Mon Sep 17 00:00:00 2001 From: telamonian Date: Mon, 1 Feb 2021 05:04:26 -0500 Subject: [PATCH 1/2] fix typos in existing jsdoc annotations --- src/js/events.js | 35 +++++++++++++++++++++------- src/js/index.js | 8 +++---- src/js/scroll_panel.js | 53 ++++++++++++++++++++++++++++++++---------- 3 files changed, 72 insertions(+), 24 deletions(-) diff --git a/src/js/events.js b/src/js/events.js index 21ee30da..e1b4a44d 100644 --- a/src/js/events.js +++ b/src/js/events.js @@ -29,8 +29,11 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { } /** + * + * @internal + * @private + * @memberof RegularViewEventModel * @returns - * @memberof RegularViewModel */ async _on_scroll(event) { event.stopPropagation(); @@ -45,6 +48,8 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { * and disabled to achieve clean virtual scrolling in the presence of a * `fixed` element. * + * @internal + * @private * @memberof RegularViewEventModel */ _register_glitch_scroll_listeners() { @@ -63,8 +68,10 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { * Mousewheel must precalculate in addition to `_on_scroll` to prevent * visual artifacts due to scrolling "inertia" on modern browsers. * + * @internal + * @private + * @memberof RegularViewEventModel * @param {*} event - * @memberof RegularViewModel */ _on_mousewheel(event) { if (this._virtual_scrolling_disabled) { @@ -88,9 +95,11 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { * the unfortunate side-effect of disabling scroll intertia, but the * alternative is a dodgy, glitchy mess. * + * @internal + * @private + * @memberof RegularViewEventModel * @param {*} event * @returns - * @memberof RegularViewEventModel */ _on_touchmove(event) { if (this._virtual_scrolling_disabled) { @@ -110,8 +119,10 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { * Memoize `touchstart` positions to calculate deltas, since these are not * generated on `touchmove` events. * - * @param {*} event + * @internal + * @private * @memberof RegularViewEventModel + * @param {*} event */ _on_touchstart(event) { this._memo_touch_startY = event.touches[0].screenY; @@ -121,9 +132,11 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { /** * Handles double-click header width override reset. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} event * @returns - * @memberof RegularVirtualTableViewModel */ async _on_dblclick(event) { let element = event.target; @@ -159,9 +172,11 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { * Dispatches all click events to other handlers, depending on * `event.target`. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} event * @returns - * @memberof RegularVirtualTableViewModel */ async _on_click(event) { if (event.button !== 0) { @@ -186,10 +201,12 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { /** * Regular event for column resize. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} event * @param {*} element * @param {*} metadata - * @memberof RegularVirtualTableViewModel */ _on_resize_column(event, element, metadata) { const start = event.pageX; @@ -210,12 +227,14 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel { /** * Regular event for mouse movement when resizing a column. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} event * @param {*} th * @param {*} start * @param {*} width * @param {*} metadata - * @memberof RegularVirtualTableViewModel */ @throttlePromise async _on_resize_column_move(event, th, start, width, metadata) { diff --git a/src/js/index.js b/src/js/index.js index 3f5fd5ea..3a3a8ca2 100644 --- a/src/js/index.js +++ b/src/js/index.js @@ -302,7 +302,7 @@ if (document.createElement("regular-table").constructor === HTMLElement) { * @property {number} [x1] - The `x` index of the viewport corner in * your data model, e.g. what was passed to `x1` when your * `dataListener` was invoked. - * @property {number} [y1] - The `y` index of the viewport origin in + * @property {number} [y1] - The `y` index of the viewport corner in * your data model, e.g. what was passed to `y1` when your * `dataListener` was invoked. * @property {number} [dx] - The `x` index in `DataResponse.data`, this @@ -312,7 +312,7 @@ if (document.createElement("regular-table").constructor === HTMLElement) { * @property {number} [column_header_y] - The `y` index in * `DataResponse.column_headers[x]`, this property is only generated for `` * from `column_headers`. - * @property {number} [column_header_x] - The `x` index in + * @property {number} [row_header_x] - The `x` index in * `DataResponse.row_headers[y]`, this property is only generated for `` * from `row_headers`. * @property {number} size_key - The unique index of this column in a full @@ -321,6 +321,7 @@ if (document.createElement("regular-table").constructor === HTMLElement) { * `DataResponse.row_headers`, if it was provided. * @property {Array} [column_header] - The `Array` for this `x` in * `DataResponse.column_headers`, if it was provided. + * @property {object} [value] - The value dispalyed in the cell or header. */ /** @@ -373,8 +374,7 @@ if (document.createElement("regular-table").constructor === HTMLElement) { * `Event`); and returns a `Promise` for a `DataResponse` object for this * region (as opposed to returning `void` as a standard event listener). * - * @typedef DataListener - * @type {function} + * @callback DataListener * @param {number} x0 - The origin `x` index (column). * @param {number} y0 - The origin `y` index (row). * @param {number} x1 - The corner `x` index (column). diff --git a/src/js/scroll_panel.js b/src/js/scroll_panel.js index e36a2f98..e0f9ccb6 100644 --- a/src/js/scroll_panel.js +++ b/src/js/scroll_panel.js @@ -61,6 +61,8 @@ export class RegularVirtualTableViewModel extends HTMLElement { * double buffered `` is rendered in the shadow DOM before being * swapped in. * + * @internal + * @private * @memberof RegularVirtualTableViewModel */ create_shadow_dom() { @@ -86,10 +88,12 @@ export class RegularVirtualTableViewModel extends HTMLElement { /** * Calculates the `viewport` argument for perspective's `to_columns` method. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} nrows * @param {*} reset_scroll_position * @returns - * @memberof RegularVirtualTableViewModel */ _calculate_viewport(nrows, num_columns, reset_scroll_position) { const {start_row, end_row} = this._calculate_row_range(nrows, reset_scroll_position); @@ -131,10 +135,12 @@ export class RegularVirtualTableViewModel extends HTMLElement { * | | * 600px +--------------------------+ * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} nrows * @param {*} reset_scroll_position * @returns - * @memberof RegularVirtualTableViewModel */ _calculate_row_range(nrows, reset_scroll_position) { const {height} = this._container_size; @@ -156,8 +162,10 @@ export class RegularVirtualTableViewModel extends HTMLElement { * details of which are actually calculated in `_max_column`, the equivalent * of `total_scroll_height` from `_calculate_row_range`. * - * @returns + * @internal + * @private * @memberof RegularVirtualTableViewModel + * @returns */ _calculate_column_range(num_columns) { const total_scroll_width = Math.max(1, this._virtual_panel.offsetWidth - this._container_size.width); @@ -189,8 +197,10 @@ export class RegularVirtualTableViewModel extends HTMLElement { * | | 80px | 110px | 100px | * | | | | | * - * @returns + * @internal + * @private * @memberof RegularVirtualTableViewModel + * @returns */ _max_scroll_column(num_columns) { let width = 0; @@ -213,9 +223,11 @@ export class RegularVirtualTableViewModel extends HTMLElement { * e.g. when the logical (row-wise) viewport does not change, but the pixel * viewport has moved a few px. * + * @internal + * @private + * @memberof RegularVirtualTableViewModel * @param {*} {start_col, end_col, start_row, end_row} * @returns - * @memberof RegularVirtualTableViewModel */ _validate_viewport({start_col, end_col, start_row, end_row}) { const invalid_column = this._start_col !== start_col; @@ -230,8 +242,10 @@ export class RegularVirtualTableViewModel extends HTMLElement { /** * Updates the `virtual_panel` width based on view state. * - * @param {*} invalid + * @internal + * @private * @memberof RegularVirtualTableViewModel + * @param {*} invalid */ _update_virtual_panel_width(invalid, num_columns) { if (invalid) { @@ -257,8 +271,10 @@ export class RegularVirtualTableViewModel extends HTMLElement { /** * Updates the `virtual_panel` height based on the view state. * - * @param {*} nrows + * @internal + * @private * @memberof RegularVirtualTableViewModel + * @param {*} nrows */ _update_virtual_panel_height(nrows) { const {row_height = 19} = this._column_sizes; @@ -281,23 +297,25 @@ export class RegularVirtualTableViewModel extends HTMLElement { * interaction and previous render state. * * `reset_scroll_position` will not prevent the viewport from moving as - * `draw()` may change the dmiensions of the virtual_panel (and thus, + * `draw()` may change the dimensions of the virtual_panel (and thus, * absolute scroll offset). This calls `reset_scroll`, which will * trigger `_on_scroll` and ultimately `draw()` again; however, this call * to `draw()` will be for the same viewport and will not actually cause * a render. * - * @param {*} [options] - * @param {boolean} [options.reset_scroll_position=false] + * @public + * @memberof RegularVirtualTableViewModel + * @param {DrawOptions} [options] + * @param {boolean} [options.invalid_viewport=true] * @param {boolean} [options.preserve_width=false] + * @param {boolean} [options.reset_scroll_position=false] * @param {boolean} [options.swap=false] * @returns - * @memberof RegularVirtualTableViewModel */ @throttlePromise async draw(options = {}) { const __debug_start_time__ = DEBUG && performance.now(); - const {reset_scroll_position = false, preserve_width = false, invalid_viewport = true, swap = false} = options; + const {invalid_viewport = true, preserve_width = false, reset_scroll_position = false, swap = false} = options; if (reset_scroll_position) { this.reset_scroll(); @@ -347,3 +365,14 @@ export class RegularVirtualTableViewModel extends HTMLElement { } } } + +/** + * Options for the draw method. + * + * @typedef DrawOptions + * @type {object} + * @property {boolean} [invalid_viewport] + * @property {boolean} [preserve_width] + * @property {boolean} [reset_scroll_position] + * @property {boolean} [swap] + */ From 109771d769a6692a7ae0dff319fe302c2c5c0c00 Mon Sep 17 00:00:00 2001 From: telamonian Date: Thu, 4 Feb 2021 18:23:09 -0500 Subject: [PATCH 2/2] fixup typescript typings, add missing `draw` method --- index.d.ts | 134 +++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 110 insertions(+), 24 deletions(-) diff --git a/index.d.ts b/index.d.ts index 181a17bc..7a13505f 100644 --- a/index.d.ts +++ b/index.d.ts @@ -41,6 +41,29 @@ declare module 'regular-table' { detail: RegularTableElement; }) => void): number; + /** + * Draws this virtual panel, given an object of render options that allow + * the implementor to fine tune the individual render frames based on the + * interaction and previous render state. + * + * `reset_scroll_position` will not prevent the viewport from moving as + * `draw()` may change the dimensions of the virtual_panel (and thus, + * absolute scroll offset). This calls `reset_scroll`, which will + * trigger `_on_scroll` and ultimately `draw()` again; however, this call + * to `draw()` will be for the same viewport and will not actually cause + * a render. + * + * @public + * @memberof RegularVirtualTableViewModel + * @param {DrawOptions} [options] + * @param {boolean} [options.invalid_viewport=true] + * @param {boolean} [options.preserve_width=false] + * @param {boolean} [options.reset_scroll_position=false] + * @param {boolean} [options.swap=false] + * @returns + */ + draw(options?: DrawOptions): Promise; + /** * Returns the `MetaData` object associated with a `
` or ``. When * your `StyleListener` is invoked, use this method to look up additional @@ -120,10 +143,10 @@ declare module 'regular-table' { } /** - * An object with performance statistics about calls to - * `draw()` from some time interval (captured in milliseconds by the - * `elapsed` proprty). - */ + * An object with performance statistics about calls to + * `draw()` from some time interval (captured in milliseconds by the + * `elapsed` proprty). + */ export type Performance = { /** * - Avergage milliseconds per call. @@ -149,11 +172,30 @@ declare module 'regular-table' { }; /** - * An object describing virtual rendering metadata about an - * `HTMLTableCellElement`, use this object to map rendered `` or `` - * elements back to your `data`, `row_headers` or `column_headers` within - * listener functions for `addStyleListener()` and `addEventListener()`. - */ + * An object describing virtual rendering metadata about an + * `HTMLTableCellElement`, use this object to map rendered `` or `` + * elements back to your `data`, `row_headers` or `column_headers` within + * listener functions for `addStyleListener()` and `addEventListener()`. + * + * @example + * + * MetaData (x = 0, column_header_y = 0)) + * *-------------------------------------+ + * | | + * | | + * +-------------------------------------+ + * (row_header_x = 0, y = 0) (x = 0, y = 0) + * *------------------------+ *-------------------------------------+ + * | | | | + * | | | (x0, y0) | + * | | | *---------------* | + * | | | | | | + * | | | | * (x, y) | | + * | | | | | | + * | | | *---------------* (x1, y1) | + * | | | | + * +------------------------+ +-------------------------------------+ + */ export type MetaData = { /** * - The `x` index in your virtual data model. @@ -173,10 +215,22 @@ declare module 'regular-table' { x0?: number; /** * - The `y` index of the viewport origin in - * your data model, e.g. what was passed to `x0` when your + * your data model, e.g. what was passed to `y0` when your * `dataListener` was invoked. */ y0?: number; + /** + * - The `x` index of the viewport corner in + * your data model, e.g. what was passed to `x1` when your + * `dataListener` was invoked. + */ + x1?: number; + /** + * - The `y` index of the viewport corner in + * your data model, e.g. what was passed to `y1` when your + * `dataListener` was invoked. + */ + y1?: number; /** * - The `x` index in `DataResponse.data`, this * property is only generated for ``, and `` from `column_headers`. @@ -198,7 +252,7 @@ declare module 'regular-table' { * `DataResponse.row_headers[y]`, this property is only generated for `` * from `row_headers`. */ - column_header_x?: number; + row_header_x?: number; /** * - The unique index of this column in a full * ``, which is `x` + (Total Row Header Columns). @@ -214,16 +268,38 @@ declare module 'regular-table' { * `DataResponse.column_headers`, if it was provided. */ column_header?: Array; + /** + * - The value dispalyed in the cell or header. + */ + value?: object; }; /** - * The `DataResponse` object describes a rectangular region of a virtual - * data set, and some associated metadata. `` will use this - * object to render the `
`, though it may make multiple requests for - * different regions to achieve a compelte render as it must estimate - * certain dimensions. You must construct a `DataResponse` object to - * implement a `DataListener`. - */ + * The `DataResponse` object describes a rectangular region of a virtual + * data set, and some associated metadata. `` will use this + * object to render the `
`, though it may make multiple requests for + * different regions to achieve a compelte render as it must estimate + * certain dimensions. You must construct a `DataResponse` object to + * implement a `DataListener`. + * + * @example + * { + * "num_rows": 26, + * "num_columns": 3, + * "data": [ + * [0, 1], + * ["A", "B"] + * ], + * "row_headers": [ + * ["Rowgroup 1", "Row 1"], + * ["Rowgroup 1", "Row 2"] + * ], + * "column_headers": [ + * ["Colgroup 1", "Column 1"], + * ["Colgroup 1", "Column 2"] + * ] + * } + */ export type DataResponse = { /** * - A two dimensional @@ -258,12 +334,22 @@ declare module 'regular-table' { }; /** - * The `DataListener` is similar to a normal event listener function. - * Unlike a normal event listener, it takes regular arguments (not an - * `Event`); and returns a `Promise` for a `DataResponse` object for this - * region (as opposed to returning `void` as a standard event listener). - */ - export type DataListener = Function; + * The `DataListener` is similar to a normal event listener function. + * Unlike a normal event listener, it takes regular arguments (not an + * `Event`); and returns a `Promise` for a `DataResponse` object for this + * region (as opposed to returning `void` as a standard event listener). + */ + export type DataListener = (x0: number, y0: number, x1: number, y1: number) => Promise; + + /** + * Options for the draw method. + */ + export type DrawOptions = { + invalid_viewport?: boolean; + preserve_width?: boolean; + reset_scroll_position?: boolean; + swap?: boolean; + }; global { namespace JSX {