@uwdata/mosaic-spec 0.10.0 → 0.12.0

package/src/ast/PlotMarkNode.js

@@ -1,4 +1,4 @@
-import { AGG, MARK, SQL } from '../constants.js';
+import { MARK, SQL } from '../constants.js';
 import { isObject } from '../util.js';
 import { ASTNode } from './ASTNode.js';
 import { parseExpression } from './ExpressionNode.js';
@@ -8,7 +8,7 @@ import { parseTransform } from './TransformNode.js';
 
 function maybeTransform(value, ctx) {
   if (isObject(value)) {
-    return (value[SQL] || value[AGG])
+    return value[SQL]
       ? parseExpression(value, ctx)
       : parseTransform(value, ctx);
   }

package/src/ast/SelectionNode.js

@@ -1,30 +1,62 @@
 import { ASTNode } from './ASTNode.js';
-import { INTERSECT, SELECTION } from '../constants.js';
+import { OptionsNode, parseOptions } from './OptionsNode.js';
+import { INCLUDE, INTERSECT, SELECTION } from '../constants.js';
+import { paramRef, toArray } from '../util.js';
+
+export function parseSelection(spec, ctx) {
+  const { select, include, ...options } = spec;
+  const opt = parseOptions(options, ctx);
+  if (include) {
+    opt.options.include = new IncludeNode(
+      toArray(include).map(ref => ctx.selectionRef(paramRef(ref)))
+    );
+  }
+  return new SelectionNode(select, opt);
+}
 
 export class SelectionNode extends ASTNode {
-  constructor(select = INTERSECT, cross, empty) {
+  /**
+   * Create a Selection AST node.
+   * @param {string} select The selection type.
+   * @param {OptionsNode} options Selection options.
+   */
+  constructor(select = INTERSECT, options = new OptionsNode({})) {
     super(SELECTION);
     this.select = select;
-    this.cross = cross;
-    this.empty = empty;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { select, options } = this;
+    return ctx.api.Selection[select](options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { select, options } = this;
+    return `${ctx.ns()}Selection.${select}(${options.codegen(ctx)})`;
+  }
+
+  toJSON() {
+    const { select, options } = this;
+    return { select, ...options.toJSON() };
+  }
+}
+
+export class IncludeNode extends ASTNode {
+  constructor(refs) {
+    super(INCLUDE);
+    this.refs = refs;
   }
 
   instantiate(ctx) {
-    const { select, cross, empty } = this;
-    return ctx.api.Selection[select]({ cross, empty });
+    return this.refs.map(ref => ref.instantiate(ctx));
   }
 
   codegen(ctx) {
-    const { select, cross, empty } = this;
-    const args = [['cross', cross], ['empty', empty]]
-      .filter(a => a[1] != null)
-      .map(a => `${a[0]}: ${a[1]}`);
-    const arg = args.length ? `{ ${args.join(', ')} }` : '';
-    return `${ctx.ns()}Selection.${select}(${arg})`;
+    return `[${this.refs.map(ref => ref.codegen(ctx)).join(', ')}]`;
   }
 
   toJSON() {
-    const { select, cross, empty } = this;
-    return { select, cross, empty };
+    return this.refs.map(ref => ref.toJSON());
   }
 }

package/src/ast/TransformNode.js

@@ -2,8 +2,10 @@ import { ASTNode } from './ASTNode.js';
 import { TRANSFORM } from '../constants.js';
 import { parseOptions } from './OptionsNode.js';
 
-function toArray(value) {
-  return value == null ? [] : [value].flat();
+function toArray(value, ctx) {
+  return value == null
+    ? []
+    : [value].flat().map(v => ctx.maybeParam(v));
 }
 
 export function parseTransform(spec, ctx) {
@@ -20,14 +22,14 @@ export function parseTransform(spec, ctx) {
 
   if (name === 'bin') {
     const { bin, ...options } = spec;
-    const [arg] = toArray(bin);
+    const [arg] = toArray(bin, ctx);
     return new BinTransformNode(name, arg, parseOptions(options, ctx));
   } else {
-    const args = name === 'count' && !spec[name] ? [] : toArray(spec[name]);
+    const args = name === 'count' && !spec[name] ? [] : toArray(spec[name], ctx);
     const options = {
       distinct: spec.distinct,
-      orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
-      partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
+      orderby: toArray(spec.orderby, ctx),
+      partitionby: toArray(spec.partitionby, ctx),
       rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
       range: spec.range ? ctx.maybeParam(spec.range) : null
     };
@@ -47,7 +49,7 @@ export class TransformNode extends ASTNode {
     const { name, args, options } = this;
     const { distinct, orderby, partitionby, rows, range } = options;
 
-    let expr = ctx.api[name](...args);
+    let expr = ctx.api[name](...args.map(a => a.instantiate(ctx)));
     if (distinct) {
       expr = expr.distinct();
     }
@@ -70,7 +72,7 @@ export class TransformNode extends ASTNode {
     const { distinct, orderby, partitionby, rows, range } = options;
 
     let str = `${ctx.ns()}${name}(`
-      + args.map(v => JSON.stringify(v)).join(', ')
+      + args.map(v => v.codegen(ctx)).join(', ')
       + ')';
 
     if (distinct) {
@@ -97,7 +99,7 @@ export class TransformNode extends ASTNode {
     const { name, args, options } = this;
     const { distinct, orderby, partitionby, rows, range } = options;
 
-    const json = { [name]: simplify(args) };
+    const json = { [name]: simplify(args.map(v => v.toJSON())) };
 
     if (distinct) {
       json.distinct = true;
@@ -128,21 +130,21 @@ export class BinTransformNode extends ASTNode {
 
   instantiate(ctx) {
     const { name, arg, options } = this;
-    return ctx.api[name](arg, options.instantiate(ctx));
+    return ctx.api[name](arg.instantiate(ctx), options.instantiate(ctx));
   }
 
   codegen(ctx) {
     const { name, arg, options } = this;
     const opt = options.codegen(ctx);
     return `${ctx.ns()}${name}(`
-        + JSON.stringify(arg)
+        + arg.codegen(ctx)
         + (opt ? `, ${opt}` : '')
         + ')';
   }
 
   toJSON() {
     const { name, arg, options } = this;
-    return { [name]: arg, ...options.toJSON() };
+    return { [name]: arg.toJSON(), ...options.toJSON() };
   }
 }
 

package/src/config/transforms.js

@@ -10,6 +10,7 @@ export function transformNames(overrides = []) {
     'centroid',
     'centroidX',
     'centroidY',
+    'column',
     'count',
     'covariance',
     'covarPop',

package/src/constants.js

@@ -13,7 +13,9 @@ export const OPTIONS = 'options';
 // params and selections
 export const SELECTION = 'selection';
 export const PARAMREF = 'paramref';
+export const COLUMPARAMREF = 'columnparamref';
 export const PARAM = 'param';
+export const INCLUDE = 'include';
 
 // param and selection types
 export const SELECT = 'select';
@@ -29,7 +31,6 @@ export const DATA = 'data';
 // sql expressions
 export const EXPRESSION = 'expression';
 export const SQL = 'sql';
-export const AGG = 'agg';
 
 // inputs
 export const INPUT = 'input';

package/src/parse-spec.js

@@ -68,7 +68,6 @@ export class ParseContext {
   }
 
   parse(spec) {
-    // eslint-disable-next-line no-unused-vars
     const {
       meta,
       config,
@@ -113,29 +112,67 @@ export class ParseContext {
   }
 
   /**
-   * Test if a value is param reference, if so, generate a paramter definition
-   * as needed and return a new ParamRefNode. Otherwise, return a LiteralNode.
+   * Test if a value is a param reference, if so, generates a parameter
+   * definition as needed and returns a new ParamRefNode. Otherwise,
+   * returns a LiteralNode for the given value.
    * @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;
+  maybeParam(value) {
     const name = paramRef(value);
+    return name
+      ? this.paramRef(name)
+      : new LiteralNode(value);
+  }
 
-    if (name) {
-      if (!params.has(name)) {
-        const p = makeNode();
-        params.set(name, p);
-      }
-      return new ParamRefNode(name);
+  /**
+   * Test if a value is a param reference, if so, generates a selection
+   * definition as needed and returns a new ParamRefNode. Otherwise,
+   * returns a LiteralNode for the given value.
+   * @param {*} value The value to test.
+   * @returns {ParamRefNode|LiteralNode} An AST node for the input value.
+   */
+  maybeSelection(value) {
+    const name = paramRef(value);
+    return name
+      ? this.selectionRef(name)
+      : new LiteralNode(value);
+  }
+
+  /**
+   * Create a parameter reference. Generates a parameter definition if needed
+   * and returns a new ParamRefNode.
+   * @param {string} name The parameter name.
+   * @param {() => ParamNode | SelectionNode} [makeNode] A Param or Selection AST
+   *  node constructor.
+   * @returns {ParamRefNode|null} A node referring to the param or selection.
+   */
+  paramRef(name, makeNode = () => new ParamNode) {
+    const { params } = this;
+    if (!name) return null;
+    let p = params.get(name);
+    if (!p) {
+      p = makeNode();
+      params.set(name, p);
     }
-    return new LiteralNode(value);
+    return new ParamRefNode(name);
   }
 
-  maybeSelection(value) {
-    return this.maybeParam(value, () => new SelectionNode);
+  /**
+   * Create a selection reference. Generates a selection definition if needed
+   * and returns a new ParamRefNode. Returns null if a non-selection parameter
+   * with the same name already exists and *strict* is true.
+   * @param {string} name The selection name.
+   * @param {boolean} [strict=false] Indicates if this method may return param
+   *  references (false, default) or only selection references (true).
+   * @returns {ParamRefNode|null} A node referring to the param or selection.
+   */
+  selectionRef(name, strict = false) {
+    const p = this.params.get(name);
+    if (strict && p && !(p instanceof SelectionNode)) {
+      return null;
+    }
+    return this.paramRef(name, () => new SelectionNode);
   }
 
   error(message, data) {

package/src/spec/Input.ts

@@ -171,7 +171,7 @@ export interface Table {
   /**
    * The name of a database table to use as a data source for this widget.
    */
-  from: string;
+  from: string | ParamRef;
   /**
    * A list of column names to include in the table grid.
    * If unspecified, all table columns are included.

package/src/spec/Param.ts

@@ -65,6 +65,13 @@ export interface Selection {
    * false, a selection with no clauses selects all values.
    */
   empty?: boolean;
+
+  /**
+   * Upstream selections whose clauses should be included as part of this
+   * selection. Any clauses or activations published to the upstream
+   * selections will be relayed to this selection.
+   */
+  include?: ParamRef | ParamRef[];
 }
 
 /** A Param or Selection definition. */

package/src/spec/PlotAttribute.ts

@@ -178,13 +178,21 @@ export interface PlotAttributes {
   grid?: boolean | string | ParamRef;
 
   /**
-   * A textual label to show on the axis or legend; if null, show no label. By
-   * default the scale label is inferred from channel definitions, possibly with
-   * an arrow (↑, →, ↓, or ←) to indicate the direction of increasing value.
+   * The [aria-label attribute][1] on the SVG root.
    *
-   * For axes and legends only.
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
    */
-  label?: string | null | ParamRef;
+  ariaLabel?: string | null;
+
+  /**
+   * The [aria-description attribute][1] on the SVG root.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description
+   */
+  ariaDescription?: string | null;
+
+  /** The default clip for all marks. */
+  clip?: 'frame' | 'sphere' | boolean | null | ParamRef;
 
 
   // x scale attributes

package/src/spec/PlotFrom.ts

@@ -9,7 +9,7 @@ export type PlotDataInline = any[];
 /** Input data specification for a plot mark. */
 export interface PlotFrom {
   /** The name of the backing data table. */
-  from: string;
+  from: string | ParamRef;
   /** A selection that filters the mark data. */
   filterBy?: ParamRef;
   /**

package/src/spec/PlotInteractor.ts

@@ -3,6 +3,7 @@ import { IntervalX, IntervalY } from './interactors/Interval1D.js';
 import { IntervalXY } from './interactors/Interval2D.js';
 import { NearestX, NearestY } from './interactors/Nearest.js';
 import { Pan, PanX, PanY, PanZoom, PanZoomX, PanZoomY } from './interactors/PanZoom.js';
+import { Region } from './interactors/Region.js';
 import { Toggle, ToggleColor, ToggleX, ToggleY } from './interactors/Toggle.js';
 
 /** A plot interactor entry. */
@@ -13,13 +14,14 @@ export type PlotInteractor =
   | IntervalXY
   | NearestX
   | NearestY
-  | Toggle
-  | ToggleX
-  | ToggleY
-  | ToggleColor
   | Pan
   | PanX
   | PanY
   | PanZoom
   | PanZoomX
-  | PanZoomY;
+  | PanZoomY
+  | Region
+  | Toggle
+  | ToggleX
+  | ToggleY
+  | ToggleColor;

package/src/spec/Spec.ts

@@ -1,5 +1,5 @@
 import { DataDefinition } from './Data.js';
-import { ParamDefinition } from './Param.js';
+import { ParamDefinition, ParamRef } from './Param.js';
 import { HConcat } from './HConcat.js';
 import { VConcat } from './VConcat.js';
 import { HSpace } from './HSpace.js';

package/src/spec/Transform.ts

@@ -17,7 +17,7 @@ export interface AggregateOptions {
 }
 
 /** A transform argument. */
-type Arg = string | number | boolean;
+type Arg = string | number | boolean | ParamRef;
 
 /** A zero argument transform signature. */
 type Arg0 = null | [];
@@ -102,6 +102,14 @@ export interface Bin {
   offset?: number;
 }
 
+/* A column transform. */
+export interface Column {
+  /**
+   * Intpret a string or param-value as a column reference.
+   */
+  column: Arg1;
+}
+
 /* A dateMonth transform. */
 export interface DateMonth {
   /**
@@ -423,6 +431,7 @@ export interface NthValue extends WindowOptions {
 /** A data transform that maps one column value to another. */
 export type ColumnTransform =
   | Bin
+  | Column
   | DateMonth
   | DateMonthDay
   | DateDay

package/src/spec/interactors/BrushStyles.ts

@@ -0,0 +1,27 @@
+/** Styles for rectangular selection brushes. */
+export interface BrushStyles {
+  /**
+   * The overall opacity of the brush rectangle.
+   */
+  opacity?: number;
+  /**
+   * The fill opacity of the brush rectangle.
+   */
+  fillOpacity?: number;
+  /**
+   * The stroke opacity of the brush rectangle.
+   */
+  strokeOpacity?: number;
+  /**
+   * The fill color of the brush rectangle.
+   */
+  fill?: string;
+  /**
+   * The stroke color of the brush rectangle.
+   */
+  stroke?: string;
+  /**
+   * The stroke dash array of the brush rectangle.
+   */
+  strokeDasharray?: string;
+}

package/src/spec/interactors/Interval1D.ts

@@ -1,28 +1,5 @@
 import { ParamRef } from '../Param.js';
-
-/** Styles for rectangular selection brushes. */
-export interface BrushStyles {
-  /**
-   * The overall opacity of the brush rectangle.
-   */
-  opacity?: number;
-  /**
-   * The fill opacity of the brush rectangle.
-   */
-  fillOpacity?: number;
-  /**
-   * The stroke opacity of the brush rectangle.
-   */
-  strokeOpacity?: number;
-  /**
-   * The fill color of the brush rectangle.
-   */
-  fill?: string;
-  /**
-   * The stroke color of the brush rectangle.
-   */
-  stroke?: string;
-}
+import { BrushStyles } from './BrushStyles.js';
 
 /** Options for 1D interval interactors. */
 export interface Interval1DOptions {
@@ -39,13 +16,14 @@ export interface Interval1DOptions {
   field?: string;
   /**
    * The size of an interative pixel (default `1`). Larger pixel sizes reduce
-   * the brush resolution, which can reduce the size of data cube indexes.
+   * the brush resolution, which can reduce the size of pre-aggregated
+   * materialized views.
    */
   pixelSize?: number;
   /**
-   * A flag indicating if peer (sibling) marks are when cross-filtering
-   * (default `true`). If set, peer marks will not be filtered by this
-   * interactor's selection in cross-filtering setups.
+   * A flag indicating if peer (sibling) marks are excluded when
+   * cross-filtering (default `true`). If set, peer marks will not be
+   * filtered by this interactor's selection in cross-filtering setups.
    */
   peers?: boolean;
   /**

package/src/spec/interactors/Interval2D.ts

@@ -1,5 +1,5 @@
 import { ParamRef } from '../Param.js';
-import { BrushStyles } from './Interval1D.js';
+import { BrushStyles } from './BrushStyles.js';
 
 /** Options for 2D interval interactors. */
 export interface Interval2DOptions {
@@ -23,13 +23,14 @@ export interface Interval2DOptions {
   yfield?: string;
   /**
    * The size of an interative pixel (default `1`). Larger pixel sizes reduce
-   * the brush resolution, which can reduce the size of data cube indexes.
+   * the brush resolution, which can reduce the size of pre-aggregated
+   * materialized views.
    */
   pixelSize?: number;
   /**
-   * A flag indicating if peer (sibling) marks are when cross-filtering
-   * (default `true`). If set, peer marks will not be filtered by this
-   * interactor's selection in cross-filtering setups.
+   * A flag indicating if peer (sibling) marks are excluded when
+   * cross-filtering (default `true`). If set, peer marks will not be
+   * filtered by this interactor's selection in cross-filtering setups.
    */
   peers?: boolean;
   /**

package/src/spec/interactors/Region.ts

@@ -0,0 +1,34 @@
+import { ParamRef } from '../Param.js';
+import { BrushStyles } from './BrushStyles.js';
+
+/** Options for region interactors. */
+export interface RegionOptions {
+  /**
+   * The output selection. A clause of the form
+   * `(field = value1) OR (field = value2) ...`
+   * is added for the currently selected values.
+   */
+  as: ParamRef;
+  /**
+   * The encoding channels over which to select values.
+   * For a selected mark, selection clauses will cover
+   * the backing data fields for each channel.
+   */
+  channels: string[];
+  /**
+   * A flag indicating if peer (sibling) marks are excluded when
+   * cross-filtering (default `true`). If set, peer marks will not be
+   * filtered by this interactor's selection in cross-filtering setups.
+   */
+  peers?: boolean;
+  /**
+   * CSS styles for the brush (SVG `rect`) element.
+   */
+  brush?: BrushStyles;
+}
+
+/** A rectangular region interactor. */
+export interface Region extends RegionOptions {
+  /** Select aspects of individual marks within a 2D range. */
+  select: 'region';
+}

package/src/spec/interactors/Toggle.ts

@@ -9,9 +9,9 @@ export interface ToggleOptions {
    */
   as: ParamRef;
   /**
-   * A flag indicating if peer (sibling) marks are when cross-filtering
-   * (default `true`). If set, peer marks will not be filtered by this
-   * interactor's selection in cross-filtering setups.
+   * A flag indicating if peer (sibling) marks are excluded when
+   * cross-filtering (default `true`). If set, peer marks will not be
+   * filtered by this interactor's selection in cross-filtering setups.
    */
   peers?: boolean;
 }

package/src/spec/marks/Marks.ts

@@ -432,6 +432,12 @@ export interface MarkOptions {
     | (TipOptions & { pointer?: TipPointer })
     | ParamRef;
 
+  /**
+   * Additional named channels, for example to include in a tooltip.
+   * Consists of (channel name, data field name) key-value pairs.
+   */
+  channels?: Record<string, string>;
+
   /**
    * How to clip the mark; one of:
    *