v5.0.0

[jheer]

Vega v5.0.0 Release Candidate 1

Breaking Specification Changes:

• The legend strokeWidth property now corresponds to a scale that maps data values to stroke widths. It no longer corresponds to the stroke width of the legend border. However, the legend.strokeWidth config property still corresponds to the legend border thickness.
• The bin-linear scale type has been removed. This is unlikely to affect many (if any) direct users of Vega. However, versions of Vega-Lite prior to v3 will not work with Vega v5 as a result.
• Remove deprecated Vega-Lite selection expression functions vlSingle, vlSingleDomain, vlMulti, vlMultiDomain, vlInterval, and vlIntervalDomain.

Breaking API Changes:

• The vega-lib package has been removed; use vega directly instead. The vega package no longer includes an optional node-canvas dependency. If you want to use Vega in server-side projects, your project can simply include an explicit node-canvas dependency.
• The vega package no longer directly provides command line utilities; use the new vega-cli package instead, which includes a node-canvas dependency. (The vega-cli package includes a new vg2pdf command for rendering PDF output!)
• The vega package no longer exports TypeScript typings for the vega-lib module; use the vega module instead.
• The runtime and internal APIs have other breaking changes, though most Vega users will not be affected. See the full change log below for more.

Other Notable Changes:

• The Vega project and sub-modules have now been reorganized into a single monorepo (vega/vega) to streamline development.
• Vega symbol marks now include an angle channel for symbol rotation.
• Thanks to extensions in d3-scale, Vega now includes a symmetric log (symlog) scale type.
• Vega now supports color interpolation not just for linear scales, but for all continuous scales. Internally, Vega will select among standard linear, sequential, or diverging scale implementations based on scale domain and range. A similar logic applies for log, pow, sqrt, and symlog scales. In addition, the scale interpolate property can now be used with any scale that supports a scheme-valued range, allowing customized color interpolation for continuous, ordinal, or discretizing scales.
• The sequential scale type has been deprecated, but remains for backwards-compatilibility. Use the linear scale type instead.
• The Vega dataflow now supports asynchronous evaluation. Internal dataflow operators can now return a Promise; dataflow evaluation will then pause and resume when the Promise resolves. This enables exciting new capabilities such as dynamic loading from external data sources. The View API run method still works much as before, but internally simply calls runAsync and returns immediately. If no asynchronous processing is performed (for example, no external datasets are requested or in the process of loading), the dataflow evaluation will complete before run returns. However, in general callers have no guarantee that dataflow evaluation is complete when the run method returns. We recommend using view.runAsync whenever possible; invoke then on the returned Promise to perform actions once dataflow evaluation is finished.
• Starting with v4.4, Vega started using more ES6+ constructs directly and dropped Internet Explorer support (in part due to changes in underlying d3 libraries). This trend has continued in the v5 release, most notably including Vega's use of async functions and the await keyword. Some users migrating to Vega 5.0 from an earlier version may discover incompatibilities with older browsers. If backwards compatibility is essential, we recommend using a transpiler framework such as Babel.

Detailed Changes:

docs

• Update documentation to reflect all JSON schema and API changes.
• Add wind vectors example. (Thanks @jwoLondon!)

vega

• Add test specifications and scenes for dynamic data loading.
• Add test specification and scene for symbol angle.
• Update flush-axis-labels and legend-continuous test specifications to use labelSeparation.
• Update test specifications to use linear rather than sequential scale type.
• Update rendered scenegraphs for test specifications.
• Update exports to use vega-functions package.
• Drop vega-lib module for typings.

vega-cli

• Create new package for Vega command-line utilities.
• Add vg2pdf command for generating PDF output.

vega-dataflow

• Breaking: Decouple dataflow request from pending load tracker.
• Add dataflow preload method for initial data loading.
• Add async evaluation support. Transform operators can now return a Promise that resolves to a Pulse.
• Add passing of responseType from format to loader options.
• Update data loading and dataflow methods to use async/await.
• Add async evaluation tests.

vega-encode

• Breaking: Remove bin-linear scale support. (Use new bins parameter instead.)
• Breaking: Remove utcInterval method. (Use updated timeInterval method instead.)
• Add automatic scale selection for linear, log, pow, sqrt, symlog types. If a color range is specified, sequential or diverging scale implementations will be used depending on the domain length.
• Add interpolated color array input to scheme property. (Fix Ordinal scale can interpolate scheme, but not range #995)
• Add color interpolate support for all scheme-compatible scales.
• Add support for bins property to guide tick/legend generation.
• Add minstep parameter to AxisTicks and LegendEntries transforms.
• Update unit tests to work with async evaluation.

vega-expression

• Add exports for AST node type constants.
• Update README.md to clarify the constants and functions provided. (Ambiguous documentation for vega-expression package #1556)

vega-functions

• Create new package for Vega-specific expression functions and code generation.
• Add panSymlog and zoomSymlog expression functions.
• Add intersect expression function. This function is not yet part of the official expression language, but is exposed for integration and testing with Vega-Lite. The intersect function has the signature intersect(box, options, group), where:
  • box is a rectangular brush region defined as [[x1, y1], [x2, y2]]
  • options is an optional object with marktype or markname properties (strings or arrays) for limiting the intersection tests to specific marks.
  • group is an optional scenegraph group item that serves as the root of the search. If not provided, the full scenegraph is used.
• Update README.md to clarify the functions provided. (Ambiguous documentation for vega-expression package #1556)
• Fix gradient function to handle zero span domains, add test cases. (Sequential scale does not show any color when the domain has only one value. #1479)

vega-loader

• Add response option to direct fetch response processing.
• Add responseType property to format read methods.
• Update loader to use async / await.
• Update sanitize method to copy rel loader option to the output result. The scenegraph handler will copy this over as an HTML rel attribute of a generated a element. (Specify rel in href links #1542)

vega-parser

• Breaking: Add strokeWidth scale support for legends, remove legend strokeWidth property. Similar to strokeDash, the config-level strokeWidth property is still supported. However, the spec-level property now refers to an input scale, not the legend group boundary.
• Breaking Move expression functions and code generation to vega-functions package.
• Breaking: Update data parser to include load transform for dynamic data directly within generated transform pipelines.
• Add labelSeparation property for axes and legends. (Specify a minimum distance between labels for overlap determination. #1507)
• Add tickMinStep to axis and legend parsers.
• Update legend and scale parsers to use scale type predicates.

vega-runtime

• Breaking: Remove runtime context support for dynamic loading. Instead, the dataflow now supports this directly.
• Breaking: Use dataflow preload for initial dataset loading.

vega-selections

• Create new package for Vega-Lite selection functions.

vega-scale

• Breaking: Remove bin-linear scale type.
• Add symlog scale type.
• Add transformed sequential and diverging scale implementations.
• Add scale type constants and predicate methods.
• Upgrade to d3-scale 2.2+. (Fix Support D3 Scales 2.2 scale types #1536)

vega-scenegraph

• Add support for symbol mark angle encoding. (#1557)
• Add new built-in symbol types: arrow, triangle, wedge, stroke
• Add intersection hit testing between marks and a rectangular brush.
• Add rotatedPoints method to Bounds.
• Fix picking calculation for text marks.
• Code clean-up.

vega-schema

• Breaking: Update schema with strokeWidth scale support for legends, remove legend strokeWidth property.
• Add axis/legend labelSeparation property to schema. (Specify a minimum distance between labels for overlap determination. #1507)
• Add tickMinStep to axis and legend schema.
• Update schema to support signal values in dataset definitions.
• Update schema to reflect additions and removals.
• Update code comments to reflect angle encoding availability.
• Refactor to use internal JSON schema API.

vega-transforms

• Breaking: Update load transform to use async evaluation.
• Update load transform to support explicit values as well as url.
• Update unit tests to work with async evaluation.

vega-util

• Add panSymlog and zoomSymlog methods.
• Add clampRange, extent, flush, inrange, and span array methods.
• Add quarter and utcquarter Date methods.
• Update documentaion and typings.

vega-view

• Breaking: The View API render method has been removed. As before, (re-)rendering is automatically invoked when the dataflow is evaluated.
• Update View API to override Dataflow.runAsync instead of run.
• Update headless rendering methods to use async/await.
• Update internal event handlers to use async/await to queue handler invocation.
• Update View to track signal bind element. Pass bound element as an initialize parameter when the renderer is reset. (Tooltip handler duplicates controls rendered in custom controls container #1575)
• Drop vega-parser depencency, use vega-functions instead.

vega-view-transforms

• Update Overlap transform to pre-filter all labels with null bounds.
• Update Overlap transform to support separation parameter. (Specify a minimum distance between labels for overlap determination. #1507)

[nyurik]

Thanks for awesome work! The new code structure makes things far easier, gradient colors (!!!), repackaging. Tons of good stuff!

My biggest concern is that it is very hard to review - Chrome takes a few minutes just to load the page, and there are too many minor changes that get in the way (e.g. example schema bumps). I wish there were a few separate pull requests - e.g. a few for the functional changes, and one that actually migrates everything to v5, but does not make any functional code changes other than related to the actual version.

But this is just a nitpick :) Thanks for awesome work!

[nyurik]

P.S. Would it be possible, as part of v5, to introduce an alias to signal keyword -- expr. It has caused considerable confusion among the users - every time i do Vega training, I have to explain that signal doesn't mean that you can only use a signal name (like with field), but you can actually write a proper expression. I think expr is much more intuitive for understanding. Thanks!

[jheer]

There are a number of earlier PRs with targeted updates. Please see the closed PRs. This PR consists almost exclusively of documentation updates and serves as the transition to v5.0.0, as you suggested. (I include the notes and change log for all of v5.0.0 above for convenient reference, but this PR does not include all of those changes.)

For earlier PRs there is also a huge commit backlog due to migrating all the sub-modules into the current monorepo, but that is a one-time issue.

Your "p.s." above is more fitting for a new issue than a PR comment, but I'll answer it here :) The short version is that expr is already defined in Vega and has a different meaning. A standard signal expression is like a single evaluated statement, whereas an expr is like a lambda function that can be evaluated against a number of input values. See the Vega Types documentation page for more.

[nyurik]

@jheer my apologies, I got confused by the changes in the vega-schema js files and the very large csv files :) Plus for some reason I thought you changes docs in the same PRs as the corresponding code changes (I'm not exactly sure what would be better - for the Vega docs site to show >5.0 for some new features, and not to have 5.0 out, or to keep related docs separate from code changes... probably the former?) As for the "p.s.", yeah, lets discuss it in an issue.

Oh the irony... Kibana just began the work of updating to Vega 4... What do you think is the ETA on 5, assuming we use the latest released Vega-Lite?

[domoritz]

Do we need a types property here or does depending on vega-typings suffice?

[jheer]

I'm not the right person to answer; however, I do note that vega-util has an explicit types property in its package.json file.

[domoritz]

I can make sure to test it before the final release. Do you plan to have an rc release before the final release?