@chipmobilesdk/rn-chart 0.2.1 → 0.4.0

package/src/contract/strings.ts

@@ -0,0 +1,50 @@
+/**
+ * Every text the package itself speaks or shows (CHT-05): screen-reader
+ * summaries and announcements, adjustable-action labels, built-in state text and
+ * legend hints. English defaults; an app translates them by passing `strings`
+ * (or by registering `chartStrings.user` with rn-i18n and passing the translated
+ * texts). `{name}` marks a variable.
+ */
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
+export const chartStrings = defineMessages({
+	user: {
+		'chart.family.progress': 'progress chart',
+		'chart.family.distribution': 'distribution chart',
+		'chart.family.timeSeries': 'time series chart',
+		'chart.family.bar': 'bar chart',
+		'chart.family.heatmap': 'heatmap',
+		'chart.status.loading': 'Loading data.',
+		'chart.status.empty': 'No data yet.',
+		'chart.status.error': 'Data could not be shown.',
+		'chart.status.stale': 'Showing data that may be out of date.',
+		'chart.status.noPermission': 'This data is not available to you.',
+		'chart.status.partial': 'Some data is missing.',
+		'chart.summary.heading': '{title}, {noun}.',
+		'chart.summary.headingUntitled': '{noun}.',
+		'chart.summary.scale': '{series} series, {points} points.',
+		'chart.summary.scaleSingle': '{points} points.',
+		'chart.summary.single': 'Value {value}.',
+		'chart.summary.extremes': 'Highest {maxLabel} at {max}. Lowest {minLabel} at {min}.',
+		'chart.summary.marker': '{name} {value}',
+		'chart.summary.incomplete': 'Some values are missing, so totals are incomplete.',
+		'chart.point.withheld': '{position}, {series}, not available.',
+		'chart.point.noData': '{position}, {series}, no data.',
+		'chart.point.value': '{position}, {series}, {value}.',
+		'chart.total': 'Total {value}.',
+		'chart.total.incomplete': 'Total {value}, excluding {count} values that are not available.',
+		'chart.action.next': 'Next data point',
+		'chart.action.previous': 'Previous data point',
+		'chart.state.loading': 'Loading…',
+		'chart.state.empty': 'No data yet',
+		'chart.state.error': 'Unable to show this chart',
+		'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.',
+	},
+});
+
+export type ChartStrings = typeof chartStrings.defaults;
+export type ChartStringKey = keyof ChartStrings;

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,
 	};
 }

package/src/geometry/hitTest.ts

@@ -23,6 +23,19 @@ export interface HitRegion {
 		readonly width: number;
 		readonly height: number;
 	};
+	/**
+	 * An arc segment: containment by radius and angle. Angles are radians,
+	 * clockwise from twelve o'clock, as the distribution geometry draws them.
+	 * A region with an arc is hit only inside it, never by proximity.
+	 */
+	readonly arc?: {
+		readonly cx: number;
+		readonly cy: number;
+		readonly innerRadius: number;
+		readonly outerRadius: number;
+		readonly startAngle: number;
+		readonly endAngle: number;
+	};
 	/**
 	 * False for points that must never be selectable: withheld values, and
 	 * anything the chart is not currently drawing (FR-053).
@@ -47,6 +60,20 @@ function inBounds(region: HitRegion, x: number, y: number): boolean {
 	return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
 }
 
+const TAU = Math.PI * 2;
+
+function inArc(arc: NonNullable<HitRegion['arc']>, x: number, y: number): boolean {
+	const dx = x - arc.cx;
+	const dy = y - arc.cy;
+	const radius = Math.sqrt(dx * dx + dy * dy);
+	if (radius < arc.innerRadius || radius > arc.outerRadius) {
+		return false;
+	}
+	// Clockwise from the top, the convention the arcs are drawn in.
+	const angle = (Math.atan2(dy, dx) + Math.PI / 2 + TAU) % TAU;
+	return angle >= arc.startAngle && angle < arc.endAngle;
+}
+
 /**
  * Resolves a touch to a mark.
  *
@@ -70,6 +97,14 @@ export function hitTest(
 		if (inBounds(region, x, y)) {
 			return { seriesId: region.seriesId, pointId: region.pointId, distance: 0 };
 		}
+		if (region.arc) {
+			// A large segment's edge is far from its midpoint, and a neighbour's
+			// midpoint can be nearer: only the segment under the finger counts.
+			if (inArc(region.arc, x, y)) {
+				return { seriesId: region.seriesId, pointId: region.pointId, distance: 0 };
+			}
+			continue;
+		}
 
 		const dx = region.x - x;
 		const dy = region.y - y;

package/src/geometry/progress.ts

@@ -17,7 +17,6 @@ import { rectSubpath } from './path';
 import type { GeometryInput, GeometryLabel, MarkerLine, MarkPath, ResolvedGeometry } from './types';
 
 export interface ProgressOptions {
-	readonly orientation?: 'horizontal' | 'vertical';
 	readonly trackRadius?: number;
 }
 

package/src/geometry/ticks.ts

@@ -130,16 +130,3 @@ export function reserveAxisSpace(
 	}
 	return widest + LABEL_GUTTER;
 }
-
-/**
- * Shortens a label that cannot fit, signalling the truncation with an ellipsis.
- * Callers must expose the full value through an accessible label (FR-070).
- */
-export function truncateToWidth(text: string, fontSize: number, maxWidthPx: number): string {
-	if (estimateTextWidth(text, fontSize) <= maxWidthPx) {
-		return text;
-	}
-	const perChar = fontSize * AVERAGE_ADVANCE_RATIO;
-	const fits = Math.max(1, Math.floor(maxWidthPx / perChar) - 1);
-	return `${text.slice(0, fits)}…`;
-}

package/src/geometry/timeSeries.ts

@@ -50,8 +50,13 @@ export function buildTimeSeriesGeometry<M>(
 	const values: number[] = [];
 	let excluded = 0;
 
+	// Sorted and windowed once per series; both passes below read the result.
+	const ordered = new Map(
+		datasource.series.map(series => [series, visiblePoints(series, options.range)] as const),
+	);
+
 	for (const series of datasource.series) {
-		for (const point of visiblePoints(series, options.range)) {
+		for (const point of ordered.get(series) ?? []) {
 			if (point.position.kind === 'instant') {
 				instants.push(point.position.at);
 			}
@@ -104,7 +109,7 @@ export function buildTimeSeriesGeometry<M>(
 
 		const pts: MaybePt[] = [];
 
-		for (const point of visiblePoints(series, options.range)) {
+		for (const point of ordered.get(series) ?? []) {
 			const at = point.position.kind === 'instant' ? point.position.at : 0;
 			const px = x.project(at);
 

package/src/geometry/types.ts

@@ -46,6 +46,13 @@ export interface GeometryLabel {
 	readonly muted?: boolean;
 }
 
+/** What a colour ramp runs from and to, for the legend that explains it. */
+export interface ColorScale {
+	readonly min: number;
+	readonly max: number;
+	readonly colors: readonly string[];
+}
+
 export interface ResolvedGeometry {
 	readonly plot: PlotRect;
 	readonly paths: readonly MarkPath[];
@@ -54,6 +61,8 @@ export interface ResolvedGeometry {
 	readonly xTicks: readonly Tick[];
 	readonly yTicks: readonly Tick[];
 	readonly hitRegions: readonly HitRegion[];
+	/** Present when colour encodes a value, as in a heatmap. */
+	readonly colorScale?: ColorScale;
 	/**
 	 * True when something was excluded from a total or proportion, so the chart
 	 * can say so rather than presenting a partial figure as whole (FR-013).
@@ -88,6 +97,8 @@ export interface GeometryInput {
 		Record<'unknown' | 'notApplicable' | 'withheld', NonValueTexture>
 	>;
 	readonly heatmapRamp: readonly string[];
+	/** Corner radii from the theme, for bars and heatmap cells. */
+	readonly radius?: { readonly bar: number; readonly cell: number };
 	readonly formatValue: (value: number) => string;
 	readonly formatCategory: (raw: string) => string;
 	readonly formatInstant: (at: number) => string;

package/src/index.ts

@@ -62,6 +62,8 @@ export {
 	resolveUnit,
 } from './contract/datasource';
 
+export type { DistributionValues } from './contract/distribution';
+
 export type { MarkerKind, ProgressReading, ReferenceMarker } from './contract/marker';
 export { findTarget, isUsableTarget, readProgress } from './contract/marker';
 
@@ -149,10 +151,15 @@ export {
 	TimeSeriesChart,
 } from './react/charts';
 
-export { ChartLegend, buildLegendEntries } from './react/ChartLegend';
+export { ChartLegend, ColorScaleLegend, buildLegendEntries } from './react/ChartLegend';
+export type { ColorScale } from './geometry/types';
 export { ChartThemeProvider, useChartTheme } from './react/ChartThemeProvider';
 
 // ---------------------------------------------------------------------------
 // Accessibility helpers
 // ---------------------------------------------------------------------------
 export { buildChartSummary, buildPointAnnouncement, buildTotalAnnouncement } from './a11y/summary';
+
+// The package's own texts, for translation (CHT-05).
+export { chartStrings } from './contract/strings';
+export type { ChartStringKey, ChartStrings } from './contract/strings';

package/src/react/ChartBoundary.tsx

@@ -69,7 +69,7 @@ export class ChartBoundary extends React.Component<Props, State> {
 		return { error: chartError('render', 'renderException') };
 	}
 
-	componentDidCatch(error: unknown, info: { componentStack?: string }): void {
+	override componentDidCatch(error: unknown, info: { componentStack?: string }): void {
 		const report = toFailureReport(
 			this.props.family,
 			error,
@@ -87,7 +87,7 @@ export class ChartBoundary extends React.Component<Props, State> {
 		this.props.onFailure?.(report);
 	}
 
-	render(): React.ReactNode {
+	override render(): React.ReactNode {
 		if (this.state.error) {
 			return this.props.renderFallback(this.state.error);
 		}