[madelineluke]

Closes #1081. Part of the S2 chart stability RFC.

Summary

Every exported S2 component (stable and lab) and ChartOptions now declares how the chart applies a change to each prop. The update classes are noop, signal, data, size and rebuild, and each entry also has a replay flag. Tests check each declaration against the router, and the declarations generate a docs page.

• Tables. vega-spec-builder-s2/src/updateClasses/ has one table per *Options type, for example LINE_UPDATE_CLASSES. react-spectrum-charts-s2/src/updateClasses/ has one table per component's props, for example LINE_PROP_UPDATE_CLASSES. Every table uses satisfies UpdateClassTable<T>, so an unclassified prop is a type error.
• Router reporting. viewHost.update() returns { route, channels }. Its incremental route reports which of signal, data and size it applied.
• Generated tests. Each component has a *.updateClasses.test.tsx that changes every prop. Each case asserts that the router took the declared class and that the updated scene equals a fresh mount (RFC validation tests 2 and 3). The case map is exhaustive by type. Known disagreements use knownIssue, which runs them as test.failing.
• Docs. The new page docs-s2/docs/update-behavior.mdx is generated from the props tables and listed in the sidebar. Run yarn docs:update-behavior to regenerate it. A test fails when the committed page is stale.
• Docs for contributors. architecture/rendering-and-signals.md and the adding-props skill now explain how to classify new props.

Notes

• The tables live in updateClasses/ folders rather than next to each *Spec.types.ts as the issue suggested. That puts the values, tables and props tables in one place.
• I didn't add an onUpdate hook. Tests observe the applied class by spying on the view adapter, and nothing in production needs the hook.
• replay is true only for color, dimension and metric on marks, plus markType, Chart marks and UNSAFE_vegaSpec. Nothing reads the flag yet; it's for the upcoming draw-in replay policy.
• Harness changes:
  • settle() compares scenes instead of counting renders, because Vega re-renders axis titles on every run.
  • New shared fixtures: updateCaseData, noopCallback and withDrawIn.

Bugs found, marked knownIssue

These bugs don't have issues yet.

• Legend: a Legend with a name fails to render ("Undefined data set name legend0Aggregate").
• TrendlineAnnotation: with custom text at dimensionValue: 'end', the label's bounds flip between two positions on every dataflow run. It jitters and never settles.
• Scatter: after changing colorScaleType from ordinal to linear, rows keep a stale rscSeriesId after the rebuild.

dualMetricAxis on a non-interactive Line or Bar fails to render. This is already known, and the cases work around it with a ChartInspect child.

Review

Each component owner, please review your component's table, especially the noop entries. Those are props read at render or event time through refs, for example popover sizing, tooltipAnchor, and Bar onMouseOver.

Testing

• yarn test:quiet --testPathPattern="updateClasses|updateBehaviorDocs|stability|viewHost"
• yarn build:s2, yarn tsc, yarn lint, yarn lint:sonar, yarn check:packages and yarn changeset:status

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[github-actions]

🎨 Storybook -> https://opensource.adobe.com/react-spectrum-charts/PR-1099/

🎨 S2 Storybook -> https://opensource.adobe.com/react-spectrum-charts/PR-1099-s2/

🎨 S2 Dev Storybook -> https://opensource.adobe.com/react-spectrum-charts/PR-1099-s2-dev/

📚 Docs -> https://opensource.adobe.com/react-spectrum-charts/PR-1099-docs/