6.4 KiB
04 · Live Preview
The right pane renders the active snippet's current specification as a live Vega-Lite visualization. It mirrors whatever the editor currently shows and updates on its own as the user types, giving immediate visual feedback without any explicit "run" action.
Purpose & Live Updating
- Renders the active snippet's current spec as a Vega-Lite visualization.
- Always reflects the version currently shown in the editor: while the user edits the draft, the preview renders the draft; once published/viewing the published version, it renders that (see Spec Editor & Draft/Published Workflow).
- Updates automatically as the user edits, after a brief render debounce so rapid keystrokes do not trigger constant re-rendering. The debounce delay is user-configurable (see Settings).
- A subtle busy indication may appear over the preview while a render is in progress; it clears when rendering completes.
- When no snippet is active, or the editor content is empty/blank, the preview renders nothing (a clean, empty pane) rather than showing an error.
Dataset Reference Resolution
When a spec uses inline data, the preview renders it directly. When a spec instead references a named dataset from the library, the preview resolves that reference and renders using the stored dataset's contents (see Datasets).
- A spec may point at a dataset from the library by name instead of embedding the data inline.
- Before rendering, the preview substitutes the referenced dataset's stored contents into the spec.
- URL-sourced datasets are fetched as needed at render time.
- If a referenced dataset cannot be found or fetched, the preview shows a readable error (see Error Display) rather than a broken chart.
Fit / Sizing Modes
The preview pane header has a "Fit" control offering exactly four modes that determine how the chart is sized within the pane. The chosen mode applies immediately and re-renders the current chart.
- Original — renders the chart at its natural size as defined by the spec. If the chart is larger than the pane, it overflows and the pane provides scrolling to reach the rest.
- Width — fits the chart's width to the pane (the width becomes responsive to the pane); the height is left to the chart's own natural sizing.
- Height — fits the chart's height to the pane; the width is left to the chart's own natural sizing.
- Full — fits the chart to the pane in both dimensions, so it occupies the full available width and height.
The exact spec transform each mode performs is defined in Rendering Contract below.
Behavior of the selected mode:
- The control shows the four modes with the active one visibly indicated.
- The selected mode persists across sessions, stored in Settings as
previewFitMode. - The default is the natural Original mode.
Rendering Contract
Before the chart is drawn, the spec shown in the editor is transformed into the spec actually rendered. Two deterministic transforms are applied in order. They are specified here because reproducing them faithfully is what makes references and fit modes behave correctly; the result is observable as the rendered chart.
1. Dataset reference resolution. Any named-data reference (data with a name) is replaced in-place with the referenced dataset's actual contents, shaped by the dataset's source and format (see Datasets):
| Dataset source / format | The reference's data becomes |
|---|---|
| URL (any format) | a URL reference to the dataset's address, tagged with its format |
| Inline JSON | the parsed values, inlined |
| Inline CSV / TSV | the raw text, inlined, tagged with its format (CSV or TSV) |
| Inline TopoJSON | the value, inlined, tagged as TopoJSON |
- Resolution recurses into nested sub-specs (layered and concatenated specs, and a parent spec's child
spec), so references anywhere in the spec are resolved. - If a referenced dataset does not exist, rendering fails with a "dataset not found" error (see Error Display).
2. Fit-mode sizing. The selected fit mode rewrites the spec's sizing using Vega-Lite's responsive "container" sizing keyword, recursing into the same nested sub-specs:
| Mode | Transform |
|---|---|
| Original | spec sizing left untouched (the spec's own width/height, or Vega-Lite defaults, apply) |
| Width | set width to "container"; remove any explicit height |
| Height | set height to "container"; remove any explicit width |
| Full | set both width and height to "container" |
- For the responsive (non-Original) modes the chart's container-relative dimension follows the pane size, while the unconstrained dimension is recomputed naturally — this is why Width/Height do not preserve the original aspect ratio.
- The transform operates on a copy; the user's stored spec is never modified by rendering.
The preview renders the resulting spec without the charting library's built-in action/export menu, so the output is a clean chart with no overlaid controls.
Error Display
When a spec cannot be rendered, the preview replaces the chart area with a clear, readable error message rather than a broken or partial visualization, and recovers on its own once the spec becomes valid again.
- Invalid JSON, incomplete specs, Vega-Lite errors, and data problems (e.g. a missing or unfetchable dataset) all surface as a legible error message.
- The message identifies it as a rendering error and includes the underlying reason, with a hint to check the JSON syntax and the Vega-Lite specification.
- As soon as the spec becomes valid again, the error clears automatically and the chart renders without any manual retry.
- Empty/blank specs are not treated as errors — they simply render nothing.
Responsiveness
- The preview re-fits when the pane is resized, re-applying the current fit mode so the chart continues to honor the chosen sizing (see panes in Application Shell & Navigation).
- Resizing does not require a manual refresh; the displayed chart adapts to the new pane dimensions.