@uwdata/mosaic-spec 0.7.1 → 0.8.0

package/src/parse-spec.js

@@ -5,27 +5,52 @@ import { ParamRefNode } from './ast/ParamRefNode.js';
 import { parseAttribute } from './ast/PlotAttributeNode.js';
 import { SelectionNode } from './ast/SelectionNode.js';
 import { SpecNode } from './ast/SpecNode.js';
-
 import { componentMap } from './config/components.js';
 import { inputNames } from './config/inputs.js';
 import { plotNames } from './config/plots.js';
 import { transformNames } from './config/transforms.js';
+import { error, paramRef } from './util.js';
 
-import { error, isString, paramRef } from './util.js';
+/**
+ * @typedef {{
+ *   attributes: Set<string>;
+ *   interactors: Set<string>;
+ *   legends: Set<string>;
+ *   marks: Set<string>;
+ * }} PlotNames names for supported plot elements
+ */
 
 /**
  * Parse a Mosaic specification to an AST (abstract syntax tree).
- * @param {object|string} spec The input specification as an object
- *  or JSON string.
+ * @param {import('./spec/Spec.js').Spec} spec The input specification.
  * @param {object} [options] Optional parse options object.
+ * @param {Map<string, Function>} [options.components] Map of component names to parse functions.
+ * @param {Set<string>} [options.transforms] The names of allowed transform functions.
+ * @param {Set<string>} [options.inputs] The names of supported input widgets.
+ * @param {PlotNames} [options.plot] The names of supported plot elements.
+ * @param {any[]} [options.params] An array of [name, node] pairs of pre-parsed
+ *  Param or Selection AST nodes.
+ * @param {any[]} [options.datasets] An array of [name, node] pairs of pre-parsed
+ *  dataset definition AST nodes.
  * @returns {SpecNode} The top-level AST spec node.
  */
 export function parseSpec(spec, options) {
-  spec = isString(spec) ? JSON.parse(spec) : spec;
   return new ParseContext(options).parse(spec);
 }
 
 export class ParseContext {
+  /**
+   * Create a new parser context.
+   * @param {object} [options]
+   * @param {Map<string, Function>} [options.components] Map of component names to parse functions.
+   * @param {Set<string>} [options.transforms] The names of allowed transform functions.
+   * @param {Set<string>} [options.inputs] The names of supported input widgets.
+   * @param {PlotNames} [options.plot] The names of supported plot elements.
+   * @param {any[]} [options.params] An array of [name, node] pairs of pre-parsed
+   *  Param or Selection AST nodes.
+   * @param {any[]} [options.datasets] An array of [name, node] pairs of pre-parsed
+   *  dataset definition AST nodes.
+   */
   constructor({
     components = componentMap(),
     transforms = transformNames(),
@@ -87,6 +112,14 @@ export class ParseContext {
     this.error(`Invalid specification.`, spec);
   }
 
+  /**
+   * Test if a value is param reference, if so, generate a paramter definition
+   * as needed and return a new ParamRefNode. Otherwise, return a LiteralNode.
+   * @param {*} value The value to test.
+   * @param {() => ParamNode | SelectionNode} [makeNode] A Param of Selection AST
+   *  node constructor.
+   * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
+   */
   maybeParam(value, makeNode = () => new ParamNode) {
     const { params } = this;
     const name = paramRef(value);

package/src/spec/CSSStyles.ts

@@ -0,0 +1,9 @@
+type OmittedProperties =
+  | 'parentRule'
+  | 'getPropertyPriority'
+  | 'getPropertyValue'
+  | 'item'
+  | 'removeProperty'
+  | 'setProperty';
+
+export type CSSStyles = Partial<Omit<CSSStyleDeclaration, OmittedProperties>>;

package/src/spec/Data.ts

@@ -0,0 +1,184 @@
+export interface DataBaseOptions {
+  /**
+   * A list of column names to extract upon load.
+   * Any other columns are omitted.
+   */
+  select?: string[];
+  /**
+   * A filter (WHERE clause) to apply upon load.
+   * Only rows that pass the filted are included.
+   */
+  where?: string | string[];
+  /**
+   * Flag (default `false`) to generate a view instead of a table.
+   */
+  view?: boolean;
+  /**
+   * Flag (default `true`) to generate a temporary view or table.
+   */
+  temp?: boolean;
+  /**
+   * Flag (default `true`) to replace an existing table of the same name.
+   * If `false`, creating a new table with an existing name raises an error.
+   */
+  replace?: boolean;
+}
+
+/**
+ * A SQL query defining a new temporary database table.
+ */
+export type DataQuery = string;
+
+/**
+ * An inline array of data objects to treat as JSON data.
+ */
+export type DataArray = object[];
+
+/**
+ * A data definition that loads an external data file.
+ */
+export interface DataFile extends DataBaseOptions {
+  /**
+   * The data file to load. If no type option is provided,
+   * the file suffix must be one of `.csv`, `.json`, or `.parquet`.
+   */
+  file: `${string}.parquet` | `${string}.csv` | `${string}.json`;
+}
+
+/**
+ * A data definition that queries an existing table.
+ */
+export interface DataTable extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type: 'table';
+  /**
+   * A SQL query string for the desired table data.
+   */
+  query: string;
+}
+
+/**
+ * A data definition that loads a parquet file.
+ */
+export interface DataParquet extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type: 'parquet';
+  /**
+   * The file path for the dataset to load.
+   */
+  file: string;
+}
+
+/**
+ * A data definition that loads a csv file.
+ */
+export interface DataCSV extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type: 'csv';
+  /**
+   * The file path for the dataset to load.
+   */
+  file: string;
+  /**
+   * The column delimiter string. If not specified, DuckDB will try to infer
+   * the delimiter automatically.
+   */
+  delimiter?: string,
+  /**
+   * The sample size, in table rows, to consult for type inference.
+   * Set to `-1` to process all rows in the dataset.
+   */
+  sample_size?: number;
+}
+
+/**
+ * A data definition that loads a supported spatial data file format.
+ */
+export interface DataSpatial extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type: 'spatial';
+  /**
+   * The file path for the spatial dataset to load. See the [DuckDB spatial
+   * documention][1] for more information on supported file types.
+   *
+   * [1]: https://duckdb.org/docs/extensions/spatial.html#st_read--read-spatial-data-from-files
+   */
+  file: string;
+  /**
+   * The named layer to load from the file. For example, in a TopoJSON file
+   * the layer is the named object to extract. For Excel spreadsheet files,
+   * the layer is the name of the worksheet to extract.
+   */
+  layer?: string;
+}
+
+export interface DataJSON extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type: 'json';
+  /**
+   * The file path for the dataset to load.
+   */
+  file: string;
+}
+
+export interface DataJSONObjects extends DataBaseOptions {
+  /**
+   * The data source type. One of:
+   * - `"table"`: Define a new table based on a SQL query.
+   * - `"csv"`: Load a comma-separated values (CSV) file.
+   * - `"json"`: Load JavaScript Object Notation (json) data.
+   * - `"parquet"`: Load a Parquet file.
+   * - `"spatial"`: Load a spatial data file format via `ST_Read`.
+   */
+  type?: 'json';
+  /**
+   * An array of inline objects in JSON-style format.
+   */
+  data: object[];
+}
+
+export type DataDefinition =
+  | DataQuery
+  | DataArray
+  | DataFile
+  | DataTable
+  | DataParquet
+  | DataCSV
+  | DataSpatial
+  | DataJSON
+  | DataJSONObjects;

package/src/spec/Expression.ts

@@ -0,0 +1,31 @@
+export type Expression =
+  | SQLExpression
+  | AggregateExpression;
+
+/** A custom SQL expression. */
+export interface SQLExpression {
+  /**
+   * A SQL expression string to derive a new column value.
+   * Embedded Param refrences, such as `$param + 1`, are supported.
+   * For expressions with aggregate functions, use *agg* instead.
+   */
+  sql: string;
+  /**
+   * A label for this expression, for example to label a plot axis.
+   */
+  label?: string;
+}
+
+/** A custom SQL aggregate expression. */
+export interface AggregateExpression {
+  /**
+   * A SQL expression string to calculate an aggregate value.
+   * Embedded Param references, such as `SUM($param + 1)`, are supported.
+   * For expressions without aggregate functions, use *sql* instead.
+   */
+  agg: string;
+  /**
+   * A label for this expression, for example to label a plot axis.
+   */
+  label?: string;
+}

package/src/spec/HConcat.ts

@@ -0,0 +1,9 @@
+import { Component } from './Spec.js';
+
+/** An hconcat component. */
+export interface HConcat {
+  /**
+   * Horizontally concatenate components in a row layout.
+   */
+  hconcat: Component[];
+}

package/src/spec/HSpace.ts

@@ -0,0 +1,9 @@
+/** An hspace component. */
+export interface HSpace {
+  /**
+   * Horizontal space to place between components.
+   * Number values indicate screen pixels.
+   * String values may use CSS units (em, pt, px, etc).
+   */
+  hspace: number | string;
+}

package/src/spec/Input.ts

@@ -0,0 +1,182 @@
+import { ParamRef } from './Param.js';
+
+/** A menu input component. */
+export interface Menu {
+  /**
+   * A menu input widget.
+   */
+  input: 'menu';
+  /**
+   * The output selection. A selection clause is added for the
+   * currently selected menu option.
+   */
+  as?: ParamRef;
+  /**
+   * The name of a database table to use as a data source for this widget.
+   * Used in conjunction with the `column` property.
+   */
+  from?: string;
+  /**
+   * The name of a database column from which to pull menu options.
+   * The unique column values are used as menu options.
+   * Used in conjunction with the `from` property.
+   */
+  column?: string;
+  /**
+   * A selection to filter the database table indicated by the `from` property.
+   */
+  filterBy?: ParamRef;
+  /**
+   * A text label for this input.
+   */
+  label?: string;
+  /**
+   * An array of menu options, as literal values or option objects.
+   * Option objects have a `value` property and an optional `label` property.
+   * If no label is provided, the (string-coerced) value is used.
+   */
+  options?: Array<any>;
+  /**
+   * The initial selected menu option.
+   */
+  value?: any;
+}
+
+/** A search input component. */
+export interface Search {
+  /**
+   * A text search input widget.
+   */
+  input: 'search';
+  /**
+   * The output selection. A selection clause is added for the
+   * current text search query.
+   */
+  as?: ParamRef;
+  /**
+   * The type of text search query to perform. One of:
+   * - `"contains"` (default): the query string may appear anywhere in the text
+   * - `"prefix"`: the query string must appear at the start of the text
+   * - `"suffix"`: the query string must appear at the end of the text
+   * - `"regexp"`: the query string is a regular expression the text must match
+   */
+  type?: 'contains' | 'prefix' | 'suffix' | 'regexp';
+  /**
+   * The name of a database table to use as an autocomplete data source
+   * for this widget. Used in conjunction with the `column` property.
+   */
+  from?: string;
+  /**
+   * The name of a database column from which to pull valid search results.
+   * The unique column values are used as search autocomplete values.
+   * Used in conjunction with the `from` property.
+   */
+  column?: string;
+  /**
+   * A selection to filter the database table indicated by the `from` property.
+   */
+  filterBy?: ParamRef;
+  /**
+   * A text label for this input.
+   */
+  label?: string;
+}
+
+/** A slider input component. */
+export interface Slider {
+  /**
+   * A slider input widget.
+   */
+  input: 'slider';
+  /**
+   * The output selection. A selection clause is added for the
+   * currently selected slider option.
+   */
+  as?: ParamRef;
+  /**
+   * The name of a database table to use as a data source for this widget.
+   * Used in conjunction with the `column` property.
+   * The minimum and maximum values of the column determine the slider range.
+   */
+  from?: string;
+  /**
+   * The name of a database column whose values determine the slider range.
+   * Used in conjunction with the `from` property.
+   * The minimum and maximum values of the column determine the slider range.
+   */
+  column?: string;
+  /**
+   * A selection to filter the database table indicated by the `from` property.
+   */
+  filterBy?: ParamRef;
+  /**
+   * The minumum slider value.
+   */
+  min?: number;
+  /**
+   * The maximum slider value.
+   */
+  max?: number;
+  /**
+   * The slider step, the amount to increment between consecutive values.
+   */
+  step?: number;
+  /**
+   * A text label for this input.
+   */
+  label?: string;
+  /**
+   * The initial slider value.
+   */
+  value?: number;
+  /**
+   * The width of the slider in screen pixels.
+   */
+  width?: number;
+}
+
+/** A table grid view component. */
+export interface Table {
+  /**
+   * A table grid widget.
+   */
+  input: 'table';
+  /**
+   * The name of a database table to use as a data source for this widget.
+   */
+  from: string;
+  /**
+   * A list of column names to include in the table grid.
+   * If unspecified, all table columns are included.
+   */
+  columns?: string[];
+  /**
+   * A selection to filter the database table indicated by the `from` property.
+   */
+  filterBy?: ParamRef;
+  /**
+   * An object of per-column alignment values.
+   * Column names should be object keys, which map to alignment values.
+   * Valid alignment values are: `"left"`, `"right"`, `"center"`, and `"justify"`.
+   * By default, numbers are right-aligned and other values are left-aligned.
+   */
+  align?: { [column: string]: 'left' | 'right' | 'center' | 'justify' };
+  /**
+   * If a number, sets the total width of the table widget, in pixels.
+   * If an object, provides per-column pixel width values.
+   * Column names should be object keys, mapped to numeric width values.
+   */
+  width?: number | { [column : string]: number };
+  /**
+   * The maximum width of the table widget, in pixels.
+   */
+  maxWidth?: number;
+  /**
+   * The height of the table widget, in pixels.
+   */
+  height?: number;
+  /**
+   * The number of rows load in a new batch upon table scroll.
+   */
+  rowBatch?: number;
+}

package/src/spec/Param.ts

@@ -0,0 +1,68 @@
+export type ParamRef = `$${string}`;
+
+/** Base properties shared by Param definitions. */
+export interface ParamBase {
+  /**
+   * The type of reactive parameter. One of:
+   * - `"value"` (default) for a standard `Param`
+   * - `"intersect"` for a `Selection` that intersects clauses (logical "and")
+   * - `"union"` for a `Selection` that unions clauses (logical "or")
+   * - `"single"` for a `Selection` that retains a single clause only
+   * - `"crossfilter"` for a cross-filtered intersection `Selection`
+   */
+  select?: 'value';
+}
+
+/** A Param definition. */
+export interface Param extends ParamBase {
+  /**
+   * The initial parameter value.
+   */
+  value: ParamValue;
+}
+
+/** A Date-valued Param definition. */
+export interface ParamDate extends ParamBase {
+  /**
+   * The initial parameter value as an ISO date/time
+   * string to be parsed to a Date object.
+   */
+  date: string;
+}
+
+/** Literal Param values. */
+export type ParamLiteral =
+  | string
+  | number
+  | boolean;
+
+/** Valid Param values. */
+export type ParamValue =
+  | ParamLiteral
+  | Array<ParamLiteral | ParamRef>;
+
+/** A Selection definition. */
+export interface Selection {
+  /**
+   * The type of reactive parameter. One of:
+   * - `"value"` (default) for a standard `Param`
+   * - `"intersect"` for a `Selection` that intersects clauses (logical "and")
+   * - `"union"` for a `Selection` that unions clauses (logical "or")
+   * - `"single"` for a `Selection` that retains a single clause only
+   * - `"crossfilter"` for a cross-filtered intersection `Selection`
+   */
+  select: 'crossfilter' | 'intersect' | 'single' | 'union';
+
+  /**
+   * A flag for cross-filtering, where selections made in a plot filter others
+   * but not oneself (default `false`, except for `crossfilter` selections).
+   */
+  cross?: boolean;
+}
+
+/** A Param or Selection definition. */
+export type ParamDefinition =
+  | ParamValue
+  | Param
+  | ParamDate
+  | Selection;

package/src/spec/Plot.ts

@@ -0,0 +1,15 @@
+import { PlotAttributes } from './PlotAttribute.js';
+import { PlotInteractor } from './PlotInteractor.js';
+import { PlotLegend } from './PlotLegend.js';
+import { PlotMark } from './PlotMark.js';
+
+/** A plot component. */
+export interface Plot extends PlotAttributes {
+  /**
+   * An array of plot marks, interactors, or legends.
+   * Marks are graphical elements that make up plot layers.
+   * Unless otherwise configured, interactors will use the nearest
+   * previous mark as a basis for which data fields to select.
+   */
+  plot: (PlotMark | PlotInteractor | PlotLegend)[];
+}