Style props are callback-first; enum shorthands are sugar over callbacks
Every style surface (`markers`, `lines`, `trajectories`, `labels`) takes a callback `(ctx) => StyleValue` as its canonical signature. Object literals and enum shorthands (`colorBy="xg"`) are implemented as sugar that internally resolves to a callback. Agents can always fall back to callbacks without learning chart-local magic.
Context
Charting libraries face a style-API dilemma. Enum shorthands (colorBy="xg",
shapeBy="context") are discoverable and concise for common cases. Callbacks
(markers={shot => ({ fill: … })}) are flexible but verbose. Picking one
loses the other. Picking both creates two code paths with subtle precedence
rules and makes the library harder to learn, harder to document, and much
harder for an LLM agent to drive reliably.
Decision
Callbacks are canonical. Every style prop accepts a callback signature as its primary type. Enum shorthands, object literals, and preset constants are implemented as thin resolvers that compile to callbacks before the render layer sees them.
colorBy="xg"resolves to an xG-aware fill callback internally.markers={(shot) => ({ fill: shot.outcome === "goal" ? "#c8102e" : "transparent" })}is the uncompressed form.- Both reach the same render output.
Consequences
- Agents and consumers can always write a callback that works, even when they don’t know the shorthand exists.
- Filtering, theming, and export machinery operate on resolved callback outputs — they don’t need to understand the sugar layer.
- New style surfaces ship as callbacks first; enum shorthands are added later only when a common case appears repeatedly in consumer code.
- JSDoc on every style prop documents both the callback form (primary) and the shorthand form (convenience), so discoverability is preserved.