Skip to content

Fixup jsdoc annotations, carry fixups over to typescript typings #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
texodus merged 2 commits into from
Feb 5, 2021
Merged

Fixup jsdoc annotations, carry fixups over to typescript typings #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe354cc
fix typos in existing jsdoc annotations
telamonian Feb 1, 2021
109771d
fixup typescript typings, add missing `draw` method
telamonian Feb 4, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
134 changes: 110 additions & 24 deletions index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<void>;

/**
* Returns the `MetaData` object associated with a `<td>` or `<th>`. When
* your `StyleListener` is invoked, use this method to look up additional
Expand Down Expand Up @@ -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.
Expand All @@ -149,11 +172,30 @@ declare module 'regular-table' {
};

/**
* An object describing virtual rendering metadata about an
* `HTMLTableCellElement`, use this object to map rendered `<th>` or `<td>`
* 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 `<th>` or `<td>`
* 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.
Expand All @@ -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 `<td>`, and `<th>` from `column_headers`.
Expand All @@ -198,7 +252,7 @@ declare module 'regular-table' {
* `DataResponse.row_headers[y]`, this property is only generated for `<th>`
* from `row_headers`.
*/
column_header_x?: number;
row_header_x?: number;
/**
* - The unique index of this column in a full
* `<table>`, which is `x` + (Total Row Header Columns).
Expand All @@ -214,16 +268,38 @@ declare module 'regular-table' {
* `DataResponse.column_headers`, if it was provided.
*/
column_header?: Array<object>;
/**
* - 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. `<regular-table>` will use this
* object to render the `<table>`, 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. `<regular-table>` will use this
* object to render the `<table>`, 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
Expand Down Expand Up @@ -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<DataResponse>;

/**
* Options for the draw method.
*/
export type DrawOptions = {
invalid_viewport?: boolean;
preserve_width?: boolean;
reset_scroll_position?: boolean;
swap?: boolean;
};

global {
namespace JSX {
Expand Down
35 changes: 27 additions & 8 deletions src/js/events.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,11 @@ export class RegularViewEventModel extends RegularVirtualTableViewModel {
}

/**
*
* @internal
* @private
* @memberof RegularViewEventModel
* @returns
* @memberof RegularViewModel
*/
async _on_scroll(event) {
event.stopPropagation();
Expand All @@ -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() {
Expand All @@ -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) {
Expand All @@ -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) {
Expand All @@ -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;
Expand All @@ -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;
Expand Down Expand Up @@ -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) {
Expand All @@ -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;
Expand All @@ -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) {
Expand Down
8 changes: 4 additions & 4 deletions src/js/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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 `<th>`
* 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 `<th>`
* from `row_headers`.
* @property {number} size_key - The unique index of this column in a full
Expand All @@ -321,6 +321,7 @@ if (document.createElement("regular-table").constructor === HTMLElement) {
* `DataResponse.row_headers`, if it was provided.
* @property {Array<object>} [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.
*/

/**
Expand Down Expand Up @@ -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).
Expand Down
Loading