@uwdata/mosaic-spec 0.9.0 → 0.11.0

package/dist/types/ast/ASTNode.d.ts

@@ -12,13 +12,13 @@ export class ASTNode {
      * @param {import('../ast-to-dom.js').InstantiateContext} ctx The instantiation context.
      * @returns {*} The instantiated value of this node.
      */
-    instantiate(ctx: import('../ast-to-dom.js').InstantiateContext): any;
+    instantiate(ctx: import("../ast-to-dom.js").InstantiateContext): any;
     /**
      * Generate ESM code for this AST node.
      * @param {import('../ast-to-esm.js').CodegenContext} ctx The code generator context.
      * @returns {string|void} The generated ESM code for the node.
      */
-    codegen(ctx: import('../ast-to-esm.js').CodegenContext): string | void;
+    codegen(ctx: import("../ast-to-esm.js").CodegenContext): string | void;
     /**
      * @returns {*} This AST node in JSON specification format.
      */

package/dist/types/ast/DataNode.d.ts

@@ -5,7 +5,7 @@
  * @param {import('../parse-spec.js').ParseContext} ctx The parser context.
  * @returns {DataNode} a parsed data definition AST node
  */
-export function parseData(name: string, spec: import('../spec/Data.js').DataDefinition, ctx: import('../parse-spec.js').ParseContext): DataNode;
+export function parseData(name: string, spec: import("../spec/Data.js").DataDefinition, ctx: import("../parse-spec.js").ParseContext): DataNode;
 export const TABLE_DATA: "table";
 export const PARQUET_DATA: "parquet";
 export const CSV_DATA: "csv";
@@ -21,13 +21,13 @@ export class QueryDataNode extends DataNode {
      * @param {import('../ast-to-dom.js').InstantiateContext} ctx The instantiation context.
      * @returns {string|void} The instantiated query.
      */
-    instantiateQuery(ctx: import('../ast-to-dom.js').InstantiateContext): string | void;
+    instantiateQuery(ctx: import("../ast-to-dom.js").InstantiateContext): string | void;
     /**
      * Code generate a table creation query.
      * @param {import('../ast-to-esm.js').CodegenContext} ctx The code generator context.
      * @returns {string|void} The generated query code.
      */
-    codegenQuery(ctx: import('../ast-to-esm.js').CodegenContext): string | void;
+    codegenQuery(ctx: import("../ast-to-esm.js").CodegenContext): string | void;
 }
 export class TableDataNode extends QueryDataNode {
     constructor(name: any, query: any, options: any);

package/dist/types/ast/ParamNode.d.ts

@@ -1,9 +1,8 @@
-export function parseParam(spec: any, ctx: any): SelectionNode | ParamNode;
+export function parseParam(spec: any, ctx: any): import("./SelectionNode.js").SelectionNode | ParamNode;
 export class ParamNode extends ASTNode {
     value: any;
     date: any;
     instantiate(ctx: any): any;
     codegen(ctx: any): string;
 }
-import { SelectionNode } from './SelectionNode.js';
 import { ASTNode } from './ASTNode.js';

package/dist/types/ast/ParamRefNode.d.ts

@@ -2,7 +2,7 @@ export class ParamRefNode extends ASTNode {
     constructor(name: any);
     name: any;
     instantiate(ctx: any): any;
-    codegen(): string;
+    codegen(ctx: any): string;
     toJSON(): string;
 }
 import { ASTNode } from './ASTNode.js';

package/dist/types/ast/SelectionNode.d.ts

@@ -1,12 +1,24 @@
+export function parseSelection(spec: any, ctx: any): SelectionNode;
 export class SelectionNode extends ASTNode {
-    constructor(select: string, cross: any);
+    /**
+     * Create a Selection AST node.
+     * @param {string} select The selection type.
+     * @param {OptionsNode} options Selection options.
+     */
+    constructor(select?: string, options?: OptionsNode);
     select: string;
-    cross: any;
+    options: OptionsNode;
     instantiate(ctx: any): any;
     codegen(ctx: any): string;
     toJSON(): {
         select: string;
-        cross: any;
     };
 }
+export class IncludeNode extends ASTNode {
+    constructor(refs: any);
+    refs: any;
+    instantiate(ctx: any): any;
+    codegen(ctx: any): string;
+}
 import { ASTNode } from './ASTNode.js';
+import { OptionsNode } from './OptionsNode.js';

package/dist/types/ast/TransformNode.d.ts

@@ -1,4 +1,4 @@
-export function parseTransform(spec: any, ctx: any): TransformNode;
+export function parseTransform(spec: any, ctx: any): BinTransformNode | TransformNode;
 export class TransformNode extends ASTNode {
     constructor(name: any, args: any, options: any);
     name: any;
@@ -10,4 +10,12 @@ export class TransformNode extends ASTNode {
         [x: number]: any;
     };
 }
+export class BinTransformNode extends ASTNode {
+    constructor(name: any, arg: any, options: any);
+    name: any;
+    arg: any;
+    options: any;
+    instantiate(ctx: any): any;
+    codegen(ctx: any): string;
+}
 import { ASTNode } from './ASTNode.js';

package/dist/types/constants.d.ts

@@ -5,6 +5,7 @@ export const OPTIONS: "options";
 export const SELECTION: "selection";
 export const PARAMREF: "paramref";
 export const PARAM: "param";
+export const INCLUDE: "include";
 export const SELECT: "select";
 export const VALUE: "value";
 export const CROSSFILTER: "crossfilter";

package/dist/types/index.d.ts

@@ -22,7 +22,7 @@ export { VSpaceNode } from "./ast/VSpaceNode.js";
 /**
  * A Mosaic declarative specification.
  */
-export type Spec = import('./spec/Spec.js').Spec;
+export type Spec = import("./spec/Spec.js").Spec;
 export { astToDOM, InstantiateContext } from "./ast-to-dom.js";
 export { astToESM, CodegenContext } from "./ast-to-esm.js";
 export { DataNode, QueryDataNode, TableDataNode, FileDataNode, CSVDataNode, JSONDataNode, ParquetDataNode, SpatialDataNode, LiteralJSONDataNode } from "./ast/DataNode.js";

package/dist/types/parse-spec.d.ts

@@ -20,7 +20,7 @@
  *  dataset definition AST nodes.
  * @returns {SpecNode} The top-level AST spec node.
  */
-export function parseSpec(spec: import('./spec/Spec.js').Spec, options?: {
+export function parseSpec(spec: import("./spec/Spec.js").Spec, options?: {
     components?: Map<string, Function>;
     transforms?: Set<string>;
     inputs?: Set<string>;
@@ -59,15 +59,40 @@ export class ParseContext {
     plotDefaults: import("./ast/PlotAttributeNode.js").PlotAttributeNode[];
     parseComponent(spec: any): any;
     /**
-     * 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: any, makeNode?: () => ParamNode | SelectionNode): ParamRefNode | LiteralNode;
-    maybeSelection(value: any): LiteralNode | ParamRefNode;
+    maybeParam(value: any): ParamRefNode | LiteralNode;
+    /**
+     * 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: any): ParamRefNode | LiteralNode;
+    /**
+     * 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: string, makeNode?: () => ParamNode | SelectionNode): ParamRefNode | null;
+    /**
+     * 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: string, strict?: boolean): ParamRefNode | null;
     error(message: any, data: any): void;
 }
 /**
@@ -80,7 +105,7 @@ export type PlotNames = {
     marks: Set<string>;
 };
 import { SpecNode } from './ast/SpecNode.js';
-import { ParamNode } from './ast/ParamNode.js';
-import { SelectionNode } from './ast/SelectionNode.js';
 import { ParamRefNode } from './ast/ParamRefNode.js';
 import { LiteralNode } from './ast/LiteralNode.js';
+import { ParamNode } from './ast/ParamNode.js';
+import { SelectionNode } from './ast/SelectionNode.js';

package/dist/types/spec/Input.d.ts

@@ -162,6 +162,11 @@ export interface Table {
      * A table grid widget.
      */
     input: 'table';
+    /**
+     * The output selection. A selection clause is added for each
+     * currently selected table row.
+     */
+    as?: ParamRef;
     /**
      * The name of a database table to use as a data source for this widget.
      */

package/dist/types/spec/Param.d.ts

@@ -46,6 +46,18 @@ export interface Selection {
      * but not oneself (default `false`, except for `crossfilter` selections).
      */
     cross?: boolean;
+    /**
+     * A flag for setting an initial empty selection state. If true, a selection
+     * with no clauses corresponds to an empty selection with no records. If
+     * 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. */
 export type ParamDefinition = ParamValue | Param | ParamDate | Selection;

package/dist/types/spec/PlotAttribute.d.ts

@@ -1328,6 +1328,12 @@ export interface PlotAttributes {
      * For continuous scales only.
      */
     rNice?: boolean | number | Interval | 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.
+     */
+    rLabel?: string | null | ParamRef;
     /**
      * If true, shorthand for a transform suitable for percentages, mapping
      * proportions in [0, 1] to [0, 100].

package/dist/types/spec/Transform.d.ts

@@ -31,20 +31,47 @@ type Arg2Opt = Arg | [Arg, Arg?];
  * second and third arguments are optional.
  */
 type Arg3Opt = Arg | [Arg, Arg?, Arg?];
-/** Bin transform options. */
-export interface BinOptions {
+/** Binning interval names. */
+export type BinInterval = 'date' | 'number' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'month' | 'year';
+export interface Bin {
+    /**
+     * Bin a continuous variable into discrete intervals. The bin argument
+     * specifies a data column or expression to bin. Both numerical and
+     * temporal (date/time) values are supported.
+     */
+    bin: Arg | [Arg];
+    /**
+     * The interval bin unit to use, typically used to indicate a date/time
+     * unit for binning temporal values, such as `hour`, `day`, or `month`.
+     * If `date`, the extent of data values is used to automatically select
+     * an interval for temporal data. The value `number` enforces normal
+     * numerical binning, even over temporal data. If unspecified, defaults
+     * to `number` for numerical data and `date` for temporal data.
+     */
+    interval?: BinInterval;
+    /**
+     * The step size to use between bins. When binning numerical values (or
+     * interval type `number`), this setting specifies the numerical step size.
+     * For data/time intervals, this indicates the number of steps of that unit,
+     * such as hours, days, or years.
+     */
+    step?: number;
     /**
      * The target number of binning steps to use. To accommodate human-friendly
-     * bin boundaries, the actual number of bins may diverge from this exact number.
+     * ("nice") bin boundaries, the actual number of bins may diverge from this
+     * exact value. This option is ignored when **step** is specified.
      */
     steps?: number;
     /**
-     * The minimum allowed bin step size (default `0`).
-     * For example, a setting of `1` will prevent step sizes less than 1.
+     * The minimum allowed bin step size (default `0`) when performing numerical
+     * binning. For example, a setting of `1` prevents step sizes less than 1.
+     * This option is ignored when **step** is specified.
      */
     minstep?: number;
     /**
-     * A flag requesting "nice" human-friendly step sizes (default `true`).
+     * A flag (default `true`) requesting "nice" human-friendly end points and
+     * step sizes when performing numerical binning. When **step** is specified,
+     * this option affects the binning end points (e.g., origin) only.
      */
     nice?: true;
     /**
@@ -53,13 +80,6 @@ export interface BinOptions {
      */
     offset?: number;
 }
-export interface Bin {
-    /**
-     * Bin a continuous variable into discrete intervals. This transform accepts
-     * a data column to bin over as well as an optional bin options object.
-     */
-    bin: Arg | [Arg] | [Arg, BinOptions];
-}
 export interface DateMonth {
     /**
      * Transform a Date value to a month boundary for cyclic comparison.

package/dist/types/util.d.ts

@@ -2,11 +2,11 @@ export function paramRef(value: any): any;
 export function paramStr(value: any): any;
 export function toParamRef(name: any): string;
 export function toArray(value: any): any[];
-export function isArray(value: any): boolean;
+export function isArray(value: any): value is any[];
 export function isObject(value: any): boolean;
-export function isNumber(value: any): boolean;
+export function isNumber(value: any): value is number;
 export function isNumberOrString(value: any): boolean;
-export function isString(value: any): boolean;
+export function isString(value: any): value is string;
 export function isFunction(value: any): boolean;
 export function error(message: any, data: any): void;
 export function isoparse(string: any, fallback: any): any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-spec",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Declarative specification of Mosaic-powered applications.",
   "keywords": [
     "mosaic",
@@ -10,7 +10,7 @@
     "specification"
   ],
   "license": "BSD-3-Clause",
-  "author": "Jeffrey Heer (http://idl.cs.washington.edu)",
+  "author": "Jeffrey Heer (https://idl.uw.edu)",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -28,15 +28,15 @@
     "types": "tsc -p tsconfig.json && npm run schema",
     "schema": "ts-json-schema-generator -f tsconfig.json -p src/spec/Spec.ts -t Spec --no-type-check --no-ref-encode --functions hide > dist/mosaic-schema.json",
     "pretest": "npm run prebuild && npm run types",
-    "test": "mocha 'test/**/*-test.js' && tsc -p jsconfig.json",
+    "test": "vitest run && tsc -p jsconfig.json",
     "version": "cd ../.. && npm run docs:schema",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
-    "@uwdata/mosaic-core": "^0.9.0",
-    "@uwdata/mosaic-sql": "^0.9.0",
-    "@uwdata/vgplot": "^0.9.0",
-    "ts-json-schema-generator": "^2.2.0"
+    "@uwdata/mosaic-core": "^0.11.0",
+    "@uwdata/mosaic-sql": "^0.11.0",
+    "@uwdata/vgplot": "^0.11.0",
+    "ts-json-schema-generator": "^2.3.0"
   },
-  "gitHead": "89bb9b0dfa747aed691eaeba35379525a6764c61"
+  "gitHead": "861d616f39926a1d2aee83b59dbdd70b0b3caf12"
 }

package/src/ast/ParamNode.js

@@ -1,19 +1,18 @@
 import { isArray, isObject, isoparse } from '../util.js';
 import { ASTNode } from './ASTNode.js';
+import { parseSelection } from './SelectionNode.js';
 import { CROSSFILTER, INTERSECT, PARAM, SINGLE, UNION, VALUE } from '../constants.js';
-import { SelectionNode } from './SelectionNode.js';
 
 const paramTypes = new Set([VALUE, SINGLE, CROSSFILTER, INTERSECT, UNION]);
 
 export function parseParam(spec, ctx) {
   const param = isObject(spec) ? spec : { value: spec };
-  const { select = VALUE, cross, date, value } = param;
+  const { select = VALUE, value, date } = param;
   if (!paramTypes.has(select)) {
     ctx.error(`Unrecognized param type: ${select}`, param);
   }
-
   if (select !== VALUE) {
-    return new SelectionNode(select, cross);
+    return parseSelection(spec, ctx);
   } else if (isArray(value)) {
     return new ParamNode(value.map(v => ctx.maybeParam(v)));
   } else {

package/src/ast/ParamRefNode.js

@@ -12,7 +12,7 @@ export class ParamRefNode extends ASTNode {
     return ctx.activeParams?.get(this.name);
   }
 
-  codegen() {
+  codegen(ctx) { // eslint-disable-line no-unused-vars
     return toParamRef(this.name);
   }
 

package/src/ast/SelectionNode.js

@@ -1,26 +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) {
+  /**
+   * 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.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 } = this;
-    return ctx.api.Selection[select]({ cross });
+    return this.refs.map(ref => ref.instantiate(ctx));
   }
 
   codegen(ctx) {
-    const { select, cross } = this;
-    const arg = cross != null ? `{ cross: ${cross} }` : '';
-    return `${ctx.ns()}Selection.${select}(${arg})`;
+    return `[${this.refs.map(ref => ref.codegen(ctx)).join(', ')}]`;
   }
 
   toJSON() {
-    const { select, cross } = this;
-    return { select, cross };
+    return this.refs.map(ref => ref.toJSON());
   }
 }

package/src/ast/TransformNode.js

@@ -1,5 +1,6 @@
 import { ASTNode } from './ASTNode.js';
 import { TRANSFORM } from '../constants.js';
+import { parseOptions } from './OptionsNode.js';
 
 function toArray(value) {
   return value == null ? [] : [value].flat();
@@ -17,16 +18,21 @@ export function parseTransform(spec, ctx) {
     return; // return undefined to signal no transform!
   }
 
-  const args = name === 'count' || name == null ? [] : toArray(spec[name]);
-  const options = {
-    distinct: spec.distinct,
-    orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
-    partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
-    rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
-    range: spec.range ? ctx.maybeParam(spec.range) : null
-  };
-
-  return new TransformNode(name, args, options);
+  if (name === 'bin') {
+    const { bin, ...options } = spec;
+    const [arg] = toArray(bin);
+    return new BinTransformNode(name, arg, parseOptions(options, ctx));
+  } else {
+    const args = name === 'count' && !spec[name] ? [] : toArray(spec[name]);
+    const options = {
+      distinct: spec.distinct,
+      orderby: toArray(spec.orderby).map(v => ctx.maybeParam(v)),
+      partitionby: toArray(spec.partitionby).map(v => ctx.maybeParam(v)),
+      rows: spec.rows ? ctx.maybeParam(spec.rows) : null,
+      range: spec.range ? ctx.maybeParam(spec.range) : null
+    };
+    return new TransformNode(name, args, options);
+  }
 }
 
 export class TransformNode extends ASTNode {
@@ -112,6 +118,34 @@ export class TransformNode extends ASTNode {
   }
 }
 
+export class BinTransformNode extends ASTNode {
+  constructor(name, arg, options) {
+    super(TRANSFORM);
+    this.name = name;
+    this.arg = arg;
+    this.options = options;
+  }
+
+  instantiate(ctx) {
+    const { name, arg, options } = this;
+    return ctx.api[name](arg, options.instantiate(ctx));
+  }
+
+  codegen(ctx) {
+    const { name, arg, options } = this;
+    const opt = options.codegen(ctx);
+    return `${ctx.ns()}${name}(`
+        + JSON.stringify(arg)
+        + (opt ? `, ${opt}` : '')
+        + ')';
+  }
+
+  toJSON() {
+    const { name, arg, options } = this;
+    return { [name]: arg, ...options.toJSON() };
+  }
+}
+
 function simplify(array) {
   return array.length === 0 ? '' : array.length === 1 ? array[0] : array;
 }

package/src/constants.js

@@ -14,6 +14,7 @@ export const OPTIONS = 'options';
 export const SELECTION = 'selection';
 export const PARAMREF = 'paramref';
 export const PARAM = 'param';
+export const INCLUDE = 'include';
 
 // param and selection types
 export const SELECT = 'select';

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

@@ -163,6 +163,11 @@ export interface Table {
    * A table grid widget.
    */
   input: 'table';
+  /**
+   * The output selection. A selection clause is added for each
+   * currently selected table row.
+   */
+  as?: ParamRef;
   /**
    * The name of a database table to use as a data source for this widget.
    */