Constructor functions vs plain dictionaries

[mcanouil]

Context

Gribouille requires aesthetic mappings and plot labels to be wrapped in constructor functions: aes(x: ..., y: ...) and labels(title: ..., x: ...).
Both return a tagged dictionary (kind: "aes", kind: "labels") with a fixed, named-parameter surface.
An alternative would be to accept a plain Typst dictionary directly, e.g., mapping: (x: "a", y: "b").
This thread captures the trade-offs of the current constructor-only design so the choice is documented and open for input.

Dimension	Constructor functions (aes(), labels())	Plain dictionaries
Documentation	Named parameters are discoverable and self-documenting.	No documented parameter surface or autocomplete.
Validation	kind tag distinguishes a spec from an arbitrary dict, and unknown fields surface.	No validation, so a mistyped key (colur:) fails silently or late.
API stability	Internal shape (e.g., labels() nesting into axes) can change without breaking user code.	Internal representation leaks to users, so restructuring is breaking.
Consistency	Matches scale-*(), theme(), coord-*(), and is familiar to ggplot2/plotnine/ggsql users.	Conflicts with the rest of the constructor-based API.
Verbosity	Users call a function rather than writing a literal.	Less boilerplate and Typst-native.
Dynamic use	Building or merging requires spreading into the constructor.	Trivial to build, merge, and reuse dynamically.
Learning curve	One more concept to learn and import.	No extra concept.

Note

Note on dual-form arguments

The stat and position arguments already accept plain strings alongside their constructors.
This inconsistency invites the question of why mapping and labels could not similarly accept plain dictionaries.

Open question

Should the design stay constructor-only, or add optional plain-dictionary acceptance as a convenience, as stat and position already do?