@chipmobilesdk/rn-chart 0.1.0

package/src/geometry/distribution.ts

@@ -0,0 +1,200 @@
+/**
+ * Distribution geometry: proportions between groups.
+ *
+ * Segments that do not sum to the whole are **not** rescaled to force a full
+ * circle (FR-024). The arc stops short and the geometry reports `incomplete`,
+ * so the chart can say the data is partial rather than quietly implying it is
+ * complete.
+ *
+ * PURE. No React, no SVG.
+ */
+import type { ChartDatasource } from '../contract/datasource';
+import { isKnown, isWithheld, sumKnown } from '../contract/value';
+import type { HitRegion } from './hitTest';
+import { arcPath, rectSubpath } from './path';
+import type {
+	GeometryInput,
+	GeometryLabel,
+	MarkPath,
+	ResolvedGeometry,
+} from './types';
+
+export type DistributionShape = 'donut' | 'pie' | 'segmentedBar';
+
+export interface DistributionOptions {
+	readonly shape?: DistributionShape;
+	/** Donut hole as a fraction of the outer radius. */
+	readonly innerRadiusRatio?: number;
+}
+
+const TAU = Math.PI * 2;
+
+export function buildDistributionGeometry<M>(
+	datasource: ChartDatasource<M>,
+	input: GeometryInput,
+	options: DistributionOptions = {},
+): ResolvedGeometry {
+	const { plot } = input;
+	const shape = options.shape ?? 'donut';
+
+	const segments = datasource.series.flatMap(series =>
+		series.points.map(point => ({ series, point })),
+	);
+
+	if (segments.length === 0 || plot.width <= 0 || plot.height <= 0) {
+		return {
+			plot,
+			paths: [],
+			markers: [],
+			labels: [],
+			xTicks: [],
+			yTicks: [],
+			hitRegions: [],
+			incomplete: false,
+		};
+	}
+
+	const total = sumKnown(segments.map(s => s.point.value));
+	// Nothing known: there is no distribution to draw, and drawing a full grey
+	// circle would imply a shape the data does not support.
+	if (total.countedPoints === 0 || total.total <= 0) {
+		return {
+			plot,
+			paths: [],
+			markers: [],
+			labels: [],
+			xTicks: [],
+			yTicks: [],
+			hitRegions: [],
+			incomplete: true,
+		};
+	}
+
+	// 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 coverage = total.total / denominator;
+	const incomplete = total.incomplete || coverage < 0.999;
+
+	const paths: MarkPath[] = [];
+	const labels: GeometryLabel[] = [];
+	const hitRegions: HitRegion[] = [];
+
+	if (shape === 'segmentedBar') {
+		const barHeight = Math.min(plot.height, 28);
+		const barY = plot.y + (plot.height - barHeight) / 2;
+		let cursor = plot.x;
+
+		for (const { series, point } of segments) {
+			if (!isKnown(point.value)) {
+				continue;
+			}
+			const fraction = point.value.value / denominator;
+			const width = plot.width * fraction;
+
+			paths.push({
+				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],
+				pattern: 'solid',
+				filled: true,
+			});
+
+			hitRegions.push({
+				seriesId: series.id,
+				pointId: point.id,
+				x: cursor + width / 2,
+				y: barY + barHeight / 2,
+				bounds: { x: cursor, y: barY, width, height: barHeight },
+				selectable: !isWithheld(point.value),
+			});
+
+			cursor += width;
+		}
+
+		return {
+			plot,
+			paths,
+			markers: [],
+			labels,
+			xTicks: [],
+			yTicks: [],
+			hitRegions,
+			incomplete,
+		};
+	}
+
+	const cx = plot.x + plot.width / 2;
+	const cy = plot.y + plot.height / 2;
+	const outerRadius = Math.min(plot.width, plot.height) / 2;
+	const innerRadius =
+		shape === 'pie' ? 0 : outerRadius * (options.innerRadiusRatio ?? 0.6);
+
+	let angle = 0;
+
+	for (const { series, point } of segments) {
+		if (!isKnown(point.value)) {
+			continue;
+		}
+
+		const fraction = point.value.value / denominator;
+		const sweep = fraction * TAU;
+		const start = angle;
+		const end = angle + sweep;
+		angle = end;
+
+		paths.push({
+			key: `arc-${series.id}-${point.id}`,
+			seriesId: series.id,
+			d: arcPath({
+				cx,
+				cy,
+				outerRadius,
+				innerRadius,
+				startAngle: start,
+				endAngle: end,
+			}),
+			color: input.seriesColors[point.id] ?? input.seriesColors[series.id],
+			pattern: 'solid',
+			filled: true,
+		});
+
+		// Label at the segment's midpoint, on the ring between the two radii.
+		const mid = start + sweep / 2 - Math.PI / 2;
+		const labelRadius = (outerRadius + innerRadius) / 2;
+
+		labels.push({
+			key: `arc-label-${series.id}-${point.id}`,
+			text: `${Math.round(fraction * 100)}%`,
+			x: cx + labelRadius * Math.cos(mid),
+			y: cy + labelRadius * Math.sin(mid),
+			anchor: 'middle',
+			// Hide labels on slivers where the text would not fit anyway.
+			muted: fraction < 0.05,
+		});
+
+		hitRegions.push({
+			seriesId: series.id,
+			pointId: point.id,
+			x: cx + labelRadius * Math.cos(mid),
+			y: cy + labelRadius * Math.sin(mid),
+			selectable: !isWithheld(point.value),
+		});
+	}
+
+	return {
+		plot,
+		paths,
+		markers: [],
+		labels,
+		xTicks: [],
+		yTicks: [],
+		hitRegions,
+		incomplete,
+	};
+}

package/src/geometry/heatmap.ts

@@ -0,0 +1,195 @@
+/**
+ * Heatmap geometry: a matrix of cells, batched by intensity bucket.
+ *
+ * This is where batching pays off most. A thousand cells become roughly eight
+ * paths — one per intensity bucket, plus one per non-value class — instead of a
+ * thousand elements. Cell count no longer drives element count at all
+ * (research.md R2).
+ *
+ * Empty, zero, and unavailable cells are distinct by construction (FR-027): a
+ * genuine zero lands in the lowest ramp bucket, while unknown, not-applicable,
+ * and withheld each get their own texture.
+ *
+ * PURE. No React, no SVG.
+ */
+import type { ChartDatasource } from '../contract/datasource';
+import { isKnown, isWithheld } from '../contract/value';
+import type { HitRegion } from './hitTest';
+import { rectBatchPath, type RectSpec } from './path';
+import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
+
+export interface HeatmapOptions {
+	/** Intensity buckets. More buckets means finer shading, more paths. */
+	readonly buckets?: number;
+	readonly cellGap?: number;
+	readonly cellRadius?: number;
+}
+
+export function buildHeatmapGeometry<M>(
+	datasource: ChartDatasource<M>,
+	input: GeometryInput,
+	options: HeatmapOptions = {},
+): ResolvedGeometry {
+	const { plot } = input;
+
+	const rows: string[] = [];
+	const columns: string[] = [];
+	const rowSeen = new Set<string>();
+	const colSeen = new Set<string>();
+
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (point.position.kind !== 'matrix') {
+				continue;
+			}
+			if (!rowSeen.has(point.position.row)) {
+				rowSeen.add(point.position.row);
+				rows.push(point.position.row);
+			}
+			if (!colSeen.has(point.position.column)) {
+				colSeen.add(point.position.column);
+				columns.push(point.position.column);
+			}
+		}
+	}
+
+	if (rows.length === 0 || columns.length === 0 || plot.width <= 0) {
+		return {
+			plot,
+			paths: [],
+			markers: [],
+			labels: [],
+			xTicks: [],
+			yTicks: [],
+			hitRegions: [],
+			incomplete: false,
+		};
+	}
+
+	const gap = options.cellGap ?? 2;
+	const cellWidth = plot.width / columns.length;
+	const cellHeight = plot.height / rows.length;
+
+	const ramp = input.heatmapRamp;
+	const bucketCount = Math.max(
+		2,
+		Math.min(options.buckets ?? ramp.length, ramp.length),
+	);
+
+	let min = Infinity;
+	let max = -Infinity;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (isKnown(point.value)) {
+				min = Math.min(min, point.value.value);
+				max = Math.max(max, point.value.value);
+			}
+		}
+	}
+	const hasKnown = Number.isFinite(min) && Number.isFinite(max);
+	const span = max - min;
+
+	// Rects grouped by the path they will join.
+	const byBucket = new Map<number, RectSpec[]>();
+	const byTexture = new Map<'unknown' | 'notApplicable' | 'withheld', RectSpec[]>();
+	const hitRegions: HitRegion[] = [];
+	let excluded = 0;
+
+	for (const series of datasource.series) {
+		if (series.hidden) {
+			continue;
+		}
+
+		for (const point of series.points) {
+			if (point.position.kind !== 'matrix') {
+				continue;
+			}
+
+			const colIndex = columns.indexOf(point.position.column);
+			const rowIndex = rows.indexOf(point.position.row);
+			if (colIndex < 0 || rowIndex < 0) {
+				continue;
+			}
+
+			const rect: RectSpec = {
+				x: plot.x + colIndex * cellWidth + gap / 2,
+				y: plot.y + rowIndex * cellHeight + gap / 2,
+				width: Math.max(0, cellWidth - gap),
+				height: Math.max(0, cellHeight - gap),
+				radius: options.cellRadius,
+			};
+
+			if (isKnown(point.value)) {
+				// A zero lands in bucket 0 rather than being treated as absent —
+				// "logged nothing" and "we do not know" must not look alike.
+				const t = hasKnown && span > 0 ? (point.value.value - min) / span : 0;
+				const bucket = Math.min(
+					bucketCount - 1,
+					Math.floor(t * (bucketCount - 1) + 0.5),
+				);
+				const list = byBucket.get(bucket) ?? [];
+				list.push(rect);
+				byBucket.set(bucket, list);
+			} else {
+				excluded += 1;
+				const kind = point.value.kind;
+				const list = byTexture.get(kind) ?? [];
+				list.push(rect);
+				byTexture.set(kind, list);
+			}
+
+			hitRegions.push({
+				seriesId: series.id,
+				pointId: point.id,
+				x: rect.x + rect.width / 2,
+				y: rect.y + rect.height / 2,
+				bounds: rect,
+				selectable: !isWithheld(point.value),
+			});
+		}
+	}
+
+	const paths: MarkPath[] = [];
+
+	for (const [bucket, rects] of byBucket) {
+		paths.push({
+			key: `cells-${bucket}`,
+			seriesId: datasource.series[0]?.id ?? 'heatmap',
+			d: rectBatchPath(rects),
+			color: ramp[Math.min(bucket, ramp.length - 1)],
+			pattern: 'solid',
+			filled: true,
+		});
+	}
+
+	for (const [kind, rects] of byTexture) {
+		paths.push({
+			key: `cells-${kind}`,
+			seriesId: datasource.series[0]?.id ?? 'heatmap',
+			d: rectBatchPath(rects),
+			color: ramp[0],
+			pattern: 'solid',
+			filled: true,
+			texture: input.nonValueTextures[kind],
+		});
+	}
+
+	return {
+		plot,
+		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) => ({
+			value: i,
+			position: plot.y + i * cellHeight + cellHeight / 2,
+			label: input.formatCategory(r),
+		})),
+		hitRegions,
+		incomplete: excluded > 0,
+	};
+}

package/src/geometry/hitTest.ts

@@ -0,0 +1,120 @@
+/**
+ * Hit-testing for batched marks.
+ *
+ * Because marks are batched into one path per series, there are no per-element
+ * press handlers to rely on — a touch is resolved against geometry instead.
+ * That work would be needed anyway (a mobile time-series chart needs
+ * nearest-point search regardless of how it is drawn), and doing it in one
+ * place means a single implementation serves every family.
+ *
+ * PURE. No React, no SVG.
+ */
+
+export interface HitRegion {
+	readonly seriesId: string;
+	readonly pointId: string;
+	/** Mark centre, used for nearest-point search and for highlight placement. */
+	readonly x: number;
+	readonly y: number;
+	/** Optional bounds, for marks where containment beats proximity. */
+	readonly bounds?: {
+		readonly x: number;
+		readonly y: number;
+		readonly width: number;
+		readonly height: number;
+	};
+	/**
+	 * False for points that must never be selectable: withheld values, and
+	 * anything the chart is not currently drawing (FR-053).
+	 */
+	readonly selectable: boolean;
+}
+
+export interface HitResult {
+	readonly seriesId: string;
+	readonly pointId: string;
+	readonly distance: number;
+}
+
+/** Touch slop: how far from a mark a tap still counts, in px. */
+export const DEFAULT_HIT_RADIUS = 44;
+
+function inBounds(region: HitRegion, x: number, y: number): boolean {
+	const b = region.bounds;
+	if (!b) {
+		return false;
+	}
+	return x >= b.x && x <= b.x + b.width && y >= b.y && y <= b.y + b.height;
+}
+
+/**
+ * Resolves a touch to a mark.
+ *
+ * Containment wins over proximity where bounds exist — tapping inside a bar
+ * should select that bar even if a neighbouring bar's centre happens to be
+ * closer. Otherwise the nearest selectable mark within the hit radius wins.
+ */
+export function hitTest(
+	regions: readonly HitRegion[],
+	x: number,
+	y: number,
+	hitRadius = DEFAULT_HIT_RADIUS,
+): HitResult | null {
+	let best: HitResult | null = null;
+
+	for (const region of regions) {
+		if (!region.selectable) {
+			continue;
+		}
+
+		if (inBounds(region, x, y)) {
+			return { seriesId: region.seriesId, pointId: region.pointId, distance: 0 };
+		}
+
+		const dx = region.x - x;
+		const dy = region.y - y;
+		const distance = Math.sqrt(dx * dx + dy * dy);
+
+		if (distance <= hitRadius && (best === null || distance < best.distance)) {
+			best = { seriesId: region.seriesId, pointId: region.pointId, distance };
+		}
+	}
+
+	return best;
+}
+
+/**
+ * Nearest mark by horizontal distance only.
+ *
+ * The right model for a time-series chart: a user aiming at "that Tuesday
+ * spike" cares about the x position, and demanding vertical accuracy on a line
+ * that may sit anywhere in the plot makes selection frustrating.
+ */
+export function hitTestByX(
+	regions: readonly HitRegion[],
+	x: number,
+): HitResult | null {
+	let best: HitResult | null = null;
+
+	for (const region of regions) {
+		if (!region.selectable) {
+			continue;
+		}
+		const distance = Math.abs(region.x - x);
+		if (best === null || distance < best.distance) {
+			best = { seriesId: region.seriesId, pointId: region.pointId, distance };
+		}
+	}
+
+	return best;
+}
+
+export function findRegion(
+	regions: readonly HitRegion[],
+	seriesId: string,
+	pointId?: string,
+): HitRegion | undefined {
+	return regions.find(
+		r => r.seriesId === seriesId && (pointId === undefined || r.pointId === pointId),
+	);
+}

package/src/geometry/layout.ts

@@ -0,0 +1,121 @@
+/**
+ * Plot layout: turning a container size into a drawable plot rectangle.
+ *
+ * Font scale arrives as a parameter rather than being read from `PixelRatio`
+ * here, so this module stays pure and testable at any scale without mocking a
+ * platform API. The React layer reads the real value and passes it in.
+ *
+ * PURE. No React, no SVG.
+ */
+import { reserveAxisSpace } from './ticks';
+
+export interface PlotRect {
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+}
+
+export interface ContainerSize {
+	readonly width: number;
+	readonly height: number;
+}
+
+export interface LayoutOptions {
+	readonly container: ContainerSize;
+	/** Axis label text, used to reserve exactly as much space as is needed. */
+	readonly xLabels?: readonly string[];
+	readonly yLabels?: readonly string[];
+	readonly baseFontSize: number;
+	/** System text-size multiplier, from `PixelRatio.getFontScale()` (FR-071). */
+	readonly fontScale: number;
+	readonly padding?: number;
+}
+
+/**
+ * Ceiling on how far system text scaling may inflate chart labels.
+ *
+ * Beyond this the plot area collapses faster than the labels become useful, so
+ * we cap the growth rather than let the chart squeeze itself out of existence.
+ * The cap is documented in the README as the supported dynamic-type range.
+ */
+export const MAX_FONT_SCALE = 1.6;
+
+export function effectiveFontSize(
+	baseFontSize: number,
+	fontScale: number,
+): number {
+	const clamped = Math.max(1, Math.min(fontScale, MAX_FONT_SCALE));
+	return Math.round(baseFontSize * clamped);
+}
+
+/** A container that has not been measured yet, or has collapsed (FR-078). */
+export function isMeasurable(size: ContainerSize): boolean {
+	return (
+		Number.isFinite(size.width) &&
+		Number.isFinite(size.height) &&
+		size.width > 0 &&
+		size.height > 0
+	);
+}
+
+export const EMPTY_PLOT: PlotRect = { x: 0, y: 0, width: 0, height: 0 };
+
+/**
+ * Reserves axis space from estimated label widths, then hands back what is
+ * left for the marks.
+ *
+ * If the reservations would leave nothing to draw on, they are scaled back:
+ * a cramped axis beats a zero-area plot.
+ */
+export function resolvePlotRect(options: LayoutOptions): PlotRect {
+	if (!isMeasurable(options.container)) {
+		return EMPTY_PLOT;
+	}
+
+	const pad = options.padding ?? 0;
+	const fontSize = effectiveFontSize(options.baseFontSize, options.fontScale);
+
+	let left = pad;
+	let bottom = pad;
+
+	if (options.yLabels && options.yLabels.length > 0) {
+		left += reserveAxisSpace(options.yLabels, fontSize, 'vertical');
+	}
+	if (options.xLabels && options.xLabels.length > 0) {
+		bottom += reserveAxisSpace(options.xLabels, fontSize, 'horizontal');
+	}
+
+	const availableWidth = options.container.width - pad;
+	const availableHeight = options.container.height - pad;
+
+	// Never let axis reservations consume more than 40% of either dimension.
+	const maxLeft = availableWidth * 0.4;
+	const maxBottom = availableHeight * 0.4;
+	left = Math.min(left, maxLeft);
+	bottom = Math.min(bottom, maxBottom);
+
+	return {
+		x: left,
+		y: pad,
+		width: Math.max(0, options.container.width - left - pad),
+		height: Math.max(0, options.container.height - bottom - pad),
+	};
+}
+
+export function plotBottom(plot: PlotRect): number {
+	return plot.y + plot.height;
+}
+
+export function plotRight(plot: PlotRect): number {
+	return plot.x + plot.width;
+}
+
+export function containsPoint(plot: PlotRect, x: number, y: number): boolean {
+	return (
+		x >= plot.x &&
+		x <= plotRight(plot) &&
+		y >= plot.y &&
+		y <= plotBottom(plot)
+	);
+}