mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
Chart builder: field-first shelf + value-or-field channels
This commit is contained in:
@@ -426,6 +426,12 @@ renderer service. Builder flow: `chart-builder.ts` (pure spec assembler) → `Ch
|
||||
(config + create) → `ChartBuilderModal`'s `BuilderPreview`. Reach for a reusable preview
|
||||
component only if a _third_ surface appears.
|
||||
|
||||
The builder's **X/Y axis controls live in the preview pane, not the config pane**: the
|
||||
on-chart Columns/Rows shelves (`OnChartShelves`) sit _above_ `BuilderPreview`, because axis
|
||||
position is a property of the chart (Tableau's Columns/Rows metaphor). The field shelf and
|
||||
the Colour/Size Marks card stay in the config pane. A reserved faceting slot in each shelf
|
||||
is a placeholder only.
|
||||
|
||||
---
|
||||
|
||||
## 6. Rendering Contract Lives Upstream (reference)
|
||||
|
||||
@@ -25,6 +25,29 @@
|
||||
Newest first. The at-a-glance build-order tracker is §4; per-item detail is §3. This log is
|
||||
the quick "where are we" — read it first.
|
||||
|
||||
- **2026-06-11 (Phase 2)** — **2A + 2B shipped: the field-first interaction substrate.** Up next: **3A intent-first front door**.
|
||||
- **2A · Value-or-field channels (the Property model).** `ChannelMapping` gained a constant
|
||||
`value` arm; the assembler emits `{ value }` and the measure/stack/area-split/prune logic
|
||||
all treat a constant Colour as "no series." New pure helpers (`isValueMapping`,
|
||||
`channelAcceptsValue`, `defaultChannelValue`, `coerceChannelValue`,
|
||||
`isColumnAllowedOnChannel`). `type` stays required (a constant carries a preserved-but-
|
||||
ignored type, so a field↔constant toggle round-trips). Tested.
|
||||
- **2B · Field-first builder.** The channel-first dropdown rows are replaced by a **field
|
||||
shelf** (columns as type-glyphed chips, auto Dimensions/Measures split past a column
|
||||
threshold), **click-to-assign** (armed channel, else first empty that accepts it —
|
||||
`assignField`/`focusChannel`), Tableau-style **pills** (a type chip that **cycles** the
|
||||
field type in-place, transforms beneath), and the **on-chart Columns/Rows shelves** above
|
||||
the preview (X/Y as a property of the chart) with a **reserved faceting placeholder** in
|
||||
each. Colour/Size live in a left **Marks card**, each switchable to a **constant** (2A).
|
||||
- **Decisions taken (overridable):** drag deferred (click/keyboard-first, fully tested);
|
||||
field grouping auto; aggregate stays a control under the pill (no pill context-menu yet).
|
||||
- **Spec §06** rewritten for the field-first model (Layout, Encoding channels, faceting
|
||||
placeholder, constants, validation/output).
|
||||
- **Verified:** `typecheck` + `test` (762, +20 core/store/modal) + `eslint` + `build`.
|
||||
**Owed:** a manual/visual pass against the live builder; a **`/council`** look at the
|
||||
type-cycle chip (a cycling button gives no direct type pick — explicit menu vs cycle is a
|
||||
real a11y trade-off) and the constant affordance.
|
||||
|
||||
- **2026-06-11 (later)** — **Owed debts on the Data section closed. Up next: Phase 2 (2A value-or-field channels, then 2B field shelf).**
|
||||
- **Council pass** on the new error/disclosure copy (the previously-deferred auto-fire
|
||||
surface). Three a11y conformance gaps against `architecture/10` were fixed: the inline
|
||||
@@ -393,9 +416,9 @@ Phase 1 1A actionable hints ✓ done
|
||||
1C filter (+ calculate) ✓ done
|
||||
1D data preview ✓ done
|
||||
1E expr-validate ✓ done (syntax + unknown-field; completion popup deferred)
|
||||
Phase 2 2A value-or-field channels (Property model) ← next
|
||||
2B field shelf + in-place type cycling ← Tier-C substrate
|
||||
Phase 3 3A intent-first front door (Tier C) ← built on 2B; the defining feature
|
||||
Phase 2 2A value-or-field channels (Property model) ✓ done
|
||||
2B field shelf + in-place type cycling ✓ done (field-first + on-chart shelves)
|
||||
Phase 3 3A intent-first front door (Tier C) ← next; built on 2B; the defining feature
|
||||
3B starter examples
|
||||
Phase 4 (gated) theta/facets/styling-overrides/undo/lookup — decide after Phase 3
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
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.
|
||||
> **Design level — "smart + guarded" (Tier B).** The builder is field-first — the user works from a shelf of the dataset's columns and drops them onto encoding channels — 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
|
||||
|
||||
@@ -14,8 +14,8 @@ The Chart Builder is a visual, no-JSON way to compose a Vega-Lite chart from a s
|
||||
|
||||
A two-pane modal:
|
||||
|
||||
- **Left — configuration:** dataset name, a **Data** section (row filters, calculated fields, and a collapsible row preview — see _Data_ below), mark type selector, one row per encoding channel, optional width/height inputs, and a "Create Snippet" action.
|
||||
- **Right — live preview:** a rendered chart that updates as the configuration changes, with a placeholder/error area.
|
||||
- **Left — configuration:** dataset name, a **Data** section (row filters, calculated fields, and a collapsible row preview — see _Data_ below), mark type selector, a **field shelf** (the dataset's columns, field-first), a **Marks** card (the Colour and Size encodings), optional width/height inputs, and a "Create Snippet" action.
|
||||
- **Right — live preview:** the **Columns** (X) and **Rows** (Y) shelves stacked above a rendered chart that updates as the configuration changes, with a placeholder/error area. Position is a property of the chart, so its controls sit on the chart (Tableau's Columns/Rows metaphor).
|
||||
|
||||
## Data (preview, filters, calculated fields)
|
||||
|
||||
@@ -59,17 +59,19 @@ The section is ordered **input → shaping** so the distinction reads at a glanc
|
||||
|
||||
### Encoding channels
|
||||
|
||||
- Exactly four channels are offered, in this order: **X, Y, Color, Size**.
|
||||
- For each channel the user:
|
||||
- Picks a dataset column from a dropdown of the dataset's detected columns (see _Datasets_ for column detection). A "None" option leaves the channel unmapped. Each column option shows a small type indicator alongside the column name.
|
||||
- Optionally overrides the channel's **field type**. 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.
|
||||
- The column dropdown also offers a field-less **"Count of records"** measure (Vega-Lite `count`) — a quantitative count of the rows, with no column.
|
||||
- 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.
|
||||
Exactly four channels are offered: **X, Y** (the positional axes, on the on-chart Columns/Rows shelves) and **Colour, Size** (the Marks card). Assignment is **field-first**.
|
||||
|
||||
The field-type override is presented as a fixed **`N | O | Q | T`** segmented control (abbreviations with full-name tooltips, after _Datasets_' Nominal/Ordinal/Quantitative/Temporal), always showing all four with the column's invalid types **disabled** rather than hidden — so the control keeps one shape on every channel.
|
||||
- **The field shelf** lists the dataset's detected columns (see _Datasets_), each with a small type glyph, plus any calculated fields and a field-less **"Count of records"** measure (Vega-Lite `count`). Past a threshold of columns the shelf groups into **Dimensions** (categories/dates) and **Measures** (numerics); a small dataset stays a single flat list. A column already mapped somewhere is dimmed (it may still be placed on more than one channel).
|
||||
- **Assigning a field:** clicking a shelf field places it on the **armed** channel, else the first empty channel that accepts it (X→Y→Colour→Size). A channel slot is armed by clicking it (then a clicked field fills it); the armed slot shows a "pick a field" prompt. A field that no channel can take is a no-op.
|
||||
- **A mapped channel is a pill:** a leading type chip, the field (or "Count") label, and a remove (×). The type chip **is the field-type control** — activating it cycles the field's type within the set **valid for that column** and channel (Tier B valid-type locking): number → {Quantitative (default), Ordinal, Nominal}; date → {Temporal}; text → {Nominal (default), Ordinal}; boolean → {Nominal}. When only one type applies (e.g. a date), the chip is inert. A fresh mapping defaults its type from the inferred column type (numeric → Quantitative, date → Temporal, otherwise Nominal).
|
||||
- **Constant values (the Property model):** the **Colour** and **Size** channels may instead hold a **fixed constant** — a literal colour or size applied to every mark, emitted as Vega-Lite `{ value }` rather than a field binding. An empty Colour/Size slot offers an "or constant" affordance; the bound constant shows a colour picker (Colour) or a number (Size). X and Y stay field-only (a constant position is not useful). Switching a channel between a field and a constant is reversible, and the prior field type is preserved across the toggle.
|
||||
- **Size discipline:** the **Size** channel accepts only columns whose natural type is a magnitude (numeric) — size implies an ordered magnitude, so categories and dates are not placed on Size by assignment (they remain available on X/Y/Colour). A constant size is always allowed.
|
||||
- **Clearing** a channel (the pill's ×) leaves it out of the produced spec.
|
||||
- A **Swap X/Y** control, by the on-chart shelves, exchanges the X and Y bindings (field/constant and type) in one click — for quickly flipping the axes of the pre-populated default.
|
||||
|
||||
### Faceting placeholder (reserved)
|
||||
|
||||
Each on-chart shelf shows, beside its axis slot, a **non-interactive placeholder** for **faceting → small multiples** (a future capability). It only signals where row/column faceting will live; it does nothing yet.
|
||||
|
||||
### Transforms (per channel)
|
||||
|
||||
@@ -118,14 +120,14 @@ A clean configuration shows no hints.
|
||||
|
||||
## Validation
|
||||
|
||||
- A chart requires **at least one** channel mapped to a column.
|
||||
- While no channel is mapped, the "Create Snippet" action is disabled and the preview shows the configuration prompt.
|
||||
- A chart requires **at least one** channel bound — a field, a count, or a constant value.
|
||||
- While nothing is bound, the "Create Snippet" action is disabled and the preview shows the configuration prompt.
|
||||
|
||||
## Output / Create
|
||||
|
||||
Selecting "Create Snippet" produces the final artifact:
|
||||
|
||||
- Builds a complete Vega-Lite spec containing: the schema reference, a named data reference to the dataset, any top-level `transform` (calculated fields first, then row filters — see _Data_), the chosen mark (with tooltips enabled), the mapped encodings (each with its field and field type, plus any aggregate / bin / `timeUnit` transform), chart-level sort and stacking where set, and any explicit width/height.
|
||||
- Builds a complete Vega-Lite spec containing: the schema reference, a named data reference to the dataset, any top-level `transform` (calculated fields first, then row filters — see _Data_), the chosen mark (with tooltips enabled), the bound encodings (a field encoding carries its field and field type plus any aggregate / bin / `timeUnit` transform; a constant encoding is a `{ value }`), chart-level sort and stacking where set, and any explicit width/height.
|
||||
- Channels left unmapped are omitted; if no encodings exist the spec omits the encoding block entirely (prevented by validation here).
|
||||
- Creates a new snippet from that spec with an auto-generated descriptive name, adds it to the snippet library, and records that it was built from the dataset.
|
||||
- Links the snippet to the dataset by recording the dataset reference, so the bidirectional snippet↔dataset relationship is established (see _Datasets_).
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# UX second pass — batched council review
|
||||
|
||||
A running parking lot of small UX / interaction decisions deferred for a **batched
|
||||
[`/council`](../.claude/skills/council/SKILL.md) review**, rather than gating each one the
|
||||
moment it surfaces. Append quirks here as they come up; resolve them together in one pass,
|
||||
record the resolution into the contract (`docs/architecture/09`+`10` and the relevant
|
||||
`docs/spec/`), then delete the row.
|
||||
|
||||
## Open
|
||||
|
||||
### Chart Builder — encoding type control: cycle vs. explicit pick
|
||||
|
||||
- **Where:** `src/app/components/ChartBuilderModal.tsx` → `ChannelPill` (the `pillType` chip).
|
||||
- **What:** a mapped channel's field type is shown as a **cycling chip** — activating it steps
|
||||
N → O → Q → T within the set valid for the column/channel. It is compact and matches the
|
||||
approved field-first pill design, but a _cycling_ button gives a screen-reader / keyboard
|
||||
user no way to jump straight to a type; they step through the cycle. The pre-2B control was
|
||||
an explicit `N | O | Q | T` segmented radio (direct pick, APG radio pattern).
|
||||
- **Decision to make:** keep the cycle, restore the explicit segmented control, or a hybrid
|
||||
(chip for a quick mouse cycle + an accessible radio/menu for direct selection).
|
||||
- **Lens:** WAI-ARIA APG (radio vs. toggle button), IBM Carbon, the project's keyboard-first
|
||||
accessibility bar.
|
||||
|
||||
### Chart Builder — empty Colour/Size "or constant" affordance
|
||||
|
||||
- **Where:** `ChannelPill` / `ChannelSlot` — the constant-value entry on Colour/Size (2A).
|
||||
- **What:** an empty Colour/Size slot offers a small underlined "or constant" text button to
|
||||
switch the channel from a field binding to a fixed `{ value }`. Confirm the copy, emphasis,
|
||||
and discoverability read well alongside the field-assign affordance.
|
||||
- **Lens:** Carbon / GOV.UK content + control emphasis.
|
||||
Reference in New Issue
Block a user