@chipmobilesdk/rn-chart 0.1.0

package/src/render/Axis.tsx

@@ -0,0 +1,122 @@
+/**
+ * Axis and grid rendering. Private SVG adapter.
+ *
+ * Ticks arrive already thinned by `geometry/ticks.ts`, so nothing here decides
+ * what fits — this module only draws what the geometry chose.
+ */
+import React from 'react';
+import { G, Line, Text as SvgText } from 'react-native-svg';
+
+import type { ChartTheme } from '../contract/theme';
+import type { PlotRect } from '../geometry/layout';
+import { plotBottom, plotRight } from '../geometry/layout';
+import type { Tick } from '../geometry/ticks';
+
+export function Grid({
+	plot,
+	yTicks,
+	theme,
+}: {
+	readonly plot: PlotRect;
+	readonly yTicks: readonly Tick[];
+	readonly theme: ChartTheme;
+}) {
+	return (
+		<G>
+			{yTicks.map(tick => (
+				<Line
+					key={`grid-${tick.value}`}
+					x1={plot.x}
+					y1={tick.position}
+					x2={plotRight(plot)}
+					y2={tick.position}
+					stroke={theme.grid}
+					strokeWidth={1}
+				/>
+			))}
+		</G>
+	);
+}
+
+export function XAxis({
+	plot,
+	ticks,
+	theme,
+	fontSize,
+	rotateLabels,
+}: {
+	readonly plot: PlotRect;
+	readonly ticks: readonly Tick[];
+	readonly theme: ChartTheme;
+	readonly fontSize: number;
+	readonly rotateLabels?: boolean;
+}) {
+	const baseline = plotBottom(plot);
+
+	return (
+		<G>
+			<Line
+				x1={plot.x}
+				y1={baseline}
+				x2={plotRight(plot)}
+				y2={baseline}
+				stroke={theme.axis}
+				strokeWidth={1}
+			/>
+			{ticks.map(tick => (
+				<SvgText
+					key={`x-${tick.position}-${tick.label}`}
+					x={tick.position}
+					y={baseline + fontSize + 4}
+					fill={theme.typography.axisLabel.color}
+					fontSize={fontSize}
+					textAnchor={rotateLabels ? 'end' : 'middle'}
+					transform={
+						rotateLabels
+							? `rotate(-45, ${tick.position}, ${baseline + fontSize + 4})`
+							: undefined
+					}
+				>
+					{tick.label}
+				</SvgText>
+			))}
+		</G>
+	);
+}
+
+export function YAxis({
+	plot,
+	ticks,
+	theme,
+	fontSize,
+}: {
+	readonly plot: PlotRect;
+	readonly ticks: readonly Tick[];
+	readonly theme: ChartTheme;
+	readonly fontSize: number;
+}) {
+	return (
+		<G>
+			<Line
+				x1={plot.x}
+				y1={plot.y}
+				x2={plot.x}
+				y2={plotBottom(plot)}
+				stroke={theme.axis}
+				strokeWidth={1}
+			/>
+			{ticks.map(tick => (
+				<SvgText
+					key={`y-${tick.position}-${tick.label}`}
+					x={plot.x - 6}
+					y={tick.position + fontSize / 3}
+					fill={theme.typography.axisLabel.color}
+					fontSize={fontSize}
+					textAnchor="end"
+				>
+					{tick.label}
+				</SvgText>
+			))}
+		</G>
+	);
+}

package/src/render/Marks.tsx

@@ -0,0 +1,205 @@
+/**
+ * Private SVG adapter for resolved geometry.
+ *
+ * Everything here consumes plain data produced by `geometry/`. Swapping the
+ * drawing substrate means rewriting this directory and nothing else.
+ */
+import React from 'react';
+import {
+	Defs,
+	G,
+	Path,
+	Pattern,
+	Rect,
+	Text as SvgText,
+} from 'react-native-svg';
+
+import type { SeriesPattern } from '../contract/datasource';
+import type { ChartTheme, NonValueTexture } from '../contract/theme';
+import type { GeometryLabel, MarkPath, MarkerLine } from '../geometry/types';
+
+/**
+ * Dash patterns give series a second, non-colour identity (FR-064). `undefined`
+ * means a solid stroke.
+ */
+export function dashArrayFor(pattern: SeriesPattern): string | undefined {
+	switch (pattern) {
+		case 'dashed':
+			return '6,4';
+		case 'dotted':
+			return '1,4';
+		case 'dashDot':
+			return '8,3,1,3';
+		default:
+			return undefined;
+	}
+}
+
+const TEXTURE_IDS: Record<NonValueTexture, string> = {
+	gap: 'rnchart-texture-gap',
+	hatch: 'rnchart-texture-hatch',
+	lockedHatch: 'rnchart-texture-locked',
+};
+
+/**
+ * Texture definitions for the three non-value classes.
+ *
+ * Deliberately shape-based rather than colour-based: a reader in greyscale, or
+ * with reduced colour perception, must still tell a gap from a hatch from a
+ * locked cell (FR-064, SC-012).
+ */
+export function NonValueTextures({ theme }: { readonly theme: ChartTheme }) {
+	return (
+		<Defs>
+			{/* unknown: sparse dots — visibly "nothing here". */}
+			<Pattern
+				id={TEXTURE_IDS.gap}
+				patternUnits="userSpaceOnUse"
+				width="6"
+				height="6"
+			>
+				<Rect width="6" height="6" fill={theme.surface} />
+				<Rect x="2" y="2" width="1.5" height="1.5" fill={theme.muted} />
+			</Pattern>
+
+			{/* notApplicable: single diagonal hatch. */}
+			<Pattern
+				id={TEXTURE_IDS.hatch}
+				patternUnits="userSpaceOnUse"
+				width="8"
+				height="8"
+			>
+				<Rect width="8" height="8" fill={theme.surface} />
+				<Path d="M0 8L8 0" stroke={theme.muted} strokeWidth="1" />
+			</Pattern>
+
+			{/* withheld: cross hatch — denser, reading as deliberately closed off. */}
+			<Pattern
+				id={TEXTURE_IDS.lockedHatch}
+				patternUnits="userSpaceOnUse"
+				width="8"
+				height="8"
+			>
+				<Rect width="8" height="8" fill={theme.surface} />
+				<Path d="M0 8L8 0M0 0L8 8" stroke={theme.muted} strokeWidth="1" />
+			</Pattern>
+		</Defs>
+	);
+}
+
+function fillFor(mark: MarkPath): string {
+	if (mark.texture) {
+		return `url(#${TEXTURE_IDS[mark.texture]})`;
+	}
+	return mark.filled ? mark.color : 'none';
+}
+
+export function Marks({
+	paths,
+	selectedKeys,
+}: {
+	readonly paths: readonly MarkPath[];
+	readonly selectedKeys?: ReadonlySet<string>;
+}) {
+	return (
+		<G>
+			{paths.map(mark => {
+				const highlighted = selectedKeys?.has(mark.seriesId);
+				return (
+					<Path
+						key={mark.key}
+						d={mark.d}
+						fill={fillFor(mark)}
+						stroke={mark.filled ? 'none' : mark.color}
+						strokeWidth={mark.filled ? 0 : highlighted ? 3 : 2}
+						strokeDasharray={
+							mark.filled ? undefined : dashArrayFor(mark.pattern)
+						}
+						strokeLinejoin="round"
+						strokeLinecap="round"
+						opacity={mark.opacity ?? 1}
+					/>
+				);
+			})}
+		</G>
+	);
+}
+
+export function MarkerLines({
+	markers,
+	theme,
+}: {
+	readonly markers: readonly MarkerLine[];
+	readonly theme: ChartTheme;
+}) {
+	return (
+		<G>
+			{markers.map(marker => (
+				<Path
+					key={marker.id}
+					d={marker.d}
+					stroke={theme.onSurface}
+					strokeWidth={1}
+					strokeDasharray="4,3"
+					fill="none"
+				/>
+			))}
+		</G>
+	);
+}
+
+export function GeometryLabels({
+	labels,
+	theme,
+	fontSize,
+}: {
+	readonly labels: readonly GeometryLabel[];
+	readonly theme: ChartTheme;
+	readonly fontSize: number;
+}) {
+	return (
+		<G>
+			{labels
+				.filter(label => !label.muted)
+				.map(label => (
+					<SvgText
+						key={label.key}
+						x={label.x}
+						y={label.y}
+						fill={theme.typography.valueLabel.color}
+						fontSize={fontSize}
+						fontWeight={theme.typography.valueLabel.fontWeight}
+						textAnchor={label.anchor}
+					>
+						{label.text}
+					</SvgText>
+				))}
+		</G>
+	);
+}
+
+/** Marks the currently selected point, when it still resolves. */
+export function SelectionHighlight({
+	x,
+	y,
+	color,
+}: {
+	readonly x: number;
+	readonly y: number;
+	readonly color: string;
+}) {
+	return (
+		<G>
+			<Rect
+				x={x - 6}
+				y={y - 6}
+				width={12}
+				height={12}
+				rx={6}
+				fill={color}
+				opacity={0.25}
+			/>
+			<Rect x={x - 3} y={y - 3} width={6} height={6} rx={3} fill={color} />
+		</G>
+	);
+}

package/src/validation/budgets.ts

@@ -0,0 +1,110 @@
+/**
+ * Dataset budgets (FR-074, FR-075, FR-076).
+ *
+ * Over budget, the chart **still renders**. Degrading silently would break the
+ * "never present a reduced picture as complete" rule, and refusing to draw
+ * would turn a performance hint into an outage. Instead we warn the developer
+ * once, in dev builds only.
+ *
+ * The `__DEV__` gate matters: it makes the check dead code that Metro strips
+ * from release bundles, which is what makes "never in production" verifiable
+ * rather than merely intended.
+ *
+ * The figures were validated against emitted element counts in
+ * specs/007-rn-chart-package/research.md R2 — element count scales with series,
+ * not with points, so these budgets are about JS work rather than view count.
+ */
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+
+export interface DatasetBudget {
+	readonly maxSeries: number;
+	readonly maxPointsPerSeries?: number;
+	readonly maxCells?: number;
+}
+
+export const DATASET_BUDGETS: Readonly<Record<ChartFamily, DatasetBudget>> = {
+	timeSeries: { maxSeries: 5, maxPointsPerSeries: 500 },
+	bar: { maxSeries: 5, maxPointsPerSeries: 60 },
+	distribution: { maxSeries: 1, maxPointsPerSeries: 12 },
+	progress: { maxSeries: 1, maxPointsPerSeries: 8 },
+	heatmap: { maxSeries: 1, maxCells: 1000 },
+};
+
+export interface BudgetCheck {
+	readonly withinBudget: boolean;
+	readonly seriesCount: number;
+	readonly maxPointsInAnySeries: number;
+	readonly totalPoints: number;
+}
+
+export function checkBudget<M>(
+	datasource: ChartDatasource<M>,
+	family: ChartFamily,
+): BudgetCheck {
+	const budget = DATASET_BUDGETS[family];
+	const seriesCount = datasource.series.length;
+
+	let maxPoints = 0;
+	let totalPoints = 0;
+	for (const series of datasource.series) {
+		maxPoints = Math.max(maxPoints, series.points.length);
+		totalPoints += series.points.length;
+	}
+
+	const overSeries = seriesCount > budget.maxSeries;
+	const overPoints =
+		budget.maxPointsPerSeries !== undefined &&
+		maxPoints > budget.maxPointsPerSeries;
+	const overCells =
+		budget.maxCells !== undefined && totalPoints > budget.maxCells;
+
+	return {
+		withinBudget: !overSeries && !overPoints && !overCells,
+		seriesCount,
+		maxPointsInAnySeries: maxPoints,
+		totalPoints,
+	};
+}
+
+const warnedCharts = new Set<string>();
+
+/**
+ * Warns once per chart instance per mount. De-duplicating matters: a scrolling
+ * dashboard would otherwise flood the console on every frame.
+ */
+export function warnIfOverBudget<M>(
+	datasource: ChartDatasource<M>,
+	family: ChartFamily,
+	instanceKey: string,
+): BudgetCheck {
+	const check = checkBudget(datasource, family);
+
+	if (__DEV__ && !check.withinBudget && !warnedCharts.has(instanceKey)) {
+		warnedCharts.add(instanceKey);
+		const budget = DATASET_BUDGETS[family];
+		console.warn(
+			`[rn-chart] ${family} chart "${instanceKey}" exceeds its documented dataset budget ` +
+				`(${check.seriesCount} series x up to ${check.maxPointsInAnySeries} points; ` +
+				`budget is ${budget.maxSeries} series` +
+				(budget.maxPointsPerSeries
+					? ` x ${budget.maxPointsPerSeries} points`
+					: '') +
+				(budget.maxCells ? `, ${budget.maxCells} cells` : '') +
+				'). The chart still renders and drops nothing — aggregate or downsample ' +
+				'upstream if it feels slow. This warning appears once per chart and never ' +
+				'in production builds.',
+		);
+	}
+
+	return check;
+}
+
+/** Called on unmount so a remounted chart can warn again. */
+export function releaseBudgetWarning(instanceKey: string): void {
+	warnedCharts.delete(instanceKey);
+}
+
+/** Test-only reset. */
+export function __resetBudgetWarnings(): void {
+	warnedCharts.clear();
+}

package/src/validation/validateDatasource.ts

@@ -0,0 +1,174 @@
+/**
+ * Datasource validation (FR-015, FR-017, FR-007a).
+ *
+ * Rules V1-V8 from specs/007-rn-chart-package/data-model.md §6. Every failure
+ * returns a `ChartError` built from the fixed message catalogue, so validation
+ * output can never carry a data value or a series label.
+ *
+ * Note V8: an empty datasource is **not** an error. It resolves to the empty
+ * state, which is a first-class outcome rather than a failure.
+ */
+import {
+	familyAcceptsPositionKind,
+	type ChartDatasource,
+	type ChartFamily,
+} from '../contract/datasource';
+import { validationError, type ChartError } from '../contract/errors';
+import { isKnown } from '../contract/value';
+
+export interface ValidationResult {
+	readonly error?: ChartError;
+	/** No points at all across every series (V8). */
+	readonly isEmpty: boolean;
+	/** Some points are known and others are not (FR-032). */
+	readonly isPartial: boolean;
+	/** Distribution segments that do not sum to the whole (V6, FR-024). */
+	readonly totalIncomplete: boolean;
+}
+
+const DISTRIBUTION_SUM_TOLERANCE = 0.001;
+
+export function validateDatasource<M>(
+	datasource: ChartDatasource<M>,
+	family: ChartFamily,
+	chartId?: string,
+): ValidationResult {
+	const base = { isEmpty: true, isPartial: false, totalIncomplete: false };
+
+	// V4 — the receiving family must accept the declared position kind. Checked
+	// first because a mismatch here makes everything downstream meaningless.
+	if (!familyAcceptsPositionKind(family, datasource.positionKind)) {
+		return {
+			...base,
+			isEmpty: false,
+			error: validationError('familyPositionKindUnsupported', {
+				chartId,
+				family,
+				detail: { actualKind: datasource.positionKind },
+			}),
+		};
+	}
+
+	// V1 — series ids unique.
+	const seenSeriesIds = new Set<string>();
+	for (const series of datasource.series) {
+		if (seenSeriesIds.has(series.id)) {
+			return {
+				...base,
+				isEmpty: false,
+				error: validationError('duplicateSeriesId', {
+					chartId,
+					family,
+					detail: { occurrences: seenSeriesIds.size },
+				}),
+			};
+		}
+		seenSeriesIds.add(series.id);
+	}
+
+	let totalPoints = 0;
+	let knownPoints = 0;
+	const matrixRows = new Set<string>();
+	const matrixColumns = new Set<string>();
+
+	for (const series of datasource.series) {
+		// V2 — point ids unique within their series.
+		const seenPointIds = new Set<string>();
+
+		for (const point of series.points) {
+			if (seenPointIds.has(point.id)) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('duplicatePointId', {
+						chartId,
+						family,
+						detail: { occurrences: seenPointIds.size },
+					}),
+				};
+			}
+			seenPointIds.add(point.id);
+
+			// V3 — every point matches the declared position kind.
+			if (point.position.kind !== datasource.positionKind) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('positionKindMismatch', {
+						chartId,
+						family,
+						detail: {
+							expectedKind: datasource.positionKind,
+							actualKind: point.position.kind,
+						},
+					}),
+				};
+			}
+
+			if (point.position.kind === 'matrix') {
+				matrixRows.add(point.position.row);
+				matrixColumns.add(point.position.column);
+			}
+
+			totalPoints += 1;
+			if (isKnown(point.value)) {
+				knownPoints += 1;
+			}
+		}
+	}
+
+	// V5 — a matrix must be rectangular: every row/column pair accounted for.
+	if (datasource.positionKind === 'matrix' && totalPoints > 0) {
+		const expected = matrixRows.size * matrixColumns.size;
+		if (totalPoints !== expected) {
+			return {
+				...base,
+				isEmpty: false,
+				error: validationError('inconsistentMatrix', {
+					chartId,
+					family,
+					detail: { occurrences: Math.abs(expected - totalPoints) },
+				}),
+			};
+		}
+	}
+
+	// V6 — distribution segments that do not sum to the whole are flagged, never
+	// rescaled. This is a flag rather than a rejection: the chart still renders
+	// and marks the total incomplete.
+	let totalIncomplete = knownPoints < totalPoints;
+	if (family === 'distribution' && totalPoints > 0) {
+		totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource);
+	}
+
+	return {
+		isEmpty: totalPoints === 0,
+		isPartial: totalPoints > 0 && knownPoints > 0 && knownPoints < totalPoints,
+		totalIncomplete,
+	};
+}
+
+/**
+ * Distribution values may be supplied either as proportions summing to 1 or as
+ * absolute values that the chart normalises for display. Only the proportion
+ * case can be checked for wholeness, and only when every point is known.
+ */
+function distributionSumsToWhole<M>(datasource: ChartDatasource<M>): boolean {
+	const values: number[] = [];
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (!isKnown(point.value)) {
+				return false;
+			}
+			values.push(point.value.value);
+		}
+	}
+
+	const sum = values.reduce((acc, n) => acc + n, 0);
+	const looksLikeProportions = values.every(v => v >= 0 && v <= 1);
+	if (!looksLikeProportions) {
+		// Absolute values: any positive sum is a whole by definition.
+		return sum > 0;
+	}
+	return Math.abs(sum - 1) <= DISTRIBUTION_SUM_TOLERANCE;
+}