Bugfix: project()-ing "class" onto StackedArea

Good afternoon,

This release includes a fix for a bug where project()ing the "class" attribute on Plot.StackedArea did not work (#1320). It should now work as expected.

More Hover interactivity, padding on labels, colors via CSS

Good evening,

Tonight's release includes enabling Interaction.Hover for Plot.Line and Plot.Area, the ability to set padding on Labels, and initializing the default Plottable colors through CSS.

Features

Interaction.Hover for Line and Area plots

Interaction.Hover has been enabled for Plot.Line and Plot.Area. The algorithm returns the closest point within a close range of the cursor. As Lines and Areas feature one DOM element for all the data (as opposed to one DOM element per datum, like in Plot.Scatter), a <circle class="hover-target"> selection will be returned as part of the HoverData; this circle will be centered on the hovered-over point.

Label Padding

You can now use Label.padding(padAmount) to the set the padding on a Label. Padding is the amount of pixels of blank space surrounding the text for the Label, which can help in separating the Label from adjacent Components.

Color CSS

It is now possible to initialize the default colors used in Scale.Color through CSS. For example:

.plottable-colors-0 {
  background-color: #ABCDEF;
}

will set the first Plottable color to #ABCDEF instead of Plottable.Core.Colors.INDIGO (the current default). The class plottable-colors-{{k}} can be used to set the k+1th color to the value specified in background-color.

IMPORTANT: The colors are read from CSS at the time the Scale.Color is instantiated, meaning that further changes to the CSS classes will not be registered unless the Scale.Color is regenerated. We are working on better ways to apply CSS classes to Plot elements; see the "Future Changes" section below.

Bugfixes

Ordinal Scale Reverse

Plots that utilize a Scale.Ordinal for the Y-Axis now are flipped so that labels are read top-to-bottom rather than bottom-to-top. Before:

Now:

Other notes

The extra plottable-dev.d.ts file has been removed.

Future Changes

As mentioned previously, we are looking into better ways to apply CSS to Plot subelements. Currently, CSS classes can be set/unset on Components using the classed() call, but the only way to set classes on Plot subelements (such as individual Plot.Scatter points) is to use the project() method to set the class attribute. The drawback of using project() here is that it's difficult to attach classes additively, as the last-project()ed class will overwrite all others. We're working on building an API point to make easier to attach classes to Plot elements.

Add CSS classes to Legend rows and HorizontalLegend entries

Good evening,

This is a minor patch that applies the row text as a CSS class in Legend, and the entry text as a CSS class in HorizontalLegend.

We may add the ability to directly specify the CSS class for legend entries in the near future.

Interaction.Key update, automatic bar widths, scale domain controls

Good evening,

Tonight's release features some updates to Interactions, additional controls for Scale domains, automatic bar width calculation on bar Plots, and a few other additions.

Features

Interaction.Key update

Interaction.Key now can listen for multiple keys. Use Interaction.Key.on(keycode, callback) to assign a new callback to be called when the key corresponding to keycode is pressed. An example:

var kI = new Plottable.Interaction.Key();
// keyCode for "a" is 65
kI.on(65, function() { plot.showAllData(); })
plot.registerInteraction(kI);

Pixel information included in HoverData

HoverData now includes a list of pixel positions corresponding to hovered-over elements:

export interface HoverData {
  data: any[];
  pixelPositions: Point[];
  selection: D3.Selection;
}

Retrieving Baseline Value

The .baseline() method, invoked with no arguments, now returns the baseline value on a Bar Plot.

Disabling Console Warnings

Plottable occasionally uses console warnings to alert developers to issues, such as deprecated classes and layout errors. To suppress these errors, set the global value Plottable.Config.SHOW_WARNINGS to false.

IntegerTickGenerator

Plottable.TickGenerators.integerTickGenerator() will produce a formatter that only returns integers.

Automated domain controls

• By calling automaticallyAdjustYScaleOverVisiblePoints(true) on a Plot, the Y scale's domain will automatically be adjusted to show only points visible on the X scale's domain. The adjustment is performed immediately after a call. It disables scale.autoDomain.
• automaticallyAdjustXScaleOverVisiblePoints(true) instead adjusts the X scale in response to changes in the Y scale.
• showAllData() adjusts both domains' extents to show all datasets. This call does not override auto domain adjustment behavior over visible points.

Default Bar Widths

Previously, bars on a Bar Plot backed by a non-Ordinal scale (or a Scale.Ordinal in "points" mode) would have their width default to 10px. Now, the width will automatically default to the closest spacing between two data points.

Bugfixes

• Data values outside of Scale.Ordinal's domain are not rendered.

API Breaks

• Interaction.Key's constructor no longer takes in a key code.
• Interaction.Key.callback() has been removed in favor of Interaction.Key.on(), which allows registration of callbacks to different keys.
• The 'onlyShowUnchanged' parameter in various formatters has been removed in favor of using an IntegerTickGenerator on Quantitative Scales.

Typescript API Breaks

• StackedBarPlot now extends AbstractBarPlot instead of StackedPlot.

Upgrade Instructions

• Update all uses of Interaction.Key as follows:

var kI = new Plottable.Interaction.Key(65).callback(<function>); // OLD VERSION
var kI = new Plottable.Interaction.Key().on(65, <callback>); // NEW VERSION

• Formatters relying on the onlyShowUnchanged parameter should be adjusted to use custom TickGenerators on the associated scales. For example:

// we only have integer y-values
yAxis.formatter(Plottable.Formatters.fixed(0, true)); // OLD
yScale.tickGenerator(Plottable.TickGenerators.integerTickGenerator());

• StackedBarPlot is no longer a StackedPlot; Typescript references should be updated accordingly.

Future Changes

Bugfix for Plot.Line and Plot.Area stylings

Previously, modifying or removing the CSS classes line and area would cause Plot.Line and Plot.Area to render incorrectly. This has now been fixed.

Hover Interactivity, Static Labels on Bar Plots, Tick Generators

Good evening,

Tonight's release brings with it some much-requested features.

Features

Interaction.Hover

Hover interactivity has been added as Interaction.Hover, which works with Plot.Scatter, Plot.ClusteredBar, Plot.VerticalBar, and Plot.(Vertical/Horizontal)Bar. Interaction.Hover takes two callbacks:

• onHoverOver((hoverData: HoverData) => any): Called when the user mouses over new elements; is passed the HoverData associated with elements the user has just hovered over.
• onHoverOut(callback: (hoverData: HoverData) => any): Called when the user mouses out of elements; is passed the HoverData associated with elements the user is no longer hovering over.

HoverData is an object containing the data and D3 Selection associated with items that were hovered over or out:

  export interface HoverData {
    data: any[];
    selection: D3.Selection;
  }

You can call hoverInteraction.getCurrentHoverData() to retrieve the HoverData associated with all elements the user is hovering over.

Static Labels on Bar Plots

Bar plots can now display static labels showing the bar values. Call BarPlot.barLabelsEnabled(true) to enable them. Similar to Axis.Numeric, you can supply a Formatter to control the displayed value using barLabelFormatter(formatter: Formatter)

The label color is automatically chosen for readability against the bar's color.

Default Bar Alignment

By default, bars backed by Quantitative scales now center on top of their value.

Custom Tick Generators

You can now set custom tick generation logic on Quantitative scales using tickGenerator(generator: TickGenerator). A TickGenerator is a function that produces tick values for a quantitative scale:

interface TickGenerator<D> {
  (scale: Plottable.Scale.AbstractQuantitative<D>): D[]
}

The TickGenerators module includes a function intervalTickGenerator(interval: number), which will return a TickGenerator that generates tick values separated by interval.
In the event that you wish to merely filter the original set of generated ticks, you can call scale.getDefaultTicks().

Bugfixes

• On StackedPlots, one can expect the stacking to happen if project was called after addDataset.
• On StackedAreaPlots, the y-accessor is now not ignored when plotting.
• On StackedPlots, any string data is coerced to numbers when plotting and stacking.
• On StackedPlots, stacking a 0-length dataset no longer causes an error.

API Breaks

• We removed some unused interfaces here (#1211). In the unlikely case that you were referencing an obscure, unused interface within Plottable, this may constitute a minor API break. Just remove references to the outdated interface to fix.
• Animator.ItertiveDelay has been removed, and its functionality moved to Animator.Base.

Upgrade Instructions

• If you want the previous bar alignment, call barPlot.barAlign("left") or barPlot.barAlign("top").
• Interaction.BarHover has been deprecated; please use Interaction.Hover instead. Note that the hover mode is now set by calling hoverMode(mode) on the Bar Plot instead of the Interaction.
• Move all references to Animator.IterativeDelay to Animator.Base.

Future Changes

• We will be enabling Interaction.Hover on Plot.Line and Plot.Area soon.

Bugfix for Layout Engine

Good evening,

This release fixes a bug that occasionally caused left-aligned category axes to be shifted too far to the left, resulting in their overlapping other components or falling off the edge of the SVG.

API changes to Plot, Namespace Changes

Good afternoon,

This release contains two major API changes:

1. All Plots have been converted over to the NewStylePlot API that we unveiled in version 0.25.0 with StackedBar and ClusteredBar plots. This will significantly increase API consistency, and make it easier for us to develop new features in the future.
2. We have removed the Plottable.Abstract module, instead moving all abstract classes to the appropriate module for their functionality. Thus, for example, Plottable.Abstract.Axis was renamed to Plottable.Axis.AbstractAxis. This will only affect Typescript consumers, who should see more sensible autocomplete information, and contributors, who will find a better-organized module system. For help upgrading, check out the Upgrade Instructions section of these release notes.

Additionally, we have altered the plottable.d.ts typing file published so as to include the_protected methods and variables as well as publicly-exposed methods. This will make it easier for Typescript developers to modify Plottable's internals and change the functionality. Be cautious when modifying or depending on _protected methods, as they are not part of the publicly supported API and their behavior may change without warning in future versions.

This release also includes a small tweak to the animation of Plot.StackedBar:

Stacked Bar Animation

All datasets in a stack now animate upward together, rather than each dataset in the stack animating in sequence.

Upgrade Instructions

The typing breaks consist solely of renames and should be very easy to resolve; see the notes below to see every individual rename. The actual API breaks will take a little more work to resolve but should still be very straightforward. Every use of a Plot.Scatter, Plot.Line, Plot.Area, Plot.Grid, Plot.HorizontalBar, or Plot.VerticalBar must be converted.

• Their constructors have all changed; they no longer take data as the first argument. For example, the signature for Plot.Scatter has changed from Plot.Scatter(data, xScale, yScale) to Plot.Scatter(xScale, yScale).
• The Plot.dataset method no longer exists for setting or retrieving the dataset.
• Plot.addDataset() must be used to add data to the plot.
  Other than that, everything should be the same. If your plots do not render and you see Error: XYPlots require an xScale and a yScale printed to the console, then that means that for at least one of your plots you have forgotten to remove the first dataset argument.

API-Breaking Changes

Conversion to NewStylePlot API:

Plot.Scatter, Plot.Line, Plot.Area, Plot.Grid, Plot.HorizontalBar, and Plot.VerticalBar were all converted to the NewStylePlot API. Thus, instead of taking a dataset in the constructor, datasets may now be added via the Plot.addDataset call. Here is a re-cap for how the new, consistent Plot API works.

Adding datasets

• Plot.addDataset(key: string, dataArray: any[]): Plot Add data to the Plot, registered with the given key. The data is automatically converted into a Plottable.Dataset.
• Plot.addDataset(key: string, dataset: Plottable.Dataset): Plot Add a Dataset to the Plot, registered with the given key.
• Plot.addDataset(dataArray: any[]): Plot Add data to the Plot. The data is automatically converted into a Plottable.Dataset.
• Plot.addDataset(dataset: Plottable.Dataset): Plot. Add a Dataset to the Plot.

Removing datasets

• Plot.removeDataset(key: string): Plot Remove a Dataset with the given key from the Plot.
• Plot.removeDataset(dataArray: any[]): Plot Remove a Dataset from the Plot by reference equality with the underlying data.
• Plot.removeDataset(dataset: Plottable.Dataset): Plot Remove a Dataset from the Plot by direct reference.

Retrieving datasets

• Plot.datasets(): Plottable.Dataset[] return all Datasets bound to the Plot.

Typescript-only API Breaks

The Plottable.Abstract module was removed. Classes have been renamed as follows:

• Plottable.Abstract.Scale → Plottable.Scale.AbstractScale
• Plottable.Abstract.QuantitativeScale → Plottable.Scale.AbstractQuantitative
• Plottable.Abstract.Component → Plottable.Component.AbstractComponent
• Plottable.Abstract.ComponentContainer → Plottable.Component.AbstractComponentContainer
• Plottable.Abstract.Axis → Plottable.Axis.AbstractAxis
• Plottable.Abstract.Plot → Plottable.Plot.AbstractPlot
• Plottable.Abstract.XYPlot → Plottable.Plot.AbstractXYPlot
• Plottable.Abstract.BarPlot → Plottable.Plot.AbstractBarPlot
• Plottable.Abstract.Stacked → Plottable.Plot.AbstractStacked
• Plottable.Abstract.Drawer → Plottable.Drawer.AbstractDrawer
• Plottable.Abstract.Dispatcher → Plottable.Dispatcher.AbstractDispatcher
• Plottable.Abstract.Interaction → Plottable.Interaction.AbstractInteraction

Since all Plots are now NewStylePlots, we have removed the redundant NewStylePlot class. NewStyleBarPlot was also removed.

We stopped prefixing interfaces with the letter I. Interfaces have been renamed as follows:

• IAppliedAccessor → AppliedAccessor
• IAttributeToProjector → AttributeToProjector
• IBroadcasterCallback → BroadcasterCallback
• IDataset → DatasetInterface
• IExtent → Extent
• IKeyEventListenerCallback → KeyEventListenerCallback
• IListenable → Listenable
• IMetadata → Metadata
• IPlotAnimator → PlotAnimator
• IPlotAnimatorMap → PlotAnimatorMap
• IRenderPolicy → RenderPolicy
• IWrappedText → WrappedText
• _IAccessor → _Accessor
• _IProjector → _Projector
• _ISpaceRequest → _SpaceRequest
• _IPixelArea → _PixelArea
• _ITimeInterval → _TimeInterval

Additionally, we fixed the typing information on some Animator return values, so that they now correctly return D3.Transition.Transition or any instead of D3.Selection. See #1104 for more details.

Upcoming API changes

Plot.Bar will replace Plot.HorizontalBar, Plot.VerticalBar, and Plot.ClusteredBar; the default behavior of Plot.Bar will be to cluster the bars. The orientation can be set in the constructor.

Bugfixes for Plot.StackedArea

Good afternoon,

There are two bugfixes in this release:

• Plot.StackedArea now correctly stacks data with 0 values. Note that mixed positive/negative values are not supported on Plot.StackedArea.
• Plot.StackedArea now correctly handles empty datasets.

A Grab Bag of New Features

Good afternoon,

We've got a whole bunch of new features for you this time:

• Missing values / mismatched values on StackedBar and ClusteredBar: Previously, StackedBar and ClusteredBar only supported datasets with exactly identical sets of domain values. Now, missing values are handled gracefully:
  
  
• The rotation angle of tick labels on Axis.Category can now be set with tickLabelAngle(angle). Currently only 0° (horizontal), -90° (vertical-left), and 90° (vertical-right) are supported. Currently, the text-wrapping algorithm may aggressively wrap or truncate rotated labels; we're working on improving the layout engine logic to properly account for this case. In the meantime, the gutter() method can be used to allocate more space for the tick labels.
  
• undefined and NaN values will now be skipped on Plot.Line and Plot.Area. A gap will be drawn instead:
  
• The total animation duration on Animator.IterativeDelay can be set with maxTotalDuration(maxDuration) (defaults to 600ms). If the total time to run the animation exceeds maxTotalDuration(), the delay between successive animations is shortened so the animation runs in the specified maxDuration.

Also, there are some

Breaking Changes

• Label.orient no longer accepts vertical-right/vertical-left. Accepted values are horizontal/left/right.
• Animator.IterativeDelay.iterativeDelay has been renamed to Animator.IterativeDelay.maxIterativeDelay.

Upcoming Changes

Currently, the API for StackedBar, ClusteredBar, and StackedArea are different from those of other Plots. In the interest of having a consistent API, we will be moving all Plots to the new API soon. This change will allow us to add in additional features; for example, adding multiple datasets to a Plot.Line will automatically draw each one as a separate line with a different color. We expect to implement this API change in the next version, v0.33.0.