@uwdata/mosaic-spec 0.8.0 → 0.9.0

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

@@ -10,6 +10,11 @@ export interface Menu {
      * currently selected menu option.
      */
     as?: ParamRef;
+    /**
+     * The database column name to use within generated selection clause
+     * predicates. Defaults to the `column` property.
+     */
+    field?: string;
     /**
      * The name of a database table to use as a data source for this widget.
      * Used in conjunction with the `column` property.
@@ -32,11 +37,14 @@ export interface Menu {
     /**
      * 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.
+     * If no label is provided, the string-coerced value is used.
      */
-    options?: Array<any>;
+    options?: Array<any | {
+        value: any;
+        label?: string;
+    }>;
     /**
-     * The initial selected menu option.
+     * The initial selected menu value.
      */
     value?: any;
 }
@@ -51,6 +59,11 @@ export interface Search {
      * current text search query.
      */
     as?: ParamRef;
+    /**
+     * The database column name to use within generated selection clause
+     * predicates. Defaults to the `column` property.
+     */
+    field?: string;
     /**
      * The type of text search query to perform. One of:
      * - `"contains"` (default): the query string may appear anywhere in the text
@@ -90,6 +103,18 @@ export interface Slider {
      * currently selected slider option.
      */
     as?: ParamRef;
+    /**
+     * The database column name to use within generated selection clause
+     * predicates. Defaults to the `column` property.
+     */
+    field?: string;
+    /**
+     * 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.
+     */
+    select?: 'point' | 'interval';
     /**
      * The name of a database table to use as a data source for this widget.
      * Used in conjunction with the `column` property.

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

@@ -8,6 +8,7 @@ import { DelaunayLink, DelaunayMesh, Hull, Voronoi, VoronoiMesh } from './marks/
 import { DenseLine } from './marks/DenseLine.js';
 import { Density, DensityX, DensityY } from './marks/Density.js';
 import { Circle, Dot, DotX, DotY, Hexagon } from './marks/Dot.js';
+import { ErrorBarX, ErrorBarY } from './marks/ErrorBar.js';
 import { Frame } from './marks/Frame.js';
 import { Geo, Graticule, Sphere } from './marks/Geo.js';
 import { Hexbin } from './marks/Hexbin.js';
@@ -23,4 +24,4 @@ import { Text, TextX, TextY } from './marks/Text.js';
 import { TickX, TickY } from './marks/Tick.js';
 import { Spike, Vector, VectorX, VectorY } from './marks/Vector.js';
 /** A plot mark entry. */
-export type PlotMark = Area | AreaX | AreaY | Arrow | AxisX | AxisY | AxisFx | AxisFy | GridX | GridY | GridFx | GridFy | BarX | BarY | Cell | CellX | CellY | Contour | DelaunayLink | DelaunayMesh | Hull | Voronoi | VoronoiMesh | DenseLine | Density | DensityX | DensityY | Dot | DotX | DotY | Circle | Hexagon | Frame | Geo | Graticule | Sphere | Hexbin | Hexgrid | Image | Line | LineX | LineY | Link | Raster | Heatmap | RasterTile | Rect | RectX | RectY | RegressionY | RuleX | RuleY | Text | TextX | TextY | TickX | TickY | Vector | VectorX | VectorY | Spike;
+export type PlotMark = Area | AreaX | AreaY | Arrow | AxisX | AxisY | AxisFx | AxisFy | GridX | GridY | GridFx | GridFy | BarX | BarY | Cell | CellX | CellY | Contour | DelaunayLink | DelaunayMesh | Hull | Voronoi | VoronoiMesh | DenseLine | Density | DensityX | DensityY | Dot | DotX | DotY | Circle | Hexagon | ErrorBarX | ErrorBarY | Frame | Geo | Graticule | Sphere | Hexbin | Hexgrid | Image | Line | LineX | LineY | Link | Raster | Heatmap | RasterTile | Rect | RectX | RectY | RegressionY | RuleX | RuleY | Text | TextX | TextY | TickX | TickY | Vector | VectorX | VectorY | Spike;

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

@@ -28,6 +28,13 @@ export type Data = Record<string, DataDefinition>;
 export type Params = Record<string, ParamDefinition>;
 /** Top-level specification properties. */
 export interface SpecHead {
+    /**
+     * A [JSON schema](http://json-schema.org/) URL for this specification,
+     * such as https://uwdata.github.io/mosaic/schema/latest.json. This property
+     * enables validation and autocomplete in editors with JSON schema support.
+     * @format uri
+     */
+    $schema?: string;
     /** Specification metadata. */
     meta?: Meta;
     /** Configuration options. */

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

@@ -133,6 +133,18 @@ export interface Count extends AggregateOptions, WindowOptions {
      */
     count: Arg0 | Arg1;
 }
+export interface Covariance extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the sample covariance of between the given columns.
+     */
+    covariance: Arg2;
+}
+export interface CovarPop extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the population covariance of between the given columns.
+     */
+    covarPop: Arg2;
+}
 export interface First extends AggregateOptions, WindowOptions {
     /**
      * Return the first column value found in an aggregation group.
@@ -182,12 +194,36 @@ export interface Quantile extends AggregateOptions, WindowOptions {
      */
     quantile: Arg2;
 }
+export interface Stddev extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the sum of the given column.
+     */
+    stddev: Arg1;
+}
+export interface StddevPop extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the sum of the given column.
+     */
+    stddevPop: Arg1;
+}
 export interface Sum extends AggregateOptions, WindowOptions {
     /**
      * Compute the sum of the given column.
      */
     sum: Arg1;
 }
+export interface Variance extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the sample variance of the given column.
+     */
+    variance: Arg1;
+}
+export interface VarPop extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the population variance of the given column.
+     */
+    varPop: Arg1;
+}
 export interface RowNumber extends WindowOptions {
     /**
      * Compute the 1-based row number over an ordered window partition.
@@ -271,7 +307,7 @@ export interface NthValue extends WindowOptions {
 /** A data transform that maps one column value to another. */
 export type ColumnTransform = Bin | DateMonth | DateMonthDay | DateDay | Centroid | CentroidX | CentroidY | GeoJSON;
 /** An aggregate transform that combines multiple values. */
-export type AggregateTransform = Argmax | Argmin | Avg | Count | Max | Min | First | Last | Max | Min | Median | Mode | Product | Quantile | Sum;
+export type AggregateTransform = Argmax | Argmin | Avg | Count | Max | Min | First | Last | Max | Min | Median | Mode | Product | Quantile | Stddev | StddevPop | Sum | Variance | VarPop;
 export type WindowTransform = RowNumber | Rank | DenseRank | PercentRank | CumeDist | NTile | Rank | Lag | Lead | FirstValue | LastValue | NthValue;
 /** A data transform. */
 export type Transform = ColumnTransform | AggregateTransform | WindowTransform;

package/dist/types/spec/interactors/Nearest.d.ts

@@ -7,19 +7,38 @@ export interface NearestOptions {
      */
     as: ParamRef;
     /**
-     * The name of the field (database column) over which the nearest
-     * selection should be defined. If unspecified, the  channel field of the
-     * first valid prior mark definition is used.
+     * The encoding channels whose domain values should be selected. For example,
+     * a setting of `['color']` selects the data value backing the color channel,
+     * whereas `['x', 'z']` selects both x and z channel domain values. If
+     * unspecified, the selected channels default to match the current pointer
+     * settings: a `nearestX` interactor selects the `['x']` channels, while
+     * a `nearest` interactor selects the `['x', 'y']` channels.
      */
-    field?: string;
+    channels?: string[];
+    /**
+     * The fields (database column names) to use in generated selection clause
+     * predicates. If unspecified, the fields backing the selected *channels*
+     * in the first valid prior mark definition are used by default.
+     */
+    fields?: string[];
+    /**
+     * The maximum radius of a nearest selection (default 40). Marks with (x, y)
+     * coordinates outside this radius will not be selected as nearest points.
+     */
+    maxRadius?: number;
+}
+/** A nearest interactor. */
+export interface Nearest extends NearestOptions {
+    /** Select values from the mark closest to the pointer. */
+    select: 'nearest';
 }
 /** A nearestX interactor. */
 export interface NearestX extends NearestOptions {
-    /** Select the **x** domain value of the mark closest to the pointer. */
+    /** Select values from the mark closest to the pointer *x* location. */
     select: 'nearestX';
 }
 /** A nearestY interactor. */
 export interface NearestY extends NearestOptions {
-    /** Select the **y** domain value of the mark closest to the pointer. */
+    /** Select values from the mark closest to the pointer *y* location. */
     select: 'nearestY';
 }

package/dist/types/spec/interactors/Toggle.d.ts

@@ -41,6 +41,14 @@ export interface ToggleY extends ToggleOptions {
      */
     select: 'toggleY';
 }
+/** A toggleZ interactor. */
+export interface ToggleZ extends ToggleOptions {
+    /**
+     * Select individal values in the `z` scale domain.
+     * Clicking or touching a mark toggles its selection status.
+     */
+    select: 'toggleZ';
+}
 /** A toggleColor interactor. */
 export interface ToggleColor extends ToggleOptions {
     /**

package/dist/types/spec/marks/Dot.d.ts

@@ -13,6 +13,10 @@ export interface DotOptions extends MarkOptions {
      * to the *y* scale.
      */
     y?: ChannelValueSpec;
+    /**
+     * An optional ordinal channel for grouping data into series.
+     */
+    z?: ChannelValue;
     /**
      * The radius of dots; either a channel or constant. When a number, it is
      * interpreted as a constant radius in pixels. Otherwise it is interpreted as

package/dist/types/spec/marks/ErrorBar.d.ts

@@ -0,0 +1,82 @@
+import { ParamRef } from '../Param.js';
+import { ChannelValue, ChannelValueSpec, MarkData, MarkOptions, MarkerOptions } from './Marks.js';
+/** Options for errorbar marks. */
+interface ErrorBarOptions extends MarkOptions, MarkerOptions {
+    /**
+     * The confidence interval in (0, 1); defaults to 0.95.
+     */
+    ci?: number | ParamRef;
+    /**
+     * An optional ordinal channel for grouping data, producing an independent
+     * error bar for each group. If not specified, it defaults to **stroke** if
+     * a channel.
+     */
+    z?: ChannelValue;
+}
+/** Options for the errorbarX mark. */
+export interface ErrorBarXOptions extends ErrorBarOptions {
+    /**
+     * The dependent variable horizontal position channel, typically bound to the
+     * *x* scale.
+     */
+    x: ChannelValueSpec;
+    /**
+     * The independent variable vertical position channel, typically bound to
+     * the *y* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+     */
+    y?: ChannelValueSpec;
+}
+/** The errorbarX mark. */
+export interface ErrorBarX extends MarkData, ErrorBarXOptions {
+    /**
+     * A mark that draws error bars for a calculated parametric confidence
+     * interval for a dependent variable (*x*), potentially grouped by an
+     * independent variable (*y*).
+     *
+     * This mark aggregates raw values to produce a [parametric confidence
+     * interval][1] of the mean, assuming a normal distribution. To instead
+     * visualize pre-computeted interval values or custom aggregations, use
+     * a **ruleY** mark with specified **x1** and **x2** channels.
+     *
+     * Multiple error bars can be produced by specifying a **z** or **stroke**
+     * channel. Set the **marker** option to `'tick'` to add small perpendicular
+     * lines at the start and end of the error interval.
+     *
+     * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+     */
+    mark: 'errorbarX';
+}
+/** Options for the errorbarY mark. */
+export interface ErrorBarYOptions extends ErrorBarOptions {
+    /**
+     * The independent variable horizontal position channel, typically bound to
+     * the *x* scale; defaults to the zero-based index of the data [0, 1, 2, …].
+     */
+    x?: ChannelValueSpec;
+    /**
+     * The dependent variable vertical position channel, typically bound to the
+     * *y* scale.
+     */
+    y: ChannelValueSpec;
+}
+/** The errorbarY mark. */
+export interface ErrorBarY extends MarkData, ErrorBarYOptions {
+    /**
+     * A mark that draws error bars for a calculated parametric confidence
+     * interval for a dependent variable (*y*), potentially grouped by an
+     * independent variable (*x*).
+     *
+     * This mark aggregates raw values to produce a [parametric confidence
+     * interval][1] of the mean, assuming a normal distribution. To instead
+     * visualize pre-computeted interval values or custom aggregations, use
+     * a **ruleX** mark with specified **y1** and **y2** channels.
+     *
+     * Multiple error bars can be produced by specifying a **z** or **stroke**
+     * channel. Set the **marker** option to `'tick'` to add small perpendicular
+     * lines at the start and end of the error interval.
+     *
+     * [1]: https://en.wikipedia.org/wiki/Normal_distribution#Confidence_intervals
+     */
+    mark: 'errorbarY';
+}
+export {};

package/dist/types/spec/marks/Marks.d.ts

@@ -147,6 +147,8 @@ export type SortOrder = ChannelValue | {
 };
 /** The pointer mode for the tip; corresponds to pointerX, pointerY, and pointer. */
 export type TipPointer = 'x' | 'y' | 'xy';
+/** Selection filters to apply internally to mark data. */
+export type SelectFilter = 'first' | 'last' | 'maxX' | 'maxY' | 'minX' | 'minY' | 'nearest' | 'nearestX' | 'nearestY';
 export interface MarkData {
     /**
      * The data source for the mark.
@@ -166,9 +168,22 @@ export interface MarkOptions {
      * channel values; only truthy values are retained.
      *
      * Note that filtering only affects the rendered mark index, not the
-     * associated channel values, and thus has no effect on imputed scale domains.
+     * associated channel values, and has no effect on imputed scale domains.
      */
     filter?: ChannelValue;
+    /**
+     * Applies a filter transform after data is loaded to highlight selected
+     * values only. For example, `first` and `last` select the first or last
+     * values of series only (using the *z* channel to separate series).
+     * Meanwhile, `nearestX` and `nearestY` select the point nearest to the
+     * pointer along the *x* or *y* channel dimension. Unlike Mosaic selections,
+     * a mark level *select* is internal to the mark only, and does not populate
+     * a param or selection value to be shared across clients.
+     *
+     * Note that filtering only affects the rendered mark index, not the
+     * associated channel values, and has no effect on imputed scale domains.
+     */
+    select?: SelectFilter;
     /**
      * Applies a transform to reverse the order of the mark’s index, say for
      * reverse input order.

package/dist/types/spec/marks/Text.d.ts

@@ -13,6 +13,10 @@ export interface TextOptions extends MarkOptions, TextStyles {
      * bound to the *y* scale.
      */
     y?: ChannelValueSpec;
+    /**
+     * An optional ordinal channel for grouping data into series.
+     */
+    z?: ChannelValue;
     /**
      * The text contents channel, possibly with line breaks (\n, \r\n, or \r). If
      * not specified, defaults to the zero-based index [0, 1, 2, …].

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uwdata/mosaic-spec",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Declarative specification of Mosaic-powered applications.",
   "keywords": [
     "mosaic",
@@ -29,16 +29,14 @@
     "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",
+    "version": "cd ../.. && npm run docs:schema",
     "prepublishOnly": "npm run test && npm run lint && npm run build"
   },
   "dependencies": {
-    "@uwdata/mosaic-core": "^0.8.0",
-    "@uwdata/mosaic-sql": "^0.8.0",
-    "@uwdata/vgplot": "^0.8.0",
-    "ts-json-schema-generator": "^2.1.1"
+    "@uwdata/mosaic-core": "^0.9.0",
+    "@uwdata/mosaic-sql": "^0.9.0",
+    "@uwdata/vgplot": "^0.9.0",
+    "ts-json-schema-generator": "^2.2.0"
   },
-  "devDependencies": {
-    "ajv": "^8.13.0"
-  },
-  "gitHead": "a24b4c9f7dfa1c38c6af96ec17e075326c1af9b0"
+  "gitHead": "89bb9b0dfa747aed691eaeba35379525a6764c61"
 }

package/src/config/transforms.js

@@ -11,6 +11,8 @@ export function transformNames(overrides = []) {
     'centroidX',
     'centroidY',
     'count',
+    'covariance',
+    'covarPop',
     'dateMonth',
     'dateMonthDay',
     'dateDay',
@@ -23,7 +25,11 @@ export function transformNames(overrides = []) {
     'mode',
     'product',
     'quantile',
+    'stddev',
+    'stddevPop',
     'sum',
+    'variance',
+    'varPop',
     'row_number',
     'rank',
     'dense_rank',

package/src/spec/Input.ts

@@ -11,6 +11,11 @@ export interface Menu {
    * currently selected menu option.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
   /**
    * The name of a database table to use as a data source for this widget.
    * Used in conjunction with the `column` property.
@@ -33,11 +38,11 @@ export interface Menu {
   /**
    * 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.
+   * If no label is provided, the string-coerced value is used.
    */
-  options?: Array<any>;
+  options?: Array<any | { value: any, label?: string }>;
   /**
-   * The initial selected menu option.
+   * The initial selected menu value.
    */
   value?: any;
 }
@@ -53,6 +58,11 @@ export interface Search {
    * current text search query.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
   /**
    * The type of text search query to perform. One of:
    * - `"contains"` (default): the query string may appear anywhere in the text
@@ -93,6 +103,18 @@ export interface Slider {
    * currently selected slider option.
    */
   as?: ParamRef;
+  /**
+   * The database column name to use within generated selection clause
+   * predicates. Defaults to the `column` property.
+   */
+  field?: string;
+  /**
+   * 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.
+   */
+  select?: 'point' | 'interval';
   /**
    * The name of a database table to use as a data source for this widget.
    * Used in conjunction with the `column` property.

package/src/spec/PlotMark.ts

@@ -8,6 +8,7 @@ import { DelaunayLink, DelaunayMesh, Hull, Voronoi, VoronoiMesh } from './marks/
 import { DenseLine } from './marks/DenseLine.js';
 import { Density, DensityX, DensityY } from './marks/Density.js';
 import { Circle, Dot, DotX, DotY, Hexagon } from './marks/Dot.js';
+import { ErrorBarX, ErrorBarY } from './marks/ErrorBar.js';
 import { Frame } from './marks/Frame.js';
 import { Geo, Graticule, Sphere } from './marks/Geo.js';
 import { Hexbin } from './marks/Hexbin.js';
@@ -35,6 +36,7 @@ export type PlotMark =
   | DenseLine
   | Density | DensityX | DensityY
   | Dot | DotX | DotY | Circle | Hexagon
+  | ErrorBarX | ErrorBarY
   | Frame
   | Geo | Graticule | Sphere
   | Hexbin

package/src/spec/Spec.ts

@@ -33,6 +33,13 @@ export type Params = Record<string, ParamDefinition>;
 
 /** Top-level specification properties. */
 export interface SpecHead {
+  /**
+   * A [JSON schema](http://json-schema.org/) URL for this specification,
+   * such as https://uwdata.github.io/mosaic/schema/latest.json. This property
+   * enables validation and autocomplete in editors with JSON schema support.
+   * @format uri
+   */
+  $schema?: string;
   /** Specification metadata. */
   meta?: Meta;
   /** Configuration options. */

package/src/spec/Transform.ts

@@ -168,6 +168,22 @@ export interface Count extends AggregateOptions, WindowOptions {
   count: Arg0 | Arg1;
 }
 
+/* A sample covariance aggregate transform. */
+export interface Covariance extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sample covariance of between the given columns.
+   */
+  covariance: Arg2;
+}
+
+/* A population covariance aggregate transform. */
+export interface CovarPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the population covariance of between the given columns.
+   */
+  covarPop: Arg2;
+}
+
 /* A first aggregate transform. */
 export interface First extends AggregateOptions, WindowOptions {
   /**
@@ -233,6 +249,22 @@ export interface Quantile extends AggregateOptions, WindowOptions {
   quantile: Arg2;
 }
 
+/* A sample standard deviation aggregate transform. */
+export interface Stddev extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sum of the given column.
+   */
+  stddev: Arg1;
+}
+
+/* A population standard deviation aggregate transform. */
+export interface StddevPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sum of the given column.
+   */
+  stddevPop: Arg1;
+}
+
 /* A sum aggregate transform. */
 export interface Sum extends AggregateOptions, WindowOptions {
   /**
@@ -241,6 +273,22 @@ export interface Sum extends AggregateOptions, WindowOptions {
   sum: Arg1;
 }
 
+/* A sample variance aggregate transform. */
+export interface Variance extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the sample variance of the given column.
+   */
+  variance: Arg1;
+}
+
+/* A population variance aggregate transform. */
+export interface VarPop extends AggregateOptions, WindowOptions {
+  /**
+   * Compute the population variance of the given column.
+   */
+  varPop: Arg1;
+}
+
 /* A row_number window transform. */
 export interface RowNumber extends WindowOptions {
   /**
@@ -370,7 +418,11 @@ export type AggregateTransform =
   | Mode
   | Product
   | Quantile
-  | Sum;
+  | Stddev
+  | StddevPop
+  | Sum
+  | Variance
+  | VarPop;
 
 /* A window transform that operates over a sorted domain. */
 export type WindowTransform =

package/src/spec/interactors/Nearest.ts

@@ -8,21 +8,41 @@ export interface NearestOptions {
    */
   as: ParamRef;
   /**
-   * The name of the field (database column) over which the nearest
-   * selection should be defined. If unspecified, the  channel field of the
-   * first valid prior mark definition is used.
+   * The encoding channels whose domain values should be selected. For example,
+   * a setting of `['color']` selects the data value backing the color channel,
+   * whereas `['x', 'z']` selects both x and z channel domain values. If
+   * unspecified, the selected channels default to match the current pointer
+   * settings: a `nearestX` interactor selects the `['x']` channels, while
+   * a `nearest` interactor selects the `['x', 'y']` channels.
    */
-  field?: string;
+  channels?: string[];
+  /**
+   * The fields (database column names) to use in generated selection clause
+   * predicates. If unspecified, the fields backing the selected *channels*
+   * in the first valid prior mark definition are used by default.
+   */
+  fields?: string[];
+  /**
+   * The maximum radius of a nearest selection (default 40). Marks with (x, y)
+   * coordinates outside this radius will not be selected as nearest points.
+   */
+  maxRadius?: number;
+}
+
+/** A nearest interactor. */
+export interface Nearest extends NearestOptions {
+  /** Select values from the mark closest to the pointer. */
+  select: 'nearest';
 }
 
 /** A nearestX interactor. */
 export interface NearestX extends NearestOptions {
-  /** Select the **x** domain value of the mark closest to the pointer. */
+  /** Select values from the mark closest to the pointer *x* location. */
   select: 'nearestX';
 }
 
 /** A nearestY interactor. */
 export interface NearestY extends NearestOptions {
-  /** Select the **y** domain value of the mark closest to the pointer. */
+  /** Select values from the mark closest to the pointer *y* location. */
   select: 'nearestY';
 }

package/src/spec/interactors/Toggle.ts

@@ -46,6 +46,15 @@ export interface ToggleY extends ToggleOptions {
   select: 'toggleY';
 }
 
+/** A toggleZ interactor. */
+export interface ToggleZ extends ToggleOptions {
+  /**
+   * Select individal values in the `z` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleZ';
+}
+
 /** A toggleColor interactor. */
 export interface ToggleColor extends ToggleOptions {
   /**

package/src/spec/marks/Dot.ts

@@ -19,6 +19,11 @@ export interface DotOptions extends MarkOptions {
    */
   y?: ChannelValueSpec;
 
+  /**
+   * An optional ordinal channel for grouping data into series.
+   */
+  z?: ChannelValue;
+
   /**
    * The radius of dots; either a channel or constant. When a number, it is
    * interpreted as a constant radius in pixels. Otherwise it is interpreted as