@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/render/Marks.tsx

@@ -1,205 +1,173 @@
-/**
- * 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>
-	);
-}
+/**
+ * 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

@@ -1,110 +1,113 @@
-/**
- * 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();
-}
+/**
+ * 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 { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
+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>();
+
+/** Chart diagnostics also reach the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<'over_budget'>('rn-chart');
+
+/**
+ * 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);
+		channel.emit('over_budget', 'warn', {
+			family,
+			series: check.seriesCount,
+			maxPoints: check.maxPointsInAnySeries,
+		});
+		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();
+}