@chipmobilesdk/rn-chart 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @chipmobilesdk/rn-chart
 
+## 0.4.0
+
+### Minor Changes
+
+- Props and formatters that were declared but never read now have an effect. `formatters.legendLabel` labels legend entries, `formatters.summary` words the values a screen reader hears, and `theme.radius` rounds bars and heatmap cells. `accessibility.summaryFormatter` already worked; `ProgressChart.orientation`, which did nothing, is gone, and the `segmentPress` and `seriesSelect` event kinds, which were never emitted, are gone from the interaction types. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Tapping the selected point again clears the selection and now reports `(null, null)` instead of the point the chart just stopped highlighting. Screen-reader stepping moves the selection rather than toggling it, so a chart with one point stays on that point. A screen reader hears a position in the app's own words through `formatters.axisLabel` rather than a raw epoch number, and the summary names the highest and lowest points by when or where they are — a single time series used to report one value and lose its lowest.
+
+  Values are checked rather than guessed at. `NaN` or `Infinity` in a known value or an instant is a `nonFiniteValue` validation error instead of a mark drawn at the origin, and a negative distribution segment is a `negativeDistributionValue` one. `DistributionChart` takes `valuesAre` to say whether its numbers are proportions or absolute amounts; inference no longer reads two counts of 1 as two full circles. A donut or pie segment is hit by the angle and radius under the finger, so the edge of a large segment selects that segment.
+
+  `HeatmapChart` draws the names of its rows and columns, and a key to its colours — the lowest and highest value with the ramp between them, as one accessible element. `ColorScaleLegend` and `ColorScale` are exported for apps that lay it out themselves. Bar charts label their value axis in round steps and put instant categories in time order, as the time-series chart does.
+
+### Patch Changes
+
+- Charts keep their memoization under the way apps actually write props. `formatters` and `TimeSeriesChart`'s `range` are compared by what they carry rather than by object identity, so writing either inline no longer rebuilds every scale and path string on each parent render. The hidden-series set, the selection callbacks and the legend toggle keep one identity, the drawn geometry is memoized apart from the selection so highlighting a point no longer reconciles the whole SVG tree, and the dataset budget is measured only in development builds. Text size is read reactively, so changing the system font size re-lays-out the chart immediately. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Internally, the chart shell is split into `useChartStatus`, `useChartFormatters`, `useChartA11y`, `ChartPlot` and `ChartStateOverlay` instead of one 600-line component; the budget warning runs in an effect rather than during render; and the bar, time-series and heatmap builders each make one pass over their points where they made several.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -150,6 +150,11 @@ Axis labels have room reserved for them: the plot shrinks to fit the widest
 value label on the left and one line of time or category labels below, so no
 label is clipped by the chart's edge.
 
+Every known value, and every instant, must be a **finite number**. `NaN` or
+`Infinity` is a validation error (`nonFiniteValue`) rather than a mark drawn at
+the origin: data that arrived broken is reported as broken. Use `unknown()` for
+a value you do not have.
+
 ## States
 
 Seven, and the package derives the two that only the data can determine:
@@ -212,6 +217,12 @@ ownership; the same callbacks fire either way.
 Every payload carries the point id, series id, value, position, and whatever
 metadata you attached. The package never navigates, fetches, or mutates.
 
+Tapping the selected point again clears the selection, and the callback is told
+so: `(null, null)`. Empty space clears it the same way. Screen-reader stepping
+moves the selection rather than toggling it, so a chart with one point stays on
+that point. A donut or pie is hit by the segment the finger is in — its angle
+and radius — not by distance to its label.
+
 Legends can also toggle series visibility. The state is uncontrolled unless
 you supply `hiddenSeriesIds`:
 
@@ -252,6 +263,18 @@ correctly in light and dark.
 Meaning never rides on colour alone: series carry dash patterns as well as
 colours, and non-value classes use textures.
 
+`DistributionChart` reads its numbers either as **proportions** (each in 0..1,
+summing to 1) or as **absolute** amounts it normalises by their own total. It
+infers which from the data, and a short sum of proportions is drawn short and
+reported incomplete rather than stretched to fill the circle. Two counts of `1`
+are ambiguous, so say what you mean when counts can be small:
+
+```tsx
+<DistributionChart datasource={ds} valuesAre="absolute" />
+```
+
+A negative segment is a validation error: a share of a whole cannot be negative.
+
 `DistributionChart` colours **segments**, not series. Palette entries are taken
 in order across every point, so one series of four points and four series of
 one point both give four colours. A point's own `color` overrides its segment;
@@ -275,6 +298,18 @@ default applies — the package never infers or converts a business unit. A
 formatter that throws degrades to the default **for that one label** and does
 not crash the screen.
 
+Four slots: `value` (drawn labels), `axisLabel` (axis ticks, and how a position
+is spoken to a screen reader), `legendLabel` (legend entries) and `summary` (the
+values inside the accessible summary; falls back to `value`).
+
+The `formatters` object itself may be written inline — the chart depends on the
+functions it carries, not on the object. The **functions** must be stable:
+define them at module scope or hold them in `useCallback`/`useMemo`, as with
+`datasource`. A formatter rebuilt every render rebuilds every scale and path
+string, which is the one thing `FR-073` exists to prevent. The same goes for
+`range` on `TimeSeriesChart`, which is compared by its `from` and `to`, so
+`range={{ from, to }}` inline is free.
+
 ## Accessibility
 
 Each chart is a single accessible element with a composed summary: what it is,
@@ -295,6 +330,11 @@ summary entirely, and `accessibility.label` replaces everything.
 <BarChart datasource={steps} title="Bước" strings={{ 'chart.family.bar': 'biểu đồ cột' }} />
 ```
 
+`HeatmapChart` names its rows and columns along the edges of the plot and shows
+the key to its colours — the lowest and highest value with the ramp between them
+— below it, as one accessible element. Pass `legend={false}` to leave the key
+out.
+
 Axis labels are thinned to fit rather than overlapped, and scale with the system
 text size up to **1.6×**; beyond that the growth is capped so the plot area
 survives.
@@ -309,8 +349,9 @@ survives.
 | Progress | 8 metrics |
 | Heatmap | 1,000 cells |
 
-Over budget, a chart **still renders and drops nothing**. It warns once per
-chart in development builds, and never in production. Aggregating or
+Over budget, a chart **still renders and drops nothing**: nothing is enforced
+and nothing is refused. It warns once per chart in development builds, and in
+production the dataset is not even measured. Aggregating or
 downsampling above these sizes is your call — the package will not silently
 decide what data to discard.
 
@@ -359,6 +400,7 @@ The single entrypoint exports these public groups:
   `STATUS_PRECEDENCE`, `DATASET_BUDGETS`, `checkBudget`, error/failure types,
   and `isChartError`
 - Interaction: selection and series interaction types plus `sameSelection`
+- Heatmap colour key: `ColorScaleLegend` and `ColorScale`
 - Theme and formatting: `defaultChartTheme`, `resolveSeriesColor`, default
   formatter helpers, `NON_VALUE_TEXT`, and public theme/formatter contracts
 - Accessibility: `buildChartSummary`, `buildPointAnnouncement`, and

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-chart",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",

package/skills/sdk-rn-chart/SKILL.md

@@ -18,18 +18,36 @@ accessibility support and enforced dataset budgets.
 - Shaping data to the datasource contract
 - Theming series colors or building a legend
 - Handling selection / interaction on a chart
-- A chart refuses to render a large dataset
+- A chart is slower than expected, or a dataset is larger than its budget
+- A formatter or a prop appears to have no effect
 
 ## Check what it deliberately does not do
 
 The README opens with `## What it does not do`. Read that first — it prevents building
 a feature this package intentionally excludes.
 
-## Datasets are budgeted
+## Dataset budgets are a development warning, not a limit
 
-`DATASET_BUDGETS` and `checkBudget` enforce size limits so charts stay at 60 FPS on
-low-end devices. When a budget is exceeded, aggregate or window the data — do not raise
-the budget. See `## Dataset budgets`.
+Nothing is enforced and nothing is refused: over budget a chart **still renders and
+drops nothing**, warns once per chart in development, and in production does not even
+measure the dataset. `DATASET_BUDGETS` and `checkBudget` are the figures and the check,
+for a consumer that wants to aggregate or window its own data. Do not debug a "chart
+refuses to render": no such behaviour exists. See `## Dataset budgets`.
+
+## Memoization has two requirements
+
+`datasource` must be referentially stable, and so must each **formatter function**
+(module scope, or `useCallback`). The `formatters` object itself may be inline, as may
+`range={{ from, to }}` — those are compared by what they carry. An unstable datasource
+or formatter rebuilds every scale and path string on each parent render.
+
+## What the numbers mean, where it is ambiguous
+
+`DistributionChart` reads values as proportions (0..1, summing to 1) or as absolute
+amounts, inferred from the data. Pass `valuesAre="absolute" | "proportions"` when counts
+could be read as shares (two counts of `1`). Known values and instants must be finite:
+`NaN` is a `nonFiniteValue` validation error, and a negative distribution segment is a
+`negativeDistributionValue` one. Use `unknown()` for data you do not have.
 
 ## Chart theming is separate from app theming
 
@@ -38,18 +56,35 @@ Charts use `ChartThemeProvider` / `useChartTheme`, not the app-wide theme provid
 
 ## Public API
 
-Runtime:
+Components — all five families are memoized, and all share `BaseChartProps`
+(`datasource`, `status`, `stateContent`, `title`, `legend`, `theme`, `formatters`,
+`strings`, `accessibility`, `height`, `style`, `footer`, selection and visibility
+props):
 
-- `ChartThemeProvider`, `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
-- `ChartLegend`, `buildLegendEntries`
-- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
-- `DATASET_BUDGETS`, `checkBudget`
-- `isChartError`
+- `BarChart` (`grouping`), `TimeSeriesChart` (`range`), `DistributionChart` (`shape`,
+  `innerRadiusRatio`, `valuesAre`), `ProgressChart`, `HeatmapChart` (`buckets`)
+- `ChartLegend`, `ColorScaleLegend`, `buildLegendEntries`, `ChartThemeProvider`
 
-Types: `MarkerKind`, `ProgressReading`, `ReferenceMarker`, `BudgetCheck`, `DatasetBudget`
+Runtime:
 
-Use `sameSelection` for selection equality — comparing selection objects by reference
-causes redundant re-renders.
+- `known`, `unknown`, `notApplicable`, `withheld`, `isKnown`, `isWithheld`, `sumKnown`,
+  `participatesInTotals`
+- `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
+- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
+- `resolveStatus`, `drawsData`, `suppressesInteraction`, `STATUS_PRECEDENCE`
+- `formatValueDefault`, `formatPositionDefault`, `formatLegendDefault`, `seriesRef`,
+  `NON_VALUE_TEXT`
+- `buildChartSummary`, `buildPointAnnouncement`, `buildTotalAnnouncement`
+- `DATASET_BUDGETS`, `checkBudget`, `isChartError`, `chartStrings`
+- `FAMILY_POSITION_KINDS`, `familyAcceptsPositionKind`, `resolveFormat`, `resolveUnit`
+
+Types: `ValueState`, `ChartDatasource`, `Series`, `DataPoint`, `Position`, `ChartFamily`,
+`ChartStatus`, `ChartError`, `SelectionRef`, `PointInteractionEvent`, `ChartFormatters`,
+`ChartTheme`, `LegendEntry`, `ColorScale`, `DistributionValues`, `ChartStrings`,
+`BudgetCheck`, `DatasetBudget`
+
+Use `sameSelection` to compare two selections; comparing the objects by reference
+reports a change that did not happen.
 
 ## Where the detail lives
 

package/src/a11y/summary.ts

@@ -8,7 +8,8 @@
  * Withheld values never enter a summary — that would leak exactly what the
  * withheld class exists to protect (FR-033).
  */
-import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import type { ChartDatasource, ChartFamily, Position } from '../contract/datasource';
+import { formatPositionDefault } from '../contract/format';
 import type { ReferenceMarker } from '../contract/marker';
 import type { ChartStatus } from '../contract/state';
 import { formatMessage } from '@chipmobilesdk/rn-core';
@@ -44,6 +45,8 @@ export interface SummaryInput<M = unknown> {
 	readonly status: ChartStatus;
 	readonly title?: string;
 	readonly formatValue: (value: ValueState) => string;
+	/** How a position is spoken; the app's axis formatter when it has one. */
+	readonly formatPosition?: (position: Position) => string;
 	readonly incomplete?: boolean;
 	/** The texts to speak; the English defaults when omitted. */
 	readonly strings?: ChartStrings;
@@ -53,9 +56,12 @@ function describeExtremes<M>(
 	datasource: ChartDatasource<M>,
 	formatValue: (v: ValueState) => string,
 	strings: ChartStrings,
+	formatPosition: (position: Position) => string,
 ): string {
-	let min: { label: string; value: number } | undefined;
-	let max: { label: string; value: number } | undefined;
+	type Extreme = { label: () => string; value: number; point: unknown };
+	let min: Extreme | undefined;
+	let max: Extreme | undefined;
+	const several = datasource.series.length > 1;
 
 	for (const series of datasource.series) {
 		for (const point of series.points) {
@@ -63,18 +69,25 @@ function describeExtremes<M>(
 			if (!isKnown(point.value)) {
 				continue;
 			}
-			const label =
-				point.position.kind === 'category'
-					? point.position.category
-					: point.position.kind === 'matrix'
-						? `${point.position.row} ${point.position.column}`
-						: series.label;
+			// Named by where the point is. A time series used to name both
+			// extremes after the series, so a one-series chart reported a single
+			// value and lost its lowest (CHT-07). Built lazily: only two are read.
+			const label = (): string => {
+				if (point.position.kind === 'category') {
+					return point.position.category;
+				}
+				if (point.position.kind === 'matrix') {
+					return `${point.position.row} ${point.position.column}`;
+				}
+				const at = formatPosition(point.position);
+				return several ? `${series.label} ${at}` : at;
+			};
 
 			if (!min || point.value.value < min.value) {
-				min = { label, value: point.value.value };
+				min = { label, value: point.value.value, point };
 			}
 			if (!max || point.value.value > max.value) {
-				max = { label, value: point.value.value };
+				max = { label, value: point.value.value, point };
 			}
 		}
 	}
@@ -83,14 +96,15 @@ function describeExtremes<M>(
 		return '';
 	}
 	const maxText = formatValue({ kind: 'known', value: max.value });
-	if (min.label === max.label) {
+	// One figure only when the highest and the lowest are the same point.
+	if (min.point === max.point) {
 		return formatMessage(strings['chart.summary.single'], { value: maxText });
 	}
 
 	return formatMessage(strings['chart.summary.extremes'], {
-		maxLabel: max.label,
+		maxLabel: max.label(),
 		max: maxText,
-		minLabel: min.label,
+		minLabel: min.label(),
 		min: formatValue({ kind: 'known', value: min.value }),
 	});
 }
@@ -149,7 +163,12 @@ export function buildChartSummary<M>(input: SummaryInput<M>): string {
 		heading,
 		statusPhrase,
 		scale,
-		describeExtremes(input.datasource, input.formatValue, strings),
+		describeExtremes(
+			input.datasource,
+			input.formatValue,
+			strings,
+			input.formatPosition ?? formatPositionDefault,
+		),
 		describeMarkers(input.datasource.markers, input.formatValue, strings),
 		input.incomplete ? strings['chart.summary.incomplete'] : '',
 	];

package/src/contract/distribution.ts

@@ -0,0 +1,44 @@
+/**
+ * What the numbers of a distribution mean (CHT-10).
+ *
+ * `proportions`: each value is already a share of the whole, in 0..1. A sum
+ * short of 1 is drawn short and reported incomplete. `absolute`: counts or
+ * amounts, normalised by their own total.
+ *
+ * Until 0.4.0 this was guessed from the values alone: anything in 0..1 was a
+ * proportion, so two segments counting 1 each drew two full circles on top of
+ * one another. The guess now also requires the shares to fit in one whole, and
+ * an app that knows can say so.
+ */
+import type { ChartDatasource } from './datasource';
+import { isKnown } from './value';
+
+export type DistributionValues = 'proportions' | 'absolute';
+
+export const DISTRIBUTION_SUM_TOLERANCE = 0.001;
+
+export function resolveDistributionValues<M>(
+	datasource: ChartDatasource<M>,
+	declared?: DistributionValues,
+): DistributionValues {
+	if (declared !== undefined) {
+		return declared;
+	}
+	if (datasource.format?.kind === 'percent') {
+		return 'proportions';
+	}
+	let sum = 0;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (!isKnown(point.value)) {
+				continue;
+			}
+			const value = point.value.value;
+			if (value < 0 || value > 1) {
+				return 'absolute';
+			}
+			sum += value;
+		}
+	}
+	return sum <= 1 + DISTRIBUTION_SUM_TOLERANCE ? 'proportions' : 'absolute';
+}

package/src/contract/errors.ts

@@ -18,6 +18,8 @@ export type ChartErrorCode =
 	| 'familyPositionKindUnsupported'
 	| 'inconsistentMatrix'
 	| 'distributionNotWhole'
+	| 'nonFiniteValue'
+	| 'negativeDistributionValue'
 	| 'declaredByApp'
 	| 'renderException';
 
@@ -34,6 +36,10 @@ const MESSAGES: Readonly<Record<ChartErrorCode, string>> = {
 	inconsistentMatrix: 'Matrix datasource rows and columns are inconsistent across points.',
 	distributionNotWhole:
 		'Distribution segments do not sum to the whole. The chart marks the total incomplete rather than rescaling.',
+	nonFiniteValue:
+		'A known value or an instant is not a finite number. Use an unknown value for missing data.',
+	negativeDistributionValue:
+		'A distribution segment has a negative value. A share of a whole cannot be negative.',
 	declaredByApp: 'The application declared this chart to be in an error state.',
 	renderException:
 		'The chart failed while rendering and was contained. See the report for details.',

package/src/contract/interaction.ts

@@ -18,7 +18,7 @@ export interface SelectionRef {
 }
 
 export interface PointInteractionEvent<M = unknown> {
-	readonly type: 'pointSelect' | 'segmentPress';
+	readonly type: 'pointSelect';
 	readonly seriesId: string;
 	readonly pointId: string;
 	readonly value: ValueState;
@@ -27,7 +27,7 @@ export interface PointInteractionEvent<M = unknown> {
 }
 
 export interface SeriesInteractionEvent<M = unknown> {
-	readonly type: 'seriesSelect' | 'visibilityChange';
+	readonly type: 'visibilityChange';
 	readonly seriesId: string;
 	readonly visible?: boolean;
 	readonly metadata?: M;

package/src/contract/strings.ts

@@ -41,6 +41,8 @@ export const chartStrings = defineMessages({
 		'chart.state.noPermission': 'Not available',
 		'chart.legend.hide': 'Hides this series',
 		'chart.legend.show': 'Shows this series',
+		'chart.legend.scale': 'Colour scale from {min} to {max}',
+		'chart.note.incomplete': 'Some values are unavailable, so totals are incomplete.',
 	},
 });
 

package/src/geometry/bar.ts

@@ -14,7 +14,7 @@ import { insetForAxes, plotBottom, plotRight } from './layout';
 import { horizontalMarkers, markerDomainValues } from './markers';
 import { rectBatchPath, type RectSpec } from './path';
 import { bandScale, domainFrom, linearScale, widenDegenerateDomain } from './scale';
-import { thinTicks, type Tick } from './ticks';
+import { niceTickValues, thinTicks, type Tick } from './ticks';
 import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
 
 export type BarGrouping = 'grouped' | 'stacked';
@@ -75,21 +75,24 @@ function stackedDomainValues<M>(
 ): number[] {
 	const values: number[] = [];
 
-	for (const category of categories) {
-		let positive = 0;
-		let negative = 0;
-
-		for (const series of visible) {
-			const point = series.points.find(p => categoryKey(p.position) === category);
-			if (point && isKnown(point.value)) {
-				if (point.value.value >= 0) {
-					positive += point.value.value;
-				} else {
-					negative += point.value.value;
-				}
+	// One pass over the points instead of a search per category and series.
+	const positive = new Map<string, number>();
+	const negative = new Map<string, number>();
+	for (const series of visible) {
+		const counted = new Set<string>();
+		for (const point of series.points) {
+			const category = categoryKey(point.position);
+			// The first point of a series in a category is the one drawn there.
+			if (counted.has(category) || !isKnown(point.value)) {
+				continue;
 			}
+			counted.add(category);
+			const sums = point.value.value >= 0 ? positive : negative;
+			sums.set(category, (sums.get(category) ?? 0) + point.value.value);
 		}
-		values.push(positive, negative);
+	}
+	for (const category of categories) {
+		values.push(positive.get(category) ?? 0, negative.get(category) ?? 0);
 	}
 
 	return values;
@@ -149,6 +152,13 @@ export function buildBarGeometry<M>(
 		}
 	}
 
+	// Instants have an order of their own. First-seen order put Tuesday before
+	// Monday when one series started a day late, and disagreed with the
+	// time-series chart drawn from the same datasource (CHT-20).
+	if (datasource.positionKind === 'instant') {
+		categories.sort((a, b) => Number(a) - Number(b));
+	}
+
 	const visible = datasource.series.filter(s => !s.hidden);
 	const excluded = countExcluded(datasource);
 	const values = [
@@ -168,7 +178,8 @@ export function buildBarGeometry<M>(
 		min: values.some(v => v < 0) ? padded.min : Math.max(padded.min, 0),
 		max: values.some(v => v > 0) ? padded.max : Math.min(padded.max, 0),
 	});
-	const yTickValues = [domain.min, 0, domain.max].filter((v, i, arr) => arr.indexOf(v) === i);
+	// Round steps a reader can count in, not the padded extremes (105.3).
+	const yTickValues = niceTickValues(domain, 4);
 	const xLabel = (c: string) =>
 		datasource.positionKind === 'instant'
 			? input.formatInstant(Number(c))
@@ -219,7 +230,7 @@ export function buildBarGeometry<M>(
 				y: top,
 				width: barWidth,
 				height,
-				radius: options.radius,
+				radius: options.radius ?? input.radius?.bar,
 			});
 
 			hitRegions.push({

package/src/geometry/distribution.ts

@@ -9,6 +9,7 @@
  * PURE. No React, no SVG.
  */
 import type { ChartDatasource } from '../contract/datasource';
+import { resolveDistributionValues, type DistributionValues } from '../contract/distribution';
 import { segmentKey } from '../contract/theme';
 import { isKnown, isWithheld, sumKnown } from '../contract/value';
 import type { HitRegion } from './hitTest';
@@ -21,6 +22,8 @@ export interface DistributionOptions {
 	readonly shape?: DistributionShape;
 	/** Donut hole as a fraction of the outer radius. */
 	readonly innerRadiusRatio?: number;
+	/** What the values mean; inferred from the data when omitted. */
+	readonly valuesAre?: DistributionValues;
 }
 
 const TAU = Math.PI * 2;
@@ -69,10 +72,11 @@ export function buildDistributionGeometry<M>(
 	// Proportions supplied directly (each in 0..1, summing to ~1) are honoured
 	// as given; absolute values are normalised by their own total. Either way we
 	// never stretch a short sum to fill the circle.
-	const suppliedAsProportions = segments.every(
-		s => !isKnown(s.point.value) || (s.point.value.value >= 0 && s.point.value.value <= 1),
-	);
-	const denominator = suppliedAsProportions ? 1 : total.total;
+	const suppliedAsProportions =
+		resolveDistributionValues(datasource, options.valuesAre) === 'proportions';
+	// Shares declared as proportions that add up past the whole are normalised
+	// rather than drawn over one another.
+	const denominator = suppliedAsProportions ? Math.max(1, total.total) : total.total;
 	const coverage = total.total / denominator;
 	const incomplete = total.incomplete || coverage < 0.999;
 
@@ -88,7 +92,7 @@ export function buildDistributionGeometry<M>(
 		let cursor = plot.x;
 
 		for (const { series, point } of segments) {
-			if (!isKnown(point.value)) {
+			if (!isKnown(point.value) || point.value.value < 0) {
 				continue;
 			}
 			const fraction = point.value.value / denominator;
@@ -135,7 +139,7 @@ export function buildDistributionGeometry<M>(
 	let angle = 0;
 
 	for (const { series, point } of segments) {
-		if (!isKnown(point.value)) {
+		if (!isKnown(point.value) || point.value.value < 0) {
 			continue;
 		}
 
@@ -180,6 +184,7 @@ export function buildDistributionGeometry<M>(
 			pointId: point.id,
 			x: cx + labelRadius * Math.cos(mid),
 			y: cy + labelRadius * Math.sin(mid),
+			arc: { cx, cy, innerRadius, outerRadius, startAngle: start, endAngle: end },
 			selectable: !isWithheld(point.value),
 		});
 	}

package/src/geometry/heatmap.ts

@@ -15,7 +15,9 @@
 import type { ChartDatasource } from '../contract/datasource';
 import { isKnown, isWithheld } from '../contract/value';
 import type { HitRegion } from './hitTest';
+import { insetForAxes } from './layout';
 import { rectBatchPath, type RectSpec } from './path';
+import { thinTicks } from './ticks';
 import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
 
 export interface HeatmapOptions {
@@ -30,8 +32,6 @@ export function buildHeatmapGeometry<M>(
 	input: GeometryInput,
 	options: HeatmapOptions = {},
 ): ResolvedGeometry {
-	const { plot } = input;
-
 	const rows: string[] = [];
 	const columns: string[] = [];
 	const rowSeen = new Set<string>();
@@ -53,9 +53,9 @@ export function buildHeatmapGeometry<M>(
 		}
 	}
 
-	if (rows.length === 0 || columns.length === 0 || plot.width <= 0) {
+	if (rows.length === 0 || columns.length === 0 || input.plot.width <= 0) {
 		return {
-			plot,
+			plot: input.plot,
 			paths: [],
 			markers: [],
 			labels: [],
@@ -66,6 +66,18 @@ export function buildHeatmapGeometry<M>(
 		};
 	}
 
+	// Row and column names are the heatmap's axes. The plot makes room for
+	// them; they were computed before and never drawn (CHT-15).
+	const columnLabels = columns.map(input.formatCategory);
+	const rowLabels = rows.map(input.formatCategory);
+	const plot = insetForAxes(input.plot, {
+		xLabels: columnLabels,
+		yLabels: rowLabels,
+		fontSize: input.fontSize,
+	});
+	const columnIndex = new Map(columns.map((column, index) => [column, index]));
+	const rowIndex = new Map(rows.map((row, index) => [row, index]));
+
 	const gap = options.cellGap ?? 2;
 	const cellWidth = plot.width / columns.length;
 	const cellHeight = plot.height / rows.length;
@@ -102,18 +114,18 @@ export function buildHeatmapGeometry<M>(
 				continue;
 			}
 
-			const colIndex = columns.indexOf(point.position.column);
-			const rowIndex = rows.indexOf(point.position.row);
-			if (colIndex < 0 || rowIndex < 0) {
+			const col = columnIndex.get(point.position.column);
+			const row = rowIndex.get(point.position.row);
+			if (col === undefined || row === undefined) {
 				continue;
 			}
 
 			const rect: RectSpec = {
-				x: plot.x + colIndex * cellWidth + gap / 2,
-				y: plot.y + rowIndex * cellHeight + gap / 2,
+				x: plot.x + col * cellWidth + gap / 2,
+				y: plot.y + row * cellHeight + gap / 2,
 				width: Math.max(0, cellWidth - gap),
 				height: Math.max(0, cellHeight - gap),
-				radius: options.cellRadius,
+				radius: options.cellRadius ?? input.radius?.cell,
 			};
 
 			if (isKnown(point.value)) {
@@ -173,17 +185,22 @@ export function buildHeatmapGeometry<M>(
 		paths,
 		markers: [],
 		labels: [],
-		xTicks: columns.map((c, i) => ({
-			value: i,
-			position: plot.x + i * cellWidth + cellWidth / 2,
-			label: input.formatCategory(c),
-		})),
-		yTicks: rows.map((r, i) => ({
+		xTicks: thinTicks(
+			columnLabels.map((label, i) => ({
+				value: i,
+				position: plot.x + i * cellWidth + cellWidth / 2,
+				label,
+			})),
+			input.fontSize,
+			plot.width,
+		),
+		yTicks: rowLabels.map((label, i) => ({
 			value: i,
 			position: plot.y + i * cellHeight + cellHeight / 2,
-			label: input.formatCategory(r),
+			label,
 		})),
 		hitRegions,
+		...(hasKnown ? { colorScale: { min, max, colors: ramp.slice(0, bucketCount) } } : {}),
 		incomplete: excluded > 0,
 	};
 }