Changelog

Notable changes to @workspace/active-charts. Format based on Keep a Changelog; versioning per Semantic Versioning.

This file is the authoritative release history for @workspace/active-charts from v1.0.0 onward (the externally-publishable baseline).

A note on version-numbering#

The visible version-history may look non-monotonic at first glance. The package was internally iterated through 1.0.0 → … → 9.1.0 during pre-publication development, then reset to 1.0.0 on 2026-05-18 to mark the externally-publishable baseline with an API-stability promise. The internal 1.x → 9.x history is intentionally not preserved in this file — those versions never shipped externally and the reset was the cleanest way to start the public SemVer-contract from a meaningful 1.0.0. Git tags from the pre-reset period still exist for archeological purposes; consumers should treat the post-2026-05-18 1.x line as the only authoritative version-sequence.

[Unreleased]#

Maintained in Foundation (since 2026-10-21)#

• Dependencies: @workspace/active-helpers replaces @workspace/active-utils. The export-font, delimited-text and menu helpers (./export-fonts, ./serialization, ./menu-items) now come from @workspace/active-helpers, the one package that owns them. Same functions, same behaviour; the public API is unchanged. A host that receives the charts receives active-helpers with it.

• Browser suite without the platform appearance: a Playwright project standalone runs the suite with host: 'none' (the package defaults only), for a repository that has no platform stylesheet to read by path. The default project and its screenshot baselines are unchanged.

• Documentation: references to documents of the source repository are text, marked (source repository: …), instead of links that resolve nowhere here.

Changed — BREAKING for imports (platform ADR-114)#

• IsoDateString, toIsoDateString and the zone brand come from @workspace/active-format, which owns them since ADR-114; the package no longer depends on @workspace/active-types, and the managed package set of a charts consumer no longer contains it. The props are unchanged; a consumer imports the brand constructors from active-format.

Changed — BREAKING for the managed package set (ADR-124)#

• Formatting comes from @workspace/active-format, not from the formatters entry of a translation package. The manifest declares @workspace/active-format instead of @workspace/active-i18n; the package imports nothing from a translation package any more. No prop, export or behaviour of active-charts changed: its presentation type is still the ValuePresentation union, now owned by @workspace/active-format.

• A consumer that formats next to active-charts with the same functions imports them from @workspace/active-format.

[6.0.0] - 2026-10-18#

Changed — canonical transfer form (2026-10-18, platform ADR-112)#

• The manifest is the transferable manifest (RPS-D7): no workspace package in devDependencies (what the package's own development takes from Datyx, such as the lint preset, is host tooling in the reusable package register); the declaration packages of what the source imports sit in the field of their module (@types/react and @types/react-dom as optional peers beside the react peers; the @types/d3-* packages as dependencies beside their modules). Nothing changes for a Datyx consumer.

• tsconfig.json is self-contained: it no longer extends @workspace/typescript-config, with the same compiler options, because a bundler in a consumer reads it for every source file it compiles.

• E2e harness: the host stylesheet it serves is the Datyx one, read from the host repository (active-ui's kit followed by @workspace/active-config/platform-appearance.css, fonts from packages/active-config/assets/fonts/v1); it stops with an error when they are missing, outside Datyx. Declared as host tooling. Rendered output is unchanged.

Changed — hierarchy node identity is a fixed-length structural key (ET-4B, ADR-122, CH-56, 2026-10-12)#

• Treemap, sunburst and org-chart node keys are no longer the .-joined path of segments from the root but k plus a 14-character base-36 hash of the parent's key and the node's own segment (the host id, else the sibling position). The same place gives the same key across a data replacement; a hashed key that meets another node's falls back to that node's full path (detected per build, deterministic). Stored key characters are now 15 per node instead of growing with depth × id length (a 1,000-level chain: 15,015 instead of 2,471,098). Drill path, focus retention, React keys and DOM ids keep their behaviour; the DOM ids behind aria-activedescendant change form. No public API change.

• Retained focus no longer reads the shape of a key. An org chart's focus kept across a collapse falls back to its nearest ancestor through the previous keyboard tree's parent links.

• The org chart's provisional depth boundary (ADR-119) is unchanged; its development diagnostic no longer gives the old key growth as its reason.

Changed — timeline label placement is indexed (ET-4B B6, 2026-10-12)#

• placeTimelineLabels reads only the blocks and markers near a candidate through an x-index instead of scanning all of them per event. The placement is identical (proved against the previous function on seeded layouts); 8,000 events place about 8× faster. Dense timelines still grow faster than linearly with the events per pixel column.

Added — ET-4 benchmark harness (ET-4B, ADR-123, 2026-10-12)#

• benchmark:pe4 (the minified production bundle, the only profile with verdicts), benchmark:pe3, benchmark:sim and benchmark:selftest: a typed workload registry with deterministic generators, the sample policy (p95 only at n ≥ 20, three runs, nearest rank), the reproducibility block (sourceHash, bundleHash, machine, power, load, quiet), CDP memory and long-task metrics, dashboards, soak and export resource runs, and results.json plus summary.md per run. Test and benchmark code only.

• CH-58: the selection/hover ratio of t8-selection is a diagnostic; two count guards (e2e/et4b-ch58-count-guards.spec.ts) and the absolute PE4 select budget replace it (QUALITY-BUDGETS § 28).

Added — hierarchy drill and return announced (ET-3B2, ADR-121, 2026-10-11)#

• A treemap or sunburst drill and return are announced (CH-67). With drilldown, a drill says "Drilled into {name}" and a return "Returned to {name}" in the chart's live region, once per drill or return that actually happens, from the keyboard and the pointer alike; nothing on the first render, for Backspace at the top level, Enter on a leaf or a data update. The drill state commits a record of each accepted move with the level it produced, so a render that never commits says nothing.

• Three new host keys: charts.accessibility.drilledInto, charts.accessibility.returnedTo, charts.accessibility.unnamedGroup. A host that does not provide them fails its coverage proof (ADR-028): migration note. No other public API change.

Fixed — pre-qualification (ET-3B, 2026-10-11)#

• No keyboard item model without room (CH-63). A heatmap, radar, timeline or radial bar below its room draws no items, and now has no item model either: one image with its name, its description (with the no-room sentence) and its table; not a tab stop, no arrow stepping or position announcement, and no aria-activedescendant naming an element that is not drawn. With room the keyboard returns with no focused position. The radial bar's existing guard did not hold (undefined && … fell back to the hook default); useKbdBase now names no descendant while its model is off, also in the commit that turns it off.

• A treemap leaf without a value keeps its keyboard element (CH-70). The keyboard reaches it and reads "(no value)"; its aria-activedescendant now names an element (0 × 0, nothing painted), as the sunburst's empty arc already did.

• The unavailable sentence under forced colours (CH-69). The state's text takes CanvasText, as every chart text does (ADR-108).

• No public API change. Docs: ACCESSIBILITY § 2 (the sankey switches layers with Enter, CH-68), § 5 (no room), and the ET-3 qualification protocol in BROWSER-AT-CHECKLIST and EVIDENCE (ADR-120).

Fixed — bounded safety correction (ET-2B2, ADR-119, 2026-10-10)#

• Org chart depth (CH-59, ET2-OD-5, ADR-119). The org chart's data-table walk was still recursive: a valid chain of about 2,500 levels threw a RangeError. It is iterative now, and the org chart has a PROVISIONAL depth boundary of its own, 139 levels below the root, derived from the growth of its card identity keys (one segment per ancestor, CH-56): a deeper organisation, collapsed branches included, shows the workload-unavailable state with a warn diagnostic in every environment and offers no CSV.

• No host-sized argument spread (CH-60). A collection whose length follows the data (heatmap categories, Sankey columns and a hub's neighbours, pie-like rows, sparkline points, radar values, histogram values, timeline lanes, legend entries, a series' hit-test points, linked hover rows, axis tick lines, bar rects of one category, compound series) was spread into Math.max / Math.min / push, which throws past the engine's argument limit (about 125,000). They go through maxOf / minOf (utils/math.ts) or a loop, with identical results; a sparse heatmap with 140,000 distinct rows and columns now draws. A source guard (et2b2-argument-spread-guard.test.ts) reviews every remaining spread.

Added — failure safety and resource boundaries (ET-2B, ADR-115 to ADR-118, 2026-10-10)#

• Copy outcome (IR-004, ADR-116). Copy value, Copy values and Copy as table are disabled with a reason (charts.contextMenu.copyUnavailable) when the browser cannot copy at the moment the menu opens (no clipboard API, an insecure context); otherwise the outcome is announced in the chart's live region (charts.contextMenu.copied, charts.contextMenu.copyFailed). A failed copy reaches the host through the new contextMenu.onCopyError(error: ChartCopyError) or, without it, an error diagnostic in every environment; never both, never with the copied text. New public exports: ChartCopyError, ChartCopyErrorCode, ChartCopyAction. No toast, no execCommand fallback.

• Workload-unavailable state (ADR-115). The unavailable placeholder says why: data-chart-unavailable="input" (charts.unavailable) or "workload" (new charts.unavailableWorkload). A treemap or sunburst deeper than the PROVISIONAL boundary of 139 levels below its root (derived: the largest depth whose chain writes at most 10,000 path segments) shows the workload state with a warn diagnostic in every environment.

• Sparse heatmap table (IR-005, ADR-117). The data table is the matrix while it is no larger than the list of present cells, else that list (row, column, value) with a summary (charts.dataTable.row, charts.dataTable.column, charts.dataTable.cellsListed).

Fixed — failure safety and resource boundaries (ET-2B, 2026-10-10)#

• Sankey (IR-006). The cycle check walks an explicit stack: a deep acyclic chain (100,000 nodes) validates instead of overflowing the call stack. Same cycle and duplicate-id diagnostics.

• Heatmap (IR-005). No structure grows with rows × columns: the keyboard reads present cells through a lookup and the overlay is one node, the focused position's (it still walks every position and reads an absent one "(no value)").

• Hierarchies (CH-48). Every walk of a host tree is iterative (table, CSV, node keys, colour measure, selection index, keyboard map, the org chart's walks and ancestor climbs; the org chart's table walk followed in ET-2B2, CH-59): depth alone never throws.

• Hierarchy keyboard (CH-55). One sibling list per parent instead of a copy per node: a flat tree of 10,000 leaves holds 10,000 slots, not 100 million.

• Item keys (CH-49, ADR-118). One reader for every family: NaN, an infinity, an invalid Date and any non-key type name no item (as null); a boolean is its text everywhere, so a boolean bar is now selectable.

• Unknown series type (CH-44). A runtime series type without a plugin shows the unavailable state with one development diagnostic instead of throwing in the accessible name.

• Heatmap order (CH-51). Linear matching through sets; a missing category named twice is counted once in the diagnostic.

• <Chart> in its unavailable state offers no CSV: the handle rejects with EXPORT_NO_DATA and the menu lists no CSV item.

• Tests (CH-54). The oracle import guard also reads import.meta.glob, fails closed on a loader handed on as a value or by bracket access, and compares module paths case-insensitively.

Fixed — hierarchy data is a prepared snapshot (ET-1B3, ADR-114, 2026-10-10)#

• Hierarchy (CH-52, ADR-114). A treemap or sunburst that laid out again on its own (a new size, a drill) after a host changed a fallback parent's value, or a children array, in place under the SAME root drew the live tree while every reader stated the preparation (Summary 30 drawn as 90, Sector 40 drawn as 80). One preparation now owns the measures AND the structure they were resolved over: the layout, node keys, drill path, table, keyboard, CSV, selection index and colour measure follow the prepared children, and the layout weights come from the preparation. The contract (API § 3.3): hierarchy data is a snapshot; when it changes, pass a new root object (structural sharing is fine). Under the same root the chart stays on what it prepared, consistent on every surface. Still one pass, O(nodes); no new public type.

• The ET-1 oracle import guards share one reader that also sees vi.importActual / vi.importMock / vi.mock, template-literal loads and type arguments, compares whole path segments, and fails closed on a load whose module it cannot read (CH-53).

Fixed — a measure per preparation, zoom options at the commit (ET-1B2, 2026-10-10)#

• Hierarchy (CH-50, ADR-112). A host that changed a node in place and passed a new root got geometry from the new value and every reader (table, tooltip, keyboard, announcement, Copy value, CSV, second label, share) and the strict mismatch rule from the old one: the resolved measure was cached per node for the life of the page. Each treemap and sunburst now resolves its data once per data object, and the layout, the check and every reader read that one resolution; nothing is kept across roots or charts, and hierarchy input is not required to be immutable. Still one pass, O(nodes).

• Zoom (CH-47). Drag-select and touch pinch/pan read their options (axis direction and x map, minVisibleItems, whether zoom is enabled, plot size and margins) from the last committed render, never from a host render that never commits: a held transition that reversed the axis no longer made the visible chart zoom the mirrored rows, and one that raised minVisibleItems no longer refused a valid drag. A committed change still applies to the next gesture.

• The ET-1 oracle import guard now compares the module a specifier names (extension, /index, ./ and ../ spellings), not its text.

Fixed — one measure, one identity, committed state (ADR-112, ADR-113, ET-1B, 2026-10-10)#

• Hierarchy (IR-001, ADR-112). Treemap and sunburst size, label, share, read, copy and export every node by ONE resolved measure: a leaf's value, a parent's derived sum, a summary's own value only where nothing below it is valued. A parent value beside valued children used to add to the area (150 drawn for a group of 100 over 30 + 20, read as 50, exported as 100); a matching value is now silent and a contradicting one makes the chart unavailable with a diagnostic. The hierarchy CSV value is the resolved measure; both families divide a share by the shown root. The table walk is O(nodes) instead of O(nodes · depth).

• Heatmap (IR-002, ADR-113). A coordinate is its item key (ADR-106): 1 and "1" are two columns, a timestamp and its Date one. The cells, keyboard, selection, table, hit test and Copy value share that identity. Two rows on one cell make the chart unavailable (selection on or off); a row with a null coordinate is left out with a diagnostic. HeatmapAxisConfig.order widens to readonly ChartItemKey[].

• Controlled selection (IR-003, ADR-105 restored). The selection a handler reads is published at the commit (useInsertionEffect), not in render: a suspended host transition no longer changes the next request.

• An independent semantic oracle suite (et1b-oracle-*) and its import guard check geometry and every reader against literal expectations.

Documentation — the chart-family authoring guide (ADR-111, CF-1, 2026-10-09)#

• docs/ADDING-A-CHART-FAMILY.md is the one authoring guide for a new chart family: whether it is a family at all, its archetype, the shared routes it must use, the internal family register, the UI Lab page, the evidence layers and a Definition of Done, with a table of what the repository checks. API § 7 ("Authoring a New Chart") is now a pointer to it; its old forwardRef sketch is gone.

• API § 3.2 records why RadarChart has no data labels and why its props extend BaseChartPropsWithout rather than CategoricalChartProps.

• No runtime and no public-API change.

Fixed — residual shared runtime truth (ADR-108, CF-1C3b, 2026-10-09)#

• Print keeps the chart as drawn. The print stylesheet no longer forces a grey text colour, a light-grey grid or a white page: they broke the label language (an on-mark label printed at 3.9:1 in light and 1.7:1 in dark). A chart prints on its own mode's background with its colours exact.

• Forced colours: labels on a mark. Chart text keeps CanvasText on a Canvas halo, so a label on a pie, funnel, treemap or sunburst mark that keeps its colour stays readable under any system scheme.

• A deliberate press on <Chart> and the Cartesian wrappers. A pinch and the click after a long press that opened the menu no longer select or activate; the Cartesian overlay now uses the press rule of every family.

• Radial scales show what they step. Radar rings and radial-bar ticks never repeat a label (small values, or money in whole units, step coarser).

• Diagnostics per input or chart. A development diagnostic is once per condition and input object, or per chart where it concerns a value; a second chart is no longer silenced by the first for the session.

Changed — BREAKING (what a family accepts, it does, ADR-107, CF-1C3, 2026-10-09)#

• No replay switch where there is no replay. The menu of <Chart> and the Cartesian wrappers takes features.copy, zoom, series and export; features.replay was accepted and ignored and is now a type error. LinearGauge and BulletChart no longer take animation.replay: they never replayed. GaugeChart keeps both.

Fixed — archetype and family truth (ADR-107, CF-1C3, 2026-10-09)#

• Stagger on the profile. Funnel segments and the treemap and sunburst depths stagger on the chosen profile's step and cap, not on calm.

• onAnimationComplete on time. A staggered entrance (funnel, treemap, sunburst) reports load once, when its last mark has ended, counted from the first frame it is drawn in: the treemap no longer reports up to 300 ms late, the sunburst's morph no longer early.

• No room, no broken geometry. Below its room the timeline, sankey, heatmap, radar, linear gauge and bullet draw no marks and say so in a caption and in their description; the name, the table and a scalar's readout stay. Normal sizes are unchanged.

• The organisation chart. The zoom presets are a real menu (focus moves in and back, arrows, Home, End, Escape, Tab; presets as checked radio items), the toolbar stays at full strength while focused and stops its hover transitions without motion; its shadows are the chrome tokens. Shift+F10 opens the focused card's menu on every card. A finger pans the view; a cancelled gesture ends the pan.

• Items keep their element. A reordered slice, stage, sector, ring, radar series, treemap or sunburst node, sankey node or flow, or org card keeps its DOM element: React keys follow identity.

• Radial scales. Radar rings and radial-bar ticks never step finer than the values' semantic quantum (a count at whole numbers).

• <Chart> and <ChartDefaults>. <Chart> takes the provider's tooltip and accessibility under its own, as every wrapper does.

• Copy value on a hierarchy node writes the value its tooltip and table write (the sum of its valued children, else its own).

• Internal: the timeline's CSV rows live with the other families'; the treemap's leaf shading reads its sibling position in O(1); latent literal axis colours and series easing are tokens.

Changed — BREAKING (public types say what the package does, ADR-106, CF-1C2, 2026-10-09)#

• A category is its value. A Cartesian category axis follows ChartItemKey: the number 1 and the text "1" are two categories with two bands, two marks, two table rows and two selectable items, even when both read "1"; before, the band axis merged them by text. A Date category is its time. A reference value on a category axis (cross line, annotation, tickValues, a linked range) is given in the type the data has. The tick formatter still receives the category's text.

• <Chart> is generic and takes events. <Chart<TDatum>> (inferred from data): its context menu hands the host a typed CartesianPoint<TDatum> instead of never, and events bundles the chart and selection events, the individual prop winning.

• SeriesType names only <Chart> series. It is SeriesOptions['type'], the thirteen Cartesian series; the standalone families and the scalars are gone from it.

• No internal shape in a public type. HistogramSeriesOptions loses the internal _precomputedBins; HeatmapChartProps['label'] is the new exported HeatmapLabelOptions.

• One Cartesian prop contract. Every Cartesian wrapper derives its props from CartesianChartProps, which now also carries the events bundle with the selection events. No wrapper gains or loses a prop.

Fixed — shared truth and touch (CF-1C1, 2026-10-09)#

• A tap's echo is no hover. On every Cartesian chart the compatibility mouse events a browser fires after a tap no longer turn the tap's sticky tooltip into a hover that never ends: the card stays, then leaves on its touch timer, and a real mouse afterwards hovers as before. A tap with pinning pins and announces once.

• A sliding finger names the mark under it. On the eleven standalone families a slide now carries the tooltip, attention and current item to the mark under the finger, as the pointer does; before, the card kept naming the mark the slide started on.

• CSV and copy keep every column. Raw rows without declared columns (the categorical families, the heatmap) export every field any row carries, in first-seen order, instead of the first row's fields only. Explicit columns still win.

• Missing is never blank or 0. A Cartesian data-table cell without a host value reads "(no value)", as the tooltip does. A treemap or sunburst node without a value reads "(no value)" in the tooltip and the announcement instead of 0, and a group is announced with the sum of the values below it, as the table reads it. A real 0 stays 0.

• Repeated sibling ids. Treemap, sunburst and organisation-chart siblings that repeat an id stay two nodes (keyboard, attention, drill path) instead of one silently overwriting the other, and are reported once in development.

• Category identity follows the selection key. A categorical legend keeps a number or a Date apart from a text that spells it (1 and "1") in any row order, and names a Date by its time. The legend entry id of a number or Date category changes form (it was its text); entry ids stay opaque, so store them as reported.

Added (CF-1C1, 2026-10-09)#

• SingleTooltipData.valueMissing: the item carries no value; the default card writes "(no value)" and yValue is no reading.

Changed — BREAKING (bounded host composition, ADR-105, AF-B, 2026-10-09)#

• Headless legend. useChartLegend() and the legendLink prop let a host render its own legend from the chart's resolved discrete legend (ChartLegendEntry: identity, target, label, semantic key as painted, visibility, available actions) and act through the chart's own legend route (activate, showAll), which owns the state, the guards and the announcement. The five standalone legend families now announce and report every legend change, isolate and Show all included.

• Identity-based legend events. onLegendChange replaces onLegendToggle (no alias): one event per applied change from every route, naming the entry and target by identity, every hidden target and the input. ChartLegendItemRef is removed; a menu's legend target carries the ChartLegendEntry. The export legend types are ChartExportLegendItem and ChartExportLegendOptions.

• Every export returns its file. The handle exports and the standalone functions resolve with ChartExportResult (format, filename, blob, downloadStarted, warnings); exportChartAsCsv is asynchronous. download: false produces the same file, captured once and at rest, without a download. onExportComplete(result) receives that object, also for menu exports. Failures stay ChartExportError; an inherit-mode PNG whose web font could not be embedded warns font-fallback.

• A controlled change is a request. requested is always present on ChartSelectionChange and OrgCollapseChange. With selectedItems or collapsedIds the host prop is the truth: a request is computed from it, and drawn, listed and announced only once the host passes it back.

• One input vocabulary. Selection, activation, org collapse, the legend and the context menu report ChartInteractionSource: 'pointer' (mouse, pen), 'touch' (finger) or 'keyboard'; a menu action reports the input that opened the menu (OrgCollapseChange no longer says 'menu').

• Serialisable zoom easing. zoom.animation.easing is a ChartMotionEasing name (default 'calm', the same curve) instead of a function; zoom.animation.duration is bounded to 0 to 3,000 ms.

• Per-format Export menu. contextMenu.features.export takes true, false or {png?, svg?, csv?, pdf?}; a format the chart cannot write is never offered and an empty submenu is not shown. The default is unchanged.

• Public type cleanup. ChartAnnouncementCategory (without the internal 'immediate') and ChartTooltipContext name types that public signatures referenced; contextMenu carries no any, and the thirteen Cartesian wrappers type the menu element as CartesianPoint<TDatum>.

Changed — BREAKING (motion, ADR-104, 2026-10-08)#

• animation is a profile and six classes. {enabled, profile, entrance, update, exit, tooltip, attention, replay}; the entrance fields (duration, easing, type, stagger, layers) moved under entrance. AnimationUpdateOptions and ExitPhaseOptions are removed; ChartMotionProfile, ChartMotionEasing, EntranceMotionOptions, UpdateMotionOptions, ExitMotionOptions, InteractionMotionOptions, ReplayMotionOptions and SeriesEntranceMotionOptions are new. A series owns only its entrance (with delay) and its exit.

• Profiles calm (default) and responsive. Calm: entrance 400 ms (stagger 30 ≤ 200), update 300, exit 200, tooltip 130, attention 140 (release 250), replay 1,000; responsive is shorter in every class.

• Data updates move by default. update: false switches it off.

• Named curves only. easing is 'calm' | 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out'; no free CSS curve, no callback. The default is the calm curve, also for the scalar count-up; the default gauge sweep no longer overshoots.

• Standalone, scalar and graph families take profile, and where they have them tooltip, attention (standalone, sankey, org chart) and replay (the gauge). The sankey and the organisation chart now take animation.

• animation: false also stops a discrete zoom animation and the grouped slot movement, as reduced motion already did.

Added (motion, ADR-104, 2026-10-08)#

• A calmer interaction. The tooltip fades in and out on the tooltip duration and travels between the marks it describes (a change of side, a card following the pointer or a finger, and a new card are placed directly); a return while it fades reverses instead of blinking. The crosshair and the cues stay immediate and now leave together with the tooltip. The context steps back on the attention duration and returns more slowly when the pointer leaves. The heatmap's colour-key marker travels to a new value.

• Grouped series reflow. When a grouped bar, range bar, box plot or dumbbell series is hidden or shown, the others move to their new slots on the update timing, after the exit if one is configured; the pointer and the labels follow the drawn glyph.

• A calmer gauge replay on the replay timing: back for about a third, up for the rest, on an ease-in-out.

Fixed (motion, 2026-10-08)#

• animation.update animates every data change. An isolated change snapped and only a second change inside the same window moved. Every change after the first rows now travels from what is drawn, and a change mid-update continues from there.

• A horizontal bar moves its length in an update; a bar or histogram moves its whole rectangle; waterfall, candlestick and OHLC updates move, every part of a glyph together.

• Line and area updates follow the configured curve (they used a fixed one).

• A change of orientation is drawn at once, never as a morph between a vertical and a horizontal layout.

• No neighbour flashes into its final slot when a grouped series is hidden, and range bar, box plot and dumbbell keep their slots through an exit, as grouped bars do.

• The tooltip's first frame carries its content. Firefox could show one frame of a target without its card.

• A pointer that moves within one item of a standalone family renders nothing; a travelling tooltip renders no family component either.

• A plain <Chart> follows ChartDefaults.animation.

• An export never captures a motion mid-way: every scripted motion (an update, a reflow, a count-up or replay, a discrete zoom) declares its end and the export waits for it, within the chart's motion budget plus one second (at least four).

• Invalid durations fall back to the profile with a development diagnostic; tooltip and attention are held at 600 ms, geometry at 3,000 ms.

• A two-finger gesture on <Chart> is no hover: a pinch or pan no longer drives the tooltip and the attention from its first finger.

• A tap on a radial bar ring shows its card, and a sliding finger carries it, as on the other standalone families.

Fixed (keyboard menu target, grouped bar exit, hierarchy attention, 2026-10-07)#

• Shift+F10 and the ContextMenu key open the menu on the keyboard's current item on PieChart (and the donut), FunnelChart, RadialBarChart, NightingaleChart, RadarChart, TreemapChart, SunburstChart, SankeyChart (node or link) and TimelineChart, with or without selection and activation props. Before, without those props, they opened the chart's menu. Enter, Space, selection and tab stops are unchanged; the radar opens on the same vertex for Shift+F10 as for Enter.

• A grouped bar series that leaves through its exit animation keeps its column. Hiding one of several unstacked bar series no longer fades the leaving bars across the whole category band, and the remaining bars hold their columns until the exit ends, then take their final columns. Rest geometry and an instant hide are unchanged.

• Treemap and sunburst address a tile or arc by its node identity, the same identity the keyboard, selection and the menu use. Two nodes with the same label are always two nodes; a value change, resize or reorder keeps the hovered or focused node current; drilling in or out clears the previous view's hover and keyboard highlight instead of marking another node.

Added (chart-family capabilities: histogram bins, funnel context, timeline time, bar label placements, sparkline domain, ADR-103, 2026-10-07)#

• Histogram binWidth: every bin the given width in x units, on multiples of it; the last bin includes its upper bound. One bin rule: binCount, binWidth or bins (HistogramBinRuleOptions); an untyped call with several uses bins, then binWidth, then binCount, and says so in development. A width that is not a finite number above 0, or that would make more than 1,000 bins, falls back to the default count with a diagnostic.

• Histogram areaProportional (count and sum, HistogramAmountOptions): unequal bins are drawn per the narrowest bin's width, so a bar's area is its amount; equal bins draw exactly as before. Labels, the tooltip value, the announcement and the table keep the amount; the tooltip adds a "Per {width}" row (host key charts.tooltip.binRate). Unequal bins without it are reported in development.

• Funnel formatter context: dataLabels.formatter(value, context?) receives FunnelLabelFormatterContext (datum, seriesId, seriesName, the source index, shareOfFirst, shareOfPrevious over the visible stages). FunnelDataLabelOptions types the funnel's dataLabels.

• Timeline timeAxis with TimelineEvent.time (TimelineTimeAxis, TimelineTime): events placed by machine time, equal times on one x, markers never moved by labels; keyboard, table and announcement in time order, equal times in the host's order; the CSV keeps the host's order and adds time. Ordinal placement stays the default.

• Candlestick bodyStrokeWidth (default 1, 0 allowed) on CandlestickChart and the candlestick series; the colour stays up.stroke / down.stroke, the wick keeps wickStrokeWidth; forced colours keep a border on a borderless rising body.

• Bar label positions 'inside-end' and 'inside-base' (BarLabelOptions, BarLabelPosition): inside the bar against its value end or its base, by sign and axis direction, a stack segment at its own ends. Bar only; the waterfall keeps 'inside' | 'outside'.

• BarChartSeriesConfig.label: a series' own labels, replacing the chart's label for that series as a whole object.

• Sparkline domain: an exact two-sided value domain for line, area and bar; equal values draw at equal heights across sparklines that share it; values beyond it are drawn to the edge and keep their number.

Changed (chart-family capabilities, ADR-103)#

• A bar Sparkline reads from zero. Its automatic domain now always reaches zero (padded only away from it); before, all-positive bars stood on the bottom of a padded min–max domain, so their lengths misstated the values (T9-D9). Line and area sparklines are unchanged. With a domain, a zero outside it is cut at the edge and the domain is never widened.

• HistogramSeriesOptions and TimelineChartProps are type aliases (they carry the new unions); an interface … extends of either becomes a type … &. Setting binCount and bins together is now a type error (bins already won at runtime).

Added (selection and activation on the standalone families, ADR-102, 2026-10-06)#

• Selection and activation on nine standalone families: selection, selectedItems, defaultSelectedItems, onSelectionChange and onItemActivate (also in events) on PieChart, FunnelChart, RadialBarChart, NightingaleChart, RadarChart, HeatmapChart, TreemapChart, SunburstChart and SankeyChart, with the meaning they have on <Chart> (ADR-042): a click or tap selects, then activates; Space selects, Enter activates (Shift+Enter on a sankey, whose Enter still moves between nodes and links); controlled or uncontrolled; single or multiple; an item that is not drawn is inactive, not removed. Without the props nothing changes.

• The items: a slice, stage, bar or sector (an item of the chart's one series, keyed by categoryKey or selection.itemKey); a radar vertex (series × variable, reached on the keyboard with PageUp / PageDown); a heatmap cell with a row; a treemap or sunburst leaf by its id (a parent keeps drilling); a sankey node by its id and a link by its id or its source and target.

• LinkDatum.id, optional: a link's identity for selection, activation and attention. Parallel links without ids share one identity, select together and are reported once in development.

• Types: ChartSeriesItemRef, ChartCellItemRef, ChartNodeItemRef, ChartLinkItemRef, ChartSeriesItem, ChartCellItem, ChartNodeItem, ChartLinkItem.

• selectedItemCount in the menu context now counts the selected drawn items of the standalone families.

Changed (selection and activation, ADR-102)#

• ChartItemRef and ChartItem are a union of four forms (an item of a series, a cell, a node, a link). The series form is unchanged; code that reads seriesId or key from a ChartItemRef it did not narrow now narrows ('seriesId' in ref, or kind). See the migration notes.

Fixed (selection and activation, ADR-102)#

• A sankey link's attention was named by its nodes' labels: two nodes with one label shared the attention of their links. It now reads the link's id, else its source and target node ids (T8-X1).

• CategoricalSlice.index on pie, funnel, radial bar and nightingale was the position among the drawn slices; it is now the row's index in data, as documented (T8-X5).

• Docs: a selected item carries a caret, not an outline (T8-X2); ADR-042's export sentence is superseded (T8-X3).

Added (compound grouping and orientation, ADR-101, 2026-10-06)#

• Several series on the four compound wrappers: series on RangeBarChart, RangeAreaChart, BoxPlotChart and DumbbellChart (RangeBarChartSeriesConfig, RangeAreaChartSeriesConfig, BoxPlotChartSeriesConfig, DumbbellChartSeriesConfig), each from the single-series keys or from series, never both (the type refuses the mix; a caller outside the type system is told once in development).

• Automatic grouping: several visible range bars, boxes or dumbbells of one family, orientation and axis stand side by side in their category, in series order; a hidden one gives its slot back and the rest re-centre. No option. Families never group with each other. Range areas overlay in series order, each at its own opacity.

• Horizontal box plot: horizontal on BoxPlotSeriesOptions and BoxPlotChart (no navigator or annotations when horizontal, as a horizontal range bar); the same five statistics, roles and words.

• Several dumbbells: one legend entry per series with a paired key of its two end colours, on screen and in an export; every end is read with its series first ("Plan: 2024"). One dumbbell series is unchanged.

Fixed (compound grouping and orientation, ADR-101)#

• A box on a reversed value axis ran from Q3 away from Q1; it now spans the two quartiles (T4-X1).

• Two range bars or boxes in one category drew in one slot, the earlier hidden and not reachable by pointer (T4-X5).

• Two dumbbell series were announced, tooltipped and tabled by their end names only (T4-X4).

• Endpoint labels of range bars, range areas and dumbbells could overlap another series' labels; they now join the plot's one collision decision.

• Docs: the reason given for "dumbbell single-series only" (T4-X2) and the box plot's widthRatio base (the band, not the step; T4-X3).

Added (scalar scales, targets and gauge replay, ADR-100, 2026-10-06)#

• A tick scale on GaugeChart, LinearGauge and BulletChart: scale (ScalarScaleOption): true for ticks at round values for the scale's length, {ticks: [...]} for exactly these values. The ends are always labelled; a tick label gives way to an end or the target, its tick staying; labels use the readout's notation. Ticks are in no name, table or CSV.

• One target on all three: target (ScalarTarget) is now on ScalarChartProps, so GaugeChart has one too (a mark across the band, above the needle or the bar), and takes {value, label} to name it ("Budget 1,500"). Beyond the scale its mark stops at the nearer end, every text keeps the true number.

• GaugeChart indicator: 'needle' (default) or 'bar', a narrower arc inside the band from startAngle to the value; zones, target and readout stay.

• GaugeChart replay (default off): a hidden click or tap at the pivot and, where the host's menu keeps it (contextMenu.features.replay), Replay animation re-run the entrance to the current value. Ignored while the gauge moves; nothing moves under reduced motion; no value, callback, name or export changes.

• Forced colours: the scalars' value marks and targets in CanvasText, scale ticks in GrayText.

• Host keys charts.contextMenu.replayAnimation, charts.contextMenu.replayReducedMotion, charts.contextMenu.replayAnimationOff, charts.scalar.namedTarget, charts.scalar.aboveScale, charts.scalar.belowScale, charts.accessibility.targetPlain, charts.accessibility.namedTarget, charts.accessibility.namedTargetPlain, charts.accessibility.scalarValueAbove, charts.accessibility.scalarValueBelow.

Changed (scalar scales and targets, ADR-100)#

• target on LinearGaugeProps and BulletChartProps moved to ScalarChartProps and widened from number to ScalarTarget (number | {value, label?}). Code that passes a number is unchanged; code that reads the prop as a number needs a narrowing (MIGRATION-NOTES).

Fixed (scalar scales and targets, ADR-100)#

• A target of 0 was missing from a scalar's accessible name (T7-X1).

• A target that is not a finite number was drawn at NaN coordinates and stated as "NaN"; it is now neither drawn nor stated, and reported (T7-X2).

• A value beyond the scale read "(100%)" or "(0%)" in the accessible name; it now reads "above the range" or "below the range" without a share (T7-X3).

• "% of target" was stated for a negative target or a value of the other sign; it is stated only where it means something (T7-X4).

• The documentation said a scalar has no context menu; it has one that exports (T7-X5).

Added (hierarchy and flow, ADR-099, 2026-10-06)#

• One label policy on TreemapChart and SunburstChart: label (HierarchyLabelOptions): secondary ('share', 'value' in the chart's valueSemantics, 'none'; treemap default 'share', sunburst 'none') and levels (the levels that draw text, counted from the shown root). Visual only; every reader keeps every name and value.

• Sankey: nodeAlignment ('justify' default, 'source', 'sink', 'center'), linkColor ('source' default, 'target', 'gradient', also in SVG, PNG and PDF) and nodeOrder ('auto' default, 'input').

• Org chart: collapsible with collapsedIds (controlled), defaultCollapsedIds (uncontrolled) and onCollapsedChange (OrgCollapseChange); a count badge, Enter and Space, and the menu items Collapse, Expand and Expand all below; cardFields (OrgCardField, at most three meta fields per card, default the title).

• Host keys charts.contextMenu.collapse, charts.contextMenu.expand, charts.contextMenu.expandAllBelow, charts.org.collapsedState, charts.org.expandedState, charts.org.collapsedView.

Fixed (hierarchy and flow, ADR-099)#

• A treemap with groups started 23 px below the top of its plot: the shown root reserved a header band but draws no header (CH-34). Only a group that draws a header reserves one now; the tiles use the space.

• A treemap with three or more levels reserved an empty header band on every nested group and drew no header there; every internal node now draws its header (N3). A nested group also had no drawn element behind its keyboard focus.

• A drilled treemap or sunburst kept drawing the old tree after the host replaced it; the drill path is now held by node identity (N2).

• The sankey keyboard grouped nodes by their distance from the sources instead of the column they are drawn in, and stepped them in input order; it now walks the drawn columns top to bottom (N1). The data table keeps the order of the links.

Added (quantitative scales, ADR-098, 2026-10-05)#

• One quantitative colour scale QuantitativeColorScale (LinearColorScale with its own colors, StopsColorScale/ColorStop, ClassesColorScale/ColorClass) and ColorLegendOptions, shared by the heatmap, the treemap and the sunburst.

• Colour by measure on TreemapChart and SunburstChart: colorMeasure (ColorMeasureOptions: label, scale, valueSemantics, legend) and the node field HierarchyNode.colorValue; a colour key with the measure's name; the measure in the tooltip, a table column, the announcement, the description and the CSV (colorValue).

• Bubble size: sizeDomain and sizeName on scatter series and ScatterChart; the opt-in size key sizeLegend on ScatterChart and ChartOptions; a size column in the data table.

• Heatmap axes: xAxis and yAxis (HeatmapAxisConfig: title, formatter, temporalSemantic, order, reversed, wrap, autoRotate).

• Host keys charts.scale.noValue, charts.scale.measureValue, charts.scale.valueWithMeasure, charts.scale.size, charts.scale.sizeClampedBelow, charts.scale.sizeClampedAbove; tooltip fields colorMeasure, sizeName, sizeMissing.

Changed (quantitative scales, ADR-098) — BREAKING#

• HeatmapColorScaleOptions, HeatmapLinearColorScaleOptions, HeatmapStopsColorScaleOptions, HeatmapClassesColorScaleOptions, HeatmapColorStop, HeatmapColorClass and GradientLegendOptions are replaced by the neutral names (no alias); HeatmapSeriesOptions is no longer exported.

• HeatmapChart.colorRange is removed: the colours are the linear scale's colorScale.colors. HeatmapChart.gradientLegend is renamed colorLegend.

• The heatmap's row gutter and column band are measured (no fixed 80 px): long labels wrap, turn or are cut with their full name, never overflow. With a name, the colour key carries it as a caption.

• A bubble's size domain is the full data, not the zoomed, reduced or grouped window; a bubble without a finite size is drawn at its marker size (it was drawn at the middle radius).

Fixed (quantitative scales, ADR-098)#

• A bubble kept changing its radius while the reader zoomed or panned.

• A NaN or infinite size drew an invalid circle radius.

• The bubble size never reached the data table.

• Under forced colours the heatmap's gradient kept its authored hue while every cell collapsed to Canvas.

• <Chart>'s screen-reader table re-rendered every row on every pointer move (30 moves over 10,000 points: 11.9 s → 0.47 s in the development bundle).

Added (waterfall subtotals, ADR-097, 2026-10-05)#

• Floating subtotals on the waterfall: a row of kind 'subtotal' runs from the balance at the previous subtotal or total to the current balance and states the net movement since then; a 'total' stands on zero at any position. One role field, kindKey (WaterfallStepKind: 'change', 'subtotal', 'total'), on WaterfallChart and WaterfallSeriesOptions.

• The label formatter context carries stepKind on a waterfall label.

• The data table names each waterfall bar's kind in its own column (host key charts.accessibility.stepKind); CSV and copy-as-table carry the raw kindKey column.

• Development diagnostics for an unknown kind, a summary row whose own value differs from the derived amount, and a non-finite change.

Changed (waterfall kinds, ADR-097) — BREAKING#

• totalKey and totalIndices are removed (no alias); use kindKey.

• SingleTooltipData.waterfall.isTotal is replaced by kind; its value and the tooltip's yValue are the amount the bar draws.

• A change without a value draws no bar (it drew a zero-height bar).

Fixed (waterfall, ADR-097)#

• The tooltip, the keyboard announcement and the table no longer disagree on a summary's word, and the word no longer depends on whether the row is the last of the zoom window.

• The crosshair guide of a negative total stands at its balance, not on the zero edge, where its readout already was.

• A NaN or infinite change no longer removes every later bar.

• A summary row is a pointer and keyboard stop whatever its own value field holds (hit points stand at each bar's balance), and Copy value copies the drawn amount.

• On a reversed value axis every waterfall bar is drawn at its values; it was shifted down by its own height.

• Forced colours paint a subtotal GrayText, like a total.

Added (Cartesian overlays: error bars, soft bounds, zones, ADR-096, 2026-10-05)#

• Error bars on line, scatter and bar (errorBars: {lowKey, highKey}, ErrorBarOptions; scatter also xLowKey/xHighKey, ScatterErrorBarOptions), on <Chart> and the LineChart, ScatterChart and BarChart series configs. Absolute bound fields; a stem and caps in neutral foreground ink; an end the domain or a log axis cannot show runs open to the plot edge. The bounds join the automatic domain and are read in every tooltip mode, the data table, the keyboard announcement, CSV and copy-as-table. Custom renderers receive errorBounds / xErrorBounds (TooltipErrorBounds).

• Soft axis bounds (softMin/softMax on numeric axes): the automatic domain reaches at least to them, never narrowing the data.

• Zones on line and area (zones: {axis?, ranges}, SeriesZones, ZoneRange, LineZoneRange, ZoneBoundary): the paint split by ranges of y or x where the drawn path crosses a boundary; an area's fill split by region; a named zone in tooltip (zone), table and announcement.

• Host keys charts.errorBar.range, charts.errorBar.lowerOnly, charts.errorBar.upperOnly, charts.errorBar.xValue, charts.tooltip.zone.

• One internal domain contribution model (DomainContribution).

Changed (Cartesian overlays, ADR-096)#

• Breaking: the Bar's errorBars.stroke, errorBars.strokeWidth and errorBars.capLength are removed (no alias). See the migration notes.

• A bar's error bar draws in neutral foreground ink instead of the series colour (its lower half was invisible inside its own bar, EB-3).

• A series with error bars is never reduced and blocks time grouping (the bar's bounds were summed, EB-4).

• The BarChart wrapper no longer injects a tooltip valueFormatter; the bounds come from the tooltip data on every route, and a host formatter writes all three numbers instead of silencing the range (EB-2).

Fixed (Cartesian overlays, ADR-096)#

• CSV and copy-as-table carry the error-bound columns (EB-1).

• One bound a log axis cannot show no longer erases the valid side (EB-5).

• An outside bar label and a point label sit beyond their whisker (EB-6, confirmed in Firefox).

Fixed (radial sweep entrance in every engine, ADR-095 amendment, 2026-10-05)#

• Fixed (sweep entrance, Firefox): the radial sweep of RadialBarChart, GaugeChart, NightingaleChart, SunburstChart and RadarChart turned about a point beside the pivot in Firefox (up to 95 px on a half dial; the rings and roses appeared cut, the dial skewed). The reveal is now an SVG mask in the swept group's own coordinates, about the pivot each family passes explicitly, and measures the same in Chromium and Firefox: on the pivot, from the resolved start, clockwise, the domain's share at every moment of the duration.

• Changed (internal): the CSS conic-gradient mask, its registered properties --ac-sweep-angle/--ac-sweep-open and the inline --ac-sweep-from/--ac-sweep-share/--ac-sweep-duration/ --ac-sweep-easing are gone (undocumented, read by no consumer); the transient frame circle is replaced by a transient mask. When the reveal ends the mask and the group's mask reference are removed, so a chart at rest carries no animation helper; an export taken mid-sweep leaves both out. Reduced motion draws no mask, as before.

• No public API changed. Resting geometry and every visual baseline are unchanged; the seven visual--donut-legend-* baselines updated in T2B (callout leaders on the drawn slice's middle) are reviewed and accepted.

Changed (one radial angle convention, ADR-095, 2026-10-05) — BREAKING#

One radial clock: degrees, clockwise from 12 o'clock, a domain as startAngle + endAngle. Default charts draw exactly as before. Migration: migration/MIGRATION-NOTES.md.

• Breaking (RadialBarChart): startAngle counts from 12 o'clock (was 3 o'clock; default 0, was -90, same rings). maxAngle is removed; endAngle (default startAngle + 360) is where the tracks end. No alias.

• Breaking (PieChart, NightingaleChart): padAngle is degrees (was radians); the defaults are exactly the former quantities.

• Changed (GaugeChart): a reversed, empty or full-circle pair draws the default dial and reports a diagnostic (it drew a malformed or empty arc); a startAngle alone keeps the 270° dial.

• Added: PieChart.startAngle and NightingaleChart.startAngle (default 0; whole chart).

• Added (diagnostics): an invalid radial angle (not finite, a sweep of 0° or less, more than one turn) is reported once through the host sink (ADR-076); the family default is drawn, and no NaN reaches a path.

• Fixed (sweep entrance): a partial domain is revealed over the whole duration (it finished at the domain's share of it) and the mask is centred on the pivot (it was centred on the swept group's box, up to 95 px off on a half dial). The Gauge now uses the shared radial entrance.

• Fixed (Pie): one slice-angle model for the slices, sector labels, callouts, keyboard cue and menu point and the tooltip anchor. The callouts and anchors used a second walk that shared the pad differently from the drawn slices; their leaders now leave the drawn slice's middle exactly (they sat off it by up to half the pad times the slice count: 0.92° on a five-slice allocation with the default pad).

• Removed (internal): the unexported core/shapes/pie.tsx (Pie), whose only reader now draws from the slice model.

Added (per-datum paint on more families, ADR-094, 2026-10-05)#

Additive public API (ADR-029). Without a resolver every chart draws what it drew.

• Added (paint on six more families): the BC4 per-datum paint resolver (DatumPaintResolver, fill only) on the lollipop series (the head; the stick follows it unless stickStroke is set), the range-bar series (the interval; context value is the high end), the dumbbell series (each end separately), and on FunnelChart, RadialBarChart and NightingaleChart (the item is its legend category, so its key, the radial name-column key and the export legend show the paint; a funnel key shows the stage as drawn). Tooltip swatch, export, label contrast and forced colours follow, as on bar and pie.

• Added (DatumPaintContext.role?: ChartValueRole): the part of a mark painted part by part; a dumbbell's resolver is asked once per end with role: 'low' or 'high' and that end's value. The connector keeps the series stroke.

• Changed (funnel legend): a hidden stage's key keeps its own (painted or palette) colour instead of falling back to the palette.

Fixed (truth corrections, ADR-093 amendment, 2026-10-05)#

• Fixed (CH-28): under forced colours a rising candle is hollow and a falling one filled, with solid wicks (the rules pointed at test ids that no longer existed), and range bars take the bar series' system colours, their legend keys too.

• Fixed (CH-29): the crosshair's value readout on a stacked bar or area segment names the stack's sum through the segment, and on a waterfall step its running balance: what the axis reads where the guide stands. On a reversed value axis the tooltip and crosshair anchor stands at the bar's value end (it stood at its start).

• Fixed (CH-32): sankey node and link DOM ids encode the host id (spaces, punctuation, any script) injectively, so every aria-activedescendant resolves; the host id itself is unchanged.

Fixed (truth and defect corrections, ADR-093, 2026-10-05)#

Corrections of existing promises; one additive field (Sparkline.accessibility). No new capability, no family feature.

• Fixed (CH-7, zoom follows the scale): drag selection, wheel, pan, pinch and the navigator read pixels through the x scale: a reversed axis zooms the part under the pointer (it zoomed the mirrored part), a drag on an uneven continuous axis selects exactly the rows inside it, and the navigator follows reversed. An xy drag picks the band shown on a log or reversed y axis. Changed meaning (fix): the y fractions of onZoomChange and setZoom are positions on the plot from its bottom edge, read through each y scale; on a linear axis that is not reversed nothing changes, on a log or reversed axis they now name the band shown. The x fractions stay row fractions of the full data.

• Fixed (CH-8): a pinned tooltip stays on the host row it was pinned on across zoom, pan, reduction, grouping and rerender (it showed the row at the same window position); it clears under the existing policy.

• Fixed (CH-12): a lone explicit min at or above every value (or max at or below every value) no longer turns the axis around: it is ignored with a diagnostic and the axis spans the data. A non-finite min or max shows the unavailable state with a diagnostic (W12).

• Fixed (radar): a missing or non-finite value is a gap (no vertex, edge or fill), never 0; the table, the announcement and the keyboard readout say "(no value)". Without min/max the scale follows the visible data (with zero, round ring steps) instead of a fixed 0 to 10 that clamped real values silently; beyond an explicit bound a value keeps its true number, with ≥/≤ on the scale and in the description (W-CF-3). New host keys charts.scale.axisClampedBelow and charts.scale.axisClampedAbove.

• Fixed (CH-20): RadarChart no longer takes a fixed 30 px of height for a legend above or below; the legend adds its measured rows, as on the other categorical families.

• Fixed (shared tooltip): a row without a value in <Chart>'s shared tooltip reads "(no value)" instead of a blank.

• Fixed (CH-24): without stackGroup, a stack beside an unstacked bar takes its own column instead of filling the band under the bar (the column rule of ADR-091 now holds without a declared group).

• Fixed (CH-25): a stack total or an area value that would print on a bar it does not belong to is hidden; its value stays in the tooltip, table and announcement.

• Fixed (CH-26): under forced colours bars, histogram bins and waterfall steps take their system colours (the rules targeted rect; the marks are paths), and a bar's legend key takes its bar's colour.

• Fixed (CH-27, Walt's decision): under forced colours a classed heatmap's legend swatches collapse with the cells, a missing cell keeps no edge, and the class stays a name in the legend, tooltip, table and announcement, with the current cell's class marked in Highlight.

• Fixed (LAB-AT4): each crosshair guide passes through what its readout names: a horizontal series reads its value on x and its category on y (they were swapped); a compound glyph's value guide crosses the high end, the median or the close its readout names; a histogram bin reads as its interval.

• Fixed (CH-10): a scalar's accessible name reads its range when min is not 0 ("0 in the range −50 to 50", new host key charts.accessibility.scalarValueInRange), never "0 of 50"; a missing pie, funnel, nightingale or radial-bar value reads "(no value)" in the announcement, value cell and share cell, never 0; two treemap, sunburst or org-chart siblings with one label are two reachable nodes with their own DOM id (the key is the host id or the sibling position, not the label); an empty or blank accessibility.label is no name on any family, <Chart> included, so no chart carries an empty name. Changed (DOM ids): hierarchy item ids now encode the node key (e.g. …-n0.n2), not the label.

• Fixed (CH-11): treemap, sunburst and org-chart paths isolate each label, join with → (ltr) or ← (rtl) and open with a direction mark, in the tooltip and the table; the treemap breadcrumb separator points to the inline end under rtl (it was mirrored twice).

• Added (Sparkline.accessibility): accessibility={{label}} (Pick<AccessibilityOptions, 'label'>) makes a sparkline one image with that name; without a name it is decorative and hidden from assistive technology (aria-hidden).

• Proven (QR-2): OHLC, box plot, range area and range bar name and toggle their series in the legend, and the exported legend draws the screen's key and name (browser, Chromium and Firefox).

Added (per-datum paint and quantitative colour, ADR-092, 2026-10-05)#

Additive public API (ADR-029). Without the new forms and resolvers every chart draws what it drew.

• Added (HeatmapColorScaleOptions forms): the type is now the union of HeatmapLinearColorScaleOptions (the former shape, unchanged), HeatmapStopsColorScaleOptions (type: 'stops', HeatmapColorStop[]: colours at values, the first and last stop are the ends) and HeatmapClassesColorScaleOptions (type: 'classes', HeatmapColorClass[]: named [from, to) ranges with a class legend; the class is named in the tooltip, the data table, the announcement and the description). A value in no class is drawn neutral and named; a missing value stays empty. Malformed stops and classes, overlaps, values in no class and an unused colorRange are reported.

• Added (per-datum paint): paint on bar and scatter series (and BarChartSeriesConfig, ScatterChartSeriesConfig), marker.paint on line and area series, and paint on PieChart: a bounded resolver (DatumPaintResolver, DatumPaintContext, DatumFill, DatumPaint) that returns paint only. The mark, its inside-label contrast, its tooltip swatch and its export follow the result; forced colours override it; a series legend keeps the series colour (a pie key follows its slice). Other returned fields, a non-colour and a throwing resolver are reported and fall back to the series paint.

• Added (tooltip): SingleTooltipData.colorClass, the class row of the default tooltip.

• Translations: charts.scale.classes, classRange, classFrom, classBelow, outside, valueInClass and charts.tooltip.colorClass, in every available language.

Fixed (label collision per plot, ADR-091 amendment, 2026-10-05)#

• Fixed (NEW-01): the value labels of several area series and the plot's stack totals take one collision decision: a label no longer prints over a label of another series or over a total. The totals come first, then the areas in series order; a value that gives way stays in the tooltip, the data table, the announcement and the CSV, and an export draws the same kept labels. No API change.

• Docs: API.md § 3.1 no longer says area, range, dumbbell and lollipop wrappers take no label; the § 10.8 example compiles again.

Added and fixed (Cartesian labels and stacks, ADR-091, 2026-10-04)#

Additive public API (ADR-029). Without the new options every chart draws what it drew.

• Fixed (CH-23): the export legend draws a line key with the series' dash pattern (explicit lineDash or the automatic second encoding), at the painted key's length; SVG, PNG and PDF. LegendExportItem.dash.

• Added (stackGroup): on bar and area series (<Chart>; BarChartSeriesConfig, AreaChartSeriesConfig). Implies stacking. Bar groups stand side by side in the category, each with its own baseline, percentage base, tooltip total and stack total; area groups stack from their own baselines.

• Added (stackTotal, StackTotalOptions, StackTotalFormatterContext): one total per stack and category on bar series (<Chart>; BarChart): the net total of the visible members, beyond the end its sign points to. None on a percentage stack. The data table gains a total column and the keyboard announcement names the total.

• Added (label roles): label on area and lollipop series and wrappers (PointLabelOptions); label: EndpointLabelOptions (endpoints: 'both' | 'low' | 'high') on range bar, range area and dumbbell series and wrappers. LabelFormatterContext.role names the end. Off by default.

• Added (wrap): AxisConfig.wrap and AxisOptions.label.wrap on a category axis: names wrap into at most that many lines before they rotate or are cut; the full name stays the <title>. Default 1. On a vertical category axis it caps the existing gutter wrap. TimeAxisConfig, NumberAxisConfig and the upright value axis config do not take it.

• Changed (only with the new options): an automatic value domain keeps room for a stack total or an outside value label at the end it points to, so the label at the domain's extreme is drawn rather than hidden.

Added and changed (marker shapes and legend reading order, ADR-090, 2026-10-04)#

Additive public API (ADR-029) and three changed defaults that change visual baselines where they apply.

• Added (MarkerShape): one bounded marker vocabulary, 'circle' | 'square' | 'diamond' | 'triangle' | 'triangle-down', exported from the root. MarkerOptions.shape on line and area markers (<Chart> and the wrappers); marker.shape on scatter and bubble points (ScatterChart series and <Chart> scatter series); markerShape on LollipopChart (chart and per series), DumbbellChart and their <Chart> series; marker.shape on RadarChart series. Every shape has the area of the circle of the same size. The legend key, the tooltip key, the emphasised node, the keyboard cue, every export and forced colours follow it.

• Changed (TimelineChart.marker): takes the whole vocabulary instead of 'circle' | 'diamond'. An explicit 'diamond' is now the equal-area diamond of the vocabulary: about a quarter wider than the inscribed diamond it was, and the timeline layout reserves its reach.

• Changed (default, automatic shapes): a point series whose colour does not keep it apart (from the seventh default palette slot, or where a host palette repeats; the trigger of the dash pattern, ADR-038) draws a marker shape. A chart of six or fewer distinctly coloured series is unchanged. An explicit shape always wins.

• Added (legend.align): 'start' | 'center' | 'end' along the side, logical under rtl; the default is the old alignment (center above or below, start beside). The export legend follows.

• Changed (default, stack reading): the legend and the shared tooltip of a stacked bar or area list the stack's members in the order the eye meets their segments (the top segment of a vertical stack first). No option. A chart without a stack keeps the series order. Legend entries now carry data-legend-series (the series they toggle) beside data-legend-item (their position).

• Changed (default, narrow side legend): a legend at left or right stands below the chart where beside it the chart would keep less than 240 px, and returns when the room returns. The export carries it where it is drawn. A side column is as wide as its widest entry; its names no longer wrap (closes CH-16).

• Fixed: an export handle kept from an earlier render exported the composition of that render; every handle now runs the latest export work, as the context menu already did.

Changed (default label text and pie tooltip rows follow value semantics, ADR-089, 2026-10-04)#

Two default texts now follow the value semantics. No new API.

• Changed (data labels): a bar, waterfall, line, scatter or histogram label without formatter or format writes the series' value semantics (its own, else its y axis'), in the chart's presentation, as the axis, tooltip and table already did. Without a declaration it stays the plain number; a percentage stack keeps its share labels. Placement and collision are unchanged.

• Changed (tooltip): the pie tooltip always states the value and the share on two rows; the share is a percentage (61.7%) with or without valueSemantics, never a bare number. tooltip.valueFormatter writes the value row of the pie and funnel tooltips and no longer reaches their share row. CSV and Copy value stay raw.

Added (value semantics and wrapper configuration, ADR-089, 2026-10-04)#

Value meaning on every numeric family and wrapper parity with <Chart>. Additive: no member changes meaning and no consumer migrates. See DECISIONS.md ADR-089 and API.md § 3.1, § 10.6.

• Added (value semantics): valueSemantics (ChartValueSemantics, the Cartesian type) on PieChart, FunnelChart, NightingaleChart, RadialBarChart, RadarChart, HeatmapChart, TreemapChart, SunburstChart, SankeyChart and ScalarChartProps (GaugeChart, LinearGauge, BulletChart). Labels, scales, readouts, tooltips, data tables and announcements write a value in it; a role's own formatter or format and tooltip.valueFormatter still win; a share stays a percentage; CSV and Copy value stay raw. Without it every text is as before.

• Added (wrappers): label (PointLabelOptions) on LineChart, ScatterChart and Histogram; visible and showInLegend on the series configs of LineChart, AreaChart, BarChart, ScatterChart and LollipopChart; annotations on every Cartesian wrapper, on BarChart, DumbbellChart, LollipopChart and RangeBarChart only while upright.

• Changed (types, compatible): horizontal of BarChart and DumbbellChart moved into an orientation union, as on LollipopChart and RangeBarChart; every existing call, a computed boolean included, still compiles.

• Changed (tooltip): with valueSemantics the pie tooltip states the value and the share on two rows; without it, unchanged.

Changed (unified context menu, ADR-087, ADR-088, 2026-10-04)#

One context menu across the Active product family (CM1–CM6). Breaking type changes, with a migration note in migration/MIGRATION-NOTES.md. See DECISIONS.md ADR-087.

• Changed (renderer): every chart except the Sparkline renders its menu with the Base UI menu the Active Grid uses (@base-ui/react is a new dependency). The package's own popup, useStandaloneContextMenu, useContextMenuItems and useLongPress are gone.

• Changed (types): ContextMenuItem and ContextMenuOptions are removed. New: ChartContextMenuOptions, ChartContextMenuItem (the Grid vocabulary: label, action, icon, variant, disabled, disabledReason, shortcut, keepOpen, visible, separatorBefore, children, 'separator'), ChartContextMenuBuilder, ChartContextMenuContext, ChartContextMenuTarget, ChartContextMenuFeatures, ChartLegendItemRef. items is a builder that receives one frozen context per opening.

• Added: host items first; a legend entry is a target (Hide or Show, Show only this, Show all); Copy value(s) on an element and Copy as table on the chart; disabled items with a reason; features switches the chart's own groups off; trigger: 'button' adds a visible menu button; the scalars have an export-only menu; every family announces the opening (closes CH-5); items are at least 44 px high under a coarse pointer.

• Removed: Zoom here and Pan here (Reset zoom stays); the translation keys charts.contextMenu.zoomHere and charts.contextMenu.panHere.

• Added (translation keys): copyValues, hide, show, showOnly, showAll, label, labelFor, notZoomed, allShown, lastVisible, noValue under charts.contextMenu.

• Added (token): the host role --radius, from which the menu derives its corner radius.

• Fixed (PDF, ADR-088): a PDF export draws the whole chart: the export clone always carries a viewBox, so a wide chart is scaled into the page instead of clipped on the right.

Changed (handle contract, ADR-086, 2026-10-04)#

• Changed (type, A4): setZoom exists only on ChartHandle, the handle of <Chart> and the Cartesian wrappers. Every other family (pie, heatmap, the categorical, hierarchical, graph and scalar families, timeline, sparkline) exposes the new base ChartExportHandle (exports and element access), and its runtime handle no longer carries a no-op setZoom. A ChartHandle ref still fits those charts. Supersedes ADR-085 point 4.

• Docs: the audit report under reviews/ (deleted 2026-10-07) is Prettier-formatted (whitespace only).

Fixed and narrowed (labels, export routes and public options, ADR-085, 2026-10-03)#

The one correction tranche after the independent audit reviews/ACTIVE-CHARTS-COMPREHENSIVE-FINAL-AUDIT-2026-10-03.md (deleted 2026-10-07). A public option works on its family or leaves its type (W10, ADR-082); no new capability. Breaking type changes, each with a migration note in migration/MIGRATION-NOTES.md. See DECISIONS.md ADR-085.

• Fixed (value truth, NEW-01, NEW-02): GaugeChart, LinearGauge and BulletChart rest on the semantic value in every animation mode. With count-up the readout ended on the value clamped to the scale (150 on 0–100 read 100) and rounded to two decimals (1.234 read 1.23); it now ends on value itself, as with animation: false, reduced motion and zero duration. The geometry still clamps to the scale; readout and accessible name agree.

• Fixed (CH-18): LinearGauge and BulletChart count up from min on the package ease-out, as the gauge needle (ADR-084): no wait at the start on a scale that does not start at 0.

• Fixed (export, LAB-AT12, LAB-AT18, CH-17): the context menu runs the handle's composed exports. A menu PNG, SVG or PDF carries the same legend on the same side as a handle export, on <Chart> and on every standalone family; the standalone menu writes its PNG at contextMenu.pngScale and offers CSV. A <Chart> side legend is exported beside the plot. The exported legend uses the screen's entries: a dumbbell's two endpoints, a tile for a shape series, the value key as the name where name is absent.

• Fixed (legend, LAB-AT24): FunnelChart, RadarChart, RadialBarChart and NightingaleChart draw a left/right legend, isolate an entry on a double click and export their legend.

• Fixed (AT8): a waterfall, candlestick or OHLC series has a neutral legend key instead of a palette colour that matched no mark.

• Fixed (tooltip, LAB-AT6): split cards honour tooltip.style and tooltip.valueFormatter; a shared or split row is read at the addressed x (a scatter series without a point there is not listed); a chart of only ranges, box plots or bins shows its single card instead of an empty one.

• Fixed (crosshair, LAB-AT4): the y readout uses the series value semantics, the notation of the tooltip, instead of two fixed decimals.

• Fixed (histogram, LAB-AT11): a selected bin stays selected (the selection was pruned unless a row lay exactly on the bin's bound); an explicit yAxis.min/max is honoured and a negative sum or mean reaches below zero; a sum or mean without yKey draws counts and says so.

• Fixed (motion, LAB-AT10): animation.update.easing reaches bar and histogram updates (the JavaScript transition ignored it); a range area enters with fade by default (its declared draw-x had no band renderer).

• Fixed (time axis, LAB-AT14): a parentLevel row groups by the unit it names: one "2025" under a year of daily ticks, not one per month.

• Fixed (marks, LAB-AT15): an inside label longer than its bar or waterfall step along the value direction moves outside (or hides) under fallback: 'auto'; a box plot outlier on the axis extreme is drawn whole.

• Fixed (radial bar, LAB-AT25, CH-19): the sweep entrance starts where the rings start (it began a quarter turn early); a value past max fills its track and keeps its true number; the name, key and value columns stand from the first frame instead of being revealed by the sweep.

• Fixed (navigation, LAB-AT20, LAB-AT22): the org chart's wheel zooms without also scrolling the page, and only while its zoom controls show; an image or PDF of a partial org view carries its note in the caption. The timeline pans only as far as its content, and keyboard focus brings its event into view.

• Fixed (CH-10): closing a context menu returns focus to the chart; the scalars' descriptions no longer promise arrow-key navigation.

• Fixed (LAB-AT19, LAB-AT23): a sankey node's value sizes the node (it was overwritten by the flow sum); Sparkline delivers a replaced onExportComplete, onExportError or onReady (its memo comparator kept the first); its bare-<svg> root and getContainerElement() returning null stay, now documented on the handle.

• Changed (LAB-AT7): with several yAxisIds, the yAxis of LineChart, AreaChart and ScatterChart configures the first axis only; a further axis is a plain number axis on the opposite side (title, range and formatter were copied to every axis).

• Changed (LAB-AT16): ChartHandle.setZoom on a chart without a data-range zoom reports the no-op through the chart diagnostics.

• Removed from types (no reader): CrosshairOptions.snap; per-series description and tooltip; label.position on line, scatter and histogram series; tooltip.mode other than 'single' on range area, range bar, box plot and histogram; yAxis.autoRotate/parentLevel on an upright value axis; lollipop series[].yAxisId; colors on waterfall, candlestick and OHLC; navigator on dumbbell, waterfall and a horizontal lollipop or range bar; animation.update on dumbbell, lollipop, box plot, range bar and range area; draw-x for a range area; range-area dataGrouping.approximation; histogram selection.itemKey, a category or time x axis and a sum or mean without yKey; the standalone tooltip's mode, snapDistance, pin (and valueFormatter on org chart and timeline) and animation's stagger, update, layers, exit; accessibility.announcements on the standalone families; NodeDatum.group; showLastPoint on a bar sparkline.

• Docs (LAB-AT13, LAB-AT21): contract text that contradicted the runtime (animation defaults 400 ms and 30 ms, waterfall corner radius, dumbbell and lollipop connector paint, rising candle close ≥ open, MACD without a histogram, radial startAngle, linear gauge sweep, scalar colors, standalone name, hierarchy meta).

Fixed (radial bar scale beside its columns, gauge needle motion, ADR-084, 2026-10-03)#

Two visual corrections found on the chart reference before the audit. No API change. See DECISIONS.md ADR-084 and QUALITY-BUDGETS.md § 7.

• Fixed: RadialBarChart no longer drops the scale label that falls in its name or value column's band (the 30 at nine o'clock of the reference allocation, which left a bare tick beside the first key). A column starts past the scale label its rows would meet, plus 6 px; a side without a column keeps its labels inside the frame. The rings stay centred in the room that remains.

• Fixed: GaugeChart's count-up starts at min, not at 0. On a scale that does not start at 0 the needle stood still for up to 40 % of the entrance while the readout counted through values off the scale, then swung late and fast. The needle and the readout move together from the first frame on the package's CSS ease-out (was a steeper cubic) within the unchanged 400 ms; an update moves on from the resting angle; reduced motion draws the final state at once.

• Tests: e2e/reference-corrections.spec.ts (new, scenarios ref/); baselines vq5-rest-radial-* and fv0-capture-* updated for the radial bar only.

Changed and fixed (legend in a pie export, legend height by side, ADR-083, 2026-10-03)#

Closes ROADMAP LAB-AT3. See API.md § 1, § 3.1, § 5, § 10 and migration/MIGRATION-NOTES.md.

• Fixed: a PieChart image export (PNG, SVG, PDF) carries its legend on the side it is drawn: the same entries and order, each slice's drawn colour, a hidden slice dimmed, every entry also when the painted legend is folded, no preview. includeLegend now applies to the pie.

• Added: LegendExportOptions.position takes 'left' and 'right': one column beside the chart, mirrored under rtl. top and bottom are unchanged; <Chart> still exports its legend under the plot.

• Changed: the default of LegendOptions.maxHeight depends on the side: 25 % of the chart height above or below the chart (unchanged), the chart height beside it (was 25 %). An explicit maxHeight wins on every side.

• Fixed: the default applies on PieChart, FunnelChart, NightingaleChart, RadarChart and RadialBarChart, which had no default cap; an explicit maxHeight already worked there.

Changed and fixed (API truth on PieChart and HeatmapChart, ADR-082, 2026-10-03)#

Found by the chart reference in UI Lab (ADR-081, LAB2). See API.md § 3.1, § 3.2 and migration/MIGRATION-NOTES.md.

• Narrowed (types only, no runtime change): the tooltip of PieChart and HeatmapChart no longer accepts mode, snapDistance or pin; their animation no longer accepts stagger, update, layers or exit, and the pie's no longer accepts type. Neither family ever read them.

• Fixed: PieChart draws its legend on the left and right, in one row with the pie, which takes the width the legend leaves; it drew no legend at all there before. Top and bottom are unchanged.

• Fixed: a double click on a pie legend entry isolates its slice, as LegendOptions.isolate promises; the pie did not pass it on before.

Fixed (gallery findings, ADR-080, 2026-10-03)#

No public type changes. See API.md § 2 (Automatic value domains) and § 10.4.

• Pie and donut callouts stay inside the chart. The centred pie now gives each side room for the wider callout column; a long name on one side (for example "Government bonds" beside "Equity" at 438 px) no longer runs past the chart edge. Charts with callouts of unequal width draw their pie a few pixels smaller at narrow widths.

• A box plot's outliers are inside its value domain. outliersKey now spans the automatic domain, so an outlier beyond the whiskers is drawn instead of being clipped away while the tooltip names it.

Fixed (label contrast, radial rows and heatmap scale side, ADR-079, 2026-10-02)#

No public type changes. See API.md § 1 (Text on marks), § 10 and § 10.5.

• Label contrast on real paint (N1). Inside labels and label-safe surfaces now measure the colour the browser paints in the chart's scope: tokens inside color-mix() or other functions, alias chains of any depth, and translucent paint composed over the chart's background. A colour the browser cannot resolve is unknown paint and no longer counts as readable: the label goes outside or is hidden. Affects bar, waterfall, pie and donut sector labels, funnel, treemap, sunburst and heatmap labels.

• Label background (N2). A bar or waterfall label background is a surface only through its fill; a border-only background no longer lets an unreadable inside label through.

• Heatmap scale at extreme magnitudes (N3). Positions and the repaired centre stay finite for every finite domain (-1e308 … 1e308).

• Radial Bar name rows (N4, revised 2026-10-03). Name and value rows never overprint: closer than a text line they are thinned at one regular step, outermost first, as Highcharts and AG Charts thin a crowded category axis; the rings never change for it. The value column is left out before any ring is. Each drawn name carries a small key in its ring's colour.

• Radial Bar pointer. Moving across the rings no longer returns the chart to rest in the gaps between them: each ring owns its band to the middle of the gaps (an unpainted hit band).

• Tooltip beside grouped bars. The card is placed beside the category's group, so neighbouring bars keep one side; it changes side only where the group's side cannot hold it.

• Radial Bar colour keys stand in one straight column between the names and the rings.

• Radial Bar tooltip under the pointer stands beside the pointer, towards the centre first, never over the addressed ring, and keeps its side from ring to ring; it no longer jumps to the quadrant of each ring's arc.

• Heatmap tooltip keeps its side from cell to cell while that side fits, instead of taking the first side that fits each cell. In a heatmap too short for the card to stay above or below its cells through a vertical move, the card stands beside the cell first (right, then left), so moving down a column no longer flips it across the pointer.

• gradientLegend.position: 'right' (N5). Now honoured: a vertical scale beside the matrix, which gives up the width; exported in place. 'bottom' (default) unchanged.

• Tests: the four W12 browser cases assert the host diagnostics sink (ADR-076) instead of console text.

Added (configuration: bar width, label fallback, pie roles, heatmap scale, ADR-078, 2026-10-02)#

Additive public options, decided by Walt (W-CF-1 … W-CF-3); no existing member changes meaning. See API.md § 10.2–10.5.

• Bar sizing. widthRatio (share of the category step, 0.1 … 1) and maxWidth (CSS px; Infinity allowed) on BarSeriesOptions, WaterfallSeriesOptions, RangeBarSeriesOptions and the BarChart, WaterfallChart and RangeBarChart props (BarSizingOptions). Bars shrink, never overflow; the bars of one category are sized as one centred group; the first declaring bar series decides for the group, and a disagreement is reported once.

• Label fallback. LabelOptions.fallback: 'auto' | 'hide' (default 'auto'): with position as the preferred place, 'auto' keeps the family's alternative and 'hide' keeps the preferred place only.

• Formatter context. LabelOptions.formatter(value, context?) receives {datum, seriesId, seriesName} (LabelFormatterContext) on bar, waterfall, line and scatter labels. One-argument formatters are unchanged.

• Pie and donut roles. dataLabels (the callout) takes name, value and minAngle beside percentage (PieCalloutLabelOptions); new sectorLabels puts one line inside each slice (PieSectorLabelOptions: percentage by default, value, name, formatter, format, minAngle). A sector label shows where it fits and reads, else it is hidden; with sector labels a slice is drawn on its label surface and the legend swatch follows (W-FV-3).

• Heatmap colour scale. colorScale: {type: 'sequential' | 'diverging', min, max, mid} and a three-colour colorRange for a diverging scale (HeatmapColorScaleOptions). Values beyond a fixed end take its colour, keep their true value everywhere, and the scale reads ≤ / ≥; the chart's description says so (four charts.scale.* keys in all five languages). An invalid scale is reported once and drawn safely.

• Heatmap recede. HeatmapChart highlight={{recede: true}} lets the other cells step back to Active's near context step while a cell is addressed (W-CF-2, an amendment of W-FV-4; default off, no strength, never under forced colours or in an export).

Changed (configuration, ADR-078, 2026-10-02)#

• A waterfall label honours position: inside draws it on its step where it reads; the default stays above the step.

• Stacked segment labels are inside. A stacked bar with labels and no position drew each label beyond its segment, on the next segment; it is now inside where it reads, and an explicit 'outside' is reported once.

• A bar label inside an unreadable bar that would leave the plot outside is hidden instead of clipped; a range bar on an axis with under 4 px per category draws one pixel instead of nothing; a waterfall step is never narrower than one pixel.

Changed — BREAKING (public contract and missing data, ADR-077, 2026-10-02)#

Public types narrowed to what the charts draw (Walt, W-QC-1 … W-QC-3). No consumer in the repository used a removed member; see migration/MIGRATION-NOTES.md.

• <Chart> series are Cartesian. SeriesOptions (the type of ChartOptions.series) is the thirteen series types <Chart> renders; PieSeriesOptions and HeatmapSeriesOptions are no longer members (they typechecked and then drew nothing). Use PieChart and HeatmapChart.

• Markers. MarkerOptions.shape is removed (every marker was a circle). A scatter or bubble series' marker is Pick<MarkerOptions, 'size'> (enabled, visible, fill and stroke were ignored there; the point's paint is the series fill and stroke).

• Scalar readout. dataLabels on GaugeChart, LinearGauge and BulletChart is Pick<DataLabelOptions, 'formatter' | 'format' | 'background'>: the readout is always drawn (FV4), so false, enabled, fontSize, color and percentage are gone. FunnelChart and RadialBarChart no longer accept dataLabels.fontSize or dataLabels.color, which they ignored.

Fixed (public contract and missing data, ADR-077, 2026-10-02)#

• Heatmap: a missing value is not 0. A cell whose value is null, undefined, NaN or infinite is drawn empty (no colour, no label), shows no tooltip, reads "(no value)" to the keyboard and in the data table, and never enters the colour scale's extent (a NaN used to give every cell a NaN position). 0 is a value.

• OrgChart: two people with the same name are two cards. Pointer, keyboard, tooltip anchor and reporting lines address a card by its id path; hovering the second of two equal names at one depth made both current and anchored the tooltip to the first.

• Line and scatter labels honour label.format through the shared number resolver (.25 with '.0%' is 25%); measurement and drawing read the same text.

• Horizontal bar outside labels sit beyond the value end: left of a negative bar, and on the correct side on a reversed value axis (also vertical); the edge check that moves a label inside reads that side.

• Stale JSDoc and API prose: marker visible defaults to 'hover', highlightStyle.dimOpacity defaults to the far context step (0.64 light, 0.70 dark), the heatmap 'auto' label colour is one colour, a selected item carries a caret beside it (no outline).

Added (diagnostics family parity, ADR-076, 2026-10-02)#

• Diagnostics go to a host sink. <ChartDefaults diagnostics> takes a ChartDiagnosticSink ({level: 'debug' | 'warn' | 'error', source, message, data?}, a caught error under data.error); nearest provider wins, a provider without one inherits. Without one, warn and error go to the console and debug is dropped. New public types ChartDiagnostic, ChartDiagnosticLevel, ChartDiagnosticSink; the same contract as active-grid's GridDefaults diagnostics.

Changed (diagnostics family parity, ADR-076, 2026-10-02)#

• Development diagnostics are reported outside production only and once per ground; four producers that ran in production (data validation, format strings, axis formatter, unreadable ticks) no longer do, and none repeats on a re-render or recompute.

• A contract problem the chart handles itself is warn, no longer console.error; only a failed context-menu export without onExportError is error ('Export failed', data: {error, context: format}), in every environment.

• Messages name structure and never host data: invalid sankey, hierarchy and scalar input report positions, depths and the violated rule instead of node ids, labels and values; a repeated category reports the field and the rows; a series is named by its identity, not its display name. The [active-charts] prefix is replaced by the source ([ActiveCharts], [ActiveCharts.BarChart], …).

• Empty data no longer produces a validation warning.

Changed (attention on Cartesian layout, intervals and financial charts, ADR-075, 2026-10-02)#

• No public API change. Bars and their kin speak the calm attention grammar (class A, W-FV-2, ADR-075): bar, grouped, stacked, mixed-sign and horizontal bars, histogram, range bar, waterfall, box plot, candlestick, OHLC and the bars of a combination. The hovered or focused item holds its colour; the other series at its category (a grouped neighbour, the other segments of its stack) step back a little (light 0.82, dark 0.85); everything else steps back to one moderate tier (0.64 / 0.70) instead of the old 0.35 / 0.30. A shared tooltip holds its whole category. Value labels never change on hover.

• One label colour. A value label asked inside a bar uses the chart's foreground and stays inside only where that reads (4.5:1); otherwise it stands outside the bar (a stack segment drops it). No bar picks black or white text of its own any more.

• The tooltip sits beside the bar or its category, never over it, its value label or its category label.

• Richer tooltips: a histogram bin as an interval with its boundary convention and its count, sum or mean; a range bar with its length; a waterfall step with starting balance, change and resulting balance, and a total named as a subtotal or the total; a box plot with its outliers; a stacked segment with its stack's total; a shared tooltip over two value axes grouped per axis. In a shared tooltip each row now shows its own series' key shape, and only the hovered series' row is emphasised.

• Keyboard and pointer cues: a histogram bin is named by its interval on the axis; candles and OHLC bars get a time crosshair that leaves the glyph clear (quiet for the pointer, the focus colour for the keyboard), their rising and falling colours never change; a box plot's outliers each get a marker and a value tick under the keyboard.

• Waterfall bridges are solid structure (1.5 px, the muted foreground), also into a subtotal or total, and never step back with a step.

• Horizontal bars wrap long category names in a gutter of at most 40 % of the chart's width before cutting them.

• Compact axis numbers are a trade, not a floor (N6): only the axes that need it switch, and a wider chart never draws a narrower plot.

• A zero-length range bar is drawn as one pixel at its value.

Changed (attention on Cartesian marks and connections, ADR-074, 2026-10-01)#

• No public API change. Lines, areas and points speak the calm attention grammar (W-FV-2, ADR-074). In single tooltip mode, and while a legend entry previews a series, the other series of a line, area, range area, scatter, bubble, dumbbell or lollipop chart step back to one moderate tier (light 0.64, dark 0.70) instead of nearly disappearing; a series' own points never step back; a shared or split tooltip dims nothing. Bar and other shape series keep their deeper step until FV7.

• A point keeps its size. The hovered or focused scatter point, bubble, dumbbell end or lollipop head is drawn again on top at full strength and at exactly its own radius, with no halo; the bubble's tooltip sits beside the circle. A line's 1 px emphasis no longer animates.

• One opacity per scatter point: a point is drawn at its fillOpacity once (it was that opacity twice, 0.49 for the default 0.7).

• Stacked areas are flat bands by default (gradient defaults to false for a stacked area, at the gradient's strongest opacity, 0.4); an unstacked area keeps its gradient.

• Dumbbell connectors read as data: the muted foreground at 0.8 (3.2:1 light, 5.2:1 dark), 2 px, unless the host sets connectorStroke.

• Several lollipop series stand side by side within a category instead of on top of each other.

• A range area is marked at both ends of its band under the pointer and the keyboard, never at its middle.

• A bubble at the edge of its domain stays inside the chart: the layout keeps the largest marker's radius free on every side (the domain is unchanged).

Changed (attention and labels on trees, flows and timelines, ADR-073, 2026-10-01)#

• No public API change. Trees, flows and events speak the same calm attention grammar and label language (W-FV-2, W-FV-3, ADR-073). Treemap and sunburst: every tile, arc and header label is the mode's foreground colour in light and in dark (no black-and-white patchwork per branch); tiles, arcs and header strips are drawn just far enough towards the background for it, one factor per branch colour, so the branch stays recognisable. A sibling of the addressed item steps back a little, an unrelated branch more (light 0.82 and 0.66, dark 0.85 and 0.70); the sankey keeps one-hop adjacency and steps the rest back to the far tier.

• Names wrap before they are cut. Treemap tiles, sankey node labels and org cards take a name over at most two lines, breaking only where a line may break, and cut it once at the end of its last line; a sunburst label is a straight line measured to fit inside its arc (one or two lines), never by the arc's length. Every sankey node keeps a label, also a very small one; the labels of a column make room for each other.

• Org chart. Cards rest on the card surface with a name, then the role; the reporting lines are visible in both modes and restored to full strength around the hovered or focused card, which takes a subtle tint measured so its texts keep 4.5:1. A tree that cannot fit at its readable scale starts on its root and says so ("Partly shown: drag or zoom to see the rest") in a strip under the plot, beside the zoom controls, and in its description. The tooltip names the person, the role and whom they report to, with no number.

• Timeline. Labels and dates sit in collision-free lanes above or below their marker, the first and last moved inward so they never leave the frame; a crowded lane cuts a label to the room it gets. The current event no longer grows or turns bold: its connector is drawn solid. The keyboard is located by a mark beside the event's label. The tooltip shows the date, the event and the host's description, with no index number.

• Two translation keys in every language: charts.org.partialView, charts.org.reportsTo.

Changed (heatmap and scalars at rest and under attention, ADR-072, 2026-10-01)#

• No public API change. The heatmap is quantitative colour, so nothing in it changes under attention (W-FV-4, ADR-072): no cell brightens or recedes, the addressed one included; quiet marks in the row and column header gutters locate the pointer's cell, focus-colour marks the keyboard's, and the marker on the colour scale its value. The source that acted last owns the one painted cell (a key press after a hover now names the keyboard). The pointer tooltip sits above or below the cell, leaving its row and column headers visible.

• The heatmap's numeric colour scale is shown by default (W-EC-3), inside the chart and its export, with its low end, middle and high end in the cells' notation; gradientLegend={false} hides it. Heatmap numbers use the shared chart notation (whole numbers without .00).

• Gauge fits its swept arc (N2): radius and centre follow from the actual startAngle/endAngle sweep, the end labels and the readout; below a useful size it keeps the value and says it has no room.

• Linear gauge and bullet name both domain ends and the target at rest (W-EC-5); the value has its own row and is never drawn where the maximum would be. Gauge, linear gauge and bullet draw every number in the value's notation (N11).

• Scalar keyboard focus shows a tick at the indicator (bullet: the measure's end) and a mark beside the readout; never an outline.

• Two translation keys in every language: charts.scalar.target, charts.scalar.insufficientSpace.

Changed (attention and labels on radial and categorical charts, ADR-071, 2026-10-01)#

• No public API change. One calm attention grammar and one label language for the radial and categorical families (W-FV-2, W-FV-3, ADR-071). Pie, donut, nightingale, radial bar and funnel: the addressed part keeps its own colour, size and place (the pie and donut slice no longer moves out) and every other part steps back to one moderate tier (light 0.64, dark 0.70, derived so both modes step back equally far; dark steps back less than before). Radar: a vertex no longer grows; under the pointer the other series step back to that tier, under the keyboard nothing steps back and the tooltip lists every series at that dimension; the keyboard is located by a mark beside the dimension's label. No text changes colour, weight or size on hover or focus.

• Nightingale, radial bar and funnel rest at full colour (they rested at 80–85 % opacity) and take their colours from the ten-colour palette (they repeated after five, so categories six and up change colour); colours follow each category, so hiding one recolours no other.

• Radial bar draws every category or says it cannot. Rings are fitted to the radius and the number of categories, thinning from barThickness (now the preferred thickness) to a floor; where not every ring fits, the chart shows "Too small to show all N items" (translated) and states it in its description instead of leaving rings out. An angular scale is drawn at rest outside the rings, with its origin labelled.

• Radar ring values are drawn at rest beside the first spoke, and the web is centred with slightly more room.

• Funnel labels in one colour. Inside labels are the mode's foreground on a stage drawn towards the background just as far as needed for 4.5:1 (the legend swatch shows the stage as drawn); where a colour would need more than half, the label goes outside. Percentages are shares of the first stage, which a caption under the stages names, and the tooltip adds a row with that share.

• Nightingale fits its frame. The rose is sized from its measured labels; on a narrow chart the labels are shortened, then hidden, before the rose shrinks below half the frame. Values use the shared notation in pie, nightingale, radial bar and funnel.

• Tooltips sit beside the addressed slice, wedge, ring, vertex or stage, away from the centre, its label and a donut's centre metric, wherever a side fits.

• New translation keys charts.insufficientSpace, charts.funnel.percentOf and charts.funnel.shareOf (every available language).

Changed (cues instead of rings, ADR-070, 2026-10-01)#

• No public API change. Cues instead of rings (W-FV-1, ADR-070). In normal light and dark rendering no family draws a border, outline, ring, contour, halo or bracket around a data mark any more, for pointer hover, keyboard focus or persistent selection. Keyboard focus is located by a short mark in the focus colour (3:1 or more against the background) that points at the item or sits beside its identity: in <Chart> on the category axis (a stacked segment also at its level, an interval at both ends, on the value axis; a sample with a solid marker, a quiet guide and an axis cue, a scatter point on both axes); a radial or side tick just outside a slice, wedge, radial bar end, spoke, sunburst arc, funnel stage or timeline event; a mark beside a treemap tile's label or group header, under a sankey node's label (a flow: under both endpoint labels), before an org card's name. The heatmap draws nothing around the current cell and changes nothing else: only that cell turns a touch brighter in its own hue, the colour scale marks its value, and the keyboard adds a cue in each header gutter; no text changes. Values shown in the cells (opt-in) now take one label colour, the foreground, instead of black or white per cell, and the cell scale is drawn towards the background as far as that colour needs for 4.5:1 on every cell (the colour legend shows the same range). A selected <Chart> item carries a filled caret beside it instead of an outline or ring. The current org card is tinted on its surface instead of edged in its colour. Under forced colours every cue is Highlight and the current mark keeps a Highlight edge; the chart root keeps its control focus frame. The root attribute data-ac-locator is now data-ac-cue (package-private).

Changed (branch context in hierarchy and flow, ADR-069, 2026-10-01)#

• No public API change. Treemap, sunburst and sankey: hierarchy and flow attention (ADR-069). Pointer hover draws no foreground edge on a tile, arc or node any more; the addressed item keeps full strength while its context follows the branch: a sibling steps back a little, an unrelated branch more, ancestors and descendants stay. The sunburst no longer dims by ring depth. A treemap leaf directly under the root draws no group background or header strip (the false band in a receded root leaf is gone). A keyboard-focused sankey flow keeps its colour and width and gets a link locator at both ends of its band; a thin sunburst arc gets a short radial locator. The tooltip of these three families sits beside the addressed tile, arc, node or flow when a side fits.

Changed (attention core, ADR-068, 2026-10-01)#

• No public API change. Chart entry and datum focus are two stages: while the keyboard is on the chart itself, its 2 px focus ring is the indicator; once a datum carries the keyboard locator, the chart ring becomes one quiet 1 px line, so the datum locator is the single dominant ring (ADR-068). Pointer and keyboard are two sources of attention in every standalone family: a pointer that leaves the plot hands the attention back to the keyboard's item instead of clearing it.

• Internal: a shared attention core, a closed vocabulary of relation roles, context policies and locator kinds, family sections in interaction.css without added specificity, new locator kinds in the transient layer and an anchor option for the tooltip positioner. New transient root and item attributes (data-ac-origin, data-ac-target-kind, data-ac-locator, data-ac-relation) never reach an export.

Added (family visual evidence, ADR-067, 2026-10-01)#

• No runtime change and no public API change. The family visual target is now measured in the browser (e2e/visual-family-target.spec.ts, ADR-067): encoding, isolation, relation, focus, tooltip-anchor and context-at-rest probes over every family, with a ledger of known gaps owned by the phases FV1–FV8, and a change-detecting capture matrix. The closeout ledger is re-keyed to the same phases. Source comments that cited the deleted visual designs now cite ADRs, ARCHITECTURE and QUALITY-BUDGETS (comment-only).

Changed (tooltip containment and keyboard focus shape, ADR-066, 2026-10-01)#

• A tooltip is as wide as its content needs, up to four fifths of the chart: names wrap only at that cap, and every value stays inside the card's padding. The cap now resolves against the chart (it resolved against the tooltip itself, so a value could stand outside its card). A split tooltip keeps its fixed column and wraps a long name in it instead of cutting it, inside the chart.

• A tooltip that fits the chart stays inside it: when neither side of the pointer has room, it shifts inside the chart instead of leaving it.

• One keyboard ring for every family, without an outline: the host's ring colour drawn a quarter towards the foreground, so the ring itself keeps 3:1 against the background in both modes. The Cartesian ring loses its foreground edge; the standalone families draw it on the focused shape (a sankey node's rect, an org-chart card, a timeline marker), never on a group, so a focused label is no longer drawn thick or blurred. No glow.

Fixed (tooltip containment and keyboard focus shape, ADR-066, 2026-10-01)#

• A standalone chart's tooltip stayed hidden until the pointer moved again, and never showed for the first keyboard-focused item.

• Under forced colours, a focused pie, funnel or nightingale item lost its ring to the system background; it now takes Highlight.

• An export of a chart with keyboard focus carried the focused item (data-focused) and the root's aria-activedescendant; an export shows the chart at rest.

Changed (interaction states across every family, ADR-065, 2026-10-01)#

• A narrow axis degrades in one order: a plain number axis (auto-formatted, no declared form or kind: 'number') first turns compact ("48 bn") when its labels would squeeze the plot below its minimum; only then does a title give way; a time axis whose scale knows no coarser set thins by stride rather than overlap its labels; and a category label is cut only while it stays recognisable (four graphemes, or its whole first word: "Jan …"), otherwise the axis shows fewer whole labels. An outer date label of a truncating axis takes its shorter form ("1 Jul") before it is cut.

• A tooltip is at most four fifths of the chart's width; a long name wraps, a value never does.

• Exports and prints show the chart at rest, selection included: selection marks are interaction state and no longer reach an SVG, PNG, PDF or print (W-VQ-6). The hover emphasis of an org-chart card or a timeline event comes from the stylesheet and is never exported.

• Legend spacing in ems of the legend font (identical at the default size).

Changed (standalone families on the shared state model, ADR-065, 2026-10-01)#

• Standalone families on the shared interaction state. Donut and pie (the current slice moves out, its siblings step back), funnel, nightingale and radial bar (current item full strength, siblings step back), radar (series emphasis, a growing vertex, the other series inactive), treemap (a foreground edge, the other leaves step back), sunburst (the arcs of the current ring step back) and sankey (a node keeps its links and their far ends, a link its two endpoints; the rest of the flow steps back). No standalone renderer paints a dim or an offset of its own.

• Legend preview on the donut, pie, funnel, nightingale and radial bar (the item) and the radar (the series), by pointer and keyboard focus.

• Heatmap hover and focus: an outline (a background halo and a foreground edge) over the current cell; no other cell changes colour. The keyboard ring sits on the drawn cell.

• Radar keyboard ring on the data vertex (it sat on the tip of the axis); vertices are drawn above every polygon, so a vertex inside a later series' polygon can be hovered. The axis labels are measured before the radius is fixed.

• Treemap and sunburst tints are opaque tints of the group colour, tuned per colour mode: a dark surface keeps their hue instead of turning muddy.

• Sankey labels: sources outside on the left, sinks outside on the right, middle columns in the gap; the side columns are measured from the labels. labelPadding now defaults to the measured width (it was 90 px).

• Timeline lane labels are measured and no longer cut at the chart edge.

• Entrance animations release their final state (fill mode backwards), so state paint applies after the entrance.

Fixed (interaction-state coverage, ADR-065, 2026-10-01)#

• Shared and split tooltips on bars: the hovered category now stands out in every series (its bars full strength, the other categories step back); before, a grouped, stacked or mixed-sign bar chart with a shared tooltip showed no hover at all. No series is dimmed.

• Histogram: the keyboard reaches every bin, and the tooltip shows the bin's value (it showed the bin's start).

Changed (Cartesian geometry standards, 2026-09-30)#

• Bars round their value end by default: 3 px (cornerRadius still sets a series' own, 0 rounds nothing), clamped to a quarter of the bar's width, on the value end only — the top of a positive column, the bottom of a negative one, the inline end of a horizontal bar. In a stack only the outermost segment of each sign rounds. Negative bars used to round their base.

• Bars are at most 64 px wide. A chart with few categories draws deliberate columns instead of slabs; grouped bars narrow as a group and stay together and centred. The hit targets, focus ring and selection outline follow the drawn bar.

• Crisp edges. Bar and waterfall edges sit on whole pixels (stack segments meet without a hairline); a candle's 1 px wick sits on a half pixel with an odd body centred on it, and candle and OHLC strokes render crisp.

• The waterfall joins the bar family: the same value-end radius, width cap and crisp edges; its connectors run edge to edge.

• Stroke hierarchy: a box plot's whiskers and caps are one step lighter than its box, the median stays the strongest; a lollipop stick is drawn one tier below its marker (stroke opacity 0.55 unless the series sets its own stick colour).

Changed (tooltip, typography and chrome, 2026-09-30)#

• One surface family. The tooltip (every mode), the context menu and the crosshair value chips share the popover surface, a 1 px border and a per-mode elevation from the package stylesheet: a soft shadow in light, a deeper one in dark. The context menu lost its blur; the crosshair chips are no longer foreground-filled pills. A tooltip style.boxShadow still wins.

• Tooltip hierarchy. Values are drawn one weight step above names (500 and 400), with tabular numerals at the inline end; in shared mode the row of the hovered series names it in the value weight. The key of a row has the shape of the legend key for its series type (a bar a rounded square, a line a stroke with its dash, a marker a circle); a candle or OHLC bar keys its up or down colour and a waterfall step its increase, decrease or total colour.

• Value-end anchor. A bar, histogram bin, waterfall step, range bar, box, candle or OHLC bar opens its tooltip (and its crosshair) at its value end instead of its middle.

• No blink across bar gaps. A pointer hover outlives a miss by 100 ms; the keyboard still ends its hover at once.

• Typography tiers. Data labels are drawn in the value weight (500); the empty-state text is the metadata tier (11 px, muted). No size floor moves.

• Grid. Grid lines run perpendicular to the value axis only: a category axis draws no grid by default, and a time axis only for a line, area or range-area series. The grid is a little stronger and tuned per mode, and a zero line one step stronger marks zero when the domain crosses it. gridLine.enabled still decides where it is set.

• The legend and tooltip keys of range area (a stroke) and of OHLC, box plot, range bar and candlestick (a square) now follow their series family.

Changed (interaction state model, ADR-064, 2026-09-30)#

• One interaction-state model for every Cartesian family (ADR-064). The chart computes the state once (rest, emphasis, recede, inactive, focus) and writes it as data-* attributes; the package stylesheet paints it. No series renderer applies a dim opacity of its own any more.

• Bars and other shapes answer a hover with their own geometry. The hovered bar, histogram bin, waterfall step, range bar, box, candle or OHLC bar keeps full strength and its siblings recede; other series go inactive. The dot that used to sit in the middle of a bar is gone.

• Markers get an emphasised node: the hovered scatter, bubble, dumbbell or lollipop mark is drawn again on top, slightly larger, with a background halo; a lone marker series recedes behind it.

• A shared or split tooltip dims no series: every series the tooltip lists gets a node at the hovered row.

• Keyboard focus has its own ring around the current bar body or node: the --ring colour between a background halo and a foreground edge (3:1 or more against the background), shown whether or not anything dims and with the tooltip off.

• Legend preview: hovering or focusing a legend item of <Chart> emphasises its series and fades the others. It never toggles and never changes aria-pressed; click and double-click are unchanged.

• The recede and inactive strengths are tuned per colour mode from contrast floors (2:1 and 1.4:1 for every categorical colour on background and card; QUALITY-BUDGETS § 12). highlightStyle.dimOpacity still sets a series' own inactive strength.

Fixed (interaction state model, ADR-064, 2026-09-30)#

• Exports taken while hovering, focusing or previewing a legend item carried the transient state (dimmed series, crosshairs, the hover dot). An export now shows the chart at rest, byte for byte; print does the same.

• The zoom animation of <Chart> ignored prefers-reduced-motion.

• The tooltip fade ignored reduced motion wherever the tooltip was mounted outside a chart scope; the fade is now a stylesheet rule the reduced-motion rule always reaches.

• A hover no longer re-resolves or re-measures the axis ticks (CH-13), and moving within one item re-renders nothing.

• The forced-colours rule for the hover dot targeted a circle inside the dot and never applied; the node now takes the system highlight colour.

Changed (axis layout, ADR-063, 2026-09-30)#

• Axes are laid out from measured extents (ADR-063). One internal function stacks tick, gap, measured labels, the parent row and — only when it is drawn — the title, and both the margin reservation and the axis placement read it. An axis title now keeps one gap (0.75 em of the tick font) outside its widest label: it moves in for short labels and out for wide currency or percentage labels, on left and right axes alike. Visible effect: margins and title positions shift, an unrotated x axis takes about 24 px instead of a fixed 40 px, and screenshots of Cartesian charts differ.

• Rotated x labels reserve the row they draw. The resolved rotation feeds the bottom (or top) extent; a resolved 0° no longer reserves the old 88 px. A truncating axis caps a rotated row at 70 px and cuts longer labels there (full text in <title>); rotated labels are no longer cut to the tick spacing. An axis with label.truncate: false reserves its full label length.

• A title that is not drawn reserves nothing, on every side (the vertical axes previously kept 16 px under hideAxisTitles). When the measured axes would squeeze the plot below 120 × 80 px, the titles of that dimension are left out before any label.

• First and last glyphs on an ordinal-time axis (candlestick, OHLC, box) keep the same gap to the plot edge as two neighbours: the axis pads 0.7 step instead of 0.5 when it carries glyphs.

Fixed (axis layout, ADR-063, 2026-09-30)#

• Axis titles overlapping or crowding tick labels (for example −12,5 %, € 1.234.567 or a dual NAV axis), including under dir="rtl".

• Dumbbell and lollipop markers at the value extremes were cut by the plot clip; they are now drawn whole (the domain is unchanged).

• The forced-colours and print stylesheets targeted grid-line test ids that no longer existed, so grid lines kept their screen colours in Windows High Contrast and in print.

Fixed (re-convergence, 2026-09-30)#

• A time x axis honours min and max. The domain was built from the data alone; explicit bounds (epoch milliseconds) now set it, as on a number axis.

• A chart without rows rejects exportAsCsv with EXPORT_NO_DATA. <Chart> with data={[]} and a standalone family with fixed columns (the timeline) wrote a header-only file and reported success.

• onLegendToggle fires once per toggle. It ran inside a state updater, which React may run twice (always under StrictMode).

• Sunburst ring-one labels are fitted in their painted weight (600). They were measured at the inherited weight and could overflow their arc.

• Categorical item names use the formatted value (pie, funnel, nightingale, radial bar, radar), like the announcement already did.

• A grouped bucket of ISO-string x values stays selected. The selection existence check read only Date and number x values, so an uncontrolled selection dropped the bucket at once.

• Indicators treat NaN and Infinity as missing, like null; one non-finite source value no longer hides every later EMA and MACD value.

• PeriodSelector windows clamp to the end of a shorter month: 31 March minus one month starts on 29 February, not 2 March.

Changed (packaged-artifact proof, ADR-061)#

• date-fns and @date-fns/tz are declared dependencies. The inlined formatter closure imports them; an install outside the workspace reads only this manifest. No runtime change.

• Documentation. README Quick Start passes a presentation and translator, the export paragraph describes ChartExportFonts instead of the removed base64 font, and API § 4 states that a host without jspdf/svg2pdf.js declares them external to its bundler.

Documentation (export guarantee tiers, ADR-060)#

• Export guarantees. docs/EXPORT-GUARANTEES.md states the tiers L0 to L3b-print per format and script, the route to take, the error kinds, a host font example and the host L3b recipes. No runtime change.

Added (export font sets in SVG and PNG, ADR-059)#

• Export fonts in SVG and PNG. The same ChartExportFonts as PDF, with the same precedence (the call's fonts, else ChartDefaults.exportFonts, else none; 'inherit' skips the defaults), on exportAsPng/exportAsSvg of the handle, on PngExportOptions/SvgExportOptions, and in the context menu's PNG and SVG export. With a set, every text names the host's families in order before its live font stack.

• ChartExportFonts.embedInSvg (default false): the SVG also carries every face as an @font-face data URL. A PNG with a set always embeds every face, so the browser falls back per glyph across the host's families before any system font (CH-6, for the explicit set).

• SVG and PNG embed TrueType, OpenType CFF, WOFF and WOFF2 as given; a font collection or unknown bytes reject with EXPORT_FONT_FORMAT_UNSUPPORTED. Font errors of an SVG or PNG export carry format: 'svg' or 'png'.

Without a set, SVG and PNG export exactly as before (the SVG is byte-identical to the earlier capture). PDF is unchanged.

Changed — BREAKING (export font model and PDF, ADR-058)#

• One export-font model. ChartPdfFont and the PDF option font: {family, normal, bold?} (base64) are removed. PDF export takes fonts: ChartExportFonts: families in fallback order, each with faces whose source is an ArrayBuffer, a Uint8Array or a lazy host loader, plus weight and style. exportAsPdf also accepts fonts: 'inherit'. Migrate font: {family, normal: base64} to fonts: {families: [{family, faces: [{source: bytes}]}]}.

• PDF refuses what it cannot draw. Without export fonts, text outside WinAnsi rejects with EXPORT_FONT_REQUIRED (it used to draw broken). With or without fonts, complex and right-to-left scripts, combining marks, ZWJ/ZWNJ and variation selectors, emoji and supplementary-plane characters reject with EXPORT_TEXT_UNSUPPORTED; text no family covers rejects with EXPORT_GLYPH_COVERAGE. No file is written.

• The standard font is Helvetica. Without export fonts the PDF drew in Times since FAM-V2-T6 (svg2pdf.js did not find the family Helvetica); it now draws in Helvetica, as documented.

Added (export font model and PDF, ADR-058)#

• ChartDefaults.exportFonts: the export fonts of every chart below, used by the handle's and the context menu's PDF export. An explicit fonts wins; 'inherit' skips the defaults for one call.

• Per-element font choice in PDF. Each text element draws in the first family that covers all of it (coverage read with jsPDF's own parser); bold, italic and bold italic faces are optional and fall back deterministically, never synthesised. Faces load before the capture moment; a loader runs once per face object and a failed load is retried by the next export.

• ChartExportError.code (ChartExportErrorCode) and its metadata (format, family, detected, codePoint, reason, script, normalizable, families); missingModule stays. Never the exported text.

• Types ChartExportFonts, ChartExportFontFamily, ChartExportFontFace, ChartExportFontSource, ChartExportErrorOptions.

Added (text measurement and RTL chrome, ADR-057)#

• RTL chrome. Under dir="rtl" the legend flows from the right and its arrow keys follow the reading direction; the tooltip prefers the inline-end side of the pointer; the context menu opens toward the inline end, its submenu opens left with ArrowLeft and closes with ArrowRight; exported legends and report text follow the same direction. Axes, data order, the navigator and the plot arrow keys are unchanged.

• Direction-aware SVG anchors. Geometric labels (ticks, annotations, slice, bar, funnel and sankey labels) keep their physical side in rtl; tile, header, breadcrumb and gauge titles start at the inline start. A reference-line label without a position sits at the inline end.

• Measured, grapheme-safe text. Mounted charts measure labels in their painted font (weight, style, direction, letter spacing, kerning) and again after a font load; truncation never splits a grapheme cluster; export report text wraps CJK and never breaks at NBSP or NNBSP.

Changed (text measurement and RTL chrome, ADR-057)#

• A treemap tile shows its share whole or not at all (no truncated number).

Added (direction and bidi, ADR-056)#

• dir prop on every chart. One UI direction: the explicit dir, else the page's direction (the nearest dir attribute, followed when it changes), else ltr; never the locale. The context menu under <body>, the tooltip and the screen-reader table carry it. It never reverses an axis or reorders data.

• Isolated text. Series names in the tooltip and legend and labels in the screen-reader table are dir="auto" and isolated; formatted values are one isolated run; SVG text is unicode-bidi: isolate (new partial styles/direction.css). A right-to-left series name in the legend's isolation announcement is isolated with FSI/PDI.

• Export keeps direction semantics. direction and unicode-bidi are materialised into SVG, PNG and PDF exports; an ltr chart with Latin text exports byte-identically. CSV carries no bidi controls.

• Formatted values read in their locale's direction (P6 refinement): tooltip and screen-reader table values carry their presentation locale's script direction where it differs from the chart's.

Changed (portable runtime, ADR-054)#

• jspdf and svg2pdf.js are optionalDependencies: rendering never loads them, and an installation without them fails exportChartAsPdf (and the menu's PDF export) with a ChartExportError whose missingModule names the module, instead of the bundler's resolution error.

• ChartExportError is public (root export), so a host can recognise a failed export in onExportError.

• The CSV serializers come from @workspace/active-utils/serialization, and IsoDateString from @workspace/active-types/primitives/iso-date, instead of the server-bearing /helpers barrel and the active-types root.

Fixed (reporting and export, ADR-053)#

Each defect below was found by the T6 browser evidence and has a witness that failed on the old code.

• An export across a data change shows one moment. The legend of an image export was built when the export was called and the drawing was cloned after the chart had settled; a host that changed its series in between got the new lines under the old legend. The handle now reads the legend at the capture moment, from the latest commit (<Chart> and the standalone families alike).

• Legend and report text are visible in a PDF under oklch() tokens. The legend swatches and the report title, subtitle and caption kept the host token's oklch() value, which svg2pdf cannot read: the swatches were missing and the text was drawn invisibly. Their colours are now written as rgb()/rgba() like the rest of the chart.

• A PDF draws only in the font it embeds. Text of weight 600 (the report title) fell back to Times, unembedded and Latin-1 only, also with a host font: svg2pdf asked for a style named after the weight. Numeric weights now become bold or normal, and without font.bold bold text uses the regular embedded file.

Added (reporting and export, ADR-053)#

• legendItems on exportChartAsPng, exportChartAsSvg and exportChartAsPdf accepts a function, called at the capture moment. An array is taken as given. Additive.

Fixed (accessibility and touch, ADR-052)#

No public API changed. Each defect below was found by the T5 browser evidence and has a witness that failed on the old code.

• A reference-line label is no longer hidden by the marks (PH6-01). The lines and bands of crossLines stay between the grid and the series; their labels are now drawn above the series with a halo in the chart background (Canvas under forced colours). At 390 and 320 px the "105" of the dual-axis chart was covered by the last bar.

• Every way of opening the context menu is announced. Shift+F10, the context-menu key and a long press now announce "Context menu opened", as a right click already did.

• The keyboard reader hears menu, zoom, legend and pin announcements. The chart's live region showed the keyboard cursor text before any other announcement, and that text stays set while a reader navigates, so a keyboard zoom was never heard. The most recent announcement now speaks, and a cleared one no longer brings the older cursor text back.

• A host menu item gets the item the menu was opened on. Opened from the keyboard, the element is the focused item; from a right click or a long press, the item under the pointer; on empty plot area, null as before. Opening moves focus into the menu, which cleared the hover the element was read from, so a keyboard-opened host item received null and the built-in "Copy value" was disabled.

• The keyboard focus follows onto a submenu trigger ("Export ▸"), as on a plain item.

• A long-press menu stays open when the finger lifts. A browser whose own long press is longer than the chart's (500 ms) read the lift as a tap and closed the menu with the click that followed; the press now cancels its own click.

• No console error on every touch move over a Cartesian chart. The hit layer called preventDefault() in a passive listener, which the browser ignored with an intervention error; the page scrolled regardless, and still does.

• The navigator brush follows a finger. The navigator strip declares touch-action: pan-y, so a sideways drag moves the brush instead of being taken for a page pan; a vertical swipe still scrolls the page.

Added (host-integration contract, ADR-051)#

• englishChartTranslator: the package's English translator, complete by type, for standalone hosts, fixtures and examples that pass it on purpose. Nothing installs it implicitly; a chart without a translator still throws.

• ChartPresentation is an alias of the active-i18n ValuePresentation (active-i18n D23); the type is unchanged. No breaking change.

Fixed (stylesheet activation and scoped text measurement, ADR-050)#

• A stylesheet that stops or starts applying refreshes the chart's decisions. A change of media, disabled, rel, type, href or title on a <style> or stylesheet <link> in <head>, and a stylesheet <link> that fails to load, now move the style generation: on-fill label colours follow, and an export taken during such a change starts again instead of writing the previous view. What still needs invalidateChartStyles() is listed in API.md § 13 (CSSOM edits including sheet.disabled and <style>.disabled, adopted sheets, stylesheets outside <head>, media conditions other than colour scheme and forced colours).

• Labels are measured in the font they are painted in. Tick labels, data-label collision and export report text resolve var(--font-sans), an inherited family and the weight in the chart's own element instead of the page body. Two sibling charts under different font variables now lay out the same labels differently and correctly (rotation, truncation, thinning, edge fit); a change of --font-sans to a font that is already loaded measures again. Before mount a chart estimates its labels and reads no style, so server markup and hydration agree. A bold report title wraps where its bold width says.

• No public API changed.

Changed — BREAKING (collision-safe series identity, ADR-049)#

• A series that declares an id is named id:<id> in selection. The seriesId of ChartItemRef and ChartItem (in selectedItems, defaultSelectedItems, onSelectionChange and onItemActivate) is now the series identity itself: id:<id> for a declared id, else <type>:<key> (unchanged, e.g. line:price), else position:<index>. The namespaces are disjoint, so no two series of a chart share a seriesId. The id: prefix used to be stripped, so an id spelled like another series' identity (id: 'line:a' next to a line over a, id: 'position:1', id: 'line:a#2') produced one seriesId for two series: a click on one reported the other, and a stored selection marked both or neither.

• Migration. Where a host writes a seriesId for a series with an id, prefix it: {seriesId: 'revenue', …} becomes {seriesId: 'id:revenue', …}. Selections stored from onSelectionChange must be discarded or migrated the same way. Derived identities are unchanged. No alias is provided.

• Repeats are defined, not only reported. A repeated identity keeps its order-based #n suffix and is documented as such; the development report now names that outcome.

Fixed (series-scoped display truth, ADR-048)#

• A percentage stack no longer changes what other series show. A percentage-stack member used to write its share into the displayed row shared by every series, keyed by field. A raw series over the same field then showed the share, a second percentage stack over that field overwrote the first stack's shares, and a hidden member emptied the field for every series. Each member now displays its share from rows of its own; geometry, domain, stack baselines, hit geometry, tooltips, the accessible table and announcements read those, and every other series keeps its own value. CSV, copy-as-table and the navigator stay raw, as before.

• A zoomed waterfall keeps its running total beside a percentage stack. The waterfall used to carry the running total of the steps before a zoom window only while the displayed rows were the zoomed array itself, so any percentage stack in the chart restarted it at zero. The positions are now placed on the displayed rows by the zoom window and the origin of each prepared row.

• No public API changed.

Changed (theming: the package owns only --ac-*, ADR-047)#

• The internal animation custom properties moved out of the host's namespace. The fourteen properties the charts write inline for their entrance and update animations are now --ac-fade-*, --ac-morph-*, --ac-segment-*, --ac-sweep-* and --ac-wipe-* (they were --chart-fade-duration, --chart-sweep-angle and their siblings). The public --chart-* names belong to the host's token contract. They were never documented and no workspace consumer read them; a host stylesheet that did must use the new names. Timing and behaviour are unchanged.

• Documentation. The theming design, the architecture and competitive review and the two older library comparisons are non-canonical research under docs/research/ (deleted 2026-10-07); the obsolete stacked-area analysis is removed. Canonical claims that no longer matched the source are corrected (ChartHandle exports return promises, onExportError, no ChartOptions.background, no d3-interpolate, no visual fields on <ChartDefaults>, the fixed sqrt x-axis domain, the PDF font).

Added (theming: a host palette is the host's, ADR-046)#

• Guards for the package's brand-neutral identity. The unit suite pins the chart values of styles/defaults.css in both modes and the thresholds the browser suite asserts. The platform host now sets its own chart palette (active-ui ADR-030) and charts pick it up through the token contract; the package defaults, the public API and the rendering are unchanged, so a page without host tokens shows the same palette as before.

Removed (theming: no visual theme API, ADR-045) — breaking#

• theme and ChartThemeOverride. Charts and ChartOptions take no theme prop and the type is no longer exported. A per-chart or per-region change of a token is plain CSS on the chart's className or an ancestor; charts follow it without a remount (ADR-044).

• The visual fields of <ChartDefaults>. <ChartDefaults> no longer takes theme or colors, and a chart no longer inherits a palette from it. Set colors on the chart that needs its own categorical palette; leave it out to use the host palette.

• --bullet-bar. The token, its package default and its role are gone. The bullet's value bar is drawn in the on-fill token that contrasts most with the bands and track beneath it: dark over pastel bands, as before; light over a dark track, where it used to be dark on dark.

Changed (theming, ADR-045)#

• The chart wrapper is data-chart-scope (was data-chart-theme-scope) and carries no inline style. A scoped host override set on it or on an ancestor reaches the chart.

• colors is documented as what it is: the categorical palette of one chart, replacing the host palette in the colour assignment and nothing else.

Fixed (theming, ADR-045)#

• The pie and donut legend colours every key like its slice. Without colors, the legend used a five-slot palette, so the sixth slice onwards showed a legend colour that differed from its slice; it now follows the same ten slots (or colors) as the slices.

Added (theming: live-element resolution, invalidation and export consistency, ADR-044)#

• invalidateChartStyles(). A value-free notification for a style change no observer can see (a rule inserted through the CSSOM, an adopted stylesheet): every chart re-reads its tokens in its own scope. It sets no theme and carries no value. A class, an inline custom property or a stylesheet element needs no call.

Changed (theming, ADR-044)#

• Colour decisions resolve in the chart itself. The on-fill colour of a label (bar, heatmap, treemap, sunburst, funnel) is decided on the tokens of the live chart element, so a scoped host override and the per-chart theme (removed in T3) count; it no longer reads the page body. The decision is taken after mount, before the first paint; server render and hydration read no computed style for a colour.

• Runtime switching without a remount. Charts re-decide on a colour-mode, accent, token, scoped-override or stylesheet change: a class, data-theme or custom-property change on any ancestor of the chart, a stylesheet added, removed, rewritten or loaded, and prefers-color-scheme/forced-colors. One shared observation serves every chart and is released with the last one; a colour change recomputes no geometry.

• Heatmap cells and gradient legend are one scale. A cell paints its colour as a CSS mix of the two ends of the scale, the same references the legend uses, so both follow a token change by themselves. Behaviour: a cell's fill and point.color in its hover event are now a CSS expression (color-mix(in srgb, …) or a token reference) instead of an rgb() string.

• Exports are one moment of the chart. SVG, PNG and PDF run one capture transaction: they wait for a still chart and loaded fonts, clone and read every colour and the background in one step, and start again (at most three times, then ChartExportError) when the page styles changed meanwhile. Every colour an element declares is resolved in that element's own scope and written as rgb()/rgba(), which a PDF can read. Behaviour: SVG files carry rgb() instead of the host's notation (oklch()).

• Behaviour — the PDF page takes the chart's background. exportChartAsPdf and exportAsPdf default to the chart's own background, as PNG already did, so a dark view exports as a dark page. Pass backgroundColor for another page colour; a light report from a dark view is an export in the light colour mode.

Removed (theming, ADR-044)#

• The unused dependency d3-interpolate (the heatmap no longer interpolates in JavaScript).

Changed (theming: CSS token contract and package defaults, ADR-043)#

• Charts read the public tokens directly. Categorical and data roles come from --chart-1 … --chart-10, --chart-positive/-negative/-caution, --chart-sequential-*, --chart-diverging-*, --chart-on-fill-* (and the transitional --bullet-bar); surfaces, text and controls from the host's --background, --foreground, --card, --muted, --muted-foreground, --border, --ring, --popover, --accent, --primary (and their -foreground pairs). No chart reads a Tailwind --color-* alias any more, and the scattered literal fallbacks are gone.

• Complete package defaults. Every token has a package default for light and for dark (.dark on the document root or an ancestor), so a chart renders fully without any host stylesheet. A token the host sets always wins, whatever the stylesheet order: the package never declares a public token.

• One package stylesheet, loaded by the entry. Token defaults, focus, motion, forced colours and print are one stylesheet that the package entry imports once as a static CSS side effect; components no longer import stylesheets one by one. A host needs no utility-class scan of the package source and no import.

• theme (ChartThemeOverride) writes the public tokens it overrides (--chart-N, --chart-positive, --foreground, --card, …) on the chart wrapper, so it keeps working against the new reads. theme, colors and the <ChartDefaults> visual fields are otherwise unchanged.

• Structural colours follow the host on the element. The focus ring, for example, now reads --ring where a scoped theme sets it, instead of an alias resolved on the document root.

Fixed (theming, consumer-visible, ADR-043)#

• The heatmap's cells follow the sequential colour role. The cells used a fixed light-to-dark ramp while the gradient legend used --chart-sequential-min/-max; in dark mode the two disagreed, and a host value never reached the cells. The cells now use the same resolved range as the legend.

Added (selection, linked views and navigator, ADR-041, ADR-042)#

See ADR-041 and ADR-042 and the migration notes.

• Item selection and activation. <Chart> and the thirteen Cartesian wrappers take selection (mode: 'single' | 'multiple', itemKey), selectedItems (controlled) or defaultSelectedItems (uncontrolled), onSelectionChange(selection, change) and onItemActivate(item, source), also inside events; ChartOptions.selection. An item is ChartItemRef {seriesId, key, interval?}: the series identity and the value of the item key, never an array index; a grouped bucket carries its interval. New public types ChartItem, ChartItemKey, ChartItemRef, ChartSelectionChange, ChartSelectionEvents, ChartSelectionOptions, ChartSelectionProps, ChartSelectionState.

• Selection for every reader. A click selects and activates; Space selects and Enter activates the focused item; Shift+F10 and the ContextMenu key open the context menu. A selected item is outlined (in Highlight under forced colours), read "…, selected" in the screen-reader table and in the focus announcement, and each change is announced. A hidden, zoomed-out or regrouped item stays selected but inactive; an uncontrolled selection drops removed rows with source: 'update'.

• Host words. Keys charts.accessibility.selectedState, itemSelected, itemDeselected, selectionHint, activationHint in the key contract and in every platform language.

Changed (selection, linked views and navigator, ADR-042)#

• Behaviour — linked views link by value. A <SyncGroup> shares the x value under the pointer or keyboard focus and the zoomed x range as values, and each member shows them over its own rows: two charts with other rows, sizes or series now show the same dates. Members that read x differently (another axis kind or temporal semantic) no longer follow each other, the y range is no longer linked, a member that unmounts withdraws what it shared, and ranges that arrive faster than a chart renders no longer echo between two charts.

• Behaviour — the navigator draws compound series. Candlestick and OHLC as a low–high band with the close, range area and range bar as a band, a box plot as a min–max band with the median; hidden series are left out; gaps stay gaps (a missing value was drawn as 0); long series keep every spike (extrema per pixel column). Date rows on an ordinal-time axis are placed by date (they were all drawn at the left edge).

Changed (Level 1 budgets and evidence, ADR-039, ADR-040)#

See ADR-039 and ADR-040 and the migration notes.

• Breaking — percentage stacks take raw values (W9). stackedPercentage (BarChart, and new on AreaChart and AreaSeriesOptions) draws each value as its share of the visible members of its stack; hiding a series restacks to 100 %, and a hidden member has no share. Mixed signs keep their direction (ADR-020). Axis, tooltip, table, announcement and segment labels read percentage points; CSV stays raw. stackTotal and stackTotalTolerance are removed.

• Breaking — honest options (W10). ChartOptions.background is removed. Scalar, categorical, hierarchical, graph, heatmap and timeline props no longer accept the props they cannot act on (colors, tooltip, contextMenu, onZoomChange, onLegendToggle, animation, per family; also inside events). An area's fillOpacity now acts in gradient mode too (the top of the gradient; default 0.4).

• Breaking — exports return promises (W11). exportAsPng, exportAsSvg, exportAsCsv and exportAsPdf resolve when the file is handed over and reject with an error when it could not be produced; exportChartAsSvg is asynchronous. New onExportError event; context-menu export failures are reported instead of swallowed. Image exports wait until the chart is still. New report: {title, subtitle, caption} export option (ChartExportReport) and PDF font option (ChartPdfFont); PNG embeds the host's same-origin web font. Standalone families export their own rows as CSV instead of doing nothing.

• Breaking — invalid input shows the unavailable state (W12). A sankey cycle or unknown node, an empty or inverted scalar range, a negative or cyclic hierarchy and an inverted explicit axis domain render the translated charts.unavailable state with a development diagnostic instead of throwing (sankey) or drawing a degenerate chart.

• Two y axes. One binding (axis.id ?? axis.position) for every stage; an unknown yAxisId falls back to the default axis everywhere, with a diagnostic. CrossLineOptions.yAxisId binds a reference line to an axis. Fixed: the right y axis stood on the left edge of the plot, its labels inside the plot.

• Fixed: a bottom or top axis took the unit of vertical series (an age axis under a percentage area read "30%").

• Fixed (PH5-01): the outer labels of a truncating category or ordinal-time axis stay inside the chart.

• Accent themes (W18): the active-ui accent themes no longer replace the measured categorical palette.

• Evidence: performance budgets for the accepted workloads (benchmark:browser fails on a breach), detached-DOM and heap measurement in the cleanup suite, and type-checked documentation examples.

Changed (readable presentation, ADR-037, ADR-038)#

Charts stay readable and distinguishable as width shrinks, series multiply and translations lengthen (W7, W8, ADR-037, ADR-038). No prop changed; the defaults did, and every dashboard looks different.

• Palette (W7). The default categorical palette is hue-distinct: blue, orange, teal, pink, violet, green, sky, ochre, crimson, slate, with its own lighter values in dark mode. Every colour reaches 3:1 against page and card; the first six stay distinct under simulated protanopia, deuteranopia and tritanopia. colors and per-series colours still win.

• Colour roles. Tokens at the owner (@workspace/active-ui themes.css): --chart-sequential-min/-max replaces --chart-heatmap-min/-max (the heatmap is its one reader; a host that set the old names sets the new ones), plus the new --chart-diverging-* and --chart-on-fill-dark/-light.

• Text on marks (QR-4). Inside bar labels, funnel segments, sunburst arcs, treemap tiles and headers and heatmap cells take the on-fill colour that reaches 4.5:1 against what they sit on; a label that no on-fill colour makes readable moves outside a free-standing bar or is left out. The funnel and heatmap luminance heuristics are gone; the funnel's value line is no longer drawn at 80 % opacity.

• Second encoding. A line series from the seventh palette slot on, or whose colour repeats past the palette, draws a dash pattern that follows its identity, in the plot and in the legend key. lineDash wins.

• Text floors (W8). The layout scale runs from 1.0 at 600 px to 0.9 at 320 px (it was 0.75 up to 500 px), and responsive text never goes below 10 px (ticks, labels) or 12 px (legend). Fixed 9 px texts (treemap values, sunburst outer arcs, timeline dates, small heatmap cells, pie and nightingale values) are 10 px. A text that does not fit is left out, not shrunk.

• Tick measurement. The canvas measured tick labels in its default 10px sans-serif, because it ignores a font stack with var(); it now measures the host font, and measures again once fonts have loaded. Axes show fewer ticks where labels used to touch, and vertical axes are a few pixels wider.

• Dense categories (PH3-01). A category axis with less than 4 px per category no longer rounds or pads its bands, and a bar is at least 1 px wide: a 1,000-category chart on a 1,120 px plot draws every bar instead of none.

• Plot edges (PH3-03, PH4-01). A candlestick, OHLC, box plot, bar, range bar or waterfall on a continuous x axis without an explicit domain gets half a glyph of room at both ends; the first and last glyph are whole and hoverable in every engine.

• Legend (AC-B1). A legend that does not fit its height folds behind a "Show N more" / "Show fewer" button (aria-expanded) instead of scrolling without a cue. New host keys charts.legend.showMore and charts.legend.showFewer, in every language of @workspace/locales.

• Organisation chart. The initial fit never shrinks node text below 10 px; a tree that does not fit starts on its root, and keyboard focus pans to the node it reaches.

• Motion (W8). Default entrance 400 ms (was 600, standalone families up to 800), stagger 30 ms per series (was 80) capped at 200 ms; funnel segments and hierarchy levels use the same pace. Explicit animation settings still win; reduced motion still turns motion off.

• Screen-reader table (PH1-03). The Cartesian data table sits in a clipping container and no longer widens a narrow page.

• Forced colours. The first six line series and their legend keys get system colours with distinct patterns.

Changed (complete information paths, ADR-035, ADR-036)#

What a chart draws can be read without sight or pointer (W5, W6, ADR-035, ADR-036).

• Compound glyphs are one item (W5). Candlestick, OHLC, box plot, range bar and range area now have hover targets and keyboard stops: one per glyph, covering its whole value extent. Range bar and box plot had none by an earlier decision, which W5 reverses. The default tooltip lists every value role with its host word (charts.role.*) instead of the letters O H L C, the keyboard announcement states every role, and the data table has one column per role instead of an empty cell.

• SingleTooltipData.roles (new public type ChartValueRole) carries the roles to a custom tooltip renderer.

• Standalone families have a data table (W6). Pie, donut, funnel, radar, nightingale, radial bar, heatmap, treemap, sunburst, sankey, org chart, timeline, gauge, linear gauge and bullet render a screen-reader table with their own structure (category and share, matrix, path, source and target, parent, track, value with range, target and zones). It follows accessibility.dataTable and cannot widen a narrow page. Gauge, linear gauge and bullet now render a fragment (the SVG plus the table).

• Waterfall. The table lists each step and its running total, and the announcement states both. A zoomed waterfall keeps the running total of the steps before the window; before, it restarted at zero (PH3-02).

• Instants keep their time in the tooltip, crosshair, table and announcement (datetime preset); before, rows of one day read the same (PH1-02). A calendar date stays a day.

• Standalone announcements (pie, donut, funnel, nightingale, radial bar, radar, heatmap, treemap, sunburst, sankey) read the value in the chart's notation (12,400), as the table does, instead of the raw number (12400).

• Legend announcements use the name the legend item shows; an unnamed compound series was announced with an empty name.

• New host keys (every language, ADR-028): charts.role.open, high, low, close, min, q1, median, q3, max; charts.accessibility.seriesRole, roleValue; charts.dataTable.category, value, share, series, name, parent, path, source, target, date, track, measure, zone, range, detail.

• Accessibility statement. docs/accessibility/ACCESSIBILITY.md is an evidence-scoped, AA-oriented support statement without a certification claim; the supported AT pairs are NVDA with Chrome or Edge and VoiceOver with Safari. No human AT run is recorded yet.

Changed (truth-preserving data preparation, ADR-033, ADR-034)#

Reduction and grouping may make a chart faster; they no longer change what the data means (ADR-033, ADR-034).

• Hidden series leave the automatic domain (W17). Hiding a line or a non-stacked bar now rescales the axis to the series still drawn, as hiding a stacked series already did. An explicit min or max is unchanged.

• Reduction replaces LTTB. Above maxPoints rows (default 500, 0 turns it off), lines and areas keep, per pixel column, every series' first, last, lowest and highest row, every stacked-area top edge and both sides of every gap, bucketed on the actual x value (number, time, log, sqrt, or the rank on an ordinal-time axis). Every displayed row is a source row. Before, LTTB sampled by row position on the first series only and could drop a null gap, a secondary series' spike, categories, scatter points, waterfall steps and the rows of a compound series next to a line.

• Families that are never reduced (W3). Bars (category or time x), scatter, histogram, waterfall, candlestick, OHLC, ranges, box plots, lollipops and dumbbells keep every row; next to a reduced line, every row they draw is kept. A chart with a waterfall is not reduced at all, so its running totals are computed on every step. A category x axis is never reduced. Charts below the density of their plot (at most four rows per series per pixel column) draw every row, as before; the long price series shape at desktop width now lists all its days in the data table instead of 500.

• maxPoints on LineChart and AreaChart. The threshold is reachable from the two wrappers whose families reduce.

• Grouping by role. Candlestick and OHLC group as first open, highest high, lowest low and last close; range-area and range-bar as lowest low and highest high; a bar's error bounds and a scatter's size follow the value's method. Every field is written under the series' own key (the 'ohlc' and 'range' methods no longer write hard-coded open/high/low/close fields or a [low, high] tuple). On a single-valued series, 'ohlc' and 'range' fall back to the type's default with a development diagnostic.

• One grouping policy per chart. A chart groups every series or none: a series with dataGrouping: false (or {enabled: false}), or a waterfall, histogram, box plot, lollipop, dumbbell or horizontal series, keeps the whole chart ungrouped, with a development diagnostic. Before, an opt-out on a later series was ignored and that series was averaged.

• GroupMeta.count is now the number of source rows in the bucket's interval (it counted the first series' values); GroupMeta.raw describes the first series with a value in the bucket.

• Raw and displayed data (W4). The screen-reader table and keyboard announcements describe the displayed rows: a reduced table is described as showing N of M rows, a grouped table reads each x cell as its interval and adds a column with the number of source rows, and a grouped point's announcement names both. The CSV export (handle and context menu) writes the chart's full raw data; copy-as-table now writes the raw rows of the visible range instead of the displayed ones.

• New host keys (every language, ADR-028): charts.accessibility.reducedData, groupedData, interval, sourceCount and groupedPoint.

Changed (resolved series model, ADR-031, ADR-032)#

Every stage of a Cartesian chart now reads one description of each series (ADR-031, ADR-032). Visible corrections a consumer notices without changing any code:

• Series identity (W1). A series is identified by its id, or else by its type and primary value key. A series the host adds is drawn; a user's legend hide stays with its series when the host adds, removes or reorders series; a series the host removes and adds back is visible again; colours and exit animations follow the series, not its position. Two series with the same identity are reported in development. visible: false now means "starts hidden" consistently: the series is not drawn, stacked, hit or counted until the user shows it in the legend (before, it was drawn but not interactive). Categorical legends (pie, funnel, nightingale, radial bar, radar) follow the category (or series) the same way.

• Hidden stacked series (W2). A hidden series no longer lifts the stack: the visible series restack onto zero and the automatic domain follows the visible stack.

• Bars start at zero (W16). The automatic value domain of bar, histogram, lollipop and waterfall marks includes zero (not on a log axis); an explicit min or max still wins.

• Stacked domains. A line on the same axis as a stack contributes its own extent instead of being added to the stack sum; bar and area stacks are separate stacks in the domain, as they already were in the geometry; horizontal stacked bars get a stacked x domain.

• Orientation and scale. A horizontal range bar and points on a sqrt x axis get a numeric domain and are drawn inside the plot.

• Category position. Points, lines, areas, candlestick and OHLC glyphs, hit points, annotations, vertical reference lines and the synchronised crosshair sit at the centre of their category, where the tick label is; bars are centred in their column (the gap between grouped bars is split over both sides).

• Axis binding. A series bound to a second y axis (yAxisId) is drawn on that axis's scale; line, area, scatter, candlestick, OHLC, box-plot, histogram, waterfall and range renderers projected on the default axis before.

• Hit geometry. After a legend toggle, grouped-bar hover targets are the drawn bars; a hidden series has no hover target.

Removed (breaking)#

• The root entry publishes the chart contract only (ADR-029). Removed from @workspace/active-charts: the renderer building blocks (SvgRenderer, the *Series components), axis and grid-line components, overlays (Annotations, ChartContextMenu, CrossLines, Crosshairs, ChartNavigator, BrushOverlay, ZoomSelectionOverlay, SyncCrosshair, GradientLegend, AccessibleDataTable, VoronoiOverlay, ChartTooltipContent, TooltipFadeWrapper, ChartLegend), ResponsiveContainer, all internal hooks (useLayout, usePreparedData, useScales, useVoronoi, useChartTooltip, useLegend, useChartDefaults, useChartHandle, usePeriodSelector, the touch, zoom, animation and keyboard hooks, useSyncState, useSyncPublish), scale, layout and data helpers (createChartScale, computeLayout, lttb, validateChartData, applyMissingDataStrategy with its MissingDataStrategy type (no chart option used it), the grouping internals, computeHistogramBins, computeWaterfallPositions, …), the CSV building helpers (buildCsvString, formatCsvValue, deriveColumnsFromOptions), appendLegendToSvg, resolveCssVariables, ACTIVE_CHARTS_THEME, resolveColor, normalizeDataLabelOption, the animation, touch and tooltip constants, and the utilities getSeriesColor, resolveCollisions, estimateLabelRect, mean, median, localPoint. No consumer used them. Migration: none for the documented API; a host that composed these parts uses <Chart options> instead.

• Formatter re-exports removed. formatNumber, formatCurrency, formatDate, formatDateTime, formatFractionAsPercent, formatPercentagePoints and their option types come from their owner, @workspace/active-i18n/formatters.

• GeoChartProps removed. It had no implementation; a geographic chart will bring its own props type.

Added#

• A browser benchmark (pnpm --filter @workspace/active-charts benchmark:browser, no retries) with the Phase 3 baseline in docs/PERFORMANCE.md.

• id on every series type (candlestick, OHLC, box plot, waterfall, range area, range bar, dumbbell, lollipop) and on the wrapper series configurations (LineChart, AreaChart, BarChart, LollipopChart, ScatterChart, RadarChart). Optional; the derived identity applies without it.

• Root exports for types a consumer needs to name: AxisFormatter, AxisTickValue, CategoryAxisTickValue, NumberAxisTickValue, TimeAxisTickValue, CategoryAxisConfig, NumberAxisConfig, TimeAxisConfig, AccessibilityOptions and its three option types, KeyboardAnnouncementMode, AnimationType, ExitAnimationType, ExitPhaseOptions, ChoreographyLayer, Period.

Fixed (consumer-visible)#

• CSV and clipboard export are safe for spreadsheets (ADR-030). Text fields, and the header row, go through the delimited-text boundary of @workspace/active-utils: always quoted, a carriage return or tab no longer breaks a row, and text a spreadsheet would execute as a formula (=…, @…, -1+1) is neutralised. Numbers, booleans, instants and declared calendar days stay unquoted machine literals. "Copy as table" uses tab-separated quoting instead of the CSV rules. Derived CSV columns now include the price keys of candlestick/OHLC, the low/high keys of range series and the box-plot keys (these exports contained only the x column).

• Data grouping keeps every series: a grouped multi-series chart aggregated only the first y key, so the other series rendered empty.

• Histogram bins: rows without a finite x value are skipped instead of counted as 0, explicit bins ranges are honoured as bin boundaries, and the default bin name formats its bounds in the chart's presentation instead of raw numbers.

• One Infinity value no longer empties a numeric axis; non-finite values are left out of the domain.

• Technical indicators: two indicators of the same kind and period on different source keys no longer overwrite each other (the key gains the source key when it differs from the default); a period that is not an integer ≥ 1 yields null instead of NaN.

• minPixelInterval is a hard floor: when it exceeds targetPixelInterval, ticks now stay at least minPixelInterval apart instead of the floor being lowered to the target.

• Timers of the tooltip auto-dismiss, the legend click debounce and the long-press no longer fire callbacks after unmount.

• onAnimationComplete({type: 'update'}) fires after a data-update animation; it never fired, and the update state never ended.

• GaugeChart, LinearGauge and BulletChart with min === max render an empty range instead of NaN geometry.

• SankeyChart with only zero-valued links renders like an empty chart instead of NaN paths; SankeyChart and OrgChart fire onAnimationComplete({type: 'load'}) once on mount.

• HeatmapChart context-menu cell lookup no longer confuses cells whose x or y value contains |.

• A cancelled touch no longer opens the context menu through the long-press.

• A legend at the bottom, left or right now reports a double-click isolate through onLegendToggle and announces toggles and isolates to screen readers, as a top legend already did.

Changed (breaking)#

• A chart no longer speaks English and no longer reads the translator sideways from active-i18n (ADR-028, 2026-09-18). The translator comes from the t prop or from <ChartDefaults t>, and without either every public entry point throws a configuration error: every wrapper, <Chart>, PeriodSelector, AccessibleDataTable, useKeyboardNavigation and the default fallback of ChartErrorBoundary. All hardcoded texts (about seventy, most of them screen-reader text and keyboard announcements, plus two Dutch tooltip labels) go through the ChartTranslationKey key contract.

• Removed: useChartTranslations and fallbackTranslate. New exported types: ChartTranslationKey, ChartTranslationVariables. ChartTranslateFn now takes a contract key; any host translator with a string key remains assignable.

• generateAriaLabel(options, t) and applyIndicators(data, indicators, t, sourceKey?) take the translator as an argument.

• A combination chart's accessible name uses full type names (bar chart/line chart instead of bar/line chart).

• A time axis declares temporalSemantic: 'calendarDate' | 'instant', and without that declaration the chart fails (ADR-027, 2026-09-17). Required in the type on every 'time' and 'ordinal-time' axis, including the default x-axis of LineChart, AreaChart, RangeAreaChart, CandlestickChart and OhlcChart (where xAxis is now required), and at runtime via <Chart>, including the implicit ordinal-time axis of a <Chart> without axes. The string shorthands xAxis="ordinal-time" and xAxis="time" are gone.

• useChartAxisFormatters().date(semantic, preset?) takes the semantic as its first argument.

• TimelineChart: TimelineEvent.date is display text and is shown verbatim in the tooltip, the announcement and the aria-label, as on the marker label; useTimelineKbd no longer has a locale option.

Changed#

• A chart's presentation comes from its locale prop or from <ChartDefaults locale>, and otherwise the chart fails visibly (ADR-026, 2026-09-16). The 'en' fallback of <Chart>, of the chart-local context and of useChartAxisFormatters/useKeyboardNavigation has been removed; without an owner the entry point throws a configuration error. A nested <ChartDefaults> now refines the enclosing provider instead of replacing it. ChartLocaleOverride has been removed from the public API (zero consumers).

• The accessibility documentation no longer claims WCAG 2.1 AAA or a verified screen-reader matrix (2026-09-25, Enterprise Parity Programme Phase 1). Neither was backed by a recorded run, and known gaps contradict them: compound series show empty data-table values, the standalone families have no data table, and OHLC, range and box-plot series have no keyboard stepping. accessibility/ACCESSIBILITY.md now states what each family provides and at which evidence level; the replacement claim is an open decision (W6). No runtime behaviour changed.

• Documentation now states the known limits of automatic reduction and data grouping (ACHARTS-01, ACHARTS-06): default LTTB above 500 rows can drop a null gap, another series' extreme, categories, scatter points, waterfall steps and compound rows; compound series are not grouped. Stale README, API, architecture and recipe examples were repaired to the current contract (temporal x-axis declaration, height, tooltip renderer parameters, formatter presets). No runtime behaviour changed.

Fixed#

• A calendar date no longer shows the previous day on any surface (ADR-027). Under a zone west of UTC, 2026-01-01 rendered as 31 Dec 2025 on the axis, and the tooltip, crosshair, parent row, screen-reader table and keyboard announcement each showed their own reading (a raw ISO string in the table, a parsed string in the tooltip). All surfaces now read the value through the declared semantic; the CSV export writes a calendarDate column as YYYY-MM-DD.

• The parent row groups ticks on the day its label shows, no longer on the runtime's local fields (ADR-027).

• The internal elements of the standalone wrappers follow the app's presentation (ADR-026). Tooltip and series labels of, among others, Heatmap, Pie and Funnel read a chart-local context that was never set and showed English notation, even under <ChartDefaults locale>.

• The chart context-menu labels use the infinitive and sentence case (context-menu standardisation, 2026-08-31). In Dutch, Kopieer waarde became Waarde kopiëren, Kopieer als tabel became Als tabel kopiëren, Zoom naar hier and Pan naar hier became Hierheen zoomen and Hierheen pannen, Reset zoom became Zoom resetten, Export became Exporteren, and Exporteer als PNG/SVG/CSV/PDF became Exporteren als …. In English the UI Title Case disappeared (Pin to Top -> Pin to top). Only the TEXT changed: the same keys, the same actions, the same interaction. The norm lives in docs/standards/PAGE_STANDARDS.md section "A context-menu item names the action" ("Een contextmenu-item noemt de handeling"); lint-context-menu-label.mjs guards its mechanically checkable half.

[5.0.0] - 2026-08-22#

Axis ticks are now resolved once, by one engine, and every consumer of a tick reads that result: the axis labels, the grid lines, the axis margin and the export. The immediate defect was a value axis over [0, 22] rendering twenty-three crammed labels in 130 pixels; the cause was that four layers each computed their own answer, and that integerTicks discarded the density budget the renderer had already calculated. See ADR-024 and ADR-025, and migration/MIGRATION-NOTES.md for the upgrade.

Removed#

• AxisConfig.integerTicks / AxisOptions.integerTicks. It generated twenty-plus ticks and filtered the non-integers out afterwards, which cannot control density by construction, and it silently overrode a caller's tickCount. Replaced by deriving the smallest meaningful step from valueSemantics — the declaration the library already has for what a value means (WS-13 / PP-045). {kind: 'count'} means whole numbers because that is what a count is; no second flag says it again.

• AxisConfig.gridLine.numTicks / AxisOptions.gridLine.numTicks. Grid lines had their own density, which is how twelve grid lines ended up under twenty-three labels. Grid lines now always follow the resolved ticks of their axis. A deliberate minor/major grid contract does not exist today; when it is wanted it will be designed as one.

• Axis props numTicks, tickValues, tickFormat, integerTicks, rotation, autoRotate; XAxis prop width; XAxis/YAxis prop numTicks; XGridLines/YGridLines prop numTicks. These components no longer choose anything; they receive a resolved ticks object and draw it.

Added#

• core/ticks/ — the tick engine. resolveTicks is the single authority. Interval-first: pick a nice step from {1, 2, 2.5, 5} × 10ⁿ, then generate, then measure, then coarsen if the labels do not fit. Public helpers: chooseNiceStep, enumerateNiceSteps, generateTicksForStep, niceDomainForStep, resolveTickBudget, semanticTickQuantum, hasDuplicateAdjacentLabels, getTickPixelPosition.

• AxisConfig.tickInterval. A fixed step in domain units. Stronger than tickCount; an unreadable choice warns in development but is still honoured, because an explicit statement is not silently discarded.

• AxisConfig.targetPixelInterval (default 72 vertical / 100 horizontal) and AxisConfig.minPixelInterval (default 32 / 40). The target drives how open the axis looks; the floor is a readability guarantee that no automatic resolution and no tickCount may cross. The old single minTickSpacing = 24 played both roles and was a reasonable floor but a hopeless target.

• Calendar-aware ticks for ordinal-time axes. Ticks land on the first observation of each week, month, quarter or year rather than on every n-th data point, so a 30- or 90-day window reads as a calendar.

Changed#

• tickCount now works. It is a target: the pixel floor and the semantic quantum remain constraints, but nothing overrides it behind the caller's back. The precedence tickValues > tickInterval > tickCount > automatic is documented and covered by tests.

• Axis margins are measured, not estimated. The left/right reservation now comes from measureTextWidth over the actual resolved labels. The previous 8 chars × 7px + 16 estimate reserved 82px for labels needing 30 — over ten percent of the plot width on every count chart in the repository.

• Category axes keep their labels longer. A category label is an identity, so rotation and truncation now come before thinning. Time-series axes are unchanged in that respect: there a label is a position, and thinning costs nothing.

• Category thinning uses a uniform stride anchored on the LAST value, with strides forming a doubling chain so a coarser step is always a strict subset of a finer one. Labels therefore disappear on resize without the remaining ones shifting. The previous sampleEvenly produced irregular gaps (indices 0, 2, 3, 5, 6 for seven days over five labels).

• The legend no longer takes plot space (ADR-025). It is rendered as HTML outside the ResponsiveContainer and is now the sole owner of its own height. Every chart with a legend gains ~30px of plot area, and two same-height charts side by side align again when only one has a legend.

Fixed#

• A value axis can no longer render two adjacent ticks with the same label. hasDuplicateAdjacentLabels inspects the real formatter output, so it also covers compact notation, consumer closures and every locale.

• Grid lines coincide with their labels. They previously used scale.ticks(undefined) (d3's default of ten) while the axis used its own count.

• Axis no longer re-formats labels the resolver already produced. A second formatting pass could diverge, because the boundary-aware date formatters read the tick index and the full tick list.

Also released here#

This release also cuts the work that had been accumulating under [Unreleased] since 4.1.0 — the WS-02 formatter re-exports, the WS-13 ChartValueSemantics declaration and the theme-token rename. Two of those carried their own ### Breaking notes and were waiting for a major to land in; their entries follow below, unchanged.

Why major#

Public props were removed (integerTicks, gridLine.numTicks) and the internal axis components changed shape. Independently of that, ADR-025 changes the rendered height of the plot area for every chart carrying a legend, which is a visible change on 72 call-sites. Both are contract changes, not fix size.

Added#

• ChartValueSemantics: a series declares what its values mean, once (WS-13, PP-045, 2026-08-17). Until now only the axis was served: the app passed a closure, and a closure is behaviour you can call but cannot derive anything from. The tooltip and the screen-reader table fell back to one generic shape heuristic (Number.isInteger(v) ? 'integer' : 'decimal-2'), so a chart with a currency axis showed € 1.235.000 to a sighted reader and said 1.234.567,89 to a screen-reader user. That is not a matter of taste; it is a materially different quantity.

  The declaration is generic and owner/domain-blind: number, count, money (with an explicit currency), price (currency plus a declared price precision) and percent (with its stored unit explicit). Unit and precision are two independent properties — money EUR + 4 decimals, fraction-as-percent + 3 decimals and price in EUR + its own precision must all remain expressible, so a chart never derives that currency means two decimals.

  It lives on AxisOptions/AxisConfig (the usual place — one axis normally carries one unit) and on SeriesOptionsBase (the exception, for a chart with two units on one axis); the series wins. Axis, tooltip, split tooltip, screen-reader table and keyboard announcement all read the same declaration. Without a declaration nothing changes — the pre-WS-13 fallback stands, so the repair reaches exactly as far as the declaration does. CSV/data export is untouched by construction: it never took a presentation input (PP-013).

Changed#

• Screen-reader output of custom accessible columns now follows the resolved presentation (WS-11 / CR-A11, 2026-08-16). SeriesColumn.formatter received (value, row) and therefore knew the value but not its notation. Two bar modes wrote past the shared formatters as a result: stacked percentages emitted `${v}%` and error bars concatenated raw numbers. A reader under a comma-decimal presentation heard 12.5% while the visible axis showed 12,5%.

  The signature is widened additively to (value, row, context), where context: AccessibleFormatterContext carries the chart's own presentation input — nothing else. Single- and two-argument formatters remain valid, because a function with fewer parameters is assignable in TypeScript.

  Consequences for the bar plug-in, both with the source unit stated explicitly rather than inferred from magnitude:

  • stacked percentages go through formatPercentagePoints(v, 'decimal-1', …) — percentage points by definition (the stack sums to stackTotal), never a fraction. The preset mirrors the tooltip rather than the axis: a table cell shows one value, and integer would round 12.5 to 13 in the only output a non-sighted reader has;

  • error-bar value, low and high all go through formatNumber(v, integer|decimal-2, …) — the same rule the default cell and the visible tooltip already used.

  Visible output moved with it: the default error-bar tooltip formatter of BarChart formatted its value but concatenated raw bounds. It now uses the same rule, so visible and assistive output cannot diverge.

  Nothing here changes the package boundary. The context carries a generic presentation and no administration, tenant or profile concept; machine CSV is untouched and still takes no presentation at all.

• Machine CSV no longer infers date-only semantics from a clock value (CORR-09, 2026-08-15). formatCsvValue treated any UTC-midnight Date or ISO string as a calendar day and truncated it, so a genuine instant of 2026-01-19T00:00:00.000Z left the export as 2026-01-19 — time and type gone, and unrecoverable. Midnight is a clock reading, not a meaning.

  Semantics are now declared or lossless: the new CsvValueSemantic ('date' | 'dateTime') can be supplied per column key through CsvExportOptions.columnSemantics on buildCsvString/exportChartAsCsv; without a declaration the full value is kept. No locale, no presentation context — the machine boundary stays presentation-immune (PP-013).

  Migration: a column that really is a calendar day must now say so. An undeclared Date exports as a full ISO instant, which re-reads as the same value; the previous output re-read as a different type.

Added#

• locale accepts a presentation-context object in addition to a language code. The new public type ChartPresentation (string | (DatePresentationContext & NumberPresentationContext)) applies to the locale prop of every chart, ChartDefaults.locale and all internal pass-through points; the value goes unchanged to the central active-i18n formatters. A bare language code remains fully valid ("notation follows the language") — existing consumers do not change. The package stays tenant-blind: no knowledge of administrations, profiles or settings; the consumer composes the context in the app layer.

• useChartAxisFormatters(presentation?) / createChartAxisFormatters: shared axis-formatter factories (number, currency, fractionAsPercent, percentagePoints, date) that resolve their presentation from ChartDefaults — the replacement for the hand-written axis closures in the apps.

Changed#

• Screen-reader text follows the chart's presentation (screen-reader text is presentation). The sr-only data table no longer formats numbers with the browser locale and no longer formats dates as ISO strings, but uses the central formatters with the chart presentation; the keyboard announcement of Cartesian charts formats the y-value (previously the raw JS number); the scalar aria-labels of gauge, linear-gauge and bullet format their numbers and percentages centrally. The English prose words in those labels ("of", "zone", "target") are deliberately left untouched — prose translation is a separate i18n follow-up.

Breaking#

• The formatter re-exports follow the preset API of active-i18n. formatPercent no longer exists; the barrel and utils/format.ts re-export formatFractionAsPercent and formatPercentagePoints (source unit in the name) plus the types NumberFormat/NumberPreset/ PercentPreset. formatNumber takes a closed preset instead of a free Intl.NumberFormatOptions bag.

Changed#

• Numeric type: 'number' axes without their own formatter or format string get a locale-aware default formatter. Until this change such an axis fell back to d3's tickFormat() with US punctuation, so an nl reader saw 1,234.5 on the axis next to a tooltip showing 1.234,5. Log axes deliberately keep the d3 behaviour (label suppression of non-significant ticks).

• The internal share, legend, ring and zoom labels of pie, nightingale, radial-bar, treemap, funnel, radar, heatmap, org-chart and the stacked-percentage defaults of bar format through the central presentation layer with the chart locale, instead of toFixed/${v}% with a fixed dot notation. The tooltip, crosshair and split-tooltip defaults have been moved to the same presets.

Breaking (theme)#

• ChartThemeOverride.success / .warning / .destructive are renamed positive / negative / caution, and they now write --color-chart-positive / -negative / -caution instead of --color-success / --color-warning / --color-destructive.

  Zero consumers in the monorepo: all twenty theme={{…}} call sites (nineteen in tests, one in an admin demo) set only foreground, card or mutedForeground. No compat shim, in line with CLAUDE.md Critical Rule 12.

Changed#

• This package no longer reads semantic UI colours. --color-success, --color-warning, --color-info and --color-destructive belong to @workspace/active-ui. There they carry a text contrast contract (4.5:1) that does not apply to a chart mark; as long as both roles shared one value, an accessibility retuning on the UI side silently shifted candlestick, OHLC, waterfall and sparkline — and vice versa. No type binds a colour string to a role, so this passed typecheck, lint and the full test suite green.

  Migrated: candlestick-series, ohlc-series, waterfall-series, sparkline, cross-lines, the theme object and two JSDoc locations. The values of the new tokens equal the old ones, so no chart changed colour. See the addendum to ADR-007 and active-ui ADR-013.

• core/overlays/cross-lines.tsx reads its defaults from ACTIVE_CHARTS_THEME.crossLine instead of from its own literals. Found along the way: the two sources had diverged — the theme object said band.fill: var(--color-muted) while var(--color-warning) was rendered, and the field nobody read was the one the documentation described. The theme object now carries the values that were actually shown (4,4 dashes, opacity 0.1), so there is no visual change.

• ACTIVE_CHARTS_THEME.colors.success/warning/destructive are renamed positive/negative/caution. These fields had zero readers inside the package, as did the whole crossLine sub-object until the change above.

Fixed#

• Documentation drift in ARCHITECTURE.md §5.1. The code sample of ACTIVE_CHARTS_THEME diverged from the source in four places: the bare var(--chart-N) form instead of var(--color-chart-N), five series colours instead of ten, a status key that does not exist, and axis fields (tickStroke, labelColor, titleColor, gridStroke) the theme object never had. Replaced by an excerpt from the source.

[4.1.0] - 2026-06-01#

Stacked area charts now stack at the geometry level. Previously <AreaChart stacked> only scaled the y-axis to the cumulative total while every area was still drawn from the plot floor (overlapping). Each stacked area now sits on a per-point baseline — positive segments stack upward from zero, negative segments downward — consistent with stacked-bar mixed-sign semantics (ADR-020). Stroke, markers, path-morph animation and the tooltip hit-test all follow the stacked coordinate. See ADR-023.

Added#

• Stacked-area geometry (incl. mixed-sign). <AreaChart stacked> (and the low-level area series with stacked: true) renders true stacked bands with a per-point y0 baseline. Mixed-sign data stacks positives up / negatives down from the zero-line. Non-stacked area is unchanged (still anchored at the plot floor). The stacked-baseline source is shared with the renderer and the hit-test, so the tooltip lands on the stacked band rather than the raw value.

Why minor (not major)#

No public API or prop shape changed and all non-stacked area rendering plus all bar/percentage stacking is byte-identical (regression anchors: 2150 tests green, unchanged assertions). The bump above patch (4.1.0, minor) reflects newly-defined, consumer-visible behaviour for stacked area (geometry + the docs claim that area "stacks" is now true — O-2 closed). Additive, not breaking.

[4.0.0] - 2026-05-31#

PNG/SVG/PDF export now reproduces the chart's live colours and fonts: a per-chart theme override and var(--x, fallback) syntax (in colour and font-family) are resolved correctly instead of being lost (AC-A4). See ADR-022.

BREAKING CHANGES#

• resolveCssVariables(svgClone) → resolveCssVariables(svgClone, scopeElement). The exported helper now requires a second argument: the live, in-DOM element to resolve CSS variables against (the chart's <svg>, which sits inside its theme scope). This is the only correct source — the detached clone cannot resolve its own scoped variables. All in-tree callers (the PNG/SVG/PDF export routes) pass the original svgElement. The major bump is on contract grounds: a public export's signature changed. Consistent with the v3.0.0 precedent (removed public createDefinedAccessor), the major is justified by the public-API change itself — not by the size of the change or the (zero) number of external callers. See migration note below.

Fixed#

• Export honours the per-chart theme override. CSS variables are now resolved against the chart's own scope element (getComputedStyle(svgElement)) instead of document.documentElement. Because custom properties inherit, a scoped --color-* (set by theme={...}) wins, so the export shows the same colours as the live chart. The PNG background colour is resolved the same way.

• var(--name, fallback) is honoured. The previous regex mis-parsed the name when a fallback was present (var(--color-foreground, #1f2937) captured color-foreground, #1f2937 as the name and left the reference literal). A balanced-paren parser now splits name/fallback correctly and resolves the fallback recursively (var(--a, var(--b, #fff))).

• font-family var() is resolved too. Axis labels use font-family: var(--font-sans, …); an unresolved var() there is invalid in a standalone SVG and made text fall back to the default font. font-family is now part of the resolved attributes, so the export is fully var()-free.

Migration#

• If you call resolveCssVariables directly, pass the chart's live <svg> element as the second argument: resolveCssVariables(clone, svgElement). There is no compatibility default — the scope element is required (an optional default-to-document would silently reproduce the bug). See migration/MIGRATION-NOTES.md.

• The high-level export API (ChartHandle.exportAsPng/exportAsSvg/exportAsPdf, <Chart>'s export) is unchanged — no consumer action needed there.

Notes#

• All other behaviour is unchanged. The live-chart rendering and the server-side pdf-worker route (which screenshots the live DOM and never used this resolver) were already correct.

[3.2.0] - 2026-05-31#

Axis tick labels and cartesian data labels now use accurate canvas-backed text measurement: long custom-formatted axis labels no longer overlap, the first/last tick label no longer clips at the plot edge (AC-V5), and data-label collision hiding is based on real label widths instead of a 0.6×fontSize estimate (AC-B3). See ADR-021.

Fixed#

• Axis tick-label overlap (AC-V5a). On number/log/time x-axes with autoRotate off, the tick count came from a width/70 density heuristic that ignored label width, so long custom-formatted labels overlapped. Tick labels are now thinned by measured width: overlapping labels are dropped, the two domain endpoints are always kept, and the thinning is anchor-aware (a start/end-anchored edge label reserves its true horizontal extent). Short, well-spaced labels and truncating axes (category/ordinal-time) are unchanged.

• First/last tick-label edge-clip (AC-V5d). The outermost tick labels were middle-anchored and overflowed the plot edge by half their width. The leftmost tick is now start-anchored and the rightmost end-anchored (by pixel position, so reversed axes work). Gated to non-truncating axes, so category/ordinal-time labels keep their middle anchor.

• Data-label collision accuracy (AC-B3). estimateLabelRect (bar, line, scatter, histogram, waterfall data labels) now measures label width with the shared canvas measurer instead of 0.6×fontSize, so labels are hidden/shown based on their real rendered width.

Changed#

• New internal utils/measure-text.ts — one canvas-backed measureTextWidth (with a character-count SSR fallback) now serves both the axis label layout and the data-label collision. axis.tsx's former private measurer was promoted into it; no public API changed.

Notes#

• Minor (not major): no public API/prop shape changed, and the axis/label behaviour only changes where labels actually overlapped or clipped before. Positive-path layouts (short labels, truncating axes, pie/gauge) are unchanged. The bump above patch reflects the consumer-visible layout improvement.

• Deliberately narrow: the 0.58-ratio utils/text-measurement.ts (pie/gauge/funnel/nightingale/radial-bar/bullet/linear-gauge) and the legend-export.ts canvas measurer were left untouched. Broad measurement consolidation is tracked separately.

[3.1.0] - 2026-05-31#

Mixed-sign / negative values in stacked bar charts now render correctly: positive segments stack up from zero, negative segments stack down from zero (AC-A1). Adds an absolute-sum percentage-normalisation (P1) so stackedPercentage works for mixed-sign data. See ADR-020.

Added#

• Mixed-sign stackedPercentage (P1 / absolute-sum). When a stackedPercentage stack contains a negative value, each segment renders at |value| / Σ|value| × stackTotal (keeping its sign for direction) and the value-axis is pinned to a symmetric [-stackTotal, stackTotal]. All-positive stackedPercentage data is unchanged — it still uses the consumer-pre-normalised contract (the row-sum gap stays by-design). General auto-normalisation of all-positive raw values remains future work (AC-B2), which will reuse this helper rather than add a second implementation.

Fixed#

• Stacked bar domain is mixed-sign correct. computeNumericDomain's stacked branch previously pinned min to 0 and used per-row total sums, so negative segments fell outside the domain. It now derives max from the per-row positive-sum and min from the per-row negative-sum (zero-line always in-domain). An all-negative stack now clamps max to 0 and renders downward instead of blank/clipped.

• Stacked bar baseline accumulates by sign. computeStackBaselineMap now keeps independent positive (up) and negative (down) running totals, so a negative segment stacks below zero on top of preceding negatives instead of being painted above the zero-line. Positive-only stacks are byte-identical to before.

• Negative-bar data-labels. An outside data-label on a negative bar now hangs below the bar's value-end (with bottom-edge auto-flip to inside) instead of floating above the zero-line detached from the bar. Positive bars are unchanged.

Notes#

• This is a minor (not major) release: no public API/prop shape changed and all positive-only stacked rendering is pixel-identical. The bump above patch reflects newly-defined, consumer-visible behaviour for mixed-sign stacks.

• Stacked area is out of scope here and still renders overlapping from the plot floor (the domain fix corrects its axis extent only). Real area-stacking is tracked as a new feature in ROADMAP.md §4.

[3.0.0] - 2026-05-30#

Adds a non-finite-projection guard so a value ≤ 0 on a log axis renders as a gap instead of a broken NaN path. Closes the shared root-cause behind AC-V1 (log-axis NaN coordinates) and AC-V3b (NaN path-tweens). See ADR-019.

BREAKING CHANGES#

• createDefinedAccessor removed from the public export surface. Its sole role — the defined accessor for gap rendering — is superseded by the projection-aware isDefined predicate returned from createSeriesAccessors ({xAccessor, yAccessor, isDefined}). This is a breaking change to the public contract (hence the major bump on the v1.0.0 stability promise), even though no consumer imported it.

• Internal: prepareMissingData's second parameter is now the isDefined predicate ((d) => boolean) instead of yKey: string. Not part of the public export surface.

Fixed#

• Non-finite projections no longer leak NaN/±Infinity coordinates. callScale now returns undefined for a non-finite scale result (e.g. a value ≤ 0 on a scaleLog), honouring the already-documented "undefined-on-rejection" contract of the projection helpers. Previously the NaN passed the typeof === 'number' check and the ?? 0 fallback did not catch it, producing a broken line/area path and silent NaN path-tweens.

• Every renderer now treats an unprojectable point as a gap/skip, not as pixel 0. Path series (line, area, range-area) break the path; point/rect/ segment series (scatter, box-plot, bar error-bars, range-bar, dumbbell, lollipop, histogram, waterfall) and the overlays (annotations, cross-lines) omit the element. The hit-test (Voronoi) already skipped unprojectable points via its == null guard and is fixed by the central guard alone.

Added#

• Dev-only diagnostic. A deduped console.warn (per axis-type + value) fires in development when a finite numeric value projects to a non-finite result (e.g. ≤ 0 on a log axis), making the otherwise-silent gap diagnosable. Production rendering is unchanged.

Migration#

• If you imported createDefinedAccessor, switch to the isDefined predicate from createSeriesAccessors(xKey, yKey, projectX, projectY). (No datyx or geneax consumer imported it; this is contract-hygiene, not a code migration.)

• No runtime config change is required. Charts on a log axis that previously rendered a broken path through a ≤ 0 value now show a clean gap there.

[2.0.0] - 2026-05-29#

First major since the 2026-05-18 baseline reset. Makes the x-axis tick formatter value type honest per wrapper, so the date-on-category trap is a compile-time error instead of a silent runtime invalid-date label.

BREAKING CHANGES#

• Axis-type-honest formatter typing. Each Cartesian wrapper now narrows the tick formatter value to its default scale: string for category-default wrappers (BarChart, WaterfallChart, BoxPlotChart, RangeBarChart, DumbbellChart, LollipopChart), Date | string for time-default wrappers (LineChart, AreaChart, RangeAreaChart, CandlestickChart, OhlcChart), and number for number-default wrappers (ScatterChart, Histogram). Consequence: formatDate(v as Date, ...) on a (default) bar chart no longer compiles, because v is string. Fix by pre-formatting a label and using the category axis, or by passing an explicit time type. See MIGRATION-NOTES.md.

• Dumbbell/Lollipop xAxis is now optional. Both default to category at the type level, resolving the prior "explicit xAxis required" runtime dissonance.

• The internal CartesianXKeyDiscriminator / CartesianTimeLikeAxis / CartesianCategoryAxis helpers are replaced by CartesianXKeyCategoryDefault / CartesianXKeyTimeDefault / CartesianXKeyNumberDefault (and a narrowed CartesianXKeyTimeOnly). These were not part of the public export surface.

Added#

• Dev-only runtime guard: a single console.error per dataset when a Date value reaches a category (scaleBand) x-axis, catching type bypasses (as / any / untyped data). Production rendering unchanged.

• New per-axis-type config types CategoryAxisConfig, TimeAxisConfig, NumberAxisConfig.

Notes#

• The narrowing is uniform per wrapper, not per branch: opting into a non-default scale via an explicit type does not re-narrow the formatter value. This is a deliberate trade-off to keep (v) => ... inferable without an explicit type (per-branch narrowing makes TypeScript fall back to implicit any). Functionally safe: formatDate accepts both strings and dates. See DECISIONS.md.

[1.8.1] — 2026-05-29#

Documentation#

• QR-4 — date-on-category-axis guidance. Documents the silent invalid-date trap (a Date xKey on a category/scaleBand axis is stringified to a non-ISO string, so a formatDate(v as Date, …) formatter renders common.placeholder.invalidDate as the literal tick label). No source/type change — the runtime behaviour is unchanged; this release makes the behaviour discoverable.

  • API.md §9.1 — new Default x-axis per chart table (bar-class charts default to category), a formatter value runtime type per axis type table, and a warning block with the two correct patterns.

  • New recipe page recipes/DATE-AXES.md — monthly bars, daily lines, range-comparison snippets.

  • DECISIONS.md — QR-4 (e) recorded as a deliberate non-implementation: a per-axis-type strict formatter-narrowing on AxisConfig would be a breaking change to the public x-axis discriminator (type-level time-like default vs. runtime category default on bar-class wrappers). Continues the v1.8.0 decision to keep the wide AxisTickValue default.

[1.8.0] — 2026-05-26#

Added#

• Typed axis-formatter signature (QR-4). AxisConfig.formatter and AxisOptions.label.formatter now accept (value: AxisTickValue, ...) => string instead of (value: unknown, ...) => string. AxisTickValue is the union Date | string | number — an honest representation of what the runtime can produce across all scale types. Newly exported:

  • AxisTickValue — base union of all possible tick-value runtime types.

  • TimeAxisTickValue (Date | string) — for 'time' / 'ordinal-time'.

  • NumberAxisTickValue (number) — for 'number' / 'log' / 'sqrt'.

  • CategoryAxisTickValue (string) — for 'category'.

  • AxisFormatter<V extends AxisTickValue = AxisTickValue> — generic formatter-signature alias.

  Consumers can opt into stricter typing by using AxisFormatter<TimeAxisTickValue> etc. when declaring their formatter. The default (without a type argument) stays permissive for all existing call sites.

  Background: during the datyx-v3 FormSection migration two consumer-side bugs surfaced (Number(v) on an ISO string from ordinal-time, (v as Date).getUTCMonth() on a string). The old unknown signature gave no hint about what consumers could expect at runtime. Full rationale in DONE.md §2026-05-26.

Notes#

• Non-breaking for TypeScript consumers: unknown is contravariant-assignable to AxisTickValue. Concrete narrowing casts such as v as Date keep working (Date ∈ union).

• Internal axis-rendering call sites (x-axis.tsx, y-axis.tsx) were adjusted with explicit as AxisTickValue casts. The runtime flow is identical — the cast tells TypeScript that the d3-axis callback payload fits within the typed signature.

[1.7.5] — 2026-05-22#

Performance#

• TR-9 — ChartGeometryContext referential stability. Before this change, <Chart>'s useMemo around buildChartGeometry produced a new ChartGeometry instance on every render whenever one of its deps (options, xScale, yScales, layout) was referentially unstable — which, under real-world consumer-side data instability, cascades through useScales. Consequence: all useChartGeometry() consumers re-rendered, and React.memo on the 13 series renderers + <SvgRenderer> was effectively inactive. Now the geometry bundle is reused through a structural-equality wrapper as soon as its contents are identical to the previous instance — the provider value stays reference-equal, memoized consumers do not re-render. A stability test (S1: unstable upstream + identical contents) proves N → 1 renders per unrelated parent toggle.

Added (internal)#

• useStableChartGeometry in src/hooks/use-chart-geometry/use-chart-geometry.tsx. A wrapper around buildChartGeometry that compares the geometry bundle field by field with the previous instance and reuses the previous instance when the contents are equal. <Chart> consumes it instead of a direct useMemo(buildChartGeometry, [...]). buildChartGeometry stays pure — the stabilisation lives in the wrapper layer. Not exported from src/index.ts (ADR-009 narrow discipline respected).

• Type-aware scale-contents compare. isScaleContentEqual compares scale.domain() + scale.range() element-wise. A naive Object.is(a.scale, b.scale) compare would fail under upstream instability because useScales produces new d3-scale instances on every data-ref change. Element comparison via isScaleElementEqual handles the scaleTime edge case (Date instances compared via getTime()); linear/log/sqrt/band/point/ordinal work with Object.is on number/string elements.

• Safety rail — STABILISE_MAX_AXES = 8. For pathologically large axis sets (>8 y-axes) the compare-cost-versus-re-render-cost trade-off no longer holds; the wrapper then falls back to a plain rebuild without compare. No current chart type reaches this threshold; the rail is a safety valve for future callers.

Changed (internal)#

• <Chart> uses useStableChartGeometry instead of an inline useMemo(buildChartGeometry, [options, xScale, yScales, layout]). One-line replacement plus import update.

• Stability test (src/hooks/use-chart-geometry/use-chart-geometry-stability.test.tsx) — 3 new tests that verify the invariant:

  • S1 — unrelated parent re-render with identical-content inputs → 1 render in total (no re-renders through a memoized consumer).

  • S3 (regression guard) — an actual data change → the consumer does re-render (correct behaviour, no stale-data regression).

  • S1 variant — with a memoized upstream the fix also stays stable (no regression versus the previous useMemo chain).

• ADR-009 supplemented (not superseded) with the new invariant: "provider-value contents-equal ⇒ instance-equal" — see DECISIONS.md § ADR-009.

Notes — what surfaced during execution#

• Analysis gap: the TR-9 analysis document (removed after completion) §3.1 noted "scale → compare via Object.is, stable as long as useScales is stable upstream". During execution it turned out that S1 (consumer-side data instability) cascades precisely through useScales into scale-ref instability — that was the source of the S1-red-after-fix finding. Walt's stop-moment discipline (report, do not force) led to option (i) — extending isAxisContextEqual with a scale-contents compare — without scope creep beyond TR-9.

• The stability test also uncovered a test-design bug: ConsumerSpy was initially not wrapped in React.memo, so the measuring instrument itself re-rendered on parent renders regardless of context. With memo around ConsumerSpy the test replicates the production pattern exactly (all 13 production series renderers are memo'd) and measures what we want to measure.

• Compare cost in practice: for typical charts (1-2 y-axes) ~15-25 primitive Object.is ops + 4-8 element compares per scale. Negligible compared with the re-render work it saves.

Verification#

• pnpm --filter @workspace/active-charts typecheck — 0 errors

• pnpm --filter @workspace/active-charts test — 2109/2109 green (was 2106; +3 stability tests)

• pnpm --filter @workspace/active-charts lint — 18 warnings (same baseline; motivated eslint-disable react-hooks/refs around previousRef.current access inside useMemo per the React docs)

• pnpm typecheck (monorepo) — 38/38 tasks green

• grep "✅" docs/ROADMAP.md — 0 hits

This fully closes Phase 3 (Performance) of the Traycer v2 follow-up. ROADMAP §1 (Traycer v2 follow-up) is empty after this release.

[1.7.4] — 2026-05-22#

Performance#

• TR-8 — computeWaterfallPositions out of the tooltip hot path. Previously getTooltipExtras called computeWaterfallPositions(allData, ...) on every hover event on a Waterfall chart; that function recomputes the cumulative-position array in O(n) over all steps. With fast mouse movement over large waterfalls (>100 steps) this recomputed on every mousemove frame — wasted work, because the positions are identical between hover events. Now the positions are pre-computed once per chart render in <Chart> via a useMemo over [options.series, preparedData]; getTooltipExtras does an O(1) array lookup. Pure performance refactor — tooltip content pixel-identical.

Changed (internal)#

• getTooltipExtras signature: the 3rd parameter changes from allData?: readonly ChartDatum[] to waterfallPositions?: readonly WaterfallPosition[]. The caller passes pre-computed positions for the active series instead of raw data. Per §7.14 no dual API is kept (no fallback compute path).

• useChartTooltip exports buildWaterfallPositionsBySeries + the WaterfallPositionsBySeries type. <Chart> consumes the helper in a useMemo; the result is a Map<seriesIndex, WaterfallPosition[]> passed as the 6th optional argument to handleShowTooltip and as the 5th optional argument to handlePinTooltip. buildTooltipData does the per-series lookup via point.seriesIndex.

• Scope boundary held. Only the tooltip call site in series-tooltip-extras.ts moves; the other two production callers of computeWaterfallPositions (hooks/use-scales/use-scales.ts for domain computation, core/series-plugins/waterfall-plugin.tsx for hit-testing) are untouched. Both run per render, not per mousemove — no hot-path problem. The parked "computeWaterfallPositions 3-call-site duplication" observation in DECISIONS.md has been updated: no longer "3 call sites with a tooltip hot-path concern", but "2 call sites, both per render, no performance bottleneck".

Test suite#

• 2 waterfall tests in series-tooltip-extras.test.ts migrated to the new signature — the caller now builds the pre-computed computeWaterfallPositions(...) array and passes it to getTooltipExtras. Assertions identical in substance (same value/cumulative/isTotal expectations). Test name "allData-context" → "pre-computed positions" for readability.

• 2106/2106 green on identical assertions; no test added or removed.

Verification#

• pnpm --filter @workspace/active-charts typecheck — 0 errors

• pnpm --filter @workspace/active-charts test — 2106/2106 green

• pnpm --filter @workspace/active-charts lint — 18 warnings (same baseline)

• pnpm typecheck (monorepo) — 38/38 tasks green — no external consumer affected

• grep "✅" docs/ROADMAP.md — 0 hits

Phase 3 of the Traycer v2 follow-up is now partly closed (TR-8 done; TR-9 ChartGeometryContext Map reference-equality remains open — requires an analysis phase).

[1.7.3] — 2026-05-22#

Fixed (consumer-visible behavior)#

• The tooltip stays inside the chart card and follows the cursor — three coupled fixes. v1.7.1's cursor-follow contract (ADR-016) let the tooltip visually exceed the chart area in order to stay close to the cursor; the viewport clamp caught the viewport edge. Visual verification revealed three problems that had to be addressed together:

  • Bug A — Cartesian margin-offset blind spot in the projection. useTooltipPosition computed projVpX = containerRect.left + clampedX + xOff for the viewport clamp. For Cartesian charts (chart.tsx via TooltipPositioner), + marginLeft is added to the rendered position after the hook. The projection missed that translation → the viewport clamp underestimated the actual tooltip position by marginLeft pixels → tooltip overflow on cards at the viewport edge. Present in limited form before v1.7.1 (the same blind spot in the parentElement version), masked by the bounds flip; fully visible after v1.7.1.

  • Bug B — no flip at the card boundary. v1.7.1's "always follow the cursor, the viewport is the only boundary" rule lets the tooltip exceed the chart card. Walt's requirement: the tooltip must NEVER fall outside the chart card. v1.7.3 introduces the card-boundary flip: when the tooltip would exceed the container bounds on its current side AND the other side does fit, it flips to the other side of the cursor (stays with the cursor + inside the card). Conceptually a different mechanism from the bounds flip removed in ADR-016: that one triggered at the plot boundary (smaller than the card) and pulled the tooltip away even where there was room; this one triggers only at the card boundary and flips to follow the cursor on the other side, not away from it.

  • Bug C — first-hover measurement on an empty div. The <TooltipFadeWrapper> between the TooltipPositioner div and the content delays children mounting by one render (FadeWrapper's mounted state starts false and flips via useEffect). The hook's first getBoundingClientRect therefore read 0×0; setMeasured(true) was called anyway → the tooltip got visibility:visible at the default offset before the card/viewport clamp could fire. Subsequent re-measures (on mousemove) did read the real size and corrected it — hence "first hover wrong, subsequent correct". v1.7.3 skips zero-rect measurements and uses a ResizeObserver on the tooltip div to re-measure when the size transitions from 0 to real.

• Priority rule for a tight card: when the tooltip fits inside the card on neither side (tooltip larger than the card), cursor-follow wins over card bounds — the tooltip stays with the cursor and may stick out slightly beyond the card. The viewport boundary is the absolute hard limit that is never exceeded. Three levels: cursor → card (may be given up) → viewport (never given up).

See ADR-017 for the three coupled decisions and the cross-link to ADR-016 (why the plot-boundary flip had to go then, and why the card-boundary flip is added now — a different mechanism, a different trigger, preserving cursor-follow where possible).

Changed (internal)#

• useTooltipPosition options: new originX?: number + originY?: number fields (default 0). Cartesian's TooltipPositioner (in chart.tsx) passes originX: marginLeft, originY: marginTop so that the hook's card and viewport projection accounts for the post-hook coordinate-system translation. 11 standalone call sites unchanged (default 0 suffices).

• Test suite — 2 v1.7.1 tests removed, not reshaped (§7.14 applied consistently: tests that assert removed functionality are deleted, not bent):

  • "does not flip when the cursor is near the right edge of bounds" — asserted v1.7.1's "always follow the cursor up to the viewport boundary", replaced by v1.7.3's card-boundary flip.

  • "does not flip when the cursor is near the bottom edge of bounds" — same reason, Y-axis variant.

• 6 new tests added: card flip on X, card flip on Y, cursor wins on a tight card, originX/Y in the projection (Cartesian scenario), ResizeObserver re-measure (Bug C reproduction), plus the viewport hard-limit test kept with an adjusted rationale. ResizeObserver is mocked in tests (jsdom does not have it).

[1.7.2] — 2026-05-22#

Changed (internal)#

• TR-2 — useAnimationCompleteTimer consumed by GaugeChart + TimelineChart. Both charts held the same inline useEffect + setTimeout block that v1.6.2 already extracted into useAnimationCompleteTimer for PieChart + HeatmapChart. Drift-fix per Traycer v2 §11 R-2: the shared hook is now consumed by 4 standalone wrappers. Behaviour identical (same setTimeout duration, same cleanup, same callback-invocation under !enabled).

• TR-4 — normalizeParentLevelOption(_axisType) parameter removed. The unused _axisType: AxisType | undefined parameter on normalizeParentLevelOption was retained per a JSDoc comment "for API stability and future axis-specific defaults" — but no concrete axis-specific default was planned. Removed per Traycer v2 §11 R-4. Three call-sites (x-axis.tsx, compute-layout.ts ×2, use-auto-axis-formatters.ts) adapted in the same change; AxisType import dropped from utils/normalize-options.ts (no longer referenced after the parameter removal).

• TR-5 — internal-only symbols dropped from public barrel. Removed from src/index.ts and src/types/index.ts: ANIMATION_TYPE_WHITELIST, EXIT_ANIMATION_TYPES, resolveAnimationTypeForSeries, callScale, packBarPositions, unpackBarPositions. All six are still available as direct imports from their source files (types/animation-types.ts, types/scales.ts, hooks/use-data-transition/use-data-transition.ts) for in-package consumers; only the barrel surface is reduced. Per Traycer v2 §11 R-6: these are internal implementation details (per-series animation constraints, D3-scale polymorphism escape-hatch, animation-transition packing) that external consumers should not depend on. Two in-package callsites (svg-renderer.tsx, series-accessors.test.ts) migrated to direct imports.

Removed#

• TR-1 — src/hooks/use-dark-mode/ dead folder deleted. The stub file (export {}; + a comment saying "No consumers any more. This file + the use-dark-mode/ folder can go") had been left behind since v1.6.2's useDarkMode removal. No consumers; physically removed per Traycer v2 §11 R-1.

Documentation#

• TR-3 — README de-Geneax-genericised. "Enterprise chart library for the Geneax platform." → "Enterprise chart library."; the package-structure section's themes/ # Geneax chart theme → themes/ # ACTIVE_CHARTS_THEME (post-MP-9 rename, drift). Per Traycer v2 §11 R-3.

• TR-6 — core/series-plugins/ added to README package-structure overview. The T2+T9 plug-in system was a major architectural feature (13 Cartesian plug-ins + _shared helpers + registry) but absent from the README's structure table since its introduction. Per Traycer v2 §11 R-7.

• TR-7 verified, no action. Traycer v2 §11 R-7 flagged colors-prop JSDoc-parity on Scalar charts — re-verification showed LinearGauge (lines 50–55) and BulletChart (lines 54–57) already carry the equivalent JSDoc note that GaugeChart (lines 50–55) carries. Audit drift; no change needed.

Notes#

This release closes Phase 2 (Discipline-Slip Detection) of the post-maturity roadmap from docs/traycer/traycer-v2-output.md (removed after completion). All six hygiene items + the audit-drift verification were bundled in one session per the original effort estimate (~1.5 hours). Test-suite 2103/2103 green on identical assertions, no test adapted. Lint baseline unchanged (18 warnings, well within the 100-cap). Monorepo-wide typecheck 38/38 tasks green — no consumer in apps/ reaches into the removed barrel symbols. Phase 3 performance items (TR-8 memoize computeWaterfallPositions in tooltip path, TR-9 ChartGeometryContext Map reference-equality) remain open on the ROADMAP.

[1.7.1] — 2026-05-22#

Fixed (consumer-visible behavior)#

• The tooltip now consistently follows the cursor on all 24 chart types. Before v1.7.1 (ADR-014 default #2: "edge-clamp left/top: always on") the tooltip flipped to the other side of the cursor as soon as its projected position would fall outside the chart bounds. On edge-to-edge chart types (treemap, funnel, sunburst, nightingale, radial-bar, sankey, heatmap), where the cursor is regularly close to the bounds, that constantly broke the cursor-follow agreement — treemap drill-down was visually always broken because of it, funnel intermittently. On Cartesian types (bar/line/area/scatter/etc.) the same happened only rarely because the axis margins keep the cursor away from the bounds edge: the same rule violation, just triggered less often. The bounds flip + bounds edge clamp has been removed; the tooltip now follows one rule — follow the cursor, the viewport clamp keeps it on screen. See ADR-016.

• The viewport clamp now uses the correct positioning ancestor as its anchor. Before v1.7.1 the QR-7 viewport clamp read el.parentElement.getBoundingClientRect() — which resolved to the <TooltipFadeWrapper> div (a 0×0 box that sits below the chart SVG in document flow), not to the actual positioned ancestor. The resulting viewport projection was offset by roughly the chart height from the actual tooltip position; viewport overflow was wrongly detected or missed. Masked as long as the bounds flip often kept the tooltip inside the plot area; it would have become visible after removing that flip. The hook now takes a required containerRef in its options object — the caller explicitly passes the positioning ancestor the viewport clamp computes against. All 12 call sites migrated in the same session (one API, no fallback path — §7.14). See ADR-016.

Changed (internal)#

• useTooltipPosition signature: the options parameter is now required, with containerRef: RefObject<HTMLElement | null> as a required field. Before v1.7.1 the whole options object was optional; the anchorClamp flag stays optional within the object. Not publicly exported (internal to @workspace/active-charts), so no breaking change for consumers — only package-internal call sites affected.

• Test suite — 3 flip-asserting tests removed, not reshaped. They tested functionality that deliberately disappears (per §7.14: do not "rescue" a test by asserting something else when the underlying behaviour has changed). Replaced by three new viewport-clamp tests that verify the cursor-follow agreement + the correct containerRef anchor. Removed tests, for traceability:

  • "flips to the left when first hover is near the right edge" (was use-tooltip-position.test.tsx:116)

  • "flips up when first hover is near the bottom edge" (was use-tooltip-position.test.tsx:164)

  • "clamps to left edge when mouse is already past the left boundary" (was use-tooltip-position.test.tsx:188)

[1.7.0] — 2026-05-22#

Changed (consumer-visible behavior)#

• QR-5 (revised) — Path-C rect-bounded hit-test for Histogram + Waterfall. Before v1.7.0 both types fell back to a voronoi-only hit-test (Path B), which is less precise for rect-shaped elements — a hit now registers anywhere within the whole bin rect (Histogram) or step rect (Waterfall) instead of only near the centre. Path B remains additive as a fallback where the rect does not hit (consistent with the bar plugin since T2+T9-v2).

Added (internal)#

• computeHistogramRects + computeWaterfallRects in src/core/series-plugins/_shared.ts. Shared rect-geometry helpers for Histogram + Waterfall — one source of rect bounds, shared by the renderer and the Path-C hit-test (the same philosophy as T1-v2's computeBarGeometry for bar; no drift possible).

  • computeHistogramRects: input {bins, binValues, valueAxisDomain, projectX, projectY} → BarRectPosition[]. Math identical to the pre-v1.7.0 inline computation in HistogramSeries: barX = min(x0, x1) + barWidth = abs(x1 - x0), barY = min(valuePos, baselinePixel) + barHeight = abs(baselinePixel - valuePos) via resolveBaseline.

  • computeWaterfallRects: input {data, positions, xKey, bandwidth, projectX, projectY} → BarRectPosition[]. Math identical to the pre-v1.7.0 inline computation in WaterfallSeries: pyTop = projectY(max(y0,y1)) + barHeight = max(abs(pyBottom - pyTop), 1) (minimum 1px for zero-value steps).

Changed (internal)#

• HistogramSeries uses computeHistogramRects instead of an inline computation. The renderer + the histogram plugin's Path C now share one source of bin-rect bounds.

• WaterfallSeries uses computeWaterfallRects instead of an inline computation. The renderer + the waterfall plugin's Path C now share one source of step-rect bounds. (pyTop/pyBottom for connector-Y and label-Y are still computed inline from pos.y0/y1 — those derived positions are not part of the rect bound itself.)

• histogram-plugin.tsx + waterfall-plugin.tsx now emit BarRect[] alongside FlatPoint[]. Path C is additive — the Path B fallback is unchanged.

Scope revision (vs the original QR-5)#

The roadmap text before the step-0 inventory suggested "QR-5 rollout to 4 types: RangeBar/Histogram/Waterfall/BoxPlot — mechanical rollout of a proven pattern". The step-0 inventory refuted that assumption:

Adding Path C to RangeBar/BoxPlot would reopen deliberate earlier exclusions, not tidy things up for external use. Just as the OHLC hit-test asymmetry is parked, RangeBar + BoxPlot deliberately stay without a hit-test. An external consumer does not run into a loose end here — those types work as designed.

computeWaterfallPositions call duplication — an honest note#

The observation parked before v1.7.0 (from T3 phase 2): "three call sites each compute the same running totals". The step-0 analysis showed that this is in fact three callers of one shared function (the function itself has long lived in types/waterfall-series-options.ts), not three duplicate implementations. A real "3 → 1" consolidation would mean extending the geometry context with pre-computed positions per series (data + cache in buildChartGeometry). That is a substantial geometry-shape change outside the QR-5 scope.

What v1.7.0 did do:

• Path C in the waterfall plugin uses the same computeWaterfallPositions — no new copy. Effectively: 4 callers of 1 function (was 3); no deterioration and no new duplication.

• computeWaterfallRects accepts pre-computed positions as input, so the helper itself does not call computeWaterfallPositions — the caller decides whether/how to memoize.

The observation stands: a future session can extend the geometry context with pre-computed positions if the performance concern ever becomes demonstrable. Today computeWaterfallPositions is linear and not expensive enough to justify the scope extension.

Drift test pixel-identical#

Both renderer migrations are pixel-identical for existing behaviour. 2102/2102 tests green on identical assertions, no test adjusted. The deliberate behaviour change is the added Path-C hit-test on Histogram + Waterfall (more precise rect hit detection).

Stop moments — outcome#

• Stop moment 1 (rect-geometry helper does not deliver renderer bounds): not triggered. computeHistogramRects output identical to the pre-v1.7.0 HistogramSeries inline computation; computeWaterfallRects likewise.

• Stop moment 2 (computeWaterfallPositions call sites diverge after "consolidation"): not triggered in the adjusted sense (no consolidation to 1 caller; see the honest note above).

Verification#

• pnpm --filter @workspace/active-charts typecheck — 0 errors.

• pnpm --filter @workspace/active-charts test — 2102/2102 green on identical assertions.

• pnpm --filter @workspace/active-charts lint — 18 warnings (same baseline; temporarily 19 after the plotHeight prop became unnecessary through the helper extraction, back to 18 after a destructuring cleanup).

• pnpm turbo run typecheck (monorepo) — 28/28 tasks green.

• grep "✅" docs/ROADMAP.md — 0 hits.

Files (3 changed + 0 new)#

Changed:

• package.json — 1.6.3 → 1.7.0

• src/core/series-plugins/_shared.ts — computeHistogramRects + computeWaterfallRects + HistogramBinLike + WaterfallPositionLike added

• src/core/renderer/series/histogram-series.tsx — inline computation replaced by computeHistogramRects; unused plotHeight prop removed from destructuring

• src/core/renderer/series/waterfall-series.tsx — inline computation replaced by computeWaterfallRects

• src/core/series-plugins/histogram-plugin.tsx — Path-C emit added

• src/core/series-plugins/waterfall-plugin.tsx — Path-C emit added

Bump choice#

Minor (1.6.3 → 1.7.0) — a consumer-noticeable behaviour improvement (more precise hit detection on rect-shaped Histogram/Waterfall).

Remaining open topics after v1.7.0#

• QR-2 — Parity-test category rollout (1 session, requires scope clarification)

• QR-3 — Round-4 live smoke check (2-3 sessions)

• Section 3 (MP-*) — only relevant for external npm publication

• TEST-1 — UPO chart snapshot regression (1 session, not urgent)

• Section 5/6 — Future chart types + features (growth)

New + existing parked observations (no open trigger):

• RangeBar hit-test absence (deliberate choice T2+T9-v2 §4.2.1) — newly parked

• BoxPlot hit-test absence (deliberate choice, no yKey) — newly parked

• computeWaterfallPositions call duplication — stays parked; real consolidation requires a geometry-shape extension

• OHLC hit-test asymmetry — parked, unchanged

• C1 (AxisContext extension) — parked, unchanged

• useVoronoi → useHitTest rename — parked, unchanged

• BarRect axis-id fields — parked, unchanged

[1.6.3] — 2026-05-22#

Added (internal)#

• QR-10 remainder — <SrOnlyAnnouncement> in src/core/accessibility/sr-only-announcement.tsx. A shared component for the keyboard-nav screen-reader live region. Before v1.6.3 this was copy-paste in 11 standalone wrappers (a 22-line block per wrapper, ~242 lines in total). After v1.6.3: one component, a 4-line call site per wrapper. API:

  TSX

  <SrOnlyAnnouncement testId="pie-kbd-announcement">  {kbd.announcement}</SrOnlyAnnouncement>

  API shape choice: testId prop + children. All 11 call sites had exactly identical structure (role="status" + aria-live="polite" + aria-atomic="true" + an identical sr-only clip style); the only differences were the data-testid value and the content expression. Children cleanly cover the dynamic content; testId covers the unique per-chart name. Hardcoded a11y attributes + clip style in the component (stop-moment-3 discipline: no priority/assertive props until a consumer needs them).

Changed (internal)#

• 11 standalone wrappers migrated: HeatmapChart, PieChart, SankeyChart, SunburstChart, TreemapChart, TimelineChart, RadialBarChart, NightingaleChart, RadarChart, FunnelChart, OrgChart. Per wrapper:

  • 22-line inline <div> block replaced by a 4-line <SrOnlyAnnouncement> call

  • Import of SrOnlyAnnouncement added next to the existing core/accessibility/ imports

  Pixel-identical: same a11y attributes (role="status", aria-live="polite", aria-atomic="true"), same sr-only clip style, same data-testid values, same content. 2102/2102 tests green, no test adjusted.

Code size#