@uwdata/mosaic-spec 0.9.0 → 0.10.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/SelectionNode.d.ts

@@ -1,12 +1,14 @@
 export class SelectionNode extends ASTNode {
-    constructor(select: string, cross: any);
+    constructor(select: string, cross: any, empty: any);
     select: string;
     cross: any;
+    empty: any;
     instantiate(ctx: any): any;
     codegen(ctx: any): string;
     toJSON(): {
         select: string;
         cross: any;
+        empty: any;
     };
 }
 import { ASTNode } from './ASTNode.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/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>;

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,12 @@ 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;
 }
 /** 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.10.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",
@@ -33,10 +33,10 @@
     "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.10.0",
+    "@uwdata/mosaic-sql": "^0.10.0",
+    "@uwdata/vgplot": "^0.10.0",
+    "ts-json-schema-generator": "^2.3.0"
   },
-  "gitHead": "89bb9b0dfa747aed691eaeba35379525a6764c61"
+  "gitHead": "94fc4f0d4efc622001f6afd6714d1e9dda745be2"
 }

package/src/ast/ParamNode.js

@@ -7,13 +7,13 @@ 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, cross, empty, date, value } = param;
   if (!paramTypes.has(select)) {
     ctx.error(`Unrecognized param type: ${select}`, param);
   }
 
   if (select !== VALUE) {
-    return new SelectionNode(select, cross);
+    return new SelectionNode(select, cross, empty);
   } else if (isArray(value)) {
     return new ParamNode(value.map(v => ctx.maybeParam(v)));
   } else {

package/src/ast/SelectionNode.js

@@ -2,25 +2,29 @@ import { ASTNode } from './ASTNode.js';
 import { INTERSECT, SELECTION } from '../constants.js';
 
 export class SelectionNode extends ASTNode {
-  constructor(select = INTERSECT, cross) {
+  constructor(select = INTERSECT, cross, empty) {
     super(SELECTION);
     this.select = select;
     this.cross = cross;
+    this.empty = empty;
   }
 
   instantiate(ctx) {
-    const { select, cross } = this;
-    return ctx.api.Selection[select]({ cross });
+    const { select, cross, empty } = this;
+    return ctx.api.Selection[select]({ cross, empty });
   }
 
   codegen(ctx) {
-    const { select, cross } = this;
-    const arg = cross != null ? `{ cross: ${cross} }` : '';
+    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})`;
   }
 
   toJSON() {
-    const { select, cross } = this;
-    return { select, cross };
+    const { select, cross, empty } = this;
+    return { select, cross, empty };
   }
 }

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/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.
    */

package/src/spec/Param.ts

@@ -58,6 +58,13 @@ 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;
 }
 
 /** A Param or Selection definition. */

package/src/spec/PlotAttribute.ts

@@ -1556,6 +1556,13 @@ export interface PlotAttributes {
    */
   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/src/spec/Transform.ts

@@ -41,20 +41,58 @@ type Arg2Opt = Arg | [Arg, Arg?];
  */
 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';
+
+/* A bin transform. */
+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;
   /**
@@ -64,15 +102,6 @@ export interface BinOptions {
   offset?: number;
 }
 
-/* A bin transform. */
-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];
-}
-
 /* A dateMonth transform. */
 export interface DateMonth {
   /**