@chipmobilesdk/rn-chart 0.1.0

package/src/geometry/path.ts

@@ -0,0 +1,199 @@
+/**
+ * SVG path-string builders.
+ *
+ * This is where the "never bridge a gap" guarantee (FR-012) becomes
+ * structural rather than a rule someone has to remember. A missing value does
+ * not produce a coordinate — it ends the current subpath. The next known value
+ * starts a fresh one with an `M` command. There is physically no line segment
+ * spanning the gap, so no amount of downstream carelessness can draw one.
+ *
+ * Batching into path data is also what keeps element counts flat: one `Path`
+ * per series regardless of point count (research.md R2).
+ *
+ * PURE. No React, no SVG imports — this module emits strings.
+ */
+
+export interface Pt {
+	readonly x: number;
+	readonly y: number;
+}
+
+/** A point that may be absent, mirroring the value contract. */
+export type MaybePt = Pt | null;
+
+function n(value: number): string {
+	// Two decimals is well below sub-pixel visibility and keeps `d` strings
+	// short, which matters when they cross the bridge on every data change.
+	return Number.isFinite(value) ? value.toFixed(2) : '0';
+}
+
+/**
+ * Polyline through the known points, broken at every gap.
+ *
+ * `null` entries are missing values. They terminate the current subpath; they
+ * are never interpolated, carried forward, or skipped over.
+ */
+export function linePath(points: readonly MaybePt[]): string {
+	let d = '';
+	let penDown = false;
+
+	for (const p of points) {
+		if (p === null) {
+			// Lift the pen. The gap stays a gap.
+			penDown = false;
+			continue;
+		}
+		if (!penDown) {
+			d += `M${n(p.x)} ${n(p.y)}`;
+			penDown = true;
+		} else {
+			d += `L${n(p.x)} ${n(p.y)}`;
+		}
+	}
+
+	return d;
+}
+
+/**
+ * Filled area between the polyline and a baseline, broken at gaps in the same
+ * way: each contiguous run of known points becomes its own closed shape.
+ */
+export function areaPath(
+	points: readonly MaybePt[],
+	baselineY: number,
+): string {
+	let d = '';
+	let run: Pt[] = [];
+
+	const flush = () => {
+		if (run.length === 0) {
+			return;
+		}
+		d += `M${n(run[0].x)} ${n(baselineY)}`;
+		for (const p of run) {
+			d += `L${n(p.x)} ${n(p.y)}`;
+		}
+		d += `L${n(run[run.length - 1].x)} ${n(baselineY)}Z`;
+		run = [];
+	};
+
+	for (const p of points) {
+		if (p === null) {
+			flush();
+		} else {
+			run.push(p);
+		}
+	}
+	flush();
+
+	return d;
+}
+
+export interface RectSpec {
+	readonly x: number;
+	readonly y: number;
+	readonly width: number;
+	readonly height: number;
+	readonly radius?: number;
+}
+
+/** One rectangle as a subpath, with optional corner rounding. */
+export function rectSubpath(r: RectSpec): string {
+	const radius = Math.min(r.radius ?? 0, r.width / 2, Math.abs(r.height) / 2);
+
+	if (radius <= 0) {
+		return (
+			`M${n(r.x)} ${n(r.y)}` +
+			`h${n(r.width)}v${n(r.height)}h${n(-r.width)}Z`
+		);
+	}
+
+	const { x, y, width: w, height: h } = r;
+	return (
+		`M${n(x + radius)} ${n(y)}` +
+		`h${n(w - radius * 2)}` +
+		`a${n(radius)} ${n(radius)} 0 0 1 ${n(radius)} ${n(radius)}` +
+		`v${n(h - radius * 2)}` +
+		`a${n(radius)} ${n(radius)} 0 0 1 ${n(-radius)} ${n(radius)}` +
+		`h${n(-(w - radius * 2))}` +
+		`a${n(radius)} ${n(radius)} 0 0 1 ${n(-radius)} ${n(-radius)}` +
+		`v${n(-(h - radius * 2))}` +
+		`a${n(radius)} ${n(radius)} 0 0 1 ${n(radius)} ${n(-radius)}Z`
+	);
+}
+
+/**
+ * Many rectangles batched into one path — how bars and heatmap cells stay at
+ * one element per series or per intensity bucket.
+ */
+export function rectBatchPath(rects: readonly RectSpec[]): string {
+	let d = '';
+	for (const r of rects) {
+		d += rectSubpath(r);
+	}
+	return d;
+}
+
+export interface ArcSpec {
+	readonly cx: number;
+	readonly cy: number;
+	readonly outerRadius: number;
+	readonly innerRadius: number;
+	/** Radians, clockwise from 12 o'clock. */
+	readonly startAngle: number;
+	readonly endAngle: number;
+}
+
+function polar(cx: number, cy: number, r: number, angle: number): Pt {
+	// Offset by -90 degrees so 0 radians is 12 o'clock, which is where users
+	// expect a donut to start.
+	const a = angle - Math.PI / 2;
+	return { x: cx + r * Math.cos(a), y: cy + r * Math.sin(a) };
+}
+
+/**
+ * Donut or pie segment. An inner radius of 0 yields a pie wedge.
+ *
+ * A full-circle segment is drawn as two half-arcs, because SVG cannot express
+ * a 360-degree arc in a single command — start and end would coincide and
+ * nothing would be drawn.
+ */
+export function arcPath(spec: ArcSpec): string {
+	const { cx, cy, outerRadius: ro, innerRadius: ri } = spec;
+	const sweep = spec.endAngle - spec.startAngle;
+	const full = Math.abs(sweep) >= Math.PI * 2 - 1e-9;
+
+	if (full) {
+		const mid = spec.startAngle + Math.PI;
+		return (
+			arcPath({ ...spec, endAngle: mid }) +
+			arcPath({ ...spec, startAngle: mid, endAngle: spec.startAngle + Math.PI * 2 })
+		);
+	}
+
+	const largeArc = Math.abs(sweep) > Math.PI ? 1 : 0;
+	const o0 = polar(cx, cy, ro, spec.startAngle);
+	const o1 = polar(cx, cy, ro, spec.endAngle);
+
+	if (ri <= 0) {
+		return (
+			`M${n(cx)} ${n(cy)}` +
+			`L${n(o0.x)} ${n(o0.y)}` +
+			`A${n(ro)} ${n(ro)} 0 ${largeArc} 1 ${n(o1.x)} ${n(o1.y)}Z`
+		);
+	}
+
+	const i1 = polar(cx, cy, ri, spec.endAngle);
+	const i0 = polar(cx, cy, ri, spec.startAngle);
+	return (
+		`M${n(o0.x)} ${n(o0.y)}` +
+		`A${n(ro)} ${n(ro)} 0 ${largeArc} 1 ${n(o1.x)} ${n(o1.y)}` +
+		`L${n(i1.x)} ${n(i1.y)}` +
+		`A${n(ri)} ${n(ri)} 0 ${largeArc} 0 ${n(i0.x)} ${n(i0.y)}Z`
+	);
+}
+
+/** Straight line, for axes, baselines, and threshold markers. */
+export function linearSegment(from: Pt, to: Pt): string {
+	return `M${n(from.x)} ${n(from.y)}L${n(to.x)} ${n(to.y)}`;
+}

package/src/geometry/progress.ts

@@ -0,0 +1,204 @@
+/**
+ * Progress geometry: current value against an optional target.
+ *
+ * The rule that matters (FR-021, FR-022): with no usable target there is **no
+ * proportion**. The chart shows the current value and nothing else. And a value
+ * beyond its target renders as overshoot rather than a clamped full bar that
+ * hides the excess.
+ *
+ * PURE. No React, no SVG.
+ */
+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 { rectSubpath } from './path';
+import type {
+	GeometryInput,
+	GeometryLabel,
+	MarkPath,
+	ResolvedGeometry,
+} from './types';
+
+export interface ProgressOptions {
+	readonly orientation?: 'horizontal' | 'vertical';
+	readonly trackRadius?: number;
+}
+
+/** How far past the target an overshoot bar is allowed to extend visually. */
+const OVERSHOOT_DISPLAY_CAP = 1.25;
+
+export function buildProgressGeometry<M>(
+	datasource: ChartDatasource<M>,
+	input: GeometryInput,
+	options: ProgressOptions = {},
+): ResolvedGeometry {
+	const { plot } = input;
+	const metrics = datasource.series.flatMap(series =>
+		series.points.map(point => ({ series, point })),
+	);
+
+	if (metrics.length === 0 || plot.width <= 0) {
+		return {
+			plot,
+			paths: [],
+			markers: [],
+			labels: [],
+			xTicks: [],
+			yTicks: [],
+			hitRegions: [],
+			incomplete: false,
+		};
+	}
+
+	const rowHeight = plot.height / metrics.length;
+	const barHeight = Math.min(rowHeight * 0.45, 24);
+	const radius = options.trackRadius ?? barHeight / 2;
+
+	const paths: MarkPath[] = [];
+	const labels: GeometryLabel[] = [];
+	const hitRegions: HitRegion[] = [];
+	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);
+
+		// Track: the full width, always drawn, so an empty metric still reads as
+		// a metric rather than as blank space.
+		paths.push({
+			key: `track-${series.id}-${point.id}`,
+			seriesId: series.id,
+			d: rectSubpath({
+				x: plot.x,
+				y: rowY,
+				width: plot.width,
+				height: barHeight,
+				radius,
+			}),
+			color: input.seriesColors[series.id],
+			pattern: 'solid',
+			filled: true,
+			opacity: 0.15,
+		});
+
+		if (!isKnown(point.value)) {
+			incomplete = true;
+			// No fill at all, and a texture rather than a zero-length bar — a gap
+			// must not look like "none of the target achieved".
+			paths.push({
+				key: `nonvalue-${series.id}-${point.id}`,
+				seriesId: series.id,
+				d: rectSubpath({
+					x: plot.x,
+					y: rowY,
+					width: plot.width,
+					height: barHeight,
+					radius,
+				}),
+				color: input.seriesColors[series.id],
+				pattern: 'solid',
+				filled: true,
+				texture: input.nonValueTextures[point.value.kind],
+				opacity: 0.5,
+			});
+		} else {
+			const proportion = reading.proportion;
+			// With no usable target there is no proportion to draw, so the fill
+			// shows the value's presence rather than a fabricated percentage.
+			const fillFraction =
+				proportion === undefined
+					? 1
+					: Math.min(proportion, OVERSHOOT_DISPLAY_CAP);
+
+			paths.push({
+				key: `fill-${series.id}-${point.id}`,
+				seriesId: series.id,
+				d: rectSubpath({
+					x: plot.x,
+					y: rowY,
+					width: Math.max(0, plot.width * Math.min(fillFraction, 1)),
+					height: barHeight,
+					radius,
+				}),
+				color: input.seriesColors[series.id],
+				pattern: 'solid',
+				filled: true,
+			});
+
+			// Overshoot is drawn beyond the target line rather than clamped away,
+			// 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);
+				paths.push({
+					key: `overshoot-${series.id}-${point.id}`,
+					seriesId: series.id,
+					d: rectSubpath({
+						x: plot.x + plot.width,
+						y: rowY + barHeight * 0.2,
+						width: Math.max(0, overshootWidth),
+						height: barHeight * 0.6,
+						radius: radius / 2,
+					}),
+					color: input.seriesColors[series.id],
+					pattern: 'dashed',
+					filled: true,
+					opacity: 0.7,
+				});
+			}
+		}
+
+		const valueText = isKnown(point.value)
+			? input.formatValue(point.value.value)
+			: '';
+		// Only append a percentage when one is real.
+		const proportionText =
+			reading.proportion === undefined
+				? ''
+				: ` (${Math.round(reading.proportion * 100)}%)`;
+
+		labels.push({
+			key: `label-${series.id}-${point.id}`,
+			text: input.formatCategory(
+				point.position.kind === 'category' ? point.position.category : series.label,
+			),
+			x: plot.x,
+			y: rowY - 4,
+			anchor: 'start',
+		});
+
+		if (valueText) {
+			labels.push({
+				key: `value-${series.id}-${point.id}`,
+				text: `${valueText}${proportionText}`,
+				x: plotRight(plot),
+				y: rowY - 4,
+				anchor: 'end',
+			});
+		}
+
+		hitRegions.push({
+			seriesId: series.id,
+			pointId: point.id,
+			x: plot.x + plot.width / 2,
+			y: rowY + barHeight / 2,
+			bounds: { x: plot.x, y: rowY, width: plot.width, height: barHeight },
+			selectable: !isWithheld(point.value),
+		});
+	});
+
+	return {
+		plot,
+		paths,
+		markers: [],
+		labels,
+		xTicks: [],
+		yTicks: [],
+		hitRegions,
+		incomplete,
+	};
+}

package/src/geometry/scale.ts

@@ -0,0 +1,146 @@
+/**
+ * Scales: domain values to pixel positions.
+ *
+ * PURE. No React, no SVG — enforced by the ESLint override in `.eslintrc.js`
+ * and by geometryPurity.test.ts.
+ */
+
+export interface Range {
+	readonly min: number;
+	readonly max: number;
+}
+
+export interface LinearScale {
+	readonly domain: Range;
+	readonly rangePx: Range;
+	readonly project: (value: number) => number;
+	readonly invert: (px: number) => number;
+}
+
+/**
+ * Nudges a zero-width domain outward so an all-identical dataset still gets a
+ * 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 {
+	if (domain.max > domain.min) {
+		return domain;
+	}
+	const value = domain.min;
+	// Scale the padding to the magnitude so large values do not get a
+	// meaninglessly tiny window, and zero still gets a sensible one.
+	const pad = value === 0 ? 1 : Math.abs(value) * 0.5;
+	return { min: value - pad, max: value + pad };
+}
+
+export function linearScale(domain: Range, rangePx: Range): LinearScale {
+	const safeDomain = widenDegenerateDomain(domain);
+	const domainSpan = safeDomain.max - safeDomain.min;
+	const pxSpan = rangePx.max - rangePx.min;
+
+	return {
+		domain: safeDomain,
+		rangePx,
+		project: (value: number) =>
+			rangePx.min + ((value - safeDomain.min) / domainSpan) * pxSpan,
+		invert: (px: number) =>
+			safeDomain.min + ((px - rangePx.min) / pxSpan) * domainSpan,
+	};
+}
+
+export interface BandScale {
+	readonly categories: readonly string[];
+	readonly bandWidth: number;
+	readonly step: number;
+	readonly project: (category: string) => number | undefined;
+	readonly centerOf: (category: string) => number | undefined;
+	readonly invert: (px: number) => string | undefined;
+}
+
+/**
+ * Discrete positions for category axes.
+ *
+ * `padding` is the fraction of each step left as gap, so 0.2 means bars occupy
+ * 80% of their slot.
+ */
+export function bandScale(
+	categories: readonly string[],
+	rangePx: Range,
+	padding = 0.2,
+): BandScale {
+	const count = Math.max(categories.length, 1);
+	const pxSpan = rangePx.max - rangePx.min;
+	const step = pxSpan / count;
+	const bandWidth = step * (1 - padding);
+	const offset = (step - bandWidth) / 2;
+
+	const indexOf = new Map<string, number>();
+	categories.forEach((c, i) => {
+		if (!indexOf.has(c)) {
+			indexOf.set(c, i);
+		}
+	});
+
+	const project = (category: string): number | undefined => {
+		const i = indexOf.get(category);
+		return i === undefined ? undefined : rangePx.min + i * step + offset;
+	};
+
+	return {
+		categories,
+		bandWidth,
+		step,
+		project,
+		centerOf: (category: string) => {
+			const start = project(category);
+			return start === undefined ? undefined : start + bandWidth / 2;
+		},
+		invert: (px: number) => {
+			const i = Math.floor((px - rangePx.min) / step);
+			return i >= 0 && i < categories.length ? categories[i] : undefined;
+		},
+	};
+}
+
+/**
+ * Time is just a linear scale over epoch milliseconds. Kept as a named
+ * function so call sites read clearly and so tick generation can branch on it.
+ */
+export function timeScale(domain: Range, rangePx: Range): LinearScale {
+	return linearScale(domain, rangePx);
+}
+
+/**
+ * Domain from known values, padded so marks do not touch the plot edges.
+ *
+ * `includeZero` matters for bar charts: a bar's length is only meaningful when
+ * measured from zero. Time-series charts leave it off so a narrow band of
+ * values stays legible.
+ */
+export function domainFrom(
+	values: readonly number[],
+	options: { includeZero?: boolean; padFraction?: number } = {},
+): Range {
+	if (values.length === 0) {
+		return { min: 0, max: 1 };
+	}
+
+	let min = values[0];
+	let max = values[0];
+	for (const v of values) {
+		if (v < min) {
+			min = v;
+		}
+		if (v > max) {
+			max = v;
+		}
+	}
+
+	if (options.includeZero) {
+		min = Math.min(min, 0);
+		max = Math.max(max, 0);
+	}
+
+	const pad = (max - min) * (options.padFraction ?? 0);
+	return { min: min - pad, max: max + pad };
+}

package/src/geometry/ticks.ts

@@ -0,0 +1,153 @@
+/**
+ * Tick generation and label thinning (FR-070).
+ *
+ * React Native offers no synchronous text measurement, and an `onLayout`
+ * round-trip per label would cost a second layout pass — enough to breach the
+ * first-paint budget. So we estimate width from character count and thin ticks
+ * to fit.
+ *
+ * The estimate is deliberately generous: over-estimating drops one tick too
+ * many, which is legible. Under-estimating produces overlapping text, which is
+ * the failure FR-070 exists to prevent. See research.md R6.
+ *
+ * PURE. No React, no SVG.
+ */
+import type { Range } from './scale';
+
+/**
+ * Average glyph advance as a fraction of font size, for the Latin digits and
+ * letters that dominate axis labels. Rounded up from the ~0.5-0.55 typical of
+ * the platform sans-serif faces.
+ */
+export const AVERAGE_ADVANCE_RATIO = 0.62;
+
+/** Minimum breathing room between two adjacent labels, in px. */
+export const LABEL_GUTTER = 8;
+
+export function estimateTextWidth(text: string, fontSize: number): number {
+	return text.length * fontSize * AVERAGE_ADVANCE_RATIO;
+}
+
+export interface Tick {
+	/** Domain value this tick represents. */
+	readonly value: number;
+	/** Pixel position along the axis. */
+	readonly position: number;
+	readonly label: string;
+}
+
+/**
+ * "Nice" step sizes: 1, 2, 5 and their powers of ten. Standard axis practice —
+ * these are the intervals people read fluently.
+ */
+function niceStep(rawStep: number): number {
+	if (rawStep <= 0 || !Number.isFinite(rawStep)) {
+		return 1;
+	}
+	const magnitude = Math.pow(10, Math.floor(Math.log10(rawStep)));
+	const normalized = rawStep / magnitude;
+
+	if (normalized <= 1) {
+		return magnitude;
+	}
+	if (normalized <= 2) {
+		return 2 * magnitude;
+	}
+	if (normalized <= 5) {
+		return 5 * magnitude;
+	}
+	return 10 * magnitude;
+}
+
+export function niceTickValues(domain: Range, targetCount: number): number[] {
+	const span = domain.max - domain.min;
+	if (span <= 0 || targetCount < 1) {
+		return [domain.min];
+	}
+
+	const step = niceStep(span / targetCount);
+	const start = Math.ceil(domain.min / step) * step;
+
+	const values: number[] = [];
+	// Guard against a pathological step producing an unbounded loop.
+	for (let v = start, guard = 0; v <= domain.max && guard < 1000; v += step) {
+		// Re-round to kill floating-point drift such as 0.30000000000000004.
+		values.push(Number((Math.round(v / step) * step).toFixed(10)));
+		guard += 1;
+	}
+	return values.length > 0 ? values : [domain.min];
+}
+
+/**
+ * Drops ticks until no two labels can overlap.
+ *
+ * Thinning is preferred over rotation as the default: rotated labels are harder
+ * to read on a phone and cost vertical space a mobile chart cannot spare.
+ * Rotation stays available as an opt-in for dense category axes.
+ *
+ * The first tick is always kept, so an axis never renders empty.
+ */
+export function thinTicks(
+	ticks: readonly Tick[],
+	fontSize: number,
+	axisLengthPx: number,
+): Tick[] {
+	if (ticks.length <= 1) {
+		return [...ticks];
+	}
+
+	let widest = 0;
+	for (const t of ticks) {
+		widest = Math.max(widest, estimateTextWidth(t.label, fontSize));
+	}
+
+	const slot = widest + LABEL_GUTTER;
+	const maxLabels = Math.max(1, Math.floor(axisLengthPx / slot));
+	if (ticks.length <= maxLabels) {
+		return [...ticks];
+	}
+
+	const stride = Math.ceil(ticks.length / maxLabels);
+	return ticks.filter((_, i) => i % stride === 0);
+}
+
+/**
+ * How much space an axis must reserve for its labels, at the current system
+ * font scale (FR-071).
+ */
+export function reserveAxisSpace(
+	labels: readonly string[],
+	fontSize: number,
+	orientation: 'horizontal' | 'vertical',
+): number {
+	if (labels.length === 0) {
+		return 0;
+	}
+	if (orientation === 'horizontal') {
+		// One line of text plus a gutter.
+		return fontSize * 1.4 + LABEL_GUTTER;
+	}
+
+	let widest = 0;
+	for (const label of labels) {
+		widest = Math.max(widest, estimateTextWidth(label, fontSize));
+	}
+	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)}…`;
+}