@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/geometry/scale.ts

@@ -1,146 +1,140 @@
-/**
- * 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.
- */
-export 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 };
-}
+/**
+ * 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.
+ */
+export 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

@@ -1,153 +1,145 @@
-/**
- * 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)}…`;
-}
+/**
+ * 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)}…`;
+}