feat: add "auto" mark that infers the mark type from encodings#9853
Open
essandhu wants to merge 4 commits into
Open
feat: add "auto" mark that infers the mark type from encodings#9853essandhu wants to merge 4 commits into
essandhu wants to merge 4 commits into
Conversation
Introduce an "auto" mark that, during normalization, resolves to the primitive mark best matching the encodings and their declared/inferred data types. Inspired by Observable Plot's auto mark and CompassQL, but the decision is made purely from declared types since Vega-Lite compiles without access to the data. - Add `prefer` to constrain the mark family (point/line/area/bar/rule); `area` is only ever produced when explicitly requested via `prefer`. - 1D specs (a single positional field) become a histogram/count bar via bin and count injection. Ref vega#8749
Add the auto mark reference page (site/docs/mark/auto.md) with the decision table, the `prefer` property, and runnable examples; mention auto in the mark overview; add an Auto entry to the docs TOC between Area and Bar. Adds six focused example specs that reuse data and field names from existing examples (cars.json, stocks.csv, movies.json): - auto_scatterplot (Q x Q -> point) - auto_line (T x Q -> line) - auto_histogram (1D Q -> bar + injected bin/count) - auto_bar (1D N -> bar + injected count) - auto_heatmap (N x O + color measure -> rect) - auto_prefer_area (T x Q with prefer="area" -> area) Compiled output under examples/compiled/ is intentionally left to CI to regenerate, per CONTRIBUTING.md. Ref vega#8749
Address a handful of small conventions surfaced by an audit against CONTRIBUTING.md: - Add `__Default value:__` line to the `prefer` JSDoc per the docs guide; regenerate the schema. - Add `AutoMark` and `AutoPreferredMark` entries to `site/_data/link.yml` so the `prefer` property table renders type links cleanly. - Rewrite the six example specs descriptions as plain prose (the `description` field is used as accessibility text; other examples in the repo use plain English). - Rename the auto.md "How the Mark Is Chosen" anchor from `selection` to `decision` to avoid conceptual overlap with the Vega-Lite "selection" feature; update the TOC link. - Add a defensive test that a `mark: "auto"` spec with no encoding still normalizes (gradual specification, design principle 3). Ref vega#8749
Match `src/normalize/pathoverlay.ts` style: no JSDoc on classes, helper functions, or type aliases in `src/normalize/automark.ts`; keep only inline comments that explain non-obvious decisions. Match `src/compositemark/boxplot.ts` for the top-level types file: drop JSDoc on `AUTO` and `AUTO_PREFERRED_MARKS` constants; keep the required `__Default value:__` JSDoc on the `AutoMarkDef.prefer` property. Match existing test files: remove JSDoc on the `resolvedMark` helper and compress the gradual-specification block comment to a single inline line.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PR Description
Closes #8749.
Introduces an
"auto"mark that, during normalization, resolves to the primitive mark best fitting the encodings and their declared (or inferred) data types. Inspired by Observable Plot'sautomark and CompassQL.Because Vega-Lite compiles without access to the data, the decision uses only declared/inferred types. Although this is narrower than Plot/CompassQL, it is still predictable and fully documented. The full decision table lives in
site/docs/mark/auto.md.Highlights
"auto"mark, accepted as a string or a mark def with optionalprefer: "point" | "line" | "area" | "bar" | "rule"to constrain the family."area"is opt-in only viapreferbin: true+aggregate: "count"→ histogram / count barexamples/specs/auto_*.vl.json), a new doc page, mark-overview update, and docs TOC entryIntentional design choices, open for discussion
linerequires a temporal axis orprefer: "line"ordersoft signals; explicitpreferonlyChecklist
npm testruns successfullysite/docs/+ examples.Tips: