feat: Lasso Specification Compiler

build/vega-lite-schema.json

@@ -12289,6 +12289,120 @@
         }
       ]
     },
+    "LassoSelectionConfig": {
+      "additionalProperties": false,
+      "properties": {
+        "clear": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Stream"
+            },
+            {
+              "type": "string"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Clears the selection, emptying it of all values. This property can be a [Event Stream](https://vega.github.io/vega/docs/event-streams/) or `false` to disable clear.\n\n__Default value:__ `dblclick`.\n\n__See also:__ [`clear` examples ](https://vega.github.io/vega-lite/docs/selection.html#clear) in the documentation."
+        },
+        "encodings": {
+          "description": "An array of encoding channels. The corresponding data field values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/SingleDefUnitChannel"
+          },
+          "type": "array"
+        },
+        "fields": {
+          "description": "An array of field names whose values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/FieldName"
+          },
+          "type": "array"
+        },
+        "mark": {
+          "$ref": "#/definitions/BrushConfig",
+          "description": "A lasso selection also adds a path mark to depict the shape of the lasso. The `mark` property can be used to customize the appearance of the mark.\n\n__See also:__ [`mark` examples](https://vega.github.io/vega-lite/docs/selection.html#mark) in the documentation."
+        },
+        "on": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Stream"
+            },
+            {
+              "type": "string"
+            }
+          ],
+          "description": "A [Vega event stream](https://vega.github.io/vega/docs/event-streams/) (object or selector) that triggers the selection. For interval selections, the event stream must specify a [start and end](https://vega.github.io/vega/docs/event-streams/#between-filters).\n\n__See also:__ [`on` examples](https://vega.github.io/vega-lite/docs/selection.html#on) in the documentation."
+        },
+        "resolve": {
+          "$ref": "#/definitions/SelectionResolution",
+          "description": "With layered and multi-view displays, a strategy that determines how selections' data queries are resolved when applied in a filter transform, conditional encoding rule, or scale domain.\n\nOne of:\n- `\"global\"` -- only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed.\n- `\"union\"` -- each cell contains its own brush, and points are highlighted if they lie within _any_ of these individual brushes.\n- `\"intersect\"` -- each cell contains its own brush, and points are highlighted only if they fall within _all_ of these individual brushes.\n\n__Default value:__ `global`.\n\n__See also:__ [`resolve` examples](https://vega.github.io/vega-lite/docs/selection.html#resolve) in the documentation."
+        },
+        "type": {
+          "const": "lasso",
+          "description": "Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types:\n\n- `\"point\"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.\n- `\"interval\"` -- to select a continuous range of data values on `drag`.",
+          "type": "string"
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "type": "object"
+    },
+    "LassoSelectionConfigWithoutType": {
+      "additionalProperties": false,
+      "properties": {
+        "clear": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Stream"
+            },
+            {
+              "type": "string"
+            },
+            {
+              "type": "boolean"
+            }
+          ],
+          "description": "Clears the selection, emptying it of all values. This property can be a [Event Stream](https://vega.github.io/vega/docs/event-streams/) or `false` to disable clear.\n\n__Default value:__ `dblclick`.\n\n__See also:__ [`clear` examples ](https://vega.github.io/vega-lite/docs/selection.html#clear) in the documentation."
+        },
+        "encodings": {
+          "description": "An array of encoding channels. The corresponding data field values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/SingleDefUnitChannel"
+          },
+          "type": "array"
+        },
+        "fields": {
+          "description": "An array of field names whose values must match for a data tuple to fall within the selection.\n\n__See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.",
+          "items": {
+            "$ref": "#/definitions/FieldName"
+          },
+          "type": "array"
+        },
+        "mark": {
+          "$ref": "#/definitions/BrushConfig",
+          "description": "A lasso selection also adds a path mark to depict the shape of the lasso. The `mark` property can be used to customize the appearance of the mark.\n\n__See also:__ [`mark` examples](https://vega.github.io/vega-lite/docs/selection.html#mark) in the documentation."
+        },
+        "on": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Stream"
+            },
+            {
+              "type": "string"
+            }
+          ],
+          "description": "A [Vega event stream](https://vega.github.io/vega/docs/event-streams/) (object or selector) that triggers the selection. For interval selections, the event stream must specify a [start and end](https://vega.github.io/vega/docs/event-streams/#between-filters).\n\n__See also:__ [`on` examples](https://vega.github.io/vega-lite/docs/selection.html#on) in the documentation."
+        },
+        "resolve": {
+          "$ref": "#/definitions/SelectionResolution",
+          "description": "With layered and multi-view displays, a strategy that determines how selections' data queries are resolved when applied in a filter transform, conditional encoding rule, or scale domain.\n\nOne of:\n- `\"global\"` -- only one brush exists for the entire SPLOM. When the user begins to drag, any previous brushes are cleared, and a new one is constructed.\n- `\"union\"` -- each cell contains its own brush, and points are highlighted if they lie within _any_ of these individual brushes.\n- `\"intersect\"` -- each cell contains its own brush, and points are highlighted only if they fall within _all_ of these individual brushes.\n\n__Default value:__ `global`.\n\n__See also:__ [`resolve` examples](https://vega.github.io/vega-lite/docs/selection.html#resolve) in the documentation."
+        }
+      },
+      "type": "object"
+    },
     "LatLongDef": {
       "anyOf": [
         {
@@ -21936,6 +22050,10 @@
           "$ref": "#/definitions/IntervalSelectionConfigWithoutType",
           "description": "The default definition for an [`interval`](https://vega.github.io/vega-lite/docs/parameter.html#select) selection. All properties and transformations for an interval selection definition (except `type`) may be specified here.\n\nFor instance, setting `interval` to `{\"translate\": false}` disables the ability to move interval selections by default."
         },
+        "lasso": {
+          "$ref": "#/definitions/LassoSelectionConfigWithoutType",
+          "description": "The default definition for an [`lasso`](https://vega.github.io/vega-lite/docs/parameter.html#select) selection. All properties and transformations for an lasso selection definition (except `type`) may be specified here."
+        },
         "point": {
           "$ref": "#/definitions/PointSelectionConfigWithoutType",
           "description": "The default definition for a [`point`](https://vega.github.io/vega-lite/docs/parameter.html#select) selection. All properties and transformations  for a point selection definition (except `type`) may be specified here.\n\nFor instance, setting `point` to `{\"on\": \"dblclick\"}` populates point selections on double-click by default."
@@ -22013,6 +22131,9 @@
             },
             {
               "$ref": "#/definitions/IntervalSelectionConfig"
+            },
+            {
+              "$ref": "#/definitions/LassoSelectionConfig"
             }
           ],
           "description": "Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types:\n\n- `\"point\"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.\n- `\"interval\"` -- to select a continuous range of data values on `drag`."
@@ -22052,7 +22173,8 @@
     "SelectionType": {
       "enum": [
         "point",
-        "interval"
+        "interval",
+        "lasso"
       ],
       "type": "string"
     },
@@ -29512,6 +29634,9 @@
             },
             {
               "$ref": "#/definitions/IntervalSelectionConfig"
+            },
+            {
+              "$ref": "#/definitions/LassoSelectionConfig"
             }
           ],
           "description": "Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types:\n\n- `\"point\"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.\n- `\"interval\"` -- to select a continuous range of data values on `drag`."

src/compile/selection/index.ts

@@ -28,6 +28,7 @@ import toggle from './toggle';
 import translate from './translate';
 import zoom from './zoom';
 import {ParameterName} from '../../parameter';
+import lasso from './lasso';
 
 export const STORE = '_store';
 export const TUPLE = '_tuple';
@@ -69,6 +70,7 @@ export interface SelectionCompiler<T extends SelectionType = SelectionType> {
 export const selectionCompilers: SelectionCompiler[] = [
   point,
   interval,
+  lasso,
   project,
   toggle,
 

src/compile/selection/lasso.ts

@@ -0,0 +1,96 @@
+import {OnEvent, Signal, Stream} from 'vega';
+import {stringValue} from 'vega-util';
+import {SelectionCompiler, SelectionComponent, TUPLE, unitName} from '.';
+import {warn} from '../../log';
+import {BRUSH} from './interval';
+import scales from './scales';
+export const SCREEN_PATH = '_screen_path';
+
+const lasso: SelectionCompiler<'lasso'> = {
+  defined: selCmpt => selCmpt.type === 'lasso',
+
+  signals: (model, selCmpt, signals) => {
+    const name = selCmpt.name;
+    const signalsToAdd: Signal[] = [];
+
+    const screenPathName = `${name}${SCREEN_PATH}`;
+
+    const w = model.getSizeSignalRef('width').signal;
+    const h = model.getSizeSignalRef('height').signal;
+
+    signalsToAdd.push({
+      name: `${name}${TUPLE}`,
+      on: [
+        {
+          events: [{signal: screenPathName}],
+          update: `vlSelectionTuples(intersectLasso(${stringValue(
+            model.getName('marks')
+          )}, ${screenPathName}, unit), {unit: ${unitName(model)}})`
+        }
+      ]
+    });
+
+    const on = events(selCmpt, (def: OnEvent[], evt: Stream) => {
+      return [
+        ...def,
+        {events: evt.between[0], update: `[[x(unit), y(unit)]]`},
+        {events: evt, update: `lassoAppend(${screenPathName}, clamp(x(unit), 0, ${w}), clamp(y(unit), 0, ${h}))`}
+      ];
+    });
+
+    signalsToAdd.push({
+      name: screenPathName,
+      init: '[]',
+      on: on
+    });
+
+    return [...signals, ...signalsToAdd];
+  },
+
+  marks: (model, selCmpt, marks) => {
+    const name = selCmpt.name;
+    const {fill, fillOpacity, stroke, strokeDash, strokeWidth} = selCmpt.mark;
+
+    const screenPathName = `${name}${SCREEN_PATH}`;
+
+    // Do not add a brush if we're binding to scales.
+    if (scales.defined(selCmpt)) {
+      return marks;
+    }
+
+    return [
+      {
+        name: `${name + BRUSH}`,
+        type: 'path',
+        encode: {
+          enter: {
+            fill: {value: fill},
+            fillOpacity: {value: fillOpacity},
+            stroke: {value: stroke},
+            strokeWidth: {value: strokeWidth},
+            strokeDash: {value: strokeDash}
+          },
+          update: {
+            path: {
+              test: true,
+              signal: `lassoPath(${screenPathName})`
+            }
+          }
+        }
+      },
+      ...marks
+    ];
+  }
+};
+
+function events(selCmpt: SelectionComponent<'lasso'>, cb: (def: OnEvent[], evt: Stream) => OnEvent[]): OnEvent[] {
+  return selCmpt.events.reduce((on, evt) => {
+    if (!evt.between) {
+      warn(`${evt} is not an ordered event stream for lasso selections.`);
+      return on;
+    }
+    return cb(on, evt);
+  }, [] as OnEvent[]);
+}
+
+export default lasso;

src/selection.ts

@@ -7,15 +7,15 @@ import {ParameterName} from './parameter';
 import {Dict} from './util';
 
 export const SELECTION_ID = '_vgsid_';
-export type SelectionType = 'point' | 'interval';
+export type SelectionType = 'point' | 'interval' | 'lasso';
 export type SelectionResolution = 'global' | 'union' | 'intersect';
 
 export type SelectionInit = PrimitiveValue | DateTime;
 export type SelectionInitInterval = Vector2<boolean> | Vector2<number> | Vector2<string> | Vector2<DateTime>;
-
+export type SelectionInitLasso = number[];
 export type SelectionInitMapping = Dict<SelectionInit>;
 export type SelectionInitIntervalMapping = Dict<SelectionInitInterval>;
-
+export type SelectionInitLassoMapping = Dict<SelectionInitLasso>;
 export type LegendStreamBinding = {legend: string | Stream};
 export type LegendBinding = 'legend' | LegendStreamBinding;
 
@@ -200,6 +200,25 @@ export interface IntervalSelectionConfig extends BaseSelectionConfig<'interval'>
   mark?: BrushConfig;
 }
 
+export interface LassoSelectionConfig extends BaseSelectionConfig<'lasso'> {
+  /**
+   * A lasso selection also adds a path mark to depict the
+   * shape of the lasso. The `mark` property can be used to customize the
+   * appearance of the mark.
+   *
+   * __See also:__ [`mark` examples](https://vega.github.io/vega-lite/docs/selection.html#mark) in the documentation.
+   */
+  mark?: BrushConfig;
+
+  /**
+   * An array of field names whose values must match for a data tuple to
+   * fall within the selection.
+   *
+   * __See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.
+   */
+  fields?: FieldName[];
+}
+
 export interface SelectionParameter<T extends SelectionType = SelectionType> {
   /**
    * Required. A unique name for the selection parameter. Selection names should be valid JavaScript identifiers: they should contain only alphanumeric characters (or "$", or "_") and may not start with a digit. Reserved keywords that may not be used as parameter names are "datum", "event", "item", and "parent".
@@ -212,7 +231,15 @@ export interface SelectionParameter<T extends SelectionType = SelectionType> {
    * - `"point"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.
    * - `"interval"` -- to select a continuous range of data values on `drag`.
    */
-  select: T | (T extends 'point' ? PointSelectionConfig : T extends 'interval' ? IntervalSelectionConfig : never);
+  select:
+    | T
+    | (T extends 'point'
+        ? PointSelectionConfig
+        : T extends 'interval'
+        ? IntervalSelectionConfig
+        : T extends 'lasso'
+        ? LassoSelectionConfig
+        : never);
 
   /**
    * Initialize the selection with a mapping between [projected channels or field names](https://vega.github.io/vega-lite/docs/selection.html#project) and initial values.
@@ -282,6 +309,8 @@ export type PointSelectionConfigWithoutType = Omit<PointSelectionConfig, 'type'>
 
 export type IntervalSelectionConfigWithoutType = Omit<IntervalSelectionConfig, 'type'>;
 
+export type LassoSelectionConfigWithoutType = Omit<LassoSelectionConfig, 'type'>;
+
 export interface SelectionConfig {
   /**
    * The default definition for a [`point`](https://vega.github.io/vega-lite/docs/parameter.html#select) selection. All properties and transformations
@@ -299,6 +328,12 @@ export interface SelectionConfig {
    * interval selections by default.
    */
   interval?: IntervalSelectionConfigWithoutType;
+
+  /**
+   * The default definition for an [`lasso`](https://vega.github.io/vega-lite/docs/parameter.html#select) selection. All properties and transformations
+   * for an lasso selection definition (except `type`) may be specified here.
+   */
+  lasso?: LassoSelectionConfigWithoutType;
 }
 
 export const defaultConfig: SelectionConfig = {
@@ -317,6 +352,13 @@ export const defaultConfig: SelectionConfig = {
     mark: {fill: '#333', fillOpacity: 0.125, stroke: 'white'},
     resolve: 'global',
     clear: 'dblclick'
+  },
+  lasso: {
+    on: '[mousedown, window:mouseup] > window:mousemove!',
+    resolve: 'global',
+    fields: [SELECTION_ID],
+    mark: {fill: '#333', fillOpacity: 0.125, stroke: 'gray', strokeWidth: 2, strokeDash: [8, 5]},
+    clear: 'dblclick'
   }
 };