vega / vega-tooltip Goto Github PK

Currently we are using vega-lite.min.js from the vega-lite github page. The vega-lite library (v1.0.8) we get via npm doesn't seem to have vl.timeUnit.format

When vega-lite composite is ready, we should add logic to the getValue() function in vl-tooltip.js to mute the "[Tooltip] Cannot find field ... in data." warnings when the field is not in a composition.

By default, we use auto format for Vega.

In future version, we can have a option in the API for specifying custom format.

Points, especially the enlarged ones, are not very easy to mouseover. You have to put mouse on the edge of a point to see the tooltip.

In this example I think it's better to use solid marks because they are easier to mouseover:

On the other hand, when marks overlap with each other, hover on edge actually works well. In the example below, hover on edge allows more marks to be picked up.

options.delay can be true or false or a number. If it's false, there will be no delay. If it's true, tooltip will be delayed for 200 ms. If it's a number, tooltip will be delayed for the number of milliseconds provided.

It would be nice to have options.theme that can be light (default) or dark

Right now, there are way too many redundant parts in vl.tooltip and vg.tooltip
that's why you have call everything twice.

This is not a good practice for a few reasons:

• Have to write the code twice for everything
• If you do something wrong, then you have to correct twice.
• It's entirely possible that you'll forget something in one of the place
• Hard for code review.

• two ways
  • add tooltip channel
  • For the tooltip API that gets call inside vg.embed or vg.parse.spec, add a third tooltip: FieldDef[] parameters to the API (1st=view, 2nd=spec) .
    • (Of course only field def that matches fields in the spec would be displayed.)
    • this mean you the spec must have all fields you want to show in tooltip already

Idea

• This plugin becomes vg.embedVegaLiteWithTooltip(..embedparams.., tooltips, callback)

From PR #64

It would be good if we can allow users to specify custom names for tooltip field names. I can pass in alias in the opt object through the API

Since the code is <100 lines and does not leverage any typings, using typescript simply complicates things.

For small codebase like this, using only JS will have the benefit that you have the ready-to-use file in the repo without requiring complicated deploy system.

Example 1:

Example 2:

To fix this, we can read vega-lite default config timeFormat

Related issue: https://github.com/vega/vega-lite-ui/issues/167

Before we release 1.0, we should look ahead and understand how would this work with Vega-Lite's composition.

Currently tooltip for line chart does not report correct data because data is bound to path, not to points. In the screenshot below, price should be a number around 200 and date should be in human-readable format (that's another issue).

This function does not involve interaction.

The inputs and output of this function can have a lot of variations.

/**
  * (Vega-Lite only) Supplement options with vlSpec
  *
  * @param options - user-provided options
  * @param vlSpec - vega-lite spec
  * @return the vlSpec-supplemented options object
  * 
  * if options.showAllFields is true or undefined, vlSpec will supplement
  * options.fields with all fields in the spec
  * if options.showAllFields is false, vlSpec will only supplement existing fields
  * in options.fields
  */
  function supplementOptions(options, vlSpec)

For example, vega-lite-ui has a need to log when tooltip appears and disappears.

vl.tooltip(vgView, vlSpec)
  .on('appear', function() { /* callback */})
  .on('disappear', function() { /* callback */})

• update doc

Right now tooltip is a rectangle with 3px rounded corners. It would be nice to express more shapes (e.g. bubble?)

Our css is simpler, better not use scss.

This will let us correctly show quarters in tooltip.

• result/view object from vega embed

Currently, for Vega-Lite visualizations, if no options is passed in the tooltip will show all top-level fields an item has.

But we should make it so that if no options is passed in, tooltip will only show fields that's used in the visualization, i.e. vl.spec.fieldDefs.

The spirit is that we want the user to specify as little as possible, but make the result look as good as possible.

Right now the APIs are
vlTooltip.linkToView(view, spec, opt)
and
vgTooltip.linkToView(view, opt).

Potentially we want to move the tooltip to vl and vg namespaces (?) Then the APIs will become
vl.tooltip(view, spec, opt)
and
vg.tooltip(view, opt)

Currently our documentation does not contain any code example of using options to customize the tooltip. We can use the ## Options section in customizing_your_tooltip.md to do this.

The tooltip APIs are now documented in this page. So the customizing_your_tooltip.md page should be more like tutorials.

When user calls the destroy() method, all event listeners on that view should be freed, so we don't have memory leak.

vl.tooltip(vgView, vlSpec).destroy()
vg.tooltip(vgView).destroy()

• Update doc

Right now the anchor point on the tooltip is top left, so the tooltip is always at the bottom right of the mouse. It would be nice to allow users to overwrite the anchor point through options. This would make tooltip positioning more flexible.

Related: options.offset.x and options.offset.y describes the x and y distances between the mouse and the tooltip anchor point. Changing the anchor point may create some confusion around offset. For example, if anchorPoint = 'left center', should offset.x be 10px or -10px?

Our documentations contain code examples for Vega-Lite and Vega. Currently they look like this:

Can we make the doc look simpler/shorter/cleaner by using tabs? Here's an example from MSDN:

Once we're done with everything else in 1.0 milestone.

We should integrate this with

• VLUI (hence Voyager and Polestar)

and maybe:

• Vega-Lite docs
• Vega-Editor

(migrated from https://github.com/vega/vega-lite-ui/issues/56)

Currently, the complete structure of options look like this:

var options = {
  showFields: [{ // specify data fields to be shown in the tooltip
    field: ..., // field name in the dataset
    fieldTitle: ..., // (optional) field title the tooltip should display
    type: 'date' | 'number' | 'string',
    format: timeUnit | string specifier
  }],
  offset: { // x and y offset (in pixels) of the tooltip
    x: 10,
    y: 10
  },
  colorTheme: 'light' | 'dark' // specify a color theme the tooltip should use
}

For both Vega-Lite and Vega tooltips, if you want to specify the format of a field you have to put an object like {field:..., format: ...} into options.showFields[], and if you put in an object for one field you have to put in objects for all the other fields that you want to display in the tooltip (because the tooltip plugin right now assumes you only want to display the fields in the showFields array).

It's better to separate fields and their formats. If a user wants to specify a format, she specifies the format -- it doesn't affect the "which fields get displayed" decision.

var options = {
  showFields: ['field1', 'field2', 'field3'],
  fieldsConfig: {
    field1: {
      fieldTitle: ..., // (optional) field title the tooltip should display
      type: 'time' | 'number' | 'string',
      format: timeUnit | string specifier
    }
  },
  offset: { // x and y offset (in pixels) of the tooltip
    x: 10,
    y: 10
  },
  colorTheme: 'light' | 'dark' // specify a color theme the tooltip should use
}

A comment from @arvind – at its simplest form, this plugin is useful for Vega too.

Maybe we can design make this more generic, while optionallly supporting some vega-lite specific features?

• change license to BSD like other vega projects
• use pre 1.0 version
• add a build script

Instead of putting data in master, we can just copy required data from vega-datasets only for gh-pages branch.

Generally we want the user to write a field name without any underscore prefixes in options.fields and options.fieldConfigs. Then the tooltip plugin supplements the field names with underscore prefixes derived from vlSpec. We want to supplement the user-provided field names in order to match the field names returned by item.datum.

For aggregated fields, user should provide field name (e.g. 'yield'). Then tooltip supplements the field name with the aggregate operation (e.g. 'mean_yield'). This should match the field names in item.datum.

One exception is the aggregate operation count, where the field name is '*'. In this case the supplemented field name should be 'count' instead of 'count_*'

For fields with timeUnit, user should provide the field name (e.g. 'date'). Tooltip supplements the field name with the timeUnit (e.g. 'month_date').

For binned fields, user should provide field name (e.g. 'Acceleration'). Tooltip supplements the field name with 'bin_' (e.g. 'bin_Acceleration'). In runtime the tooltip plugin calculates the range of the bin field (issue #29).

If user don't provide options.fields, tooltip supplements options.fields with all fieldDefs in the vlSpec, using the underscore prefixes described above.

For example

vl.tooltip(vgView, vlSpec[, options])
  .showAllFields(false)
  .colorTheme('dark');

• update doc

I'm voting for vega-tooltip?

@domoritz @arvind @jheer – any opinion?

Hover colors would be a nice complement to tooltip, especially when data is dense. With hover color I can actually see which mark is I'm actually looking at.

Currently, if a field in options is a temporal field, the type is date. For example:

var stackedBarOpts = {
    showFields: [
      {
        field: "month_date",
        fieldTitle: "Month",
        type: "date", // right now we use "date", but it can be "time" or "utc"
        format: "month"
      },
      {
        field: "weather",
        fieldTitle: "Weather"
      },
      {
        field: "count",
        fieldTitle: "Count"
      }
    ]
  };

Vega axes formatType uses "time" and "utc"

Currently, in options.fields.formatType we allow three options: number, time, and string.

We want to remove string as an option because

• string don't really have format specifier
• When Vega parses data, the options are number, boolean or date (string is the default and thus not an option) https://github.com/vega/vega/wiki/Data

• take original vega-lite spec as input
• import datalib
• read timeUnit so we can set timeFormat
• read config.numberFormat so we use the correct numberFormat

1. VL / VG

For Vega users, they don't need to code for vega-lite.

For Vega-Lite users, compile a version that provide all the necessary methods within one import.

2. Modularize?

Now we have overlay config for overlaying line and area.

Test if this plugin works well with mark overlayed on top of line and area.
https://github.com/vega/vega-lite/blob/master/examples/specs/overlay_line_short.json
https://github.com/vega/vega-lite/blob/master/examples/specs/overlay_area_short.json