@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/geometry/path.ts

@@ -1,199 +1,193 @@
-/**
- * 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)}`;
-}
+/**
+ * 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)}`;
+}