mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
Add Chart Builder: no-JSON Vega-Lite composer from a dataset (M4)
This commit is contained in:
@@ -43,6 +43,7 @@ four; that wastes tokens and dilutes the answer. Map the decision to its seat(s)
|
||||
| **Forms / validation / destructive-action** flow | **GOV.UK** → Carbon |
|
||||
| General **usability** gut-check on a flow | **NN/g** 10 heuristics |
|
||||
| **Visual** styling (type, spacing, colour, component look) | **Carbon** + our `docs/architecture/09` |
|
||||
| **Which chart** for the data/intent (chart-type choice) | **FT Visual Vocabulary** + **Datawrapper** |
|
||||
|
||||
Then: read the cited file(s), extract the **specific** principle, and report it back with
|
||||
a **citation (member + file path)** and a one-line "how it lands in Astrolabe." Don't
|
||||
@@ -54,11 +55,13 @@ All paths are under `/Users/oleh/code/reference/`. Treat clones as **inspiration
|
||||
law** — they drift; the published guidance is the truth, the clone is the fast index.
|
||||
|
||||
| Member | Path | Authoritative for | How to query |
|
||||
| ------------------------------ | ---------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| ------------------------------ | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **IBM Carbon** | `carbon-website/src/pages/` | Notification taxonomy, status levels, empty/loading states, content basics, data-viz styling | grep `.mdx` under `components/notification`, `patterns/{empty-states,loading,status-indicator}-pattern`, `guidelines/content` |
|
||||
| **GOV.UK Design System** | `govuk-design-system/src/` | Error & validation messages, failure pages, forms, plain-language content, accessibility | `index.md` under `components/{error-message,error-summary,notification-banner}`, `patterns/{problem-with-the-service-pages,service-unavailable-pages,check-answers}`, `accessibility/` |
|
||||
| **WAI-ARIA APG** | `aria-practices/content/patterns/` | Keyboard interaction, focus management, ARIA roles/states for widgets | `<pattern>/<pattern>-pattern.html` — e.g. `dialog-modal`, `alertdialog`, `alert`, `listbox`, `menu-button`, `disclosure`, `switch`, `tabs`, `tooltip`, `windowsplitter` |
|
||||
| **Nielsen Norman (distilled)** | `principles/nielsen-norman.md` | 10 usability heuristics; response-time / feedback budgets (0.1s / 1s / 10s) | read directly — it is short and curated |
|
||||
| **FT Visual Vocabulary** | `chart-doctor/visual-vocabulary/` | Chart choice: data-relationship taxonomy (Magnitude, Correlation, Change-over-Time, Ranking, Distribution, Deviation, Part-to-whole, Spatial, Flow) → chart type | read `README.md` — the taxonomy is prose; each category gives a "use when…" definition + recommended chart types |
|
||||
| **Datawrapper (distilled)** | `principles/datawrapper.md` | Chart choice in plain language; practical rules of thumb (bar-is-safe-default, line-vs-column, circles hard to compare, size = quantity) | read directly — short and curated; pairs with the FT clone |
|
||||
|
||||
## Close the loop
|
||||
|
||||
@@ -82,6 +85,10 @@ contract, not the external source.
|
||||
have never been applied before. This is the one event that reopens the one-off sweep
|
||||
(see _Scope_); after it, pointwise maintains the new seat like the rest.
|
||||
|
||||
Candidate future seats (not yet seated): **FT Visual Vocabulary / Datawrapper** (chart
|
||||
choice — our domain), **Shopify Polaris** (UX-writing depth), **web.dev** (perceived
|
||||
performance / PWA / offline UX).
|
||||
Candidate future seats (not yet seated): **Shopify Polaris** (UX-writing depth),
|
||||
**web.dev** (perceived performance / PWA / offline UX — seat at M6 per the plan).
|
||||
|
||||
Seated at M4 (chart choice — our domain): **FT Visual Vocabulary** (clone) +
|
||||
**Datawrapper** (distilled). Backfill is scoped to the Chart Builder itself (new
|
||||
surface — no pre-existing chart-choice code to reconcile), so the seating debt is
|
||||
discharged by building the builder against this canon rather than a separate sweep.
|
||||
|
||||
@@ -48,7 +48,7 @@ doc before implementing.
|
||||
| **M1** | **MVP core loop** | Author a Vega-Lite snippet, see it render live, it persists | §02, §03A–C, §04, §09A |
|
||||
| **M1.5** | Visual design foundation ✅ | Apply the design language: tokens, IBM Plex, restyled M1 surfaces, chart theme | [arch 09](architecture/09-visual-design.md) |
|
||||
| **M2** | Editor robustness | Draft/Published, validation, schema autocomplete, fit modes | §03D–E, §04, §07(editor) |
|
||||
| **M3** | Datasets | Named reusable data + reference resolution in preview | §05, §03F, §09B |
|
||||
| **M3** | Datasets ✅ | Named reusable data + reference resolution in preview | §05, §03F, §09B |
|
||||
| **M4** | Chart Builder | No-JSON chart composition from a dataset | §06 |
|
||||
| **M5** | Settings + Import/Export | Preferences + workspace backup/transfer | §07, §08, §09C |
|
||||
| **M6** | Shell polish | Resize/toggle panes, routing, shortcuts, toasts, a11y, offline | §01, §10 |
|
||||
@@ -307,11 +307,15 @@ the reference.
|
||||
- Build a bar chart from a dataset in a few clicks; preview live-updates;
|
||||
Create → new snippet opens and renders.
|
||||
|
||||
**Council** — seat **FT Visual Vocabulary** + **Datawrapper** (chart-choice canon) here:
|
||||
this is where Astrolabe stops being a pass-through JSON editor and starts making
|
||||
**Council** — **FT Visual Vocabulary** + **Datawrapper** are now **seated** (chart-choice
|
||||
canon): this is where Astrolabe stops being a pass-through JSON editor and starts making
|
||||
chart-shaped suggestions/defaults, so "_which chart, and why_" becomes a decision the app
|
||||
owns — the one thing Carbon's data-viz styling doesn't cover. Seating triggers a one-off
|
||||
backfill of the builder's defaults/affordances (see [`/council`](../.claude/skills/council/SKILL.md)).
|
||||
owns — the one thing Carbon's data-viz styling doesn't cover. Rather than a styling-only
|
||||
seating, we ran a full **research-first** pass (FT + Datawrapper + the formal engines
|
||||
**Draco** and **Voyager**), recorded in [`docs/chart-builder-research.md`](chart-builder-research.md),
|
||||
and chose the **Tier B "smart + guarded"** design: smart default mark for the data shape,
|
||||
valid-type-locked field-type menus, Size-channel discipline, and non-blocking guidance.
|
||||
The convergent rules and citations live in that doc; the spec (§06) was amended to match.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,206 @@
|
||||
# Chart Builder — Design Research (M4)
|
||||
|
||||
> **Status:** research complete; informs the M4 build (spec §06).
|
||||
> **Decision:** build **Tier B — "smart + guarded"** (mark-first, still §06-shaped).
|
||||
> **Why this doc exists:** the Chart Builder is the point where Astrolabe stops being
|
||||
> a pass-through JSON editor and starts making chart-shaped suggestions/defaults.
|
||||
> "Which chart, and why" becomes a decision the app owns, so we researched it
|
||||
> deliberately before building. This is the record of what we studied and what we
|
||||
> took from each source — the citations behind every default and guardrail in
|
||||
> `src/core/chart-builder.ts`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Scope of the builder (the constraint everything maps into)
|
||||
|
||||
Spec §06: compose a Vega-Lite chart from a dataset with **one mark** ∈
|
||||
{Bar, Line, Point, Area, Circle}, mapping columns to **four channels** (X, Y, Color,
|
||||
Size), each carrying a **field type** ∈ {Quantitative, Nominal, Ordinal, Temporal},
|
||||
plus optional pixel width/height → a complete spec saved as a snippet that
|
||||
references the dataset by name. Column types are inferred upstream as
|
||||
`number | string | date | boolean` (`src/core/type-inference.ts`).
|
||||
|
||||
No transforms (no binning, aggregation, stacking, regression), no second axis, no
|
||||
geo. That narrow surface is the lens through which every source below was read:
|
||||
"what does this canon tell us to do **within Bar/Line/Point/Area/Circle and
|
||||
X/Y/Color/Size?**"
|
||||
|
||||
## 2. The sources
|
||||
|
||||
Two kinds: **formal CS** (how recommendation engines actually rank charts) and
|
||||
**chart-choice canon** (how practitioners pick). They were chosen for being
|
||||
**cloneable/grep-able offline** (the council's working model) and authoritative for
|
||||
"which chart," which our other seats (Carbon/GOV.UK/APG/NN/g) don't cover.
|
||||
|
||||
| Source | What it is | Local path |
|
||||
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
|
||||
| **Draco** (uwdata) | Visualization design knowledge as ASP constraints — the formal "what makes a good chart," with hard (validity) + soft (preference) rules and weights, some learned from human perception experiments (Kim 2018, Saket 2018). | `reference/draco` |
|
||||
| **Voyager** (vega) | UW IDL's recommendation/exploration tool on CompassQL — the _interaction_ model (field shelves, auto-add, type chips) and effectiveness-ranked encoding suggestions. | `reference/voyager` |
|
||||
| **FT Visual Vocabulary** (Financial Times) | A poster/taxonomy mapping _what you want to show_ (9 data-relationship categories) → chart types. **Seated** in the council. | `reference/chart-doctor/visual-vocabulary/` |
|
||||
| **Datawrapper** | Practitioner chart-choice in plain language; intent-first ("the chart's main statement becomes a compass"). **Seated** (distilled). | `reference/principles/datawrapper.md` |
|
||||
|
||||
**Theoretical basis, not seated (deliberately):** **Munzner**, _Visualization Analysis
|
||||
and Design_ (marks & channels; the channel-effectiveness rankings — magnitude:
|
||||
position → length → angle → area …; identity: spatial region → hue → shape;
|
||||
expressiveness & effectiveness principles) and **Wilke**, _Fundamentals of Data
|
||||
Visualization_ (`clauswilke/dataviz`; example directory by intent + "ugly/bad/wrong"
|
||||
pedagogy). They are the _why_ beneath Draco and Voyager — Draco's soft weights are an
|
||||
operationalization of exactly these Mackinlay/APT/Munzner effectiveness rankings — but
|
||||
they restate the same rules the seated sources already give us, so seating them would
|
||||
add overlap, not coverage. Cited here as grounding; revisit if we ever build the
|
||||
intent-first "Tier C" front door, where Munzner's typology and Wilke's directory
|
||||
would earn their place.
|
||||
|
||||
## 3. What we take from each source
|
||||
|
||||
### From Draco — validity guardrails + a preference ranking (the rigorous core)
|
||||
|
||||
Draco models a chart as ASP facts and rejects/ranks them with **hard** (∞ cost) and
|
||||
**soft** (weighted) constraints (`asp/optimize.lp`). We can't ship an ASP solver in a
|
||||
browser, but the rules are a lookup table. The portable subset:
|
||||
|
||||
- **Hard validity (block in the UI):** `reference/draco/asp/hard.lp`
|
||||
- Quantitative on a string/boolean column — illegal (`:6`). Temporal only on a
|
||||
datetime column (`:7`).
|
||||
- **Size encoding a Nominal field — illegal** ("size implies order; nominal is
|
||||
misleading", `:53`). Size cannot encode **negative** values (`:56`). Size only on
|
||||
point/text marks (`:110`).
|
||||
- Bar/Area must include a **zero baseline** on the measure axis (`:103-104`).
|
||||
- Bar needs a categorical axis — both x and y continuous on a bar is malformed
|
||||
(`:97`); Line/Area need **both** x and y, and not both discrete (`:91,:94`).
|
||||
- Same field on x and y — illegal (`:122`). >20 categorical colors — illegal (`:172`).
|
||||
- **Soft preference (the weights, `asp/weights.lp` + `asp/soft.lp`):**
|
||||
- Channel-by-type appropriateness (lower = better): continuous data is free on x/y,
|
||||
costs to put on color (10) or size (1); nominal cheapest on y then x then color;
|
||||
ordered data expensive on size. → **fill X/Y before Color/Size.**
|
||||
- Mark by data shape: continuous×continuous → **point** (line/area heavily
|
||||
penalized); continuous×discrete aggregated → **bar**; discrete×discrete → point/rect.
|
||||
- Prefer time on x (`temporal_y`, `:147`); never type a number as nominal
|
||||
(`number_nominal`, weight 10); the loudest nudge is an all-discrete chart with no
|
||||
measure (`only_discrete`, weight 30).
|
||||
|
||||
The hand-tuned `weights.lp` is the portable "common-sense" set; the learned
|
||||
`weights_learned.lp` corroborates direction, not magnitude.
|
||||
|
||||
### From Voyager — the interaction model + the valid-type table
|
||||
|
||||
- **`getValidTypes` (`src/components/data-pane/field-list.tsx:140-155`) — adopted
|
||||
almost verbatim:** number→{quantitative, nominal}, integer→{quantitative, nominal},
|
||||
datetime→{temporal}, string→{nominal}, boolean→{nominal}. The type toggle shows only
|
||||
when ≥2 valid types exist. (We extend slightly — see §4 — to also offer Ordinal,
|
||||
which Voyager deliberately omits, `encoding.ts:131-134`.)
|
||||
- **Auto-add / "auto" mark (`models/shelf/index.ts:72-81`):** Voyager lets a field be
|
||||
added with `channel:'?'` and asks CompassQL to place it by `effectiveness`. The small
|
||||
builder analogue is a **non-empty smart default** (`defaultBuilderConfig`) so the
|
||||
preview is never blank.
|
||||
- **Type chips + swap:** per-field type indicator with a click-to-change popover, and a
|
||||
cheap x↔y swap (Voyager's `SPEC_FIELD_MOVE` is remove-both + re-add).
|
||||
- **Out of scope (Voyager scope creep we reject):** wildcard shelves, the full Related
|
||||
Views gallery, faceting (row/column), and embedding CompassQL/`compassql@0.20.2`
|
||||
itself. We hand-roll a small decision table in `src/core/` instead of pulling the
|
||||
engine.
|
||||
|
||||
### From FT Visual Vocabulary — the intent→chart taxonomy (and our coverage gaps)
|
||||
|
||||
`reference/chart-doctor/visual-vocabulary/README.md` (taxonomy is prose). Nine
|
||||
categories; mapped to **our five marks**:
|
||||
|
||||
| FT category | What it shows | Our expression |
|
||||
| -------------------- | --------------------------- | ----------------------------------------------------------------------------- |
|
||||
| **Magnitude** | size comparisons | **Bar** (x=N, y=Q; horizontal x=Q, y=N for long labels) — primary |
|
||||
| **Ranking** | position in an ordered list | **Bar, sorted** by value (the sort _is_ the feature) |
|
||||
| **Change over Time** | trends | **Line** (x=T, y=Q; color=N for series); Bar/Area alternatives, single series |
|
||||
| **Correlation** | relationship of 2+ measures | **Point** (x=Q, y=Q); **Circle/bubble** + size=Q for a third measure |
|
||||
| **Deviation** | +/− from a reference | **Bar** with signed Q (diverging bar only) |
|
||||
| **Distribution** | spread/frequency | weak: raw **Point** strip, or **Bar** of pre-binned counts (no bin transform) |
|
||||
| **Part-to-whole** | component shares | **none well** — redirect to Magnitude/Bar; we can't show true proportions |
|
||||
| **Spatial** | geography | **none** — exclude |
|
||||
| **Flow** | movement between states | **none** — exclude |
|
||||
|
||||
**Coverage:** strong on Magnitude, Ranking, Change-over-Time, Correlation; partial on
|
||||
Deviation/Distribution; none on Part-to-whole/Spatial/Flow. Honest gaps, not silent
|
||||
degradation.
|
||||
|
||||
### From Datawrapper — plain-language rules + intent labels
|
||||
|
||||
`reference/principles/datawrapper.md`. Corroborates the same default-mark-by-intent
|
||||
table (comparison→Bar, time→Line, correlation→Point/bubble) and supplies friendlier
|
||||
intent words (Developments over time / Shares / Comparison / Correlation). Bindable
|
||||
rules: bar is the safe default; bar over column on small screens; line for continuous
|
||||
time, columns for a few points; circles are hard to compare precisely; size encodes a
|
||||
quantity; area = single total (warn on multi-series).
|
||||
|
||||
## 4. The convergent rules — what all four agree on (high-confidence)
|
||||
|
||||
These are not a judgment call; the formal engines and the practitioner canon land on
|
||||
the same place. They are the spec for `src/core/chart-builder.ts`:
|
||||
|
||||
1. **Column type → valid field types** (Voyager `getValidTypes`; Draco `hard.lp:6-7`):
|
||||
`number`→{Quantitative (default), Ordinal, Nominal}; `date`→{Temporal only};
|
||||
`string`→{Nominal (default), Ordinal}; `boolean`→{Nominal}. Never offer Q for
|
||||
string/boolean, never Temporal for a non-date. (We add Ordinal where it's a defensible
|
||||
user assertion of order; Voyager omits it for UX simplicity — our deliberate superset.)
|
||||
2. **Default mark from the (X, Y) shape** (Draco mark-by-shape; Voyager effectiveness;
|
||||
FT; Datawrapper): temporal × quantitative → **Line**; quantitative × quantitative →
|
||||
**Point**; (nominal/ordinal) × quantitative → **Bar**; both-discrete → **Point**
|
||||
(Bar/Line/Area are invalid with no continuous axis); single axis or unknown → Bar.
|
||||
3. **Channel priority + Size discipline** (Draco `hard.lp:53,56,110` + non-positional
|
||||
pref): fill X/Y before Color/Size; Color before Size. **Size is only valid for
|
||||
Quantitative/Ordinal positive measures on Point/Circle marks** — disabled for Nominal,
|
||||
Temporal, and negative data (not merely discouraged).
|
||||
4. **Bar/Area zero-baseline; Line exempt** (Draco `hard.lp:103-104`; FT; ONS/Vox sources
|
||||
FT links). We expose no axis-truncation control, so Vega-Lite's own defaults already
|
||||
give zero-baseline bars and free-baseline lines — the rule is satisfied by _not adding_
|
||||
an override, nothing to emit.
|
||||
5. **Chart-choice polish** (FT; Datawrapper): sort bars when ranking; horizontal bar for
|
||||
long category labels; Size encodes a quantity, Color a category; Area is for a single
|
||||
series (warn against color-splitting into many).
|
||||
|
||||
## 5. The decision: Tier B — "smart + guarded"
|
||||
|
||||
Three tiers were on the table. **Tier B** was chosen (2026-06-05).
|
||||
|
||||
- **Tier A — spec-literal:** Bar default, four channel dropdowns, type override, smart
|
||||
pre-population. Matches §06 verbatim but uses almost none of the research; stays a
|
||||
"dumb" composer.
|
||||
- **Tier B — smart + guarded (chosen):** Tier A **+** default _mark_ from the (X, Y) type
|
||||
shape (not always Bar) **+** valid-type-only menus **+** inline non-blocking warnings
|
||||
from the Draco rules **+** swap-X/Y **+** Size disabled for Nominal/Temporal/negative.
|
||||
Still mark-first and §06-shaped, but genuinely intelligent. Requires a small §06
|
||||
amendment (documented in the spec).
|
||||
- **Tier C — intent-first aid:** Tier B **+** a "what do you want to show?" front door
|
||||
(FT/Datawrapper intents → recommended mark + channel layout from intent × column
|
||||
types). Highest "which chart & why" value; biggest UI; clearly extends §06. Deferred —
|
||||
if revisited, this is where Munzner's typology and Wilke's directory would be seated.
|
||||
|
||||
## 6. How it maps to implementation
|
||||
|
||||
The convergent rules become pure functions in `src/core/chart-builder.ts`
|
||||
(tested in `chart-builder.test.ts`), consumed by the builder store/modal:
|
||||
|
||||
- `validFieldTypes(columnType)` → the type menu (rule 1); `defaultFieldType` = its head.
|
||||
- `defaultMark(xType, yType)` → smart default mark (rule 2); used by
|
||||
`defaultBuilderConfig`.
|
||||
- `isChannelTypeAllowed(channel, type)` → Size discipline gate (rule 3).
|
||||
- `builderWarnings(config)` → inline non-blocking hints (rules 3–5: line/area need both
|
||||
axes, area + many series, two measures better as a scatter, etc.).
|
||||
- `buildChartSpec` / `buildSnippetSpecText` → assemble the final spec; zero-baseline is
|
||||
Vega-Lite-default (rule 4), so nothing is emitted for it.
|
||||
|
||||
## 7. Anti-recommendations (what a naive builder would happily produce, and we don't)
|
||||
|
||||
The highest-value guardrails — encodings a naive UI emits that the canon rejects:
|
||||
|
||||
- A categorical column on **Size** (Draco hard `:53`) — blocked, not warned.
|
||||
- A **truncated-axis bar** — prevented by never exposing an axis override (Draco `:103`).
|
||||
- A high-cardinality category on **Color** → unreadable legend (soft w=10; >20 hard).
|
||||
- A **Line between two raw measures** instead of a scatter (Draco soft w=20) — warned.
|
||||
- An **all-categorical chart with no measure** (Draco soft w=30, the loudest) — warned.
|
||||
- A **number typed Nominal** (Draco soft w=10) — discouraged via default = Quantitative.
|
||||
|
||||
---
|
||||
|
||||
_Citations are to files under `/Users/oleh/code/reference/`. The seated chart-choice
|
||||
canon (FT clone + Datawrapper distill) lives in the council roster
|
||||
(`.claude/skills/council/SKILL.md`); Draco/Voyager are reference clones, not council
|
||||
seats — they're engineering sources, not user-facing design authorities._
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
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_.
|
||||
|
||||
> **Design level — "smart + guarded" (Tier B).** The builder is mark-first and stays within the inputs below, but it is not a dumb composer: it picks a sensible default mark for the data shape, offers only field types valid for each column, keeps unsuitable channel mappings out of reach, and surfaces non-blocking guidance for encodings that render poorly. These behaviors are derived from cross-source chart-choice research recorded in [`docs/chart-builder-research.md`](../chart-builder-research.md) (the convergence of Draco, Voyager, the FT Visual Vocabulary, and Datawrapper). The richer "intent-first" front door (ask _what do you want to show?_ and recommend a chart) is explicitly out of scope for now and noted there as a future tier.
|
||||
|
||||
## Opening
|
||||
|
||||
- Launched from a selected dataset in the _Datasets_ manager via that dataset's "build chart" action.
|
||||
@@ -20,7 +22,7 @@ A two-pane modal:
|
||||
### Mark type
|
||||
|
||||
- Single selection from an exact set of five mark types: **Bar, Line, Point, Area, Circle**.
|
||||
- Defaults to **Bar**.
|
||||
- On open, the mark **defaults to the type that best fits the pre-populated X/Y field-type shape** (Tier B smart default): a temporal axis against a measure → **Line**; two measures → **Point**; a category against a measure → **Bar**; two categories → **Point**; and **Bar** as the fallback when only one axis (or none) is mapped. The user can switch to any of the five afterward.
|
||||
- Exactly one mark type is active at any time; selecting one updates the preview.
|
||||
|
||||
### Encoding channels
|
||||
@@ -28,13 +30,26 @@ A two-pane modal:
|
||||
- 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.
|
||||
- Optionally overrides the channel's **field type**. The override appears only once a column is selected, and offers only the **types valid for that column** (Tier B valid-type locking) — a string/boolean column never offers Quantitative, and only a date column offers Temporal. Concretely: number → {Quantitative (default), Ordinal, Nominal}; date → {Temporal}; text → {Nominal (default), Ordinal}; boolean → {Nominal}. When a column admits only one valid type, no override control is shown.
|
||||
- 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 within the valid set above.
|
||||
- **Size discipline:** the **Size** channel accepts only Quantitative or Ordinal columns — size implies an ordered magnitude, so categorical (Nominal) and Temporal columns are not offered for Size (they remain available on X/Y/Color). A column that can't go on Size is shown disabled there with a brief reason.
|
||||
- Clearing a channel back to "None" leaves it out of the produced spec.
|
||||
- A **Swap X/Y** control exchanges the X and Y mappings (field and type) in one click, for quickly flipping the axes of the pre-populated default without re-selecting both columns.
|
||||
|
||||
### 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.
|
||||
- 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. The mark starts at the smart default for that X/Y shape (see _Mark type_), not unconditionally Bar.
|
||||
|
||||
### Guidance (non-blocking)
|
||||
|
||||
The builder surfaces short, plain-language hints for configurations that render but read poorly — advisory only, never blocking the **Create Snippet** action (validation below is the sole gate). These follow the chart-choice research ([`docs/chart-builder-research.md`](../chart-builder-research.md)) and include, for example:
|
||||
|
||||
- A **Line** or **Area** mark with only one axis mapped (both axes are needed to draw it).
|
||||
- A **Bar/Line/Area** whose X and Y are both categories (nothing to measure).
|
||||
- **Two measures** on a non-scatter mark (a scatter — Point/Circle — usually reads better).
|
||||
- An **Area** chart split into multiple colour series (per-series change is hard to see).
|
||||
|
||||
A clean configuration shows no hints.
|
||||
|
||||
### Dimensions (optional)
|
||||
|
||||
|
||||
@@ -0,0 +1,254 @@
|
||||
/* Chart Builder — two-pane modal body (spec §06). */
|
||||
|
||||
.builder {
|
||||
display: grid;
|
||||
grid-template-columns: minmax(320px, 360px) 1fr;
|
||||
min-height: 480px;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.muted {
|
||||
margin: 0;
|
||||
padding: var(--space-5);
|
||||
font-size: 14px;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
/* ── Left: configuration ─────────────────────────────────────────────── */
|
||||
|
||||
.configPane {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-5);
|
||||
padding: var(--space-5);
|
||||
border-right: var(--border-width) solid var(--border);
|
||||
overflow-y: auto;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.datasetName {
|
||||
margin: 0;
|
||||
font-size: 13px;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.datasetName strong {
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.field {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-2);
|
||||
}
|
||||
|
||||
.fieldLabel {
|
||||
font-size: 12px;
|
||||
font-weight: 500;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.channels {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-3);
|
||||
}
|
||||
|
||||
.channelsHeader {
|
||||
display: flex;
|
||||
align-items: baseline;
|
||||
justify-content: space-between;
|
||||
}
|
||||
|
||||
.swap {
|
||||
border: none;
|
||||
background: transparent;
|
||||
color: var(--accent);
|
||||
font: inherit;
|
||||
font-size: 12px;
|
||||
cursor: pointer;
|
||||
padding: var(--space-1) var(--space-2);
|
||||
border-radius: var(--radius);
|
||||
}
|
||||
|
||||
.swap:hover {
|
||||
background: var(--layer-01);
|
||||
}
|
||||
|
||||
.swap:focus-visible {
|
||||
outline: 2px solid var(--focus);
|
||||
outline-offset: 1px;
|
||||
}
|
||||
|
||||
.channelRow {
|
||||
display: grid;
|
||||
grid-template-columns: 48px 1fr auto;
|
||||
align-items: center;
|
||||
gap: var(--space-2);
|
||||
}
|
||||
|
||||
.channelLabel {
|
||||
font-size: 12px;
|
||||
font-weight: 600;
|
||||
color: var(--text);
|
||||
}
|
||||
|
||||
.select,
|
||||
.typeSelect {
|
||||
padding: var(--space-2) var(--space-3);
|
||||
border: var(--border-width) solid var(--border-strong);
|
||||
border-radius: var(--radius);
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
font: inherit;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.typeSelect {
|
||||
font-size: 12px;
|
||||
}
|
||||
|
||||
.select:focus-visible,
|
||||
.typeSelect:focus-visible,
|
||||
.dimInput:focus-visible {
|
||||
outline: 2px solid var(--focus);
|
||||
outline-offset: -1px;
|
||||
}
|
||||
|
||||
.dimensions {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-2);
|
||||
}
|
||||
|
||||
.dimInputs {
|
||||
display: flex;
|
||||
gap: var(--space-3);
|
||||
}
|
||||
|
||||
.dimField {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-1);
|
||||
font-size: 12px;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.dimInput {
|
||||
width: 100px;
|
||||
padding: var(--space-2) var(--space-3);
|
||||
border: var(--border-width) solid var(--border-strong);
|
||||
border-radius: var(--radius);
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
font: inherit;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.warnings {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
gap: var(--space-2);
|
||||
margin: 0;
|
||||
padding: var(--space-3);
|
||||
list-style: none;
|
||||
background: var(--layer-01);
|
||||
border: var(--border-width) solid var(--border);
|
||||
border-radius: var(--radius);
|
||||
}
|
||||
|
||||
.warning {
|
||||
font-size: 12px;
|
||||
line-height: 1.4;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.warning::before {
|
||||
content: '⚠ ';
|
||||
color: var(--support-warning, var(--text-secondary));
|
||||
}
|
||||
|
||||
.actions {
|
||||
display: flex;
|
||||
justify-content: flex-end;
|
||||
gap: var(--space-3);
|
||||
margin-top: auto;
|
||||
}
|
||||
|
||||
.action {
|
||||
height: 36px;
|
||||
padding: 0 var(--space-5);
|
||||
border: var(--border-width) solid var(--border-strong);
|
||||
border-radius: var(--radius);
|
||||
background: transparent;
|
||||
color: var(--text);
|
||||
font: inherit;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: background var(--dur-fast) var(--ease);
|
||||
}
|
||||
|
||||
.action:hover {
|
||||
background: var(--layer-01);
|
||||
}
|
||||
|
||||
.action:focus-visible {
|
||||
outline: 2px solid var(--focus);
|
||||
outline-offset: 2px;
|
||||
}
|
||||
|
||||
.primary {
|
||||
background: var(--accent);
|
||||
border-color: transparent;
|
||||
color: var(--accent-contrast);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.primary:hover {
|
||||
background: var(--accent-hover);
|
||||
}
|
||||
|
||||
.primary:disabled {
|
||||
background: var(--layer-02, var(--layer-01));
|
||||
color: var(--text-placeholder);
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
/* ── Right: live preview ─────────────────────────────────────────────── */
|
||||
|
||||
.previewPane {
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
padding: var(--space-5);
|
||||
min-width: 0;
|
||||
background: var(--bg);
|
||||
}
|
||||
|
||||
.previewHint {
|
||||
margin: auto;
|
||||
font-size: 13px;
|
||||
color: var(--text-secondary);
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.previewFrame {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
}
|
||||
|
||||
.previewHost {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.previewError {
|
||||
margin: auto 0;
|
||||
padding: var(--space-3);
|
||||
font-family: var(--font-mono);
|
||||
font-size: 12px;
|
||||
line-height: 1.5;
|
||||
white-space: pre-wrap;
|
||||
color: var(--support-error);
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
|
||||
import { act } from 'react';
|
||||
import { createRoot, type Root } from 'react-dom/client';
|
||||
import { createDataset } from '@core/dataset';
|
||||
import { useChartBuilderStore } from '../stores/ChartBuilderStore';
|
||||
import { useDatasetStore } from '../stores/DatasetStore';
|
||||
import { useSnippetStore } from '../stores/SnippetStore';
|
||||
import { ChartBuilderModal } from './ChartBuilderModal';
|
||||
|
||||
// The builder preview embeds a real Vega chart in an effect; stub the renderer so
|
||||
// this render test stays a pure React/DOM check (the loop we guard against happens
|
||||
// during commit, long before any chart is drawn).
|
||||
vi.mock('../services/chart-renderer', () => ({
|
||||
renderSpec: () => Promise.resolve({ destroy() {}, resize() {} }),
|
||||
}));
|
||||
|
||||
// React 19 wants this flag set for act() to drive effects without warnings.
|
||||
(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
|
||||
|
||||
const T = new Date('2026-06-01T00:00:00Z');
|
||||
let container: HTMLDivElement;
|
||||
let root: Root;
|
||||
|
||||
beforeEach(() => {
|
||||
useChartBuilderStore.getState().reset();
|
||||
useDatasetStore.getState().reset();
|
||||
useSnippetStore.getState().reset();
|
||||
container = document.createElement('div');
|
||||
document.body.appendChild(container);
|
||||
root = createRoot(container);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
act(() => root.unmount());
|
||||
container.remove();
|
||||
});
|
||||
|
||||
describe('ChartBuilderModal', () => {
|
||||
test('renders without an infinite update loop when the config has warnings (regression)', async () => {
|
||||
// Two numeric columns → default mark Point (clean). Switching to Bar makes it
|
||||
// "two measures on a non-scatter" → a NON-EMPTY warnings array — the exact
|
||||
// condition that previously looped because the warnings selector returned a
|
||||
// fresh array of objects on every render. The fix derives warnings via useMemo
|
||||
// over the stable `config` reference instead.
|
||||
const ds = createDataset({
|
||||
name: 'Nums',
|
||||
data: [
|
||||
{ a: 1, b: 2 },
|
||||
{ a: 3, b: 4 },
|
||||
],
|
||||
format: 'json',
|
||||
source: 'inline',
|
||||
now: T,
|
||||
});
|
||||
useDatasetStore.getState().add(ds);
|
||||
useChartBuilderStore.getState().init(ds.id);
|
||||
useChartBuilderStore.getState().setMark('bar');
|
||||
expect(useChartBuilderStore.getState().config.mark).toBe('bar');
|
||||
|
||||
// If the component looped, this act() would throw "Maximum update depth exceeded".
|
||||
await act(async () => {
|
||||
root.render(<ChartBuilderModal />);
|
||||
await Promise.resolve();
|
||||
});
|
||||
|
||||
expect(container.textContent).toContain('Building from');
|
||||
expect(container.textContent).toContain('scatter'); // the guidance hint rendered
|
||||
});
|
||||
|
||||
test('shows the empty state when no dataset is loaded', async () => {
|
||||
await act(async () => {
|
||||
root.render(<ChartBuilderModal />);
|
||||
await Promise.resolve();
|
||||
});
|
||||
expect(container.textContent).toContain('No dataset loaded');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,333 @@
|
||||
/**
|
||||
* Chart Builder — the modal body (spec §06).
|
||||
*
|
||||
* A two-pane composer: left is the configuration (dataset name, mark selector, one
|
||||
* row per channel, optional dimensions, guidance, Create), right is a live preview
|
||||
* of the spec the configuration produces. All spec logic and Tier-B defaults/guards
|
||||
* come from `@core/chart-builder` via `ChartBuilderStore`; this component is the
|
||||
* view. The preview is builder-local (its own debounced render over the shared
|
||||
* `chart-renderer` service) rather than a reuse of `LivePreview`, which is bound to
|
||||
* the snippet editor's stores.
|
||||
*/
|
||||
|
||||
import { useEffect, useMemo, useRef, useState } from 'react';
|
||||
import { useShallow } from 'zustand/react/shallow';
|
||||
import type { VisualizationSpec } from 'vega-embed';
|
||||
import {
|
||||
CHANNELS,
|
||||
MARK_TYPES,
|
||||
builderWarnings,
|
||||
defaultFieldType,
|
||||
isBuilderConfigValid,
|
||||
isChannelTypeAllowed,
|
||||
validFieldTypes,
|
||||
type ChannelName,
|
||||
type FieldType,
|
||||
type MarkType,
|
||||
} from '@core/chart-builder';
|
||||
import type { ColumnType } from '@core/type-inference';
|
||||
import { DatasetNotFoundError, prepareSpecForRender } from '@core/rendering';
|
||||
import { chartConfigFor } from '@core/vega-themes';
|
||||
import { renderSpec, type RenderHandle } from '../services/chart-renderer';
|
||||
import { closeModal } from '../modals/ModalCoordinator';
|
||||
import { useAppStore } from '../stores/AppStore';
|
||||
import { useDatasetStore } from '../stores/DatasetStore';
|
||||
import {
|
||||
selectBuilderSpecText,
|
||||
selectBuilderValid,
|
||||
useChartBuilderStore,
|
||||
} from '../stores/ChartBuilderStore';
|
||||
import { SegmentedControl, type SegmentedOption } from './SegmentedControl';
|
||||
import styles from './ChartBuilderModal.module.css';
|
||||
|
||||
const RENDER_DEBOUNCE_MS = 300;
|
||||
|
||||
/** Title-case a token for display (e.g. `bar` → `Bar`, `quantitative` → `Quantitative`). */
|
||||
function titleCase(s: string): string {
|
||||
return s.charAt(0).toUpperCase() + s.slice(1);
|
||||
}
|
||||
|
||||
const MARK_OPTIONS: ReadonlyArray<SegmentedOption<MarkType>> = MARK_TYPES.map((m) => ({
|
||||
value: m,
|
||||
label: titleCase(m),
|
||||
}));
|
||||
|
||||
const CHANNEL_LABELS: Record<ChannelName, string> = {
|
||||
x: 'X',
|
||||
y: 'Y',
|
||||
color: 'Color',
|
||||
size: 'Size',
|
||||
};
|
||||
|
||||
/** A compact type indicator for a column option (text · # · date · ✓). */
|
||||
function typeBadge(type: ColumnType): string {
|
||||
switch (type) {
|
||||
case 'number':
|
||||
return '#';
|
||||
case 'date':
|
||||
return 'date';
|
||||
case 'boolean':
|
||||
return 'bool';
|
||||
default:
|
||||
return 'text';
|
||||
}
|
||||
}
|
||||
|
||||
/** Whether a column may be placed on a channel at all (Size discipline, §06). */
|
||||
function columnAllowedOnChannel(channel: ChannelName, colType: ColumnType): boolean {
|
||||
return isChannelTypeAllowed(channel, defaultFieldType(colType));
|
||||
}
|
||||
|
||||
function ChannelRow({ channel }: { channel: ChannelName }) {
|
||||
const columns = useChartBuilderStore((s) => s.columns);
|
||||
const mapping = useChartBuilderStore((s) => s.config.encodings[channel] ?? null);
|
||||
const setChannelColumn = useChartBuilderStore((s) => s.setChannelColumn);
|
||||
const setChannelType = useChartBuilderStore((s) => s.setChannelType);
|
||||
|
||||
const colTypeOf = (name: string): ColumnType =>
|
||||
columns.columnTypes.find((c) => c.name === name)?.type ?? 'string';
|
||||
|
||||
// Type options valid for this column AND allowed on this channel (e.g. Size hides
|
||||
// Nominal). Shown only when >1 option and a column is selected (spec §06).
|
||||
const typeOptions: FieldType[] = mapping
|
||||
? validFieldTypes(colTypeOf(mapping.field)).filter((t) => isChannelTypeAllowed(channel, t))
|
||||
: [];
|
||||
|
||||
return (
|
||||
<div className={styles.channelRow}>
|
||||
<label className={styles.channelLabel} htmlFor={`ch-${channel}`}>
|
||||
{CHANNEL_LABELS[channel]}
|
||||
</label>
|
||||
<select
|
||||
id={`ch-${channel}`}
|
||||
className={styles.select}
|
||||
value={mapping?.field ?? ''}
|
||||
onChange={(e) => setChannelColumn(channel, e.target.value === '' ? null : e.target.value)}
|
||||
>
|
||||
<option value="">None</option>
|
||||
{columns.columns.map((name) => {
|
||||
const allowed = columnAllowedOnChannel(channel, colTypeOf(name));
|
||||
return (
|
||||
<option key={name} value={name} disabled={!allowed}>
|
||||
{name} · {typeBadge(colTypeOf(name))}
|
||||
{allowed ? '' : ' (needs a measure)'}
|
||||
</option>
|
||||
);
|
||||
})}
|
||||
</select>
|
||||
|
||||
{mapping && typeOptions.length > 1 && (
|
||||
<select
|
||||
className={styles.typeSelect}
|
||||
aria-label={`${CHANNEL_LABELS[channel]} field type`}
|
||||
value={mapping.type}
|
||||
onChange={(e) => setChannelType(channel, e.target.value as FieldType)}
|
||||
>
|
||||
{typeOptions.map((t) => (
|
||||
<option key={t} value={t}>
|
||||
{titleCase(t)}
|
||||
</option>
|
||||
))}
|
||||
</select>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
function BuilderPreview() {
|
||||
const hostRef = useRef<HTMLDivElement>(null);
|
||||
const handleRef = useRef<RenderHandle | null>(null);
|
||||
const generationRef = useRef(0);
|
||||
const [error, setError] = useState<string | null>(null);
|
||||
|
||||
const specText = useChartBuilderStore(selectBuilderSpecText);
|
||||
const valid = useChartBuilderStore(selectBuilderValid);
|
||||
const uiTheme = useAppStore((s) => s.uiTheme);
|
||||
const datasets = useDatasetStore(useShallow((s) => s.datasets));
|
||||
|
||||
useEffect(() => {
|
||||
const node = hostRef.current;
|
||||
const timer = setTimeout(() => {
|
||||
void (async () => {
|
||||
const mine = ++generationRef.current;
|
||||
// Below validation there is nothing to draw — clear the chart and show the
|
||||
// configuration prompt, not an error (spec §06 → Live Preview placeholder).
|
||||
if (!valid) {
|
||||
handleRef.current?.destroy();
|
||||
handleRef.current = null;
|
||||
setError(null);
|
||||
return;
|
||||
}
|
||||
if (!node) return;
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(specText);
|
||||
const prepared = prepareSpecForRender(parsed, { fitMode: 'width', datasets });
|
||||
handleRef.current?.destroy();
|
||||
handleRef.current = null;
|
||||
const handle = await renderSpec(
|
||||
node,
|
||||
prepared as VisualizationSpec,
|
||||
chartConfigFor(uiTheme),
|
||||
);
|
||||
if (mine !== generationRef.current) {
|
||||
handle.destroy();
|
||||
return;
|
||||
}
|
||||
handleRef.current = handle;
|
||||
setError(null);
|
||||
} catch (e) {
|
||||
if (mine !== generationRef.current) return;
|
||||
if (e instanceof DatasetNotFoundError) {
|
||||
setError(`Dataset "${e.datasetName}" not found.`);
|
||||
} else {
|
||||
setError(`Couldn't render this chart: ${(e as Error).message}`);
|
||||
}
|
||||
}
|
||||
})();
|
||||
}, RENDER_DEBOUNCE_MS);
|
||||
|
||||
return () => clearTimeout(timer);
|
||||
}, [specText, valid, uiTheme, datasets]);
|
||||
|
||||
// Finalize the view on unmount so the Vega view and its listeners don't leak.
|
||||
useEffect(
|
||||
() => () => {
|
||||
handleRef.current?.destroy();
|
||||
handleRef.current = null;
|
||||
},
|
||||
[],
|
||||
);
|
||||
|
||||
return (
|
||||
<div className={styles.previewPane}>
|
||||
{!valid && (
|
||||
<p className={styles.previewHint}>Map at least one channel to a column to see a chart.</p>
|
||||
)}
|
||||
<div className={styles.previewFrame} hidden={!valid || error !== null}>
|
||||
<div className={styles.previewHost} ref={hostRef} />
|
||||
</div>
|
||||
{valid && error !== null && (
|
||||
<pre className={styles.previewError} role="alert">
|
||||
{error}
|
||||
</pre>
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function ChartBuilderModal() {
|
||||
const datasetId = useChartBuilderStore((s) => s.datasetId);
|
||||
const datasetName = useChartBuilderStore((s) => s.config.datasetName);
|
||||
const mark = useChartBuilderStore((s) => s.config.mark);
|
||||
const width = useChartBuilderStore((s) => s.config.width);
|
||||
const height = useChartBuilderStore((s) => s.config.height);
|
||||
const setMark = useChartBuilderStore((s) => s.setMark);
|
||||
const swapXY = useChartBuilderStore((s) => s.swapXY);
|
||||
const setWidth = useChartBuilderStore((s) => s.setWidth);
|
||||
const setHeight = useChartBuilderStore((s) => s.setHeight);
|
||||
const runCreate = useChartBuilderStore((s) => s.createSnippet);
|
||||
// Derive validity + guidance from the stable `config` reference via useMemo, NOT
|
||||
// from a store selector: `builderWarnings` builds a fresh array of objects each
|
||||
// call, which no selector-equality (even useShallow, since the element objects
|
||||
// differ every time) can stabilize — subscribing to it would re-render forever.
|
||||
const config = useChartBuilderStore((s) => s.config);
|
||||
const valid = useMemo(() => isBuilderConfigValid(config), [config]);
|
||||
const warnings = useMemo(() => builderWarnings(config), [config]);
|
||||
|
||||
if (datasetId === null) {
|
||||
return <p className={styles.muted}>No dataset loaded. Open this from a dataset in Datasets.</p>;
|
||||
}
|
||||
|
||||
/** Parse a dimension input: blank → undefined, otherwise a non-negative integer. */
|
||||
const parseDim = (raw: string): number | undefined => {
|
||||
if (raw.trim() === '') return undefined;
|
||||
const n = Number(raw);
|
||||
return Number.isFinite(n) && n > 0 ? Math.round(n) : undefined;
|
||||
};
|
||||
|
||||
return (
|
||||
<div className={styles.builder}>
|
||||
<div className={styles.configPane}>
|
||||
<p className={styles.datasetName}>
|
||||
Building from <strong>{datasetName}</strong>
|
||||
</p>
|
||||
|
||||
<div className={styles.field}>
|
||||
<span className={styles.fieldLabel}>Mark</span>
|
||||
<SegmentedControl
|
||||
label="Mark type"
|
||||
options={MARK_OPTIONS}
|
||||
value={mark}
|
||||
onChange={setMark}
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div className={styles.channels}>
|
||||
<div className={styles.channelsHeader}>
|
||||
<span className={styles.fieldLabel}>Encoding</span>
|
||||
<button type="button" className={styles.swap} onClick={swapXY}>
|
||||
⇄ Swap X/Y
|
||||
</button>
|
||||
</div>
|
||||
{CHANNELS.map((channel) => (
|
||||
<ChannelRow key={channel} channel={channel} />
|
||||
))}
|
||||
</div>
|
||||
|
||||
<div className={styles.dimensions}>
|
||||
<span className={styles.fieldLabel}>Dimensions (optional)</span>
|
||||
<div className={styles.dimInputs}>
|
||||
<label className={styles.dimField}>
|
||||
<span>Width</span>
|
||||
<input
|
||||
type="number"
|
||||
min={1}
|
||||
className={styles.dimInput}
|
||||
value={width ?? ''}
|
||||
placeholder="auto"
|
||||
onChange={(e) => setWidth(parseDim(e.target.value))}
|
||||
/>
|
||||
</label>
|
||||
<label className={styles.dimField}>
|
||||
<span>Height</span>
|
||||
<input
|
||||
type="number"
|
||||
min={1}
|
||||
className={styles.dimInput}
|
||||
value={height ?? ''}
|
||||
placeholder="auto"
|
||||
onChange={(e) => setHeight(parseDim(e.target.value))}
|
||||
/>
|
||||
</label>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{warnings.length > 0 && (
|
||||
<ul className={styles.warnings}>
|
||||
{warnings.map((w) => (
|
||||
<li key={w.message} className={styles.warning}>
|
||||
{w.message}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
|
||||
<div className={styles.actions}>
|
||||
<button type="button" className={styles.action} onClick={() => void closeModal()}>
|
||||
Cancel
|
||||
</button>
|
||||
<button
|
||||
type="button"
|
||||
className={`${styles.action} ${styles.primary}`}
|
||||
disabled={!valid}
|
||||
onClick={() => runCreate()}
|
||||
>
|
||||
Create Snippet
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<BuilderPreview />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -16,7 +16,7 @@ import { useState } from 'react';
|
||||
import { useShallow } from 'zustand/react/shallow';
|
||||
import { datasetReference, type DataSource, type Dataset } from '@core/dataset';
|
||||
import { detectFormat, detectFormatFromUrl, type DataFormat } from '@core/format-detection';
|
||||
import { closeModal, resnapshot } from '../modals/ModalCoordinator';
|
||||
import { closeModal, openModal, resnapshot } from '../modals/ModalCoordinator';
|
||||
import { confirm } from '../stores/ConfirmStore';
|
||||
import { notify } from '../stores/NotificationStore';
|
||||
import { selectSelectedDataset, useDatasetStore, byModifiedDesc } from '../stores/DatasetStore';
|
||||
@@ -221,9 +221,16 @@ function DatasetDetail({
|
||||
<button type="button" className={styles.action} onClick={handleEdit}>
|
||||
Edit
|
||||
</button>
|
||||
{/* "Build Chart from dataset" (spec §05) lands enabled with the Chart
|
||||
Builder in M4. Per council (GOV.UK / NN/g), we don't ship a dead
|
||||
disabled control in the meantime — the action appears when it works. */}
|
||||
{/* Build Chart (spec §05 → §06) — opens the Chart Builder on this dataset.
|
||||
Replaces the Datasets modal (one modal at a time, §01C); detail view has
|
||||
no transient form state, so no discard prompt. */}
|
||||
<button
|
||||
type="button"
|
||||
className={styles.action}
|
||||
onClick={() => openModal('chartBuilder', String(dataset.id))}
|
||||
>
|
||||
Build Chart
|
||||
</button>
|
||||
<button
|
||||
type="button"
|
||||
className={`${styles.action} ${styles.danger}`}
|
||||
|
||||
@@ -22,7 +22,7 @@ export function ModalShell() {
|
||||
const name = useAppStore((s) => s.activeModal);
|
||||
const config = getModalConfig(name);
|
||||
|
||||
const isLarge = name === 'datasets';
|
||||
const isLarge = name === 'datasets' || name === 'chartBuilder';
|
||||
|
||||
// Move focus into the modal on open, return it to the trigger on close. For a
|
||||
// large manager (list + detail), APG dialog-modal advises focusing a static
|
||||
|
||||
@@ -16,8 +16,10 @@
|
||||
|
||||
import type { ComponentType } from 'react';
|
||||
import type { ActiveModal, ModalName } from './types';
|
||||
import { ChartBuilderModal } from '../components/ChartBuilderModal';
|
||||
import { DatasetsModal } from '../components/DatasetsModal';
|
||||
import { ExtractModal } from '../components/ExtractModal';
|
||||
import { useChartBuilderStore } from '../stores/ChartBuilderStore';
|
||||
import { useDatasetStore } from '../stores/DatasetStore';
|
||||
import { useExtractStore } from '../stores/ExtractStore';
|
||||
|
||||
@@ -62,6 +64,17 @@ export const MODAL_REGISTRY: Partial<Record<ModalName, ModalConfig>> = {
|
||||
init: () => useExtractStore.getState().init(),
|
||||
getState: () => ({ name: useExtractStore.getState().name }),
|
||||
},
|
||||
|
||||
// Opened from a selected dataset's "Build Chart" action; `arg` is its id. Loads
|
||||
// the dataset and pre-populates a smart default config (§06). Applies on Create
|
||||
// (a new snippet), so there is nothing transient to lose on close — no getState.
|
||||
chartBuilder: {
|
||||
name: 'chartBuilder',
|
||||
title: 'Chart Builder',
|
||||
component: ChartBuilderModal,
|
||||
isUrlNavigable: true,
|
||||
init: (datasetId) => useChartBuilderStore.getState().init(datasetId ? Number(datasetId) : null),
|
||||
},
|
||||
};
|
||||
|
||||
export const getModalConfig = (name: ActiveModal): ModalConfig | undefined =>
|
||||
|
||||
@@ -0,0 +1,104 @@
|
||||
import { beforeEach, describe, expect, test } from 'vitest';
|
||||
import { createDataset } from '@core/dataset';
|
||||
import { useChartBuilderStore } from './ChartBuilderStore';
|
||||
import { useDatasetStore } from './DatasetStore';
|
||||
import { useSnippetStore } from './SnippetStore';
|
||||
|
||||
const cb = () => useChartBuilderStore.getState();
|
||||
const T = new Date('2026-06-01T00:00:00Z');
|
||||
|
||||
/** Seed a dataset directly into the store and return its id. */
|
||||
function seedDataset(name: string, data: unknown): number {
|
||||
const ds = createDataset({ name, data, format: 'json', source: 'inline', now: T });
|
||||
useDatasetStore.getState().add(ds);
|
||||
return ds.id;
|
||||
}
|
||||
|
||||
beforeEach(() => {
|
||||
cb().reset();
|
||||
useDatasetStore.getState().reset();
|
||||
useSnippetStore.getState().reset();
|
||||
});
|
||||
|
||||
describe('init', () => {
|
||||
test('pre-populates a smart default config from the dataset columns', () => {
|
||||
const id = seedDataset('Traffic', [
|
||||
{ day: '2026-01-01', visits: 10 },
|
||||
{ day: '2026-01-02', visits: 20 },
|
||||
]);
|
||||
cb().init(id);
|
||||
|
||||
expect(cb().datasetId).toBe(id);
|
||||
expect(cb().config.datasetName).toBe('Traffic');
|
||||
// date × number → a Line time series, first col on X, second on Y.
|
||||
expect(cb().config.mark).toBe('line');
|
||||
expect(cb().config.encodings.x).toEqual({ field: 'day', type: 'temporal' });
|
||||
expect(cb().config.encodings.y).toEqual({ field: 'visits', type: 'quantitative' });
|
||||
});
|
||||
|
||||
test('lands empty when no dataset is found', () => {
|
||||
cb().init(999);
|
||||
expect(cb().datasetId).toBeNull();
|
||||
expect(cb().config.encodings).toEqual({});
|
||||
});
|
||||
});
|
||||
|
||||
describe('channel editing', () => {
|
||||
test('mapping a column seeds a channel-appropriate type (Size stays a measure)', () => {
|
||||
const id = seedDataset('Mixed', [{ name: 'A', value: 5 }]);
|
||||
cb().init(id);
|
||||
// A numeric column on Size → Quantitative (allowed); a category cannot be chosen
|
||||
// for Size in the UI, and the store keeps the type valid for the channel.
|
||||
cb().setChannelColumn('size', 'value');
|
||||
expect(cb().config.encodings.size).toEqual({ field: 'value', type: 'quantitative' });
|
||||
});
|
||||
|
||||
test('swapXY flips the two axis mappings', () => {
|
||||
const id = seedDataset('XY', [{ a: 'x', b: 1 }]);
|
||||
cb().init(id);
|
||||
const x0 = cb().config.encodings.x;
|
||||
const y0 = cb().config.encodings.y;
|
||||
cb().swapXY();
|
||||
expect(cb().config.encodings.x).toEqual(y0);
|
||||
expect(cb().config.encodings.y).toEqual(x0);
|
||||
});
|
||||
|
||||
test('clearing a channel to None removes it from the config', () => {
|
||||
const id = seedDataset('XY', [{ a: 'x', b: 1 }]);
|
||||
cb().init(id);
|
||||
cb().setChannelColumn('x', null);
|
||||
expect(cb().config.encodings.x).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('createSnippet', () => {
|
||||
test('builds a linked snippet, activates it, and resets the builder', () => {
|
||||
const id = seedDataset('Sales', [
|
||||
{ region: 'N', revenue: 100 },
|
||||
{ region: 'S', revenue: 80 },
|
||||
]);
|
||||
cb().init(id);
|
||||
|
||||
expect(cb().createSnippet(T)).toBe(true);
|
||||
|
||||
const snippets = useSnippetStore.getState().snippets;
|
||||
expect(snippets).toHaveLength(1);
|
||||
const made = snippets[0];
|
||||
// Linked to its dataset by name (§09F), and the spec references it.
|
||||
expect(made.datasetRefs).toEqual(['Sales']);
|
||||
expect(made.spec).toContain('"name": "Sales"');
|
||||
expect(made.meta.createdWith).toBe('chart-builder');
|
||||
expect(useSnippetStore.getState().activeSnippetId).toBe(made.id);
|
||||
// Builder state is reset for a fresh next open.
|
||||
expect(cb().datasetId).toBeNull();
|
||||
});
|
||||
|
||||
test('refuses to create when no channel is mapped', () => {
|
||||
const id = seedDataset('Empty', [{ a: 1 }]);
|
||||
cb().init(id);
|
||||
cb().setChannelColumn('x', null);
|
||||
cb().setChannelColumn('y', null);
|
||||
expect(cb().createSnippet(T)).toBe(false);
|
||||
expect(useSnippetStore.getState().snippets).toHaveLength(0);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,180 @@
|
||||
/**
|
||||
* Chart Builder state (spec §06).
|
||||
*
|
||||
* Backs the Chart Builder modal: a no-JSON composer that turns a dataset + a mark
|
||||
* + four channel mappings into a Vega-Lite spec saved as a new snippet. All the
|
||||
* spec grammar and the Tier-B defaults/guards live in the portable core
|
||||
* (`@core/chart-builder`); this store is the thin app-layer state + actions over
|
||||
* that, plus the create-flow side effects (new snippet, toast, activate, close).
|
||||
*
|
||||
* `init(datasetId)` loads the dataset's columns and pre-populates a smart default
|
||||
* config; with no dataset it lands empty so the modal can show "No dataset loaded".
|
||||
* The mark is sticky after open (changing a column does not re-derive it) so the
|
||||
* user's choice is never overridden mid-edit.
|
||||
*/
|
||||
|
||||
import { create } from 'zustand';
|
||||
import {
|
||||
buildSnippetSpecText,
|
||||
defaultBuilderConfig,
|
||||
defaultFieldType,
|
||||
generateChartName,
|
||||
isBuilderConfigValid,
|
||||
isChannelTypeAllowed,
|
||||
validFieldTypes,
|
||||
type BuilderColumns,
|
||||
type BuilderConfig,
|
||||
type ChannelName,
|
||||
type FieldType,
|
||||
type MarkType,
|
||||
} from '@core/chart-builder';
|
||||
import type { ColumnType } from '@core/type-inference';
|
||||
import { closeModal } from '../modals/ModalCoordinator';
|
||||
import { useDatasetStore } from './DatasetStore';
|
||||
import { notify } from './NotificationStore';
|
||||
import { useSnippetStore } from './SnippetStore';
|
||||
|
||||
/** An empty config — no dataset, nothing mapped (the "No dataset loaded" state). */
|
||||
const EMPTY_CONFIG: BuilderConfig = { datasetName: '', mark: 'bar', encodings: {} };
|
||||
const EMPTY_COLUMNS: BuilderColumns = { columns: [], columnTypes: [] };
|
||||
|
||||
export interface ChartBuilderState {
|
||||
/** The dataset being built from, or null when none is loaded. */
|
||||
datasetId: number | null;
|
||||
/** The dataset's columns + inferred types (drives the dropdowns and defaults). */
|
||||
columns: BuilderColumns;
|
||||
/** The working configuration the preview and the produced spec read from. */
|
||||
config: BuilderConfig;
|
||||
|
||||
/** Load a dataset and pre-populate a smart default config (spec §06 → Opening). */
|
||||
init: (datasetId: number | null) => void;
|
||||
setMark: (mark: MarkType) => void;
|
||||
/** Map a column to a channel (null = "None"); seeds the channel's default type. */
|
||||
setChannelColumn: (channel: ChannelName, columnName: string | null) => void;
|
||||
setChannelType: (channel: ChannelName, type: FieldType) => void;
|
||||
/** Swap the X and Y mappings (a one-click axis flip). */
|
||||
swapXY: () => void;
|
||||
setWidth: (width: number | undefined) => void;
|
||||
setHeight: (height: number | undefined) => void;
|
||||
/** Build the spec, create + activate a linked snippet, toast, and close. */
|
||||
createSnippet: (now?: Date) => boolean;
|
||||
reset: () => void;
|
||||
}
|
||||
|
||||
/** The inferred type of a named column, defaulting to `string` if unknown. */
|
||||
function columnType(columns: BuilderColumns, name: string): ColumnType {
|
||||
return columns.columnTypes.find((c) => c.name === name)?.type ?? 'string';
|
||||
}
|
||||
|
||||
export const useChartBuilderStore = create<ChartBuilderState>((set, get) => ({
|
||||
datasetId: null,
|
||||
columns: EMPTY_COLUMNS,
|
||||
config: EMPTY_CONFIG,
|
||||
|
||||
init: (datasetId) => {
|
||||
const dataset =
|
||||
datasetId === null
|
||||
? undefined
|
||||
: useDatasetStore.getState().datasets.find((d) => d.id === datasetId);
|
||||
if (!dataset) {
|
||||
set({ datasetId: null, columns: EMPTY_COLUMNS, config: EMPTY_CONFIG });
|
||||
return;
|
||||
}
|
||||
const columns: BuilderColumns = {
|
||||
columns: dataset.columns,
|
||||
columnTypes: dataset.columnTypes,
|
||||
};
|
||||
set({
|
||||
datasetId: dataset.id,
|
||||
columns,
|
||||
config: defaultBuilderConfig(dataset.name, columns),
|
||||
});
|
||||
},
|
||||
|
||||
setMark: (mark) => set((s) => ({ config: { ...s.config, mark } })),
|
||||
|
||||
setChannelColumn: (channel, columnName) =>
|
||||
set((s) => {
|
||||
const encodings = { ...s.config.encodings };
|
||||
if (columnName === null) {
|
||||
encodings[channel] = null;
|
||||
} else {
|
||||
// Default to the column's natural type, but if that type isn't allowed on
|
||||
// this channel (e.g. a category on Size), fall back to the first valid type
|
||||
// that is — the UI also disables unsuitable columns, this is the guard.
|
||||
const valid = validFieldTypes(columnType(s.columns, columnName));
|
||||
const type =
|
||||
valid.find((t) => isChannelTypeAllowed(channel, t)) ??
|
||||
defaultFieldType(columnType(s.columns, columnName));
|
||||
encodings[channel] = { field: columnName, type };
|
||||
}
|
||||
return { config: { ...s.config, encodings } };
|
||||
}),
|
||||
|
||||
setChannelType: (channel, type) =>
|
||||
set((s) => {
|
||||
const current = s.config.encodings[channel];
|
||||
if (!current) return s; // no field on this channel → nothing to retype
|
||||
return {
|
||||
config: {
|
||||
...s.config,
|
||||
encodings: { ...s.config.encodings, [channel]: { ...current, type } },
|
||||
},
|
||||
};
|
||||
}),
|
||||
|
||||
swapXY: () =>
|
||||
set((s) => ({
|
||||
config: {
|
||||
...s.config,
|
||||
encodings: {
|
||||
...s.config.encodings,
|
||||
x: s.config.encodings.y ?? null,
|
||||
y: s.config.encodings.x ?? null,
|
||||
},
|
||||
},
|
||||
})),
|
||||
|
||||
setWidth: (width) => set((s) => ({ config: { ...s.config, width } })),
|
||||
setHeight: (height) => set((s) => ({ config: { ...s.config, height } })),
|
||||
|
||||
createSnippet: (now) => {
|
||||
const { config } = get();
|
||||
if (!isBuilderConfigValid(config)) return false; // guarded by a disabled action too
|
||||
|
||||
const name = generateChartName(config);
|
||||
const specText = buildSnippetSpecText(config);
|
||||
// createSnippet mirrors datasetRefs from the spec, so the new snippet is linked
|
||||
// to its dataset (§09F) without extra wiring. Provenance kept in meta (§06).
|
||||
useSnippetStore.getState().createSnippet({
|
||||
name,
|
||||
spec: specText,
|
||||
now,
|
||||
meta: { createdWith: 'chart-builder', builtFromDataset: config.datasetName },
|
||||
});
|
||||
|
||||
notify({
|
||||
kind: 'success',
|
||||
title: 'Snippet created',
|
||||
message: `"${name}" was added to your library and opened in the editor.`,
|
||||
});
|
||||
void closeModal(true); // the create is the user's confirmation — no discard prompt
|
||||
get().reset();
|
||||
return true;
|
||||
},
|
||||
|
||||
reset: () => set({ datasetId: null, columns: EMPTY_COLUMNS, config: EMPTY_CONFIG }),
|
||||
}));
|
||||
|
||||
/**
|
||||
* Selector: whether the config can be saved (≥1 channel mapped, spec §06 →
|
||||
* Validation). Returns a boolean (stable under Object.is), so it is safe to
|
||||
* subscribe to directly. Non-blocking *guidance* (`builderWarnings`) deliberately
|
||||
* has NO selector here — it builds a fresh array of objects each call, which no
|
||||
* subscription equality can stabilize; the component derives it via `useMemo` over
|
||||
* the stable `config` reference instead (see ChartBuilderModal).
|
||||
*/
|
||||
export const selectBuilderValid = (s: ChartBuilderState) => isBuilderConfigValid(s.config);
|
||||
|
||||
/** Selector: the built spec as JSON text, for the live preview. */
|
||||
export const selectBuilderSpecText = (s: ChartBuilderState) => buildSnippetSpecText(s.config);
|
||||
@@ -124,7 +124,11 @@ export const useSnippetStore = create<SnippetState>((set, get) => ({
|
||||
|
||||
createSnippet: (options) => {
|
||||
get().commitDraft(); // flush the outgoing snippet's valid edits before switching away
|
||||
const snippet = createSnippet(options);
|
||||
const created = createSnippet(options);
|
||||
// Mirror datasetRefs from the spec at creation, like publish does, so a snippet
|
||||
// built with a named-data reference (Chart Builder, §06) is linked to its dataset
|
||||
// immediately. Inline-data specs (the sample template) resolve to no refs.
|
||||
const snippet = { ...created, datasetRefs: recomputeDatasetRefs(created.spec) };
|
||||
set((s) => ({
|
||||
snippets: [snippet, ...s.snippets],
|
||||
activeSnippetId: snippet.id,
|
||||
|
||||
@@ -0,0 +1,294 @@
|
||||
import { describe, it, expect } from 'vitest';
|
||||
import {
|
||||
defaultFieldType,
|
||||
validFieldTypes,
|
||||
defaultMark,
|
||||
isChannelTypeAllowed,
|
||||
builderWarnings,
|
||||
defaultBuilderConfig,
|
||||
isBuilderConfigValid,
|
||||
buildChartSpec,
|
||||
buildSnippetSpecText,
|
||||
generateChartName,
|
||||
type BuilderColumns,
|
||||
type BuilderConfig,
|
||||
} from './chart-builder';
|
||||
import { VEGA_LITE_SCHEMA_URL } from './snippet';
|
||||
|
||||
const columns: BuilderColumns = {
|
||||
columns: ['category', 'value', 'when', 'flag'],
|
||||
columnTypes: [
|
||||
{ name: 'category', type: 'string' },
|
||||
{ name: 'value', type: 'number' },
|
||||
{ name: 'when', type: 'date' },
|
||||
{ name: 'flag', type: 'boolean' },
|
||||
],
|
||||
};
|
||||
|
||||
describe('defaultFieldType', () => {
|
||||
it('maps inferred column types to Vega-Lite field types (spec §06)', () => {
|
||||
expect(defaultFieldType('number')).toBe('quantitative');
|
||||
expect(defaultFieldType('date')).toBe('temporal');
|
||||
expect(defaultFieldType('string')).toBe('nominal');
|
||||
expect(defaultFieldType('boolean')).toBe('nominal');
|
||||
});
|
||||
|
||||
it('is always the head of validFieldTypes (no drift)', () => {
|
||||
for (const t of ['number', 'date', 'string', 'boolean'] as const) {
|
||||
expect(defaultFieldType(t)).toBe(validFieldTypes(t)[0]);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('validFieldTypes (Tier B valid-type locking)', () => {
|
||||
it('never offers Quantitative for string/boolean, nor Temporal for non-date', () => {
|
||||
expect(validFieldTypes('string')).not.toContain('quantitative');
|
||||
expect(validFieldTypes('boolean')).not.toContain('quantitative');
|
||||
expect(validFieldTypes('number')).not.toContain('temporal');
|
||||
expect(validFieldTypes('string')).not.toContain('temporal');
|
||||
});
|
||||
|
||||
it('locks date to Temporal only and offers Ordinal where order is plausible', () => {
|
||||
expect(validFieldTypes('date')).toEqual(['temporal']);
|
||||
expect(validFieldTypes('number')).toContain('ordinal');
|
||||
expect(validFieldTypes('string')).toContain('ordinal');
|
||||
});
|
||||
});
|
||||
|
||||
describe('defaultMark (Tier B smart default)', () => {
|
||||
it('picks Line for time × measure, Point for two measures, Bar for category × measure', () => {
|
||||
expect(defaultMark('temporal', 'quantitative')).toBe('line');
|
||||
expect(defaultMark('quantitative', 'temporal')).toBe('line');
|
||||
expect(defaultMark('quantitative', 'quantitative')).toBe('point');
|
||||
expect(defaultMark('nominal', 'quantitative')).toBe('bar');
|
||||
expect(defaultMark('quantitative', 'nominal')).toBe('bar');
|
||||
});
|
||||
|
||||
it('uses Point when both axes are discrete (Bar/Line/Area need a continuous axis)', () => {
|
||||
expect(defaultMark('nominal', 'nominal')).toBe('point');
|
||||
expect(defaultMark('nominal', 'ordinal')).toBe('point');
|
||||
});
|
||||
|
||||
it('falls back to Bar when an axis is unmapped', () => {
|
||||
expect(defaultMark('quantitative', null)).toBe('bar');
|
||||
expect(defaultMark(null, null)).toBe('bar');
|
||||
});
|
||||
});
|
||||
|
||||
describe('isChannelTypeAllowed (Size discipline)', () => {
|
||||
it('forbids Size for Nominal and Temporal, allows it for Quantitative/Ordinal', () => {
|
||||
expect(isChannelTypeAllowed('size', 'nominal')).toBe(false);
|
||||
expect(isChannelTypeAllowed('size', 'temporal')).toBe(false);
|
||||
expect(isChannelTypeAllowed('size', 'quantitative')).toBe(true);
|
||||
expect(isChannelTypeAllowed('size', 'ordinal')).toBe(true);
|
||||
});
|
||||
|
||||
it('allows any type on X/Y/Color', () => {
|
||||
for (const ch of ['x', 'y', 'color'] as const) {
|
||||
expect(isChannelTypeAllowed(ch, 'nominal')).toBe(true);
|
||||
expect(isChannelTypeAllowed(ch, 'temporal')).toBe(true);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('builderWarnings (Tier B advisories)', () => {
|
||||
it('warns when a line/area mark is missing an axis', () => {
|
||||
const w = builderWarnings({
|
||||
datasetName: 'D',
|
||||
mark: 'line',
|
||||
encodings: { x: { field: 'a', type: 'temporal' } },
|
||||
});
|
||||
expect(w.some((m) => /need both an X and a Y/.test(m.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('warns when two measures are drawn on a non-scatter mark', () => {
|
||||
const w = builderWarnings({
|
||||
datasetName: 'D',
|
||||
mark: 'bar',
|
||||
encodings: {
|
||||
x: { field: 'a', type: 'quantitative' },
|
||||
y: { field: 'b', type: 'quantitative' },
|
||||
},
|
||||
});
|
||||
expect(w.some((m) => /scatter/.test(m.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('warns when a bar/line/area has no measure on either axis', () => {
|
||||
const w = builderWarnings({
|
||||
datasetName: 'D',
|
||||
mark: 'bar',
|
||||
encodings: { x: { field: 'a', type: 'nominal' }, y: { field: 'b', type: 'nominal' } },
|
||||
});
|
||||
expect(w.some((m) => /need a measure/.test(m.message))).toBe(true);
|
||||
});
|
||||
|
||||
it('warns when an area chart is split into colour series', () => {
|
||||
const w = builderWarnings({
|
||||
datasetName: 'D',
|
||||
mark: 'area',
|
||||
encodings: {
|
||||
x: { field: 't', type: 'temporal' },
|
||||
y: { field: 'v', type: 'quantitative' },
|
||||
color: { field: 'g', type: 'nominal' },
|
||||
},
|
||||
});
|
||||
expect(w.some((m) => m.channel === 'color')).toBe(true);
|
||||
});
|
||||
|
||||
it('is silent for a clean configuration', () => {
|
||||
const w = builderWarnings({
|
||||
datasetName: 'D',
|
||||
mark: 'line',
|
||||
encodings: { x: { field: 't', type: 'temporal' }, y: { field: 'v', type: 'quantitative' } },
|
||||
});
|
||||
expect(w).toEqual([]);
|
||||
});
|
||||
});
|
||||
|
||||
describe('defaultBuilderConfig', () => {
|
||||
it('puts the first column on X and the second on Y, each with derived type', () => {
|
||||
const config = defaultBuilderConfig('Sales', columns);
|
||||
expect(config.mark).toBe('bar');
|
||||
expect(config.datasetName).toBe('Sales');
|
||||
expect(config.encodings.x).toEqual({ field: 'category', type: 'nominal' });
|
||||
expect(config.encodings.y).toEqual({ field: 'value', type: 'quantitative' });
|
||||
expect(config.encodings.color).toBeNull();
|
||||
expect(config.encodings.size).toBeNull();
|
||||
});
|
||||
|
||||
it('opens as a Line when the first two columns are date × number (smart mark)', () => {
|
||||
const timeSeries: BuilderColumns = {
|
||||
columns: ['day', 'visits'],
|
||||
columnTypes: [
|
||||
{ name: 'day', type: 'date' },
|
||||
{ name: 'visits', type: 'number' },
|
||||
],
|
||||
};
|
||||
const config = defaultBuilderConfig('Traffic', timeSeries);
|
||||
expect(config.mark).toBe('line');
|
||||
expect(config.encodings.x).toEqual({ field: 'day', type: 'temporal' });
|
||||
expect(config.encodings.y).toEqual({ field: 'visits', type: 'quantitative' });
|
||||
});
|
||||
|
||||
it('leaves Y unmapped when the dataset has a single column', () => {
|
||||
const single: BuilderColumns = {
|
||||
columns: ['only'],
|
||||
columnTypes: [{ name: 'only', type: 'number' }],
|
||||
};
|
||||
const config = defaultBuilderConfig('One', single);
|
||||
expect(config.encodings.x).toEqual({ field: 'only', type: 'quantitative' });
|
||||
expect(config.encodings.y).toBeNull();
|
||||
});
|
||||
|
||||
it('maps nothing when the dataset has no detected columns', () => {
|
||||
const config = defaultBuilderConfig('Empty', { columns: [], columnTypes: [] });
|
||||
expect(isBuilderConfigValid(config)).toBe(false);
|
||||
expect(config.encodings.x).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe('isBuilderConfigValid', () => {
|
||||
const base: BuilderConfig = { datasetName: 'D', mark: 'bar', encodings: {} };
|
||||
|
||||
it('requires at least one mapped channel', () => {
|
||||
expect(isBuilderConfigValid(base)).toBe(false);
|
||||
expect(isBuilderConfigValid({ ...base, encodings: { x: null, y: null } })).toBe(false);
|
||||
expect(
|
||||
isBuilderConfigValid({ ...base, encodings: { color: { field: 'c', type: 'nominal' } } }),
|
||||
).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe('buildChartSpec', () => {
|
||||
it('assembles schema, named data, tooltip mark, and mapped encodings', () => {
|
||||
const config = defaultBuilderConfig('Sales', columns);
|
||||
const spec = buildChartSpec(config);
|
||||
expect(spec).toEqual({
|
||||
$schema: VEGA_LITE_SCHEMA_URL,
|
||||
data: { name: 'Sales' },
|
||||
mark: { type: 'bar', tooltip: true },
|
||||
encoding: {
|
||||
x: { field: 'category', type: 'nominal' },
|
||||
y: { field: 'value', type: 'quantitative' },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
it('omits unmapped channels and preserves canonical channel order', () => {
|
||||
const config: BuilderConfig = {
|
||||
datasetName: 'D',
|
||||
mark: 'point',
|
||||
encodings: {
|
||||
size: { field: 's', type: 'quantitative' },
|
||||
x: { field: 'a', type: 'nominal' },
|
||||
color: null,
|
||||
},
|
||||
};
|
||||
const spec = buildChartSpec(config);
|
||||
expect(Object.keys(spec.encoding as object)).toEqual(['x', 'size']);
|
||||
});
|
||||
|
||||
it('omits the encoding block entirely when nothing is mapped', () => {
|
||||
const spec = buildChartSpec({ datasetName: 'D', mark: 'bar', encodings: {} });
|
||||
expect(spec.encoding).toBeUndefined();
|
||||
expect(spec.mark).toEqual({ type: 'bar', tooltip: true });
|
||||
});
|
||||
|
||||
it('writes explicit width/height only when provided', () => {
|
||||
const config: BuilderConfig = {
|
||||
datasetName: 'D',
|
||||
mark: 'area',
|
||||
encodings: { x: { field: 'a', type: 'temporal' } },
|
||||
width: 400,
|
||||
height: 300,
|
||||
};
|
||||
const spec = buildChartSpec(config);
|
||||
expect(spec.width).toBe(400);
|
||||
expect(spec.height).toBe(300);
|
||||
|
||||
const noDims = buildChartSpec({ ...config, width: undefined, height: undefined });
|
||||
expect(noDims.width).toBeUndefined();
|
||||
expect(noDims.height).toBeUndefined();
|
||||
});
|
||||
|
||||
it('carries every mark type through to the spec', () => {
|
||||
for (const mark of ['bar', 'line', 'point', 'area', 'circle'] as const) {
|
||||
const spec = buildChartSpec({
|
||||
datasetName: 'D',
|
||||
mark,
|
||||
encodings: { x: { field: 'a', type: 'nominal' } },
|
||||
});
|
||||
expect((spec.mark as { type: string }).type).toBe(mark);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe('buildSnippetSpecText', () => {
|
||||
it('produces pretty-printed JSON that parses back to the spec', () => {
|
||||
const config = defaultBuilderConfig('Sales', columns);
|
||||
const text = buildSnippetSpecText(config);
|
||||
expect(text).toContain('\n ');
|
||||
expect(JSON.parse(text)).toEqual(buildChartSpec(config));
|
||||
});
|
||||
});
|
||||
|
||||
describe('generateChartName', () => {
|
||||
it('reads "<Mark> chart of <y> by <x>" when both axes are mapped', () => {
|
||||
const config = defaultBuilderConfig('Sales', columns);
|
||||
expect(generateChartName(config)).toBe('Bar chart of value by category');
|
||||
});
|
||||
|
||||
it('names the single mapped field when only one channel is set', () => {
|
||||
const config: BuilderConfig = {
|
||||
datasetName: 'Sales',
|
||||
mark: 'line',
|
||||
encodings: { color: { field: 'region', type: 'nominal' } },
|
||||
};
|
||||
expect(generateChartName(config)).toBe('Line chart of region');
|
||||
});
|
||||
|
||||
it('falls back to the dataset name when nothing is mapped', () => {
|
||||
const config: BuilderConfig = { datasetName: 'Sales', mark: 'circle', encodings: {} };
|
||||
expect(generateChartName(config)).toBe('Circle chart of Sales');
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,323 @@
|
||||
/**
|
||||
* Chart Builder — pure Vega-Lite spec assembler (spec §06).
|
||||
*
|
||||
* Portable core: no browser APIs, no React, no store access. Turns a no-JSON
|
||||
* builder configuration (a mark, four optional encoding channels mapped to
|
||||
* dataset columns, optional pixel dimensions) into a complete Vega-Lite spec that
|
||||
* references the source dataset by name. The UI layer owns the controls; this
|
||||
* module owns the spec grammar — what a configuration *means* as Vega-Lite — and
|
||||
* the defaults the spec prescribes (pre-population, field-type derivation).
|
||||
*
|
||||
* The produced spec mirrors what the rest of Astrolabe authors by hand: a
|
||||
* `$schema` stamp (shared with the sample template), a named-data reference the
|
||||
* renderer resolves at preview time (rendering.ts), a mark with tooltips enabled,
|
||||
* the mapped encodings, and any explicit width/height. It is the same string-spec
|
||||
* shape the editor and preview consume — `buildSnippetSpecText` serializes it.
|
||||
*/
|
||||
|
||||
import type { ColumnType } from './type-inference';
|
||||
import { VEGA_LITE_SCHEMA_URL } from './snippet';
|
||||
|
||||
/** The five mark types the builder offers, in selector order (spec §06). */
|
||||
export const MARK_TYPES = ['bar', 'line', 'point', 'area', 'circle'] as const;
|
||||
export type MarkType = (typeof MARK_TYPES)[number];
|
||||
|
||||
/** The four Vega-Lite field types a channel may carry, in override-menu order. */
|
||||
export const FIELD_TYPES = ['quantitative', 'nominal', 'ordinal', 'temporal'] as const;
|
||||
export type FieldType = (typeof FIELD_TYPES)[number];
|
||||
|
||||
/** The four encoding channels the builder offers, in display order (spec §06). */
|
||||
export const CHANNELS = ['x', 'y', 'color', 'size'] as const;
|
||||
export type ChannelName = (typeof CHANNELS)[number];
|
||||
|
||||
/**
|
||||
* One channel's mapping: a dataset column `field` plus its `type`. A channel left
|
||||
* on "None" is represented by `null` in the config (omitted from the spec).
|
||||
*/
|
||||
export interface ChannelMapping {
|
||||
field: string;
|
||||
type: FieldType;
|
||||
}
|
||||
|
||||
/** The full builder configuration the assembler consumes. */
|
||||
export interface BuilderConfig {
|
||||
/** The dataset the spec references by name (`{ data: { name } }`). */
|
||||
datasetName: string;
|
||||
/** The active mark type. */
|
||||
mark: MarkType;
|
||||
/** Per-channel mapping; `null` (or absent) means the channel is unmapped. */
|
||||
encodings: Partial<Record<ChannelName, ChannelMapping | null>>;
|
||||
/** Optional explicit chart width in pixels. */
|
||||
width?: number;
|
||||
/** Optional explicit chart height in pixels. */
|
||||
height?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* The field types a column may legitimately carry, given its inferred type — the
|
||||
* options the channel's type control offers (spec §06 → Tier B, valid-type
|
||||
* locking). A string/boolean is never Quantitative and a non-date is never
|
||||
* Temporal (Vega-Lite would mis-encode or error); a number defaults to
|
||||
* Quantitative but may be treated as a category. Ordinal is offered wherever the
|
||||
* user might reasonably assert an order (numbers, text), a deliberate superset of
|
||||
* Voyager's stricter menu. The list head is the default (see `defaultFieldType`).
|
||||
*
|
||||
* Convergent across the research: Voyager `getValidTypes`
|
||||
* (data-pane/field-list.tsx) + Draco `hard.lp` enc_type_valid (a string/boolean
|
||||
* can't be quantitative; temporal requires datetime). See
|
||||
* docs/chart-builder-research.md §4.
|
||||
*/
|
||||
export function validFieldTypes(columnType: ColumnType): FieldType[] {
|
||||
switch (columnType) {
|
||||
case 'number':
|
||||
return ['quantitative', 'ordinal', 'nominal'];
|
||||
case 'date':
|
||||
return ['temporal'];
|
||||
case 'boolean':
|
||||
return ['nominal'];
|
||||
default: // 'string'
|
||||
return ['nominal', 'ordinal'];
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Default Vega-Lite field type for a column from its inferred type (spec §06):
|
||||
* numeric → Quantitative, date → Temporal, everything else (text, boolean) →
|
||||
* Nominal. The default is the head of `validFieldTypes`, so the two never drift.
|
||||
* The user may override afterward, within `validFieldTypes`.
|
||||
*/
|
||||
export function defaultFieldType(columnType: ColumnType): FieldType {
|
||||
return validFieldTypes(columnType)[0];
|
||||
}
|
||||
|
||||
/** Continuous (measure-like) field types — quantitative and temporal. */
|
||||
function isContinuous(type: FieldType): boolean {
|
||||
return type === 'quantitative' || type === 'temporal';
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether a field type may be placed on a channel at all (spec §06 → Tier B, Size
|
||||
* discipline). X/Y/Color accept any type; **Size accepts only Quantitative or
|
||||
* Ordinal** — encoding a category or a date by symbol size is misleading (size
|
||||
* implies ordered magnitude). Draco makes this a hard constraint
|
||||
* (`hard.lp:53` size_nominal); we surface it as a UI gate that disables Size for
|
||||
* unsuitable columns rather than letting the user produce the bad encoding.
|
||||
* (Negative-value exclusion, `hard.lp:56`, needs row data and is left to the
|
||||
* data-aware layer; this type-level gate is what the builder enforces.)
|
||||
*/
|
||||
export function isChannelTypeAllowed(channel: ChannelName, type: FieldType): boolean {
|
||||
if (channel === 'size') return type === 'quantitative' || type === 'ordinal';
|
||||
return true;
|
||||
}
|
||||
|
||||
/**
|
||||
* The mark that best fits the X/Y field-type shape (spec §06 → Tier B, smart
|
||||
* default mark) — the research's strongest convergence (Draco mark-by-shape soft
|
||||
* constraints, Voyager effectiveness, FT, Datawrapper all agree;
|
||||
* docs/chart-builder-research.md §4):
|
||||
*
|
||||
* - temporal × quantitative → **Line** (a time series)
|
||||
* - quantitative × quantitative → **Point** (a scatter)
|
||||
* - one continuous + one discrete axis → **Bar** (category vs measure)
|
||||
* - both axes discrete → **Point** (Bar/Line/Area need a continuous axis)
|
||||
* - a single mapped axis, or nothing yet → **Bar** (the safe default)
|
||||
*
|
||||
* `null` means the channel is unmapped. This is the *default*; the user can switch
|
||||
* to any of the five marks afterward.
|
||||
*/
|
||||
export function defaultMark(xType: FieldType | null, yType: FieldType | null): MarkType {
|
||||
if (xType === null || yType === null) return 'bar';
|
||||
const timeVsMeasure =
|
||||
(xType === 'temporal' && yType === 'quantitative') ||
|
||||
(xType === 'quantitative' && yType === 'temporal');
|
||||
if (timeVsMeasure) return 'line';
|
||||
const xc = isContinuous(xType);
|
||||
const yc = isContinuous(yType);
|
||||
if (xc && yc) return 'point'; // two measures → scatter
|
||||
if (xc === yc) return 'point'; // both discrete → bar/line/area are invalid here
|
||||
return 'bar'; // one continuous axis, one categorical → category-vs-measure bar
|
||||
}
|
||||
|
||||
/** A dataset's columns paired with their inferred types — the builder's input. */
|
||||
export interface BuilderColumns {
|
||||
columns: readonly string[];
|
||||
columnTypes: ReadonlyArray<{ name: string; type: ColumnType }>;
|
||||
}
|
||||
|
||||
/** The derived field type for a named column, defaulting to Nominal if unknown. */
|
||||
function fieldTypeForColumn(name: string, columns: BuilderColumns): FieldType {
|
||||
const match = columns.columnTypes.find((c) => c.name === name);
|
||||
return defaultFieldType(match?.type ?? 'string');
|
||||
}
|
||||
|
||||
/**
|
||||
* The builder's opening configuration for a dataset (spec §06 → Default
|
||||
* pre-population, Tier B): the first column on X and the second (if any) on Y, each
|
||||
* with its derived field type; Color and Size start unmapped. The mark is the
|
||||
* **smart default** for the resulting X/Y shape (`defaultMark`) rather than always
|
||||
* Bar — a date-vs-number dataset opens as a Line, two measures as a Point — so the
|
||||
* first preview is already the conventional chart. A dataset with no detected
|
||||
* columns yields an all-unmapped config (the modal then prompts / disables Create).
|
||||
*/
|
||||
export function defaultBuilderConfig(datasetName: string, columns: BuilderColumns): BuilderConfig {
|
||||
const encodings: Partial<Record<ChannelName, ChannelMapping | null>> = {
|
||||
x: null,
|
||||
y: null,
|
||||
color: null,
|
||||
size: null,
|
||||
};
|
||||
const [first, second] = columns.columns;
|
||||
if (first !== undefined) {
|
||||
encodings.x = { field: first, type: fieldTypeForColumn(first, columns) };
|
||||
}
|
||||
if (second !== undefined) {
|
||||
encodings.y = { field: second, type: fieldTypeForColumn(second, columns) };
|
||||
}
|
||||
const mark = defaultMark(encodings.x?.type ?? null, encodings.y?.type ?? null);
|
||||
return { datasetName, mark, encodings };
|
||||
}
|
||||
|
||||
/** The channels actually mapped to a column, in canonical order. */
|
||||
function mappedChannels(config: BuilderConfig): Array<[ChannelName, ChannelMapping]> {
|
||||
return CHANNELS.flatMap((channel) => {
|
||||
const mapping = config.encodings[channel];
|
||||
return mapping ? [[channel, mapping] as [ChannelName, ChannelMapping]] : [];
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether the configuration is renderable / saveable (spec §06 → Validation): at
|
||||
* least one channel must be mapped to a column. The modal gates the Create action
|
||||
* and the preview prompt on this.
|
||||
*/
|
||||
export function isBuilderConfigValid(config: BuilderConfig): boolean {
|
||||
return mappedChannels(config).length > 0;
|
||||
}
|
||||
|
||||
/** A non-blocking advisory about a configuration (spec §06 → Tier B warnings). */
|
||||
export interface BuilderWarning {
|
||||
/** The channel the hint is about, when it's channel-specific. */
|
||||
channel?: ChannelName;
|
||||
/** A short, plain-language hint the modal shows inline (not an error). */
|
||||
message: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* Non-blocking advisories for the current configuration (spec §06 → Tier B): the
|
||||
* encodings that render but read poorly, drawn from the research's soft rules
|
||||
* (docs/chart-builder-research.md §4, §7). These never block Create — `isBuilder
|
||||
* ConfigValid` is the only gate — they just steer the user toward a better chart.
|
||||
* Returned in a stable order so the UI list doesn't jitter as config changes.
|
||||
*/
|
||||
export function builderWarnings(config: BuilderConfig): BuilderWarning[] {
|
||||
const warnings: BuilderWarning[] = [];
|
||||
const x = config.encodings.x ?? null;
|
||||
const y = config.encodings.y ?? null;
|
||||
const { mark } = config;
|
||||
|
||||
// Line/area are two-axis marks: a single mapped axis can't draw a meaningful line
|
||||
// or band (Draco hard.lp:91 line_area requires both x and y).
|
||||
if ((mark === 'line' || mark === 'area') && (x === null || y === null)) {
|
||||
warnings.push({
|
||||
message: `${mark === 'line' ? 'Line' : 'Area'} charts need both an X and a Y axis.`,
|
||||
});
|
||||
}
|
||||
|
||||
// Bar/line/area need a measure on one axis; two categories give nothing to compare
|
||||
// (Draco soft.lp:47 only_discrete — the loudest nudge; hard.lp:97/:100 for bar).
|
||||
if (
|
||||
(mark === 'bar' || mark === 'line' || mark === 'area') &&
|
||||
x !== null &&
|
||||
y !== null &&
|
||||
!isContinuous(x.type) &&
|
||||
!isContinuous(y.type)
|
||||
) {
|
||||
warnings.push({
|
||||
message: `${markLabel(mark)} charts need a measure (quantitative or temporal) on the X or Y axis.`,
|
||||
});
|
||||
}
|
||||
|
||||
// Two measures on a non-scatter mark: a line/bar/area over two quantitative axes
|
||||
// misleads; a scatter is the conventional choice (Draco soft.lp c_c weights).
|
||||
if (
|
||||
x !== null &&
|
||||
y !== null &&
|
||||
x.type === 'quantitative' &&
|
||||
y.type === 'quantitative' &&
|
||||
mark !== 'point' &&
|
||||
mark !== 'circle'
|
||||
) {
|
||||
warnings.push({
|
||||
message: 'Two measures usually read best as a scatter — try Point or Circle.',
|
||||
});
|
||||
}
|
||||
|
||||
// Area split into many series hides per-component change (FT Visual Vocabulary:
|
||||
// "seeing change in components can be very difficult").
|
||||
if (mark === 'area' && config.encodings.color) {
|
||||
warnings.push({
|
||||
channel: 'color',
|
||||
message:
|
||||
'Area charts make per-series change hard to read; consider Line for multiple series.',
|
||||
});
|
||||
}
|
||||
|
||||
return warnings;
|
||||
}
|
||||
|
||||
/** A built Vega-Lite spec, as a plain object (serialize with `buildSnippetSpecText`). */
|
||||
export type ChartSpec = Record<string, unknown>;
|
||||
|
||||
/**
|
||||
* Assemble the complete Vega-Lite spec from a builder configuration (spec §06 →
|
||||
* Output). Includes the schema reference, a named data reference to the dataset,
|
||||
* the mark with tooltips enabled, every mapped encoding (field + field type), and
|
||||
* any explicit width/height. Unmapped channels are omitted; if nothing is mapped
|
||||
* the `encoding` block is omitted entirely (validation prevents saving that, but
|
||||
* the live preview may render a bare mark while the user is still configuring).
|
||||
*/
|
||||
export function buildChartSpec(config: BuilderConfig): ChartSpec {
|
||||
const spec: ChartSpec = {
|
||||
$schema: VEGA_LITE_SCHEMA_URL,
|
||||
data: { name: config.datasetName },
|
||||
mark: { type: config.mark, tooltip: true },
|
||||
};
|
||||
|
||||
const encoding: Record<string, { field: string; type: FieldType }> = {};
|
||||
for (const [channel, mapping] of mappedChannels(config)) {
|
||||
encoding[channel] = { field: mapping.field, type: mapping.type };
|
||||
}
|
||||
if (Object.keys(encoding).length > 0) spec.encoding = encoding;
|
||||
|
||||
if (config.width !== undefined) spec.width = config.width;
|
||||
if (config.height !== undefined) spec.height = config.height;
|
||||
|
||||
return spec;
|
||||
}
|
||||
|
||||
/** The built spec as pretty-printed JSON text, ready for a snippet's `spec`. */
|
||||
export function buildSnippetSpecText(config: BuilderConfig): string {
|
||||
return JSON.stringify(buildChartSpec(config), null, 2);
|
||||
}
|
||||
|
||||
/** Title-case a single mark type for display/naming (e.g. `bar` → `Bar`). */
|
||||
function markLabel(mark: MarkType): string {
|
||||
return mark.charAt(0).toUpperCase() + mark.slice(1);
|
||||
}
|
||||
|
||||
/**
|
||||
* An auto-generated, descriptive name for the created snippet (spec §06 → Output:
|
||||
* "an auto-generated descriptive name"). When both X and Y are mapped it reads
|
||||
* "Bar chart of <y> by <x>"; otherwise it falls back to naming the dataset:
|
||||
* "Bar chart of <dataset>". Deterministic — no timestamp — so the name describes
|
||||
* the chart, not when it was made.
|
||||
*/
|
||||
export function generateChartName(config: BuilderConfig): string {
|
||||
const mark = markLabel(config.mark);
|
||||
const x = config.encodings.x;
|
||||
const y = config.encodings.y;
|
||||
if (x && y) return `${mark} chart of ${y.field} by ${x.field}`;
|
||||
const only = mappedChannels(config)[0];
|
||||
if (only) return `${mark} chart of ${only[1].field}`;
|
||||
return `${mark} chart of ${config.datasetName}`;
|
||||
}
|
||||
+11
-2
@@ -14,6 +14,13 @@
|
||||
/** Current schema version for a Snippet record (read-time migration target). */
|
||||
export const CURRENT_SNIPPET_VERSION = 1;
|
||||
|
||||
/**
|
||||
* The Vega-Lite schema URL stamped into generated specs (`$schema`). Shared so the
|
||||
* sample template and the Chart Builder agree on one version; the Monaco schema
|
||||
* service pins the same URI independently (infrastructure/monaco-schema.ts).
|
||||
*/
|
||||
export const VEGA_LITE_SCHEMA_URL = 'https://vega.github.io/schema/vega-lite/v6.json';
|
||||
|
||||
export interface Snippet {
|
||||
/** Unique, stable identifier. */
|
||||
id: string;
|
||||
@@ -45,7 +52,7 @@ export interface Snippet {
|
||||
* Inline data only — datasets arrive in M3.
|
||||
*/
|
||||
export const SAMPLE_SPEC = {
|
||||
$schema: 'https://vega.github.io/schema/vega-lite/v6.json',
|
||||
$schema: VEGA_LITE_SCHEMA_URL,
|
||||
description: 'A simple bar chart.',
|
||||
data: {
|
||||
values: [
|
||||
@@ -92,6 +99,8 @@ export interface CreateSnippetOptions {
|
||||
now?: Date;
|
||||
/** Id injection for deterministic tests; defaults to a random UUID. */
|
||||
id?: string;
|
||||
/** Seed the extensible metadata bag (e.g. Chart Builder provenance). */
|
||||
meta?: Record<string, unknown>;
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -113,7 +122,7 @@ export function createSnippet(options: CreateSnippetOptions = {}): Snippet {
|
||||
comment: '',
|
||||
tags: [],
|
||||
datasetRefs: [],
|
||||
meta: {},
|
||||
meta: options.meta ?? {},
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user