06 · Chart Builder

The Chart Builder is a visual, no-JSON way to compose a Vega-Lite chart from a selected dataset. The user picks a mark type and maps the dataset's columns to encoding channels; the builder produces a complete Vega-Lite spec and saves it as a new snippet that references the dataset. It is intended for users who want to start a chart quickly without hand-writing JSON in the Spec Editor & Draft/Published Workflow.

Opening

Launched from a selected dataset in the Datasets manager via that dataset's "build chart" action.
Opens as a modal dialog over the application; the URL reflects the dataset's "build" action so the open builder is shareable/restorable (see Application Shell & Navigation).
On open, the builder loads the selected dataset, displays its name, and pre-populates sensible defaults (see below). If no dataset is available, it shows a "No dataset loaded" message and offers no controls.

Layout

A two-pane modal:

Left — configuration: dataset name, mark type selector, one row per encoding channel, optional width/height inputs, and a "Create Snippet" action.
Right — live preview: a rendered chart that updates as the configuration changes, with a placeholder/error area.

Inputs and Controls

Mark type

Single selection from an exact set of five mark types: Bar, Line, Point, Area, Circle.
Defaults to Bar.
Exactly one mark type is active at any time; selecting one updates the preview.

Encoding channels

Exactly four channels are offered, in this order: X, Y, Color, Size.
For each channel the user:
- Picks a dataset column from a dropdown of the dataset's detected columns (see Datasets for column detection). A "None" option leaves the channel unmapped. Each column option shows a small type indicator alongside the column name.
- Optionally overrides the channel's field type, chosen from an exact set: Quantitative, Nominal, Ordinal, Temporal. The type override only appears once a column is selected for that channel.
When a column is chosen, its field type defaults from the dataset's inferred column type (numeric → Quantitative, date → Temporal, otherwise Nominal); the user may change it afterward.
Clearing a channel back to "None" leaves it out of the produced spec.

Default pre-population

On open, the first detected column is assigned to X and the second (if any) to Y, each with its derived field type. Remaining channels start unmapped. Mark type starts at Bar.

Dimensions (optional)

Optional numeric Width and Height inputs in pixels.
When left empty, the chart uses default/responsive sizing (consistent with Live Preview); when provided, the values are written into the spec.

Live Preview

The right pane renders the chart described by the current mark, encodings, and dimensions, resolving the dataset reference to its actual data (same rendering behavior as Live Preview).
Updates are debounced: changes to mark, encodings, or dimensions trigger a re-render after a short pause rather than on every keystroke.
While no encoding is mapped, the pane shows a placeholder instructing the user to configure at least one encoding.
If the spec fails to render, the pane shows an inline error message describing the problem instead of a chart.

Validation

A chart requires at least one channel mapped to a column.
While no channel is mapped, the "Create Snippet" action is disabled and the preview shows the configuration prompt.

Output / Create

Selecting "Create Snippet" produces the final artifact:

Builds a complete Vega-Lite spec containing: the schema reference, a named data reference to the dataset, the chosen mark (with tooltips enabled), the mapped encodings (each with its field and field type), and any explicit width/height.
Channels left unmapped are omitted; if no encodings exist the spec omits the encoding block entirely (prevented by validation here).
Creates a new snippet from that spec with an auto-generated descriptive name, adds it to the snippet library, and records that it was built from the dataset.
Links the snippet to the dataset by recording the dataset reference, so the bidirectional snippet↔dataset relationship is established (see Datasets).
Raises a success toast naming the created snippet.
Closes the builder; the newly created snippet becomes the active snippet in the library/editor.

Closing

The builder can be dismissed without creating anything (close control / modal dismissal).
Closing resets all builder state (dataset, mark type, encodings, dimensions, preview) so a later open starts fresh, and any pending preview render is cancelled.

4.6 KiB Raw Blame History