@chipmobilesdk/rn-chart 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ All notable changes to `@chipmobilesdk/rn-chart` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-11-01
+
+Three drawing defects on the production path. **No code change is required.**
+
+### Fixed
+
+- **Axis labels are no longer clipped.** The frame handed every builder the
+  full container, so Y labels (right-aligned left of the plot) were drawn at
+  negative x and X labels fell below the bottom of the SVG: on a device a bar
+  or time-series chart showed no value scale and cut-off dates. Builders now
+  reserve room for their own labels before projecting anything, in one pass.
+- **Distribution legends match their segments.** Segments were coloured by
+  point index while the legend listed series, so a one-series donut of four
+  segments had four colours and one legend entry; four one-point series all
+  drew in the first palette colour. Segment colours now come from one resolver
+  shared by the arcs and the legend, which has one entry per segment. Point
+  colours also had their own map: they shared the series map, so a point id
+  equal to a series id overwrote that series' colour, in every family.
+- **Reference markers are drawn.** Every builder returned no markers, so
+  targets, baselines and thresholds reached the accessibility summary only.
+  Bar and time-series charts now draw them across the plot (with the domain
+  stretched to include them); progress draws its target on each bar.
+- **Progress overshoot stays inside the plot.** It started at the plot's
+  right edge and was clipped, so 118% looked like 100%. The track is now scaled
+  so the target sits inside the plot and the excess is visible beyond it.
+
+- **No phantom axis below zero on all-positive bars.** The domain was padded
+  past zero on both sides, so a bar chart with no negative value printed a
+  negative tick (`-5.5`) on top of the `0` label once labels became visible.
+
+### Added
+
+- `DataPoint.color`, a per-segment colour for distribution charts.
+- `LegendEntry.pointId`, set on distribution entries.
+- `buildLegendEntries(..., family)`: pass `'distribution'` for segment entries.
+
+### Changed
+
+- The plot area of bar and time-series charts is smaller by the space its axis
+  labels need, and `ResolvedGeometry.plot` reports that inner rectangle.
+
 ## [0.1.0] - Unreleased
 
 ### Added

package/README.md

@@ -1,12 +1,12 @@
 # @chipmobilesdk/rn-chart
 
-Domain-agnostic charts for ChipMobileSdk-family React Native apps.
-
-> **License:** `UNLICENSED`. Published publicly for use by the owner's
-> applications; no open-source license is granted.
-
-- **Version**: `0.1.0`
-- **Entrypoint**: `@chipmobilesdk/rn-chart`
+Domain-agnostic charts for ChipMobileSdk-family React Native apps.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.2.x` (see [CHANGELOG](CHANGELOG.md))
+- **Entrypoint**: `@chipmobilesdk/rn-chart`
 
 One datasource contract spans five chart families. The package knows nothing
 about nutrition, finance, health, or productivity — you hand it aggregated,
@@ -133,6 +133,23 @@ error**, not a rendering guess.
 Time is epoch milliseconds and carries no timezone. All date wording comes from
 your formatters.
 
+### Reference markers
+
+`datasource.markers` holds targets, baselines and thresholds. Those with a known
+value are drawn as dashed lines:
+
+- `BarChart` and `TimeSeriesChart` draw each one across the plot, with its
+  `label` at the right end. The value axis is stretched to include it, so a
+  threshold above every data point is still on the chart.
+- `ProgressChart` draws the target on each row's bar. A value past its target
+  is drawn as overshoot beyond that line, inside the plot: the track is scaled
+  so the target sits at `1 / min(largest proportion, 1.25)` of its width.
+- `DistributionChart` and `HeatmapChart` ignore markers.
+
+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.
+
 ## States
 
 Seven, and the package derives the two that only the data can determine:
@@ -192,20 +209,20 @@ 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.
-
-Legends can also toggle series visibility. The state is uncontrolled unless
-you supply `hiddenSeriesIds`:
-
-```tsx
-<BarChart
-  datasource={ds}
-  seriesToggleEnabled
-  hiddenSeriesIds={hiddenSeriesIds}
-  onVisibilityChange={event => updateHiddenSeries(event.seriesId)}
-/>
-```
+Every payload carries the point id, series id, value, position, and whatever
+metadata you attached. The package never navigates, fetches, or mutates.
+
+Legends can also toggle series visibility. The state is uncontrolled unless
+you supply `hiddenSeriesIds`:
+
+```tsx
+<BarChart
+  datasource={ds}
+  seriesToggleEnabled
+  hiddenSeriesIds={hiddenSeriesIds}
+  onVisibilityChange={event => updateHiddenSeries(event.seriesId)}
+/>
+```
 
 Pan, pinch-zoom, and brush-to-select are out of scope. `range` on
 `TimeSeriesChart` is a window **you** supply, not one the user draws.
@@ -235,6 +252,12 @@ 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` 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;
+a series with a single point is that segment, so its series `color` applies.
+The legend has one entry per segment, in the same colour as its arc.
+
 ## Formatting
 
 ```tsx
@@ -304,32 +327,32 @@ If you render your own narrative text near a chart — particularly text from an
 AI service or from users — moderation and content obligations are entirely
 yours. The package ships no free-text surface at all.
 
-## Public API
+## Public API
 
 `src/index.ts` is the only entrypoint. Geometry, scales, layout maths, path
 builders, the chart shell, and the SVG adapter are private so they can change
 without a breaking release.
 
-**Stable**: value semantics, `Position`, the datasource types, the five chart
-components and their base props, `ChartStatus`, the error types, interaction
-events.
-
-The single entrypoint exports these public groups:
-
-- Components: `BarChart`, `DistributionChart`, `HeatmapChart`,
-  `ProgressChart`, `TimeSeriesChart`, `ChartLegend`, `ChartThemeProvider`,
-  `useChartTheme`, `buildLegendEntries`, and their props
-- Values and datasource: `known`, `unknown`, `notApplicable`, `withheld`,
-  `isKnown`, `isWithheld`, `sumKnown`, position/series/datasource types,
-  marker helpers, and format resolution helpers
-- State and validation: `resolveStatus`, `drawsData`, `suppressesInteraction`,
-  `STATUS_PRECEDENCE`, `DATASET_BUDGETS`, `checkBudget`, error/failure types,
-  and `isChartError`
-- Interaction: selection and series interaction types plus `sameSelection`
-- Theme and formatting: `defaultChartTheme`, `resolveSeriesColor`, default
-  formatter helpers, `NON_VALUE_TEXT`, and public theme/formatter contracts
-- Accessibility: `buildChartSummary`, `buildPointAnnouncement`, and
-  `buildTotalAnnouncement`
+**Stable**: value semantics, `Position`, the datasource types, the five chart
+components and their base props, `ChartStatus`, the error types, interaction
+events.
+
+The single entrypoint exports these public groups:
+
+- Components: `BarChart`, `DistributionChart`, `HeatmapChart`,
+  `ProgressChart`, `TimeSeriesChart`, `ChartLegend`, `ChartThemeProvider`,
+  `useChartTheme`, `buildLegendEntries`, and their props
+- Values and datasource: `known`, `unknown`, `notApplicable`, `withheld`,
+  `isKnown`, `isWithheld`, `sumKnown`, position/series/datasource types,
+  marker helpers, and format resolution helpers
+- State and validation: `resolveStatus`, `drawsData`, `suppressesInteraction`,
+  `STATUS_PRECEDENCE`, `DATASET_BUDGETS`, `checkBudget`, error/failure types,
+  and `isChartError`
+- Interaction: selection and series interaction types plus `sameSelection`
+- Theme and formatting: `defaultChartTheme`, `resolveSeriesColor`, default
+  formatter helpers, `NON_VALUE_TEXT`, and public theme/formatter contracts
+- Accessibility: `buildChartSummary`, `buildPointAnnouncement`, and
+  `buildTotalAnnouncement`
 
 **Experimental** — may change in a minor: `ChartTheme` token set, `LegendEntry`,
 family-specific props (`shape`, `grouping`, `buckets`), and the
@@ -352,7 +375,7 @@ npm run lint
 npm test
 npm run typecheck:chart
 npm run pack:chart
-npm run validate:chart   # all of the above
-```
-
-The demo integration lives in `src/screens/ChartDemoScreen.tsx`.
+npm run validate:chart   # all of the above
+```
+
+The demo integration lives in `src/screens/ChartDemoScreen.tsx`.

package/package.json

@@ -1,9 +1,9 @@
 {
 	"name": "@chipmobilesdk/rn-chart",
-	"version": "0.1.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
+	"version": "0.2.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
 	"types": "src/index.ts",
 	"exports": {
 		".": {
@@ -20,6 +20,7 @@
 		"src/react",
 		"src/render",
 		"src/validation",
+		"skills",
 		"README.md",
 		"CHANGELOG.md"
 	],
@@ -41,8 +42,8 @@
 	"engines": {
 		"node": ">=22.11.0"
 	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

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

@@ -0,0 +1,69 @@
+---
+name: sdk-rn-chart
+description: "Charts via @chipmobilesdk/rn-chart: datasource contract, series theming, legends, selection, dataset budgets, chart accessibility. Use when rendering a chart, wiring chart data, theming series, or hitting a dataset size limit."
+metadata:
+  package: "@chipmobilesdk/rn-chart"
+  packageVersion: "0.1.0"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-chart
+
+Chart rendering with an explicit datasource contract, its own theme provider,
+accessibility support and enforced dataset budgets.
+
+## Use this when
+
+- Rendering any chart or adding a series
+- 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
+
+## 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` 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`.
+
+## Chart theming is separate from app theming
+
+Charts use `ChartThemeProvider` / `useChartTheme`, not the app-wide theme provider from
+`sdk-rn-theme`. Series colors come from `resolveSeriesColor`, never from hardcoded values.
+
+## Public API (v0.2.0)
+
+Runtime:
+
+- `ChartThemeProvider`, `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
+- `ChartLegend`, `buildLegendEntries`
+- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
+- `DATASET_BUDGETS`, `checkBudget`
+- `isChartError`
+
+Types: `MarkerKind`, `ProgressReading`, `ReferenceMarker`, `BudgetCheck`, `DatasetBudget`
+
+Use `sameSelection` for selection equality — comparing selection objects by reference
+causes redundant re-renders.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-chart/README.md` (~360 lines):
+
+| Need | Section |
+|---|---|
+| Scope check | `## What it does not do` |
+| First integration | `## Install`, `## Quick start` |
+| Shaping data | `## The datasource contract`, `## Value semantics` |
+| Loading/empty/error rendering | `## States` |
+| Touch and selection | `## Interaction` |
+| Colors and legends | `## Theming` |
+| Axis/label formatting | `## Formatting` |
+| Screen reader support | `## Accessibility` |
+| Size limits | `## Dataset budgets` |

package/src/contract/datasource.ts

@@ -61,6 +61,8 @@ export interface DataPoint<M = unknown> {
 	readonly unit?: string;
 	/** Overrides the series format hint. */
 	readonly format?: FormatHint;
+	/** Colour of this point's segment in a distribution chart. Ignored elsewhere. */
+	readonly color?: string;
 	/** Opaque to the package: never read, never logged, returned unchanged. */
 	readonly metadata?: M;
 }

package/src/contract/theme.ts

@@ -53,6 +53,8 @@ export interface ChartTheme {
 
 export interface LegendEntry {
 	readonly seriesId: string;
+	/** Set on distribution entries, which describe one segment rather than a series. */
+	readonly pointId?: string;
 	readonly label: string;
 	readonly color: string;
 	readonly pattern: 'solid' | 'dashed' | 'dotted' | 'dashDot';
@@ -137,3 +139,39 @@ export function resolveSeriesColor(
 ): string {
 	return override ?? theme.palette[index % theme.palette.length];
 }
+
+/** Key of one distribution segment: point ids are only unique within a series. */
+export function segmentKey(seriesId: string, pointId: string): string {
+	return `${seriesId}/${pointId}`;
+}
+
+/**
+ * Colours for distribution segments, keyed by `segmentKey`. The single source
+ * for both the arcs and the legend, so the two cannot disagree (CHT-02).
+ *
+ * Segments take palette entries in order across the whole datasource, so one
+ * series of four points and four series of one point both give four colours.
+ * A point's own `color` wins; a series with a single point is that segment, so
+ * the series `color` applies to it.
+ */
+export function resolveSegmentColors(
+	datasource: {
+		readonly series: readonly {
+			readonly id: string;
+			readonly color?: string;
+			readonly points: readonly { readonly id: string; readonly color?: string }[];
+		}[];
+	},
+	theme: ChartTheme,
+): Record<string, string> {
+	const colors: Record<string, string> = {};
+	let index = 0;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			const override = point.color ?? (series.points.length === 1 ? series.color : undefined);
+			colors[segmentKey(series.id, point.id)] = resolveSeriesColor(theme, index, override);
+			index += 1;
+		}
+	}
+	return colors;
+}

package/src/geometry/bar.ts

@@ -10,9 +10,10 @@
 import type { ChartDatasource, Position, Series } from '../contract/datasource';
 import { isKnown, isWithheld } from '../contract/value';
 import type { HitRegion } from './hitTest';
-import { plotBottom, plotRight } from './layout';
+import { insetForAxes, plotBottom, plotRight } from './layout';
+import { horizontalMarkers, markerDomainValues } from './markers';
 import { rectBatchPath, type RectSpec } from './path';
-import { bandScale, domainFrom, linearScale } from './scale';
+import { bandScale, domainFrom, linearScale, widenDegenerateDomain } from './scale';
 import { thinTicks, type Tick } from './ticks';
 import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
 
@@ -135,7 +136,6 @@ export function buildBarGeometry<M>(
 	input: GeometryInput,
 	options: BarOptions = {},
 ): ResolvedGeometry {
-	const { plot } = input;
 	const grouping: BarGrouping = options.grouping ?? 'grouped';
 
 	// Preserve first-seen order rather than sorting: the app chose this order.
@@ -153,16 +153,36 @@ export function buildBarGeometry<M>(
 
 	const visible = datasource.series.filter(s => !s.hidden);
 	const excluded = countExcluded(datasource);
-	const values =
-		grouping === 'stacked'
+	const values = [
+		...(grouping === 'stacked'
 			? stackedDomainValues(categories, visible)
-			: groupedDomainValues(datasource);
+			: groupedDomainValues(datasource)),
+		// A threshold above every bar must still be on the chart.
+		...markerDomainValues(datasource.markers),
+	];
+
+	// Labels depend only on the domain, so they are known before any pixel is,
+	// and the plot can make room for them first.
+	// Bars grow from zero, so padding past zero on a side no bar reaches only
+	// adds a meaningless tick (-5.5 under all-positive data) crowding the 0.
+	const padded = domainFrom(values, { includeZero: true, padFraction: 0.05 });
+	const domain = widenDegenerateDomain({
+		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);
+	const xLabel = (c: string) =>
+		datasource.positionKind === 'instant'
+			? input.formatInstant(Number(c))
+			: input.formatCategory(c);
+	const plot = insetForAxes(input.plot, {
+		xLabels: categories.map(xLabel),
+		yLabels: yTickValues.map(input.formatValue),
+		fontSize: input.fontSize,
+	});
 
 	const xBand = bandScale(categories, { min: plot.x, max: plotRight(plot) }, 0.25);
-	const y = linearScale(
-		domainFrom(values, { includeZero: true, padFraction: 0.05 }),
-		{ min: plotBottom(plot), max: plot.y },
-	);
+	const y = linearScale(domain, { min: plotBottom(plot), max: plot.y });
 	const zeroY = y.project(0);
 
 	const paths: MarkPath[] = [];
@@ -229,25 +249,22 @@ export function buildBarGeometry<M>(
 	const xTicks: Tick[] = categories.map(c => ({
 		value: 0,
 		position: xBand.centerOf(c) ?? plot.x,
-		label:
-			datasource.positionKind === 'instant'
-				? input.formatInstant(Number(c))
-				: input.formatCategory(c),
+		label: xLabel(c),
+	}));
+
+	const yTicks: Tick[] = yTickValues.map(v => ({
+		value: v,
+		position: y.project(v),
+		label: input.formatValue(v),
 	}));
 
-	const yTicks: Tick[] = [y.domain.min, 0, y.domain.max]
-		.filter((v, i, arr) => arr.indexOf(v) === i)
-		.map(v => ({
-			value: v,
-			position: y.project(v),
-			label: input.formatValue(v),
-		}));
+	const markers = horizontalMarkers(datasource.markers, plot, y.project);
 
 	return {
 		plot,
 		paths,
-		markers: [],
-		labels: [],
+		markers: markers.lines,
+		labels: markers.labels,
 		xTicks: thinTicks(xTicks, input.fontSize, plot.width),
 		yTicks,
 		hitRegions,

package/src/geometry/distribution.ts

@@ -9,6 +9,7 @@
  * PURE. No React, no SVG.
  */
 import type { ChartDatasource } from '../contract/datasource';
+import { segmentKey } from '../contract/theme';
 import { isKnown, isWithheld, sumKnown } from '../contract/value';
 import type { HitRegion } from './hitTest';
 import { arcPath, rectSubpath } from './path';
@@ -83,6 +84,8 @@ export function buildDistributionGeometry<M>(
 	const paths: MarkPath[] = [];
 	const labels: GeometryLabel[] = [];
 	const hitRegions: HitRegion[] = [];
+	const colorOf = (seriesId: string, pointId: string) =>
+		input.segmentColors?.[segmentKey(seriesId, pointId)] ?? input.seriesColors[seriesId];
 
 	if (shape === 'segmentedBar') {
 		const barHeight = Math.min(plot.height, 28);
@@ -100,7 +103,7 @@ export function buildDistributionGeometry<M>(
 				key: `seg-${series.id}-${point.id}`,
 				seriesId: series.id,
 				d: rectSubpath({ x: cursor, y: barY, width, height: barHeight }),
-				color: input.seriesColors[point.id] ?? input.seriesColors[series.id],
+				color: colorOf(series.id, point.id),
 				pattern: 'solid',
 				filled: true,
 			});
@@ -159,7 +162,7 @@ export function buildDistributionGeometry<M>(
 				startAngle: start,
 				endAngle: end,
 			}),
-			color: input.seriesColors[point.id] ?? input.seriesColors[series.id],
+			color: colorOf(series.id, point.id),
 			pattern: 'solid',
 			filled: true,
 		});

package/src/geometry/layout.ts

@@ -7,7 +7,7 @@
  *
  * PURE. No React, no SVG.
  */
-import { reserveAxisSpace } from './ticks';
+import { estimateTextWidth, reserveAxisSpace } from './ticks';
 
 export interface PlotRect {
 	readonly x: number;
@@ -103,6 +103,58 @@ export function resolvePlotRect(options: LayoutOptions): PlotRect {
 	};
 }
 
+export interface AxisLabels {
+	readonly xLabels: readonly string[];
+	readonly yLabels: readonly string[];
+	readonly fontSize: number;
+}
+
+/**
+ * Shrinks a plot so its own axis labels fit inside the container.
+ *
+ * Builders call this once they know their tick labels (which depend only on
+ * the data domain) and before projecting anything, so the reservation costs no
+ * second pass. Without it the frame handed every builder the full container:
+ * Y labels, drawn right-aligned left of the plot, landed at negative x, and X
+ * labels below the baseline fell past the bottom of the SVG (CHT-01).
+ *
+ * - left: the widest Y label plus a gutter, and at least half the widest X
+ *   label, because the first X label is centred on the plot's left edge;
+ * - right: half the widest X label, for the last one;
+ * - top: the part of the topmost Y label that rises above its tick;
+ * - bottom: one line of X labels plus a gutter.
+ *
+ * Each side is capped so labels can never squeeze the plot out of existence.
+ */
+export function insetForAxes(outer: PlotRect, labels: AxisLabels): PlotRect {
+	const { fontSize } = labels;
+	let widestX = 0;
+	for (const label of labels.xLabels) {
+		widestX = Math.max(widestX, estimateTextWidth(label, fontSize));
+	}
+	const hasY = labels.yLabels.length > 0;
+	const hasX = labels.xLabels.length > 0;
+
+	const left = Math.min(
+		Math.max(hasY ? reserveAxisSpace(labels.yLabels, fontSize, 'vertical') : 0, widestX / 2),
+		outer.width * 0.4,
+	);
+	const right = Math.min(widestX / 2, outer.width * 0.25);
+	// Y labels sit on their tick at `position + fontSize / 3`, so two thirds of
+	// the glyph box rise above it.
+	const top = hasY ? Math.min(Math.ceil((fontSize * 2) / 3), outer.height * 0.2) : 0;
+	const bottom = hasX
+		? Math.min(reserveAxisSpace(labels.xLabels, fontSize, 'horizontal'), outer.height * 0.4)
+		: 0;
+
+	return {
+		x: outer.x + left,
+		y: outer.y + top,
+		width: Math.max(0, outer.width - left - right),
+		height: Math.max(0, outer.height - top - bottom),
+	};
+}
+
 export function plotBottom(plot: PlotRect): number {
 	return plot.y + plot.height;
 }

package/src/geometry/markers.ts

@@ -0,0 +1,57 @@
+/**
+ * Reference markers on a value axis: thresholds, baselines and targets drawn
+ * as horizontal lines across the plot (FR-008, FR-072).
+ *
+ * Every builder used to return `markers: []`, so a threshold the app supplied
+ * reached the accessibility summary and nowhere else (CHT-03).
+ *
+ * PURE. No React, no SVG.
+ */
+import type { ReferenceMarker } from '../contract/marker';
+import { isKnown } from '../contract/value';
+import { plotRight, type PlotRect } from './layout';
+import type { GeometryLabel, MarkerLine } from './types';
+
+type PlacedMarker = ReferenceMarker & { readonly value: { kind: 'known'; value: number } };
+
+/** Markers that can be placed on a value axis: those with a known value. */
+export function placeableMarkers(
+	markers: readonly ReferenceMarker[] | undefined,
+): PlacedMarker[] {
+	return (markers ?? []).filter((m): m is PlacedMarker => isKnown(m.value));
+}
+
+/** Values the domain must include so every marker lands inside the plot. */
+export function markerDomainValues(markers: readonly ReferenceMarker[] | undefined): number[] {
+	return placeableMarkers(markers).map(m => m.value.value);
+}
+
+/** One line per marker across the plot, plus its label when it has one. */
+export function horizontalMarkers(
+	markers: readonly ReferenceMarker[] | undefined,
+	plot: PlotRect,
+	project: (value: number) => number,
+): { lines: MarkerLine[]; labels: GeometryLabel[] } {
+	const lines: MarkerLine[] = [];
+	const labels: GeometryLabel[] = [];
+	for (const marker of placeableMarkers(markers)) {
+		const y = project(marker.value.value);
+		lines.push({
+			id: `marker-${marker.id}`,
+			d: `M${plot.x},${y}H${plotRight(plot)}`,
+			label: marker.label,
+			kind: marker.kind,
+		});
+		if (marker.label) {
+			labels.push({
+				key: `marker-label-${marker.id}`,
+				text: marker.label,
+				x: plotRight(plot),
+				// Above the line, unless that would leave the plot.
+				y: y - 4 >= plot.y + 8 ? y - 4 : y + 12,
+				anchor: 'end',
+			});
+		}
+	}
+	return { lines, labels };
+}

package/src/geometry/progress.ts

@@ -12,11 +12,12 @@ import type { ChartDatasource } from '../contract/datasource';
 import { findTarget, readProgress } from '../contract/marker';
 import { isKnown, isWithheld } from '../contract/value';
 import type { HitRegion } from './hitTest';
-import { plotRight } from './layout';
+import { plotBottom, plotRight } from './layout';
 import { rectSubpath } from './path';
 import type {
 	GeometryInput,
 	GeometryLabel,
+	MarkerLine,
 	MarkPath,
 	ResolvedGeometry,
 } from './types';
@@ -52,6 +53,22 @@ export function buildProgressGeometry<M>(
 		};
 	}
 
+	const readings = metrics.map(({ point }) =>
+		readProgress(point.value, findTarget(datasource.markers, point.id) ?? findTarget(datasource.markers)),
+	);
+
+	// The track spans 0..displayMax of the target, shared by every row so their
+	// targets line up. With an overshoot the target sits inside the plot and the
+	// excess is drawn to its right — previously the target was the plot's right
+	// edge, so overshoot started there and was clipped by the SVG (CHT-03).
+	const displayMax = readings.reduce(
+		(max, r) =>
+			r.proportion === undefined ? max : Math.max(max, Math.min(r.proportion, OVERSHOOT_DISPLAY_CAP)),
+		1,
+	);
+	const unit = plot.width / displayMax;
+	const targetX = plot.x + unit;
+
 	const rowHeight = plot.height / metrics.length;
 	const barHeight = Math.min(rowHeight * 0.45, 24);
 	const radius = options.trackRadius ?? barHeight / 2;
@@ -59,12 +76,12 @@ export function buildProgressGeometry<M>(
 	const paths: MarkPath[] = [];
 	const labels: GeometryLabel[] = [];
 	const hitRegions: HitRegion[] = [];
+	const markers: MarkerLine[] = [];
 	let incomplete = false;
 
 	metrics.forEach(({ series, point }, index) => {
 		const rowY = plot.y + index * rowHeight + (rowHeight - barHeight) / 2;
-		const target = findTarget(datasource.markers, point.id) ?? findTarget(datasource.markers);
-		const reading = readProgress(point.value, target);
+		const reading = readings[index];
 
 		// Track: the full width, always drawn, so an empty metric still reads as
 		// a metric rather than as blank space.
@@ -119,7 +136,7 @@ export function buildProgressGeometry<M>(
 				d: rectSubpath({
 					x: plot.x,
 					y: rowY,
-					width: Math.max(0, plot.width * Math.min(fillFraction, 1)),
+					width: Math.max(0, unit * Math.min(fillFraction, 1)),
 					height: barHeight,
 					radius,
 				}),
@@ -132,13 +149,12 @@ export function buildProgressGeometry<M>(
 			// so exceeding a goal is visible instead of indistinguishable from
 			// exactly meeting it.
 			if (reading.overshoot && proportion !== undefined) {
-				const overshootWidth =
-					plot.width * (Math.min(proportion, OVERSHOOT_DISPLAY_CAP) - 1);
+				const overshootWidth = unit * (Math.min(proportion, OVERSHOOT_DISPLAY_CAP) - 1);
 				paths.push({
 					key: `overshoot-${series.id}-${point.id}`,
 					seriesId: series.id,
 					d: rectSubpath({
-						x: plot.x + plot.width,
+						x: targetX,
 						y: rowY + barHeight * 0.2,
 						width: Math.max(0, overshootWidth),
 						height: barHeight * 0.6,
@@ -152,6 +168,16 @@ export function buildProgressGeometry<M>(
 			}
 		}
 
+		// The target itself, across this row's bar (FR-022, FR-072).
+		if (reading.proportion !== undefined && reading.target) {
+			markers.push({
+				id: `target-${series.id}-${point.id}`,
+				d: `M${targetX},${Math.max(plot.y, rowY - 3)}V${Math.min(plotBottom(plot), rowY + barHeight + 3)}`,
+				label: reading.target.label,
+				kind: 'target',
+			});
+		}
+
 		const valueText = isKnown(point.value)
 			? input.formatValue(point.value.value)
 			: '';
@@ -194,7 +220,7 @@ export function buildProgressGeometry<M>(
 	return {
 		plot,
 		paths,
-		markers: [],
+		markers,
 		labels,
 		xTicks: [],
 		yTicks: [],

package/src/geometry/scale.ts

@@ -22,7 +22,7 @@ export interface LinearScale {
  * usable axis. Without this the projection divides by zero and every point
  * lands on the same pixel — or on NaN.
  */
-function widenDegenerateDomain(domain: Range): Range {
+export function widenDegenerateDomain(domain: Range): Range {
 	if (domain.max > domain.min) {
 		return domain;
 	}

package/src/geometry/timeSeries.ts

@@ -10,9 +10,10 @@
 import type { ChartDatasource, Series } from '../contract/datasource';
 import { isKnown, isWithheld } from '../contract/value';
 import type { HitRegion } from './hitTest';
-import { plotBottom, plotRight } from './layout';
+import { insetForAxes, plotBottom, plotRight } from './layout';
+import { horizontalMarkers, markerDomainValues } from './markers';
 import { linePath, type MaybePt } from './path';
-import { domainFrom, linearScale, timeScale } from './scale';
+import { domainFrom, linearScale, timeScale, widenDegenerateDomain } from './scale';
 import { niceTickValues, thinTicks, type Tick } from './ticks';
 import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
 
@@ -45,8 +46,6 @@ export function buildTimeSeriesGeometry<M>(
 	input: GeometryInput,
 	options: TimeSeriesOptions = {},
 ): ResolvedGeometry {
-	const { plot } = input;
-
 	const instants: number[] = [];
 	const values: number[] = [];
 	let excluded = 0;
@@ -66,7 +65,7 @@ export function buildTimeSeriesGeometry<M>(
 
 	if (instants.length === 0) {
 		return {
-			plot,
+			plot: input.plot,
 			paths: [],
 			markers: [],
 			labels: [],
@@ -77,15 +76,24 @@ export function buildTimeSeriesGeometry<M>(
 		};
 	}
 
-	const x = timeScale(domainFrom(instants), {
-		min: plot.x,
-		max: plotRight(plot),
-	});
-	const y = linearScale(domainFrom(values, { padFraction: 0.1 }), {
-		min: plotBottom(plot),
-		max: plot.y,
+	// Tick labels depend only on the domains, so the plot can make room for
+	// them before anything is projected.
+	// Widened here, as the scales would, so the ticks label the axes actually drawn.
+	const xDomain = widenDegenerateDomain(domainFrom(instants));
+	const yDomain = widenDegenerateDomain(
+		domainFrom([...values, ...markerDomainValues(datasource.markers)], { padFraction: 0.1 }),
+	);
+	const xTickValues = niceTickValues(xDomain, 4);
+	const yTickValues = niceTickValues(yDomain, 4);
+	const plot = insetForAxes(input.plot, {
+		xLabels: xTickValues.map(input.formatInstant),
+		yLabels: yTickValues.map(input.formatValue),
+		fontSize: input.fontSize,
 	});
 
+	const x = timeScale(xDomain, { min: plot.x, max: plotRight(plot) });
+	const y = linearScale(yDomain, { min: plotBottom(plot), max: plot.y });
+
 	const paths: MarkPath[] = [];
 	const hitRegions: HitRegion[] = [];
 
@@ -133,23 +141,25 @@ export function buildTimeSeriesGeometry<M>(
 		}
 	}
 
-	const xTicks: Tick[] = niceTickValues(x.domain, 4).map(v => ({
+	const xTicks: Tick[] = xTickValues.map(v => ({
 		value: v,
 		position: x.project(v),
 		label: input.formatInstant(v),
 	}));
 
-	const yTicks: Tick[] = niceTickValues(y.domain, 4).map(v => ({
+	const yTicks: Tick[] = yTickValues.map(v => ({
 		value: v,
 		position: y.project(v),
 		label: input.formatValue(v),
 	}));
 
+	const markers = horizontalMarkers(datasource.markers, plot, y.project);
+
 	return {
 		plot,
 		paths,
-		markers: [],
-		labels: [],
+		markers: markers.lines,
+		labels: markers.labels,
 		xTicks: thinTicks(xTicks, input.fontSize, plot.width),
 		yTicks,
 		hitRegions,

package/src/geometry/types.ts

@@ -78,6 +78,12 @@ export interface GeometryInput {
 	readonly fontSize: number;
 	/** Resolved per series, so geometry never reaches into the theme itself. */
 	readonly seriesColors: Readonly<Record<string, string>>;
+	/**
+	 * Distribution segment colours keyed by `segmentKey(seriesId, pointId)`.
+	 * Only resolved for the distribution family. Point colours used to share
+	 * `seriesColors`, so a point id equal to a series id overwrote that series.
+	 */
+	readonly segmentColors?: Readonly<Record<string, string>>;
 	readonly nonValueTextures: Readonly<
 		Record<'unknown' | 'notApplicable' | 'withheld', NonValueTexture>
 	>;

package/src/react/ChartFrame.tsx

@@ -167,6 +167,7 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 		theme,
 		layout,
 		geometryFormatters,
+		family,
 	);
 
 	const showData = drawsData(status);
@@ -362,9 +363,10 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 						theme,
 						visibility.hidden,
 						visibility.enabled,
+						family,
 				  )
 				: [],
-		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled],
+		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled, family],
 	);
 
 	const legendPosition =

package/src/react/ChartLegend.tsx

@@ -9,18 +9,52 @@
 import React from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
 
-import type { ChartDatasource } from '../contract/datasource';
-import { resolveSeriesColor, type ChartTheme, type LegendEntry } from '../contract/theme';
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import {
+	resolveSegmentColors,
+	resolveSeriesColor,
+	segmentKey,
+	type ChartTheme,
+	type LegendEntry,
+} from '../contract/theme';
 
 /** Minimum tap target, per platform accessibility guidance (UX-003). */
 const MIN_TAP_TARGET = 44;
 
+/**
+ * Legend model. A distribution chart gets one entry per segment, in the colour
+ * its arc is drawn in; it used to get one per series, so a one-series donut of
+ * four segments showed a single entry (CHT-02).
+ */
 export function buildLegendEntries<M>(
 	datasource: ChartDatasource<M>,
 	theme: ChartTheme,
 	hidden: ReadonlySet<string>,
 	toggleable: boolean,
+	family?: ChartFamily,
 ): LegendEntry[] {
+	if (family === 'distribution') {
+		const colors = resolveSegmentColors(datasource, theme);
+		return datasource.series.flatMap(series =>
+			series.points.map(point => {
+				const single = series.points.length === 1;
+				let label = series.label;
+				if (!single) {
+					label = point.position.kind === 'category' ? point.position.category : point.id;
+				}
+				return {
+					seriesId: series.id,
+					pointId: point.id,
+					label,
+					color: colors[segmentKey(series.id, point.id)],
+					pattern: 'solid' as const,
+					visible: !hidden.has(series.id),
+					// Visibility is per series, so only a one-segment series toggles.
+					toggleable: toggleable && single,
+				};
+			}),
+		);
+	}
 	return datasource.series.map((series, index) => ({
 		seriesId: series.id,
 		label: series.label,
@@ -31,6 +65,10 @@ export function buildLegendEntries<M>(
 	}));
 }
 
+function keyOf(entry: LegendEntry): string {
+	return entry.pointId === undefined ? entry.seriesId : segmentKey(entry.seriesId, entry.pointId);
+}
+
 function segmentCountFor(pattern: LegendEntry['pattern']): number {
 	switch (pattern) {
 		case 'dotted':
@@ -113,7 +151,7 @@ export function ChartLegend({
 
 				if (!entry.toggleable || !onToggle) {
 					return (
-						<View key={entry.seriesId} style={styles.entry} accessibilityRole="text">
+						<View key={keyOf(entry)} style={styles.entry} accessibilityRole="text">
 							{content}
 						</View>
 					);
@@ -121,7 +159,7 @@ export function ChartLegend({
 
 				return (
 					<Pressable
-						key={entry.seriesId}
+						key={keyOf(entry)}
 						onPress={() => onToggle(entry.seriesId)}
 						accessibilityRole="switch"
 						accessibilityState={{ checked: entry.visible }}

package/src/react/useChartLayout.ts

@@ -13,8 +13,8 @@
 import { useCallback, useMemo, useState } from 'react';
 import { PixelRatio, type LayoutChangeEvent } from 'react-native';
 
-import type { ChartDatasource } from '../contract/datasource';
-import { resolveSeriesColor, type ChartTheme } from '../contract/theme';
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import { resolveSegmentColors, resolveSeriesColor, type ChartTheme } from '../contract/theme';
 import {
 	EMPTY_PLOT,
 	isMeasurable,
@@ -98,27 +98,27 @@ export function useGeometryInput<M>(
 		readonly formatCategory: (raw: string) => string;
 		readonly formatInstant: (at: number) => string;
 	},
+	family?: ChartFamily,
 ): GeometryInput {
 	return useMemo(() => {
 		const seriesColors: Record<string, string> = {};
 		datasource.series.forEach((series, index) => {
 			seriesColors[series.id] = resolveSeriesColor(theme, index, series.color);
-			// Distribution segments are coloured per point rather than per series,
-			// so give each point a palette entry too.
-			series.points.forEach((point, pointIndex) => {
-				seriesColors[point.id] = resolveSeriesColor(theme, pointIndex);
-			});
 		});
 
 		return {
 			plot: layout.plot,
 			fontSize: layout.fontSize,
 			seriesColors,
+			// Per point only where segments exist; resolving one per point for
+			// every family cost a colour per data point at the time-series budget.
+			segmentColors:
+				family === 'distribution' ? resolveSegmentColors(datasource, theme) : undefined,
 			nonValueTextures: theme.nonValue,
 			heatmapRamp: theme.heatmapRamp,
 			formatValue: formatters.formatValue,
 			formatCategory: formatters.formatCategory,
 			formatInstant: formatters.formatInstant,
 		};
-	}, [datasource, theme, layout.plot, layout.fontSize, formatters]);
+	}, [datasource, theme, layout.plot, layout.fontSize, formatters, family]);
 }