@uwdata/mosaic-inputs 0.12.1 → 0.13.0

package/src/Slider.js

@@ -1,12 +1,47 @@
-import { MosaicClient, Param, clauseInterval, clausePoint, isParam, isSelection } from '@uwdata/mosaic-core';
+import { Param, Selection, clauseInterval, clausePoint, isParam, isSelection } from '@uwdata/mosaic-core';
 import { Query, max, min } from '@uwdata/mosaic-sql';
-import { input } from './input.js';
+import { Input, input } from './input.js';
 
 let _id = 0;
 
+/**
+ * Create a new slider input instance.
+ * @param {object} [options] Options object
+ * @param {HTMLElement} [options.element] The parent DOM element in which to
+ *  place the slider elements. If undefined, a new `div` element is created.
+ * @param {Selection} [options.filterBy] A selection to filter the database
+ *  table indicated by the *from* option.
+ * @param {Param} [options.as] The output param or selection. A selection
+ *  clause is added based on the currently selected slider option.
+ * @param {string} [options.field] The database column name to use within
+ *  generated selection clause predicates. Defaults to the *column* option.
+ * @param {'point' | 'interval'} [options.select] The type of selection clause
+ *  predicate to generate if the **as** option is a Selection.  If `'point'`
+ *  (the default), the selection predicate is an equality check for the slider
+ *  value. If `'interval'`, the predicate checks an interval from the minimum
+ *  to the current slider value.
+ * @param {number} [options.min] The minimum slider value.
+ * @param {number} [options.max] The maximum slider value.
+ * @param {number} [options.step] The slider step, the amount to increment
+ *  between consecutive values.
+ * @param {number} [options.value] The initial slider value.
+ * @param {string} [options.from] The name of a database table to use as a data
+ *  source for this widget. Used in conjunction with the *column* option.
+ *  The minimum and maximum values of the column determine the slider range.
+ * @param {string} [options.column] The name of a database column whose values
+ *  determine the slider range. Used in conjunction with the *from* option.
+ *  The minimum and maximum values of the column determine the slider range.
+ * @param {string} [options.label] A text label for this input.
+ * @param {number} [options.width] The width of the slider in screen pixels.
+ * @returns {HTMLElement} The container element for a slider input.
+ */
 export const slider = options => input(Slider, options);
 
-export class Slider extends MosaicClient {
+/**
+ * A HTML range-based slider input.
+ * @extends {Input}
+ */
+export class Slider extends Input {
   /**
    * Create a new slider input.
    * @param {object} [options] Options object
@@ -52,7 +87,7 @@ export class Slider extends MosaicClient {
     field = column,
     width
   } = {}) {
-    super(filterBy);
+    super(filterBy, element);
     this.id = 'slider_' + (++_id);
     this.from = from;
     this.column = column || 'value';
@@ -63,10 +98,6 @@ export class Slider extends MosaicClient {
     this.max = max;
     this.step = step;
 
-    this.element = element || document.createElement('div');
-    this.element.setAttribute('class', 'input');
-    Object.defineProperty(this.element, 'value', { value: this });
-
     if (label) {
       const desc = document.createElement('label');
       desc.setAttribute('for', this.id);
@@ -165,8 +196,9 @@ export class Slider extends MosaicClient {
   }
 
   activate() {
-    // @ts-ignore - activate is only called for a Selection
-    this.selection.activate(this.clause(0));
+    if (isSelection(this.selection)) {
+      this.selection.activate(this.clause(0));
+    }
   }
 
   publish(value) {

package/src/Table.js

@@ -1,16 +1,77 @@
-import { MosaicClient, clausePoints, coordinator, isParam, toDataColumns } from '@uwdata/mosaic-core';
-import { Query, column, desc } from '@uwdata/mosaic-sql';
+import { Selection, clausePoints, coordinator, isParam, isSelection, toDataColumns } from '@uwdata/mosaic-core';
+import { Query, desc } from '@uwdata/mosaic-sql';
 import { formatDate, formatLocaleAuto, formatLocaleNumber } from './util/format.js';
-import { input } from './input.js';
+import { Input, input } from './input.js';
 
 let _id = -1;
 
+/**
+ * Create a new table input instance.
+ * @param {object} options Options object
+ * @param {HTMLElement} [options.element] The parent DOM element in which to
+ *  place the table element. If undefined, a new `div` element is created.
+ * @param {Selection} [options.filterBy] A selection to filter the database
+ *  table indicated by the *from* option.
+ * @param {Selection} [options.as] The output selection. A selection
+ *  clause is added for the currently selected table row.
+ * @param {{ [name: string]: 'left' | 'right' | 'center' }} [options.align]
+ *  An object that maps column names to horiztonal text alignment values. If
+ *  unspecified, alignment is determined based on the column data type.
+ * @param {{ [name: string]: (value: any) => string }} [options.format] An
+ *  object that maps column names to format functions to use for that
+ *  column's data. Each format function takes a value as input and generates
+ *  formatted text to show in the table.
+ * @param {string} [options.from] The name of a database table to use as a data
+ *  source for this widget. Used in conjunction with the *columns* option.
+ * @param {string[]} [options.columns] The name of database columns to include
+ *  in the table component. If unspecified, all columns are included.
+ *  Used in conjunction with the *from* option.
+ * @param {number | { [name: string]: number }} [options.width] If a number,
+ *  sets the desired width of the table, in pixels. If an object, is used to
+ *  set explicit pixel widts for each named column included in the object.
+ * @param {number} [options.maxWidth] The maximum width of the table, in pixels.
+ * @param {number} [options.height] The desired height of the table, in pixels.
+ * @param {number} [options.rowBatch] The number of rows to request per query
+ *  batch. The batch size will be used to prefetch data beyond the currently
+ *  visible range.
+ * @returns {HTMLElement} The container element for a table component.
+ */
 export const table = options => input(Table, options);
 
-export class Table extends MosaicClient {
+/**
+ * A HTML table based table component.
+ * @extends {Input}
+ */
+export class Table extends Input {
   /**
    * Create a new Table instance.
    * @param {object} options Options object
+   * @param {HTMLElement} [options.element] The parent DOM element in which to
+   *  place the table element. If undefined, a new `div` element is created.
+   * @param {Selection} [options.filterBy] A selection to filter the database
+   *  table indicated by the *from* option.
+   * @param {Selection} [options.as] The output selection. A selection
+   *  clause is added for the currently selected table row.
+   * @param {{ [name: string]: 'left' | 'right' | 'center' }} [options.align]
+   *  An object that maps column names to horiztonal text alignment values. If
+   *  unspecified, alignment is determined based on the column data type.
+   * @param {{ [name: string]: (value: any) => string }} [options.format] An
+   *  object that maps column names to format functions to use for that
+   *  column's data. Each format function takes a value as input and generates
+   *  formatted text to show in the table.
+   * @param {string} [options.from] The name of a database table to use as a data
+   *  source for this widget. Used in conjunction with the *columns* option.
+   * @param {string[]} [options.columns] The name of database columns to include
+   *  in the table component. If unspecified, all columns are included.
+   *  Used in conjunction with the *from* option.
+   * @param {number | { [name: string]: number }} [options.width] If a number,
+   *  sets the desired width of the table, in pixels. If an object, is used to
+   *  set explicit pixel widts for each named column included in the object.
+   * @param {number} [options.maxWidth] The maximum width of the table, in pixels.
+   * @param {number} [options.height] The desired height of the table, in pixels.
+   * @param {number} [options.rowBatch] The number of rows to request per query
+   *  batch. The batch size will be used to prefetch data beyond the currently
+   *  visible range.
    */
   constructor({
     element,
@@ -25,8 +86,11 @@ export class Table extends MosaicClient {
     rowBatch = 100,
     as
   } = {}) {
-    super(filterBy);
+    super(filterBy, element, null);
+
     this.id = `table-${++_id}`;
+    this.element.setAttribute('id', this.id);
+
     this.from = from;
     this.columns = columns;
     this.format = format;
@@ -40,7 +104,7 @@ export class Table extends MosaicClient {
 
     this.offset = 0;
     this.limit = +rowBatch;
-    this.pending = false;
+    this.isPending = false;
 
     this.selection = as;
     this.currentRow = -1;
@@ -49,9 +113,6 @@ export class Table extends MosaicClient {
     this.sortColumn = null;
     this.sortDesc = false;
 
-    this.element = element || document.createElement('div');
-    this.element.setAttribute('id', this.id);
-    Object.defineProperty(this.element, 'value', { value: this });
     if (typeof width === 'number') this.element.style.width = `${width}px`;
     if (maxWidth) this.element.style.maxWidth = `${maxWidth}px`;
     this.element.style.maxHeight = `${height}px`;
@@ -59,15 +120,16 @@ export class Table extends MosaicClient {
 
     let prevScrollTop = -1;
     this.element.addEventListener('scroll', evt => {
-      const { pending, loaded } = this;
+      const { isPending, loaded } = this;
+      // @ts-ignore
       const { scrollHeight, scrollTop, clientHeight } = evt.target;
 
       const back = scrollTop < prevScrollTop;
       prevScrollTop = scrollTop;
-      if (back || pending || loaded) return;
+      if (back || isPending || loaded) return;
 
       if (scrollHeight - scrollTop < 2 * clientHeight) {
-        this.pending = true;
+        this.isPending = true;
         this.requestData(this.offset + this.limit);
       }
     });
@@ -125,8 +187,8 @@ export class Table extends MosaicClient {
   }
 
   fields() {
-    const from = this.sourceTable();
-    return this.columns.map(name => column(name, from));
+    const table = this.sourceTable();
+    return this.columns.map(column => ({ column, table }));
   }
 
   fieldInfo(info) {
@@ -168,7 +230,7 @@ export class Table extends MosaicClient {
   }
 
   queryResult(data) {
-    if (!this.pending) {
+    if (!this.isPending) {
       // data is not from an internal request, so reset table
       this.loaded = false;
       this.data = [];
@@ -204,10 +266,16 @@ export class Table extends MosaicClient {
       this.loaded = true;
     }
 
-    this.pending = false;
+    this.isPending = false;
     return this;
   }
 
+  activate() {
+    if (isSelection(this.selection)) {
+      this.selection.activate(this.clause([]));
+    }
+  }
+
   sort(event, column) {
     if (column === this.sortColumn) {
       this.sortDesc = !this.sortDesc;

package/src/input.js

@@ -1,7 +1,40 @@
-import { coordinator } from '@uwdata/mosaic-core';
+import { coordinator, MosaicClient } from '@uwdata/mosaic-core';
 
-export function input(InputClass, options) {
-  const input = new InputClass(options);
+/**
+ * Instantiate an input, register it with the coordinator, and
+ * return the corresponding HTML element.
+ * @template {new (...args: any) => Input} T
+ * @param {T} InputClass
+ * @param {ConstructorParameters<T>} params
+ * @returns {HTMLElement} The container element of the input.
+ */
+export function input(InputClass, ...params) {
+  const input = new InputClass(...params);
   coordinator().connect(input);
   return input.element;
 }
+
+/**
+ * Base class for input components.
+ * @import {Activatable} from '@uwdata/mosaic-core'
+ * @implements {Activatable}
+ */
+export class Input extends MosaicClient {
+  /**
+   * Create a new input instance.
+   * @param {import('@uwdata/mosaic-core').Selection} [filterBy] A selection
+   *  with which to filter backing data that parameterizes this input.
+   * @param {HTMLElement} [element] Optional container HTML element to use.
+   * @param {string} [className] A class name to set on the container element.
+   */
+  constructor(filterBy, element, className = 'input') {
+    super(filterBy);
+    this.element = element || document.createElement('div');
+    if (className) this.element.setAttribute('class', className);
+    Object.defineProperty(this.element, 'value', { value: this });
+  }
+
+  activate() {
+    // subclasses should override
+  }
+}

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineConfig } from 'vite';
+
+export default defineConfig({});