@tanstack/charts
Version:
A chart grammar for TypeScript and JavaScript. Marks consume your data directly, channels describe visual encodings, and the engine compiles them into a renderer-neutral keyed scene. TanStack's compact scales cover common numeric and categorical mappings.
63 lines (49 loc) • 5.57 kB
Markdown
# Scale and Guide Ownership
## Scale Input Decision
| Requirement | Supply | Owner |
| ---------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
| Domain follows rendered mark channels | scale factory | Charts infers domain and assigns range |
| Configure padding before inferred categorical domain | zero-argument factory returning configured scale | application owns padding; Charts owns domain/range |
| Domain is product state or shared comparison policy | configured scale instance | application owns domain; Charts copies and assigns range |
| Reverse visual direction | axis `reverse` | Charts reverses range without rewriting domain |
| Nice inferred continuous domain | axis `nice` | Charts applies after domain inference |
| Numeric or categorical basics | compact exact subpath | application chooses family |
| Elapsed time or nonlinear mapping | exact `d3-scale` family | application declares direct dependency |
Never assign positional pixel ranges in authored chart code.
## Scale Family Decision
| Meaning | Start with | Upgrade condition |
| ---------------------------------- | ------------------------------------ | ------------------------------------------------------------- |
| Numeric position | `@tanstack/charts/scales/linear` | piecewise, nonnumeric interpolation, log/power/symlog/radial |
| Categorical position with width | `@tanstack/charts/scales/band` | required behavior exceeds compact contract |
| Categorical position without width | `@tanstack/charts/scales/point` | elapsed time matters |
| Stable categorical paint | `@tanstack/charts/scales/ordinal` | sequential/diverging/quantile/threshold semantics |
| Calendar time | `d3-scale` `scaleTime` or `scaleUtc` | always; point/band dates do not preserve elapsed duration |
| Sequential/diverging quantity | D3 color scale | center, interpolation, or statistical thresholds are semantic |
## Guide Decision
| Need | Configure | Verify |
| ---------------------------- | ------------------------------------- | --------------------------------------------------------- |
| Fewer or more candidates | `ticks.count` or `ticks.spacing` | actual scale may return a different count |
| Exact semantic candidates | `ticks.values` | kept labels outside candidates do not add grid/tick stubs |
| Collision policy | `tickLabels.thin` | smallest supported width |
| Rotated labels | `tickLabels.rotate` and anchor policy | measured margins and readable baseline |
| Preserve endpoints or events | `thin.keep` / priority | hard-kept labels may collide with each other |
| Hide guide but retain scale | `axis: false` | marks still materialize scale |
| Hide grid separately | `grid: false` | guide and grid are independent |
| Shared comparison | configured instances/domains | filtering does not rescale meaning |
## Color Ownership
| Channel/config | Meaning |
| ---------------------- | ----------------------------------------------------------- |
| `z` | geometry and interaction group identity |
| mark `color` | value sent through chart color scale and legend |
| mark `fill` / `stroke` | final paint override; bypasses scale mapping for that paint |
| chart `color.scale` | categorical or quantitative mapping |
| chart `color.legend` | visual explanation of the resolved color scale |
Use a stable configured ordinal domain when a product category must retain its color across filtering, reordering, sessions, or views. Use sequential color for ordered magnitude and diverging color only around a meaningful center. Keep essential state available without color.
## Failure Diagnosis Order
1. Confirm every materialized x/y channel has the matching axis scale.
2. Confirm the scale domain type matches channel values.
3. Distinguish factory inference from instance-owned domain.
4. Check finite values, log constraints, and missing endpoints.
5. Inspect the resolved domain and final range.
6. Inspect guide margins and clipping separately from the scale.
Source: `docs/concepts/scales-and-d3.md`; `docs/reference/scales-guides-and-color.md`; `docs/guides/legends-and-color.md`