03 · Spec Editor & Draft/Published Workflow

The center pane is where the user reads and edits the active snippet's Vega-Lite specification. It is a code editor for JSON paired with a Draft/Published workflow: edits are made against a working draft that auto-saves silently, drive the Live Preview automatically, and become the snippet's stable version only when explicitly published. The pane is empty when no snippet is selected; it loads the active snippet's spec when one is chosen in the Snippet Library.

A. The Spec Editor

The editor presents the active snippet's spec as formatted JSON with full code-editing affordances tuned for Vega-Lite.

The editor displays the spec as indented, readable JSON with syntax highlighting.
As the user types, the spec is validated against the Vega-Lite schema; problems are surfaced as inline indicators at the offending locations (e.g. squiggles/markers), without blocking continued editing.
The editor offers schema-driven autocomplete/suggestions while typing (property names and allowed values from the Vega-Lite schema).
Pasting content reformats the spec automatically so it stays consistently indented; while typing, the editor maintains consistent indentation as new lines are entered (auto-indent). A format-on-demand action reflows the whole spec to the same compact, readable style.
The editor's appearance and behavior — font size, editor theme, minimap visibility, word wrap, line numbers, and tab size — are configurable and read from Settings; this section does not redefine their defaults.
The editor always edits a single active snippet. Selecting a different snippet in the Snippet Library, or toggling the Draft/Published view, replaces the editor content with the corresponding spec.

B. Auto-Save of the Draft

Edits persist automatically so the user never loses work and never needs an explicit "save" action for ordinary editing.

A short moment after the user stops typing, the current editor content is parsed and stored as the snippet's working draft, silently and with no notification.
Auto-save only commits when the editor content is valid JSON; if the content is momentarily unparseable, the save is skipped and retried after the next pause in typing, so a half-typed spec never overwrites the stored draft.
Auto-save writes the draft only. It never alters the published version (see D. Draft vs Published).
Auto-save is distinct from Publish: auto-save preserves in-progress work; Publish promotes that work to stable.

C. Auto-Render to Preview

Edits flow to the Live Preview automatically, so the user sees results without invoking a render.

A brief moment after the user stops typing, the current spec is sent to the Live Preview for rendering.
The delay before rendering is a configurable debounce (see Settings / Live Preview), letting the user trade responsiveness against churn while typing heavy specs.
Rendering also occurs immediately when a snippet is first loaded into the editor or the Draft/Published view is switched.
Rendering specifics (dataset reference resolution, fit modes) belong to Live Preview; the editor's role is to supply the current spec text on each settle.

D. Draft vs Published Workflow

Every snippet carries two versions of its spec: a published (stable) version and a working draft. This separation is the central editing model. A view toggle in the pane header switches which version the editor shows.

The header offers a Draft/Published toggle; the currently active view is visually indicated.
Draft view shows the working draft and is the editable surface — all typing, auto-save, and auto-render act on the draft.
Published view shows the last published version, for reference; the published version is never modified by ordinary editing.
Editing the draft never touches the published version until the user publishes.
The Snippet Library status indicator reflects whether a snippet currently has unpublished draft changes (draft differs from published); this section only produces that difference, it does not render the indicator.

Publish

A Publish action promotes the current draft to become the published version (the two are made identical).
Publish is also triggered by the keyboard shortcut Cmd/Ctrl+S.
On publish, the snippet's dataset references are recomputed from the now-published spec (see Datasets for reference linking).
A success toast confirms the snippet was published.
Publish is unavailable when no snippet is active.

Revert

A Revert action discards all draft changes and restores the draft to match the last published version.
Revert requires explicit confirmation before discarding, warning that the action cannot be undone.
On confirmation, the editor reloads with the published spec and a toast confirms the draft was reverted.
Revert is unavailable when no snippet is active.

E. Inline Error Surface

When the spec cannot be parsed or cannot be rendered, the editor pane shows the problem clearly while keeping the user in place to fix it.

When the spec is invalid JSON, or is valid JSON but fails to render as Vega-Lite (including an unresolved dataset reference), a clear, readable error message appears in the editor pane, near the editor area.
The error message is plainly legible (monospaced, distinct from normal content) and conveys what went wrong.
The editor remains fully usable while an error is shown, so the user can edit to fix it; the error clears automatically once a subsequent edit renders successfully.
This is the editor-side error affordance only; how a valid spec is drawn lives in Live Preview.

F. Extract Inline Data to a Dataset

When a snippet's spec embeds its data inline, the user can lift that data out into a reusable, named dataset and have the spec reference it instead. This keeps specs lean and lets the same data serve multiple snippets (see Datasets).

When the active snippet's draft spec contains inline data, an Extract to Dataset action is available in the pane header; it is hidden when the spec has no inline data.
Choosing it opens a modal that shows a read-only preview of the inline data and asks the user for a dataset name (required).
The user enters a name and confirms creation. Names must be non-empty and unique; if the name is blank or already in use, the modal shows an inline error and the action does not proceed.
On success, the system: saves the inline data as a new dataset (preserving its detected format), rewrites the snippet's draft spec so the inline data is replaced by a reference to the dataset by name, links the dataset to the snippet, and reloads the editor to show the rewritten spec.
A toast confirms the dataset was created, and the modal closes.
The user can cancel the modal at any time, leaving the spec unchanged.
Dataset-side specifics (formats, storage, the bidirectional snippet↔dataset link) are described in Datasets.

6.9 KiB Raw Blame History