@chipmobilesdk/rn-chart 0.2.1 → 0.4.0

package/src/react/useChartSelection.ts

@@ -2,15 +2,18 @@
  * Selection ownership: uncontrolled by default, controlled when the app
  * supplies a value (FR-054a).
  *
- * Two properties matter and both are load-bearing:
+ * Three properties matter and all are load-bearing:
  *
  *  - The selection is **resolved against the current datasource on every
  *    render** rather than stored resolved. A reference to a point that no
  *    longer exists therefore draws nothing, in either mode (FR-054).
  *  - Selection state lives outside the geometry memo, so highlighting repaints
  *    the highlight without recomputing scales or path strings (FR-073).
+ *  - `select` and `toggle` keep one identity for the life of the chart. They
+ *    read the app's callbacks through a ref, so an inline callback does not
+ *    make every render look like a change (CHT-08).
  */
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import type {
 	PointInteractionEvent,
@@ -42,11 +45,24 @@ export interface UseChartSelectionArgs<M> {
 	readonly geometryReady: boolean;
 }
 
+export interface SelectOptions {
+	/**
+	 * Selecting what is already selected clears it — the touch gesture. False
+	 * for screen-reader stepping, where landing on the same point again (a chart
+	 * with one point) must not switch the selection off and on (CHT-06).
+	 */
+	readonly toggle?: boolean;
+}
+
 export interface ChartSelectionApi<M> {
 	/** What to draw. Never a reference the datasource cannot resolve. */
 	readonly resolved: HitRegion | undefined;
 	readonly selection: SelectionRef | null;
-	readonly select: (ref: SelectionRef | null, event: PointInteractionEvent<M> | null) => void;
+	readonly select: (
+		ref: SelectionRef | null,
+		event: PointInteractionEvent<M> | null,
+		options?: SelectOptions,
+	) => void;
 }
 
 export function useChartSelection<M>(args: UseChartSelectionArgs<M>): ChartSelectionApi<M> {
@@ -62,39 +78,53 @@ export function useChartSelection<M>(args: UseChartSelectionArgs<M>): ChartSelec
 			? findRegion(args.hitRegions, selection.seriesId, selection.pointId)
 			: undefined;
 
+	const latest = useRef({ args, selection, isControlled });
+	latest.current = { args, selection, isControlled };
+
 	// Tell a controlling app when its selection stopped resolving, rather than
-	// silently ignoring it. Uncontrolled selections are cleared instead.
+	// silently ignoring it. Uncontrolled selections are cleared instead. Keyed
+	// on what the selection is, not on object identity, so an app passing
+	// `selection={{…}}` inline does not re-run this every render.
+	const selectionKey = selection ? `${selection.seriesId}:${selection.pointId ?? ''}` : null;
+	const unresolved =
+		selectionKey !== null && !resolved && !args.interactionSuppressed && args.geometryReady;
 	const reportedRef = useRef<string | null>(null);
 	useEffect(() => {
-		if (!selection || resolved || args.interactionSuppressed || !args.geometryReady) {
+		if (!unresolved) {
 			reportedRef.current = null;
 			return;
 		}
-
-		const key = `${selection.seriesId}:${selection.pointId ?? ''}`;
-		if (reportedRef.current === key) {
+		if (reportedRef.current === selectionKey) {
 			return;
 		}
-		reportedRef.current = key;
+		reportedRef.current = selectionKey;
 
-		if (isControlled) {
-			args.onSelectionUnresolvable?.(selection);
+		const current = latest.current;
+		if (current.isControlled) {
+			if (current.selection) {
+				current.args.onSelectionUnresolvable?.(current.selection);
+			}
 		} else {
 			setInternal(null);
 		}
-	}, [selection, resolved, isControlled, args, args.geometryReady]);
+	}, [unresolved, selectionKey]);
 
 	const select = useCallback(
-		(ref: SelectionRef | null, event: PointInteractionEvent<M> | null) => {
-			if (args.interactionSuppressed) {
+		(ref: SelectionRef | null, event: PointInteractionEvent<M> | null, options?: SelectOptions) => {
+			const current = latest.current;
+			if (current.args.interactionSuppressed) {
 				return;
 			}
-			if (!isControlled) {
-				setInternal(prev => (sameSelection(prev, ref) ? null : ref));
+			// Decided once, then used for the state and for the report: the app
+			// used to be told a point was selected at the very moment the chart
+			// dropped its highlight (CHT-06).
+			const next = options?.toggle !== false && sameSelection(current.selection, ref) ? null : ref;
+			if (!current.isControlled) {
+				setInternal(next);
 			}
-			args.onSelectionChange?.(ref, event);
+			current.args.onSelectionChange?.(next, next ? event : null);
 		},
-		[args, isControlled],
+		[],
 	);
 
 	return { resolved, selection, select };
@@ -111,42 +141,49 @@ export interface UseSeriesVisibilityArgs<M> {
 }
 
 export interface SeriesVisibilityApi {
+	/** The same Set until the hidden ids change, so memos may depend on it. */
 	readonly hidden: ReadonlySet<string>;
 	readonly toggle: (seriesId: string, metadata?: unknown) => void;
 	readonly enabled: boolean;
 }
 
+/** Cannot occur in a series id that came from JSON or a database key. */
+const SEPARATOR = '\u0000';
+
 export function useSeriesVisibility<M>(args: UseSeriesVisibilityArgs<M>): SeriesVisibilityApi {
 	const isControlled = args.controlled !== undefined;
 	const [internal, setInternal] = useState<readonly string[]>(args.initiallyHidden);
 
 	const hiddenList = isControlled ? (args.controlled ?? []) : internal;
-	const hidden = new Set(hiddenList);
+	const hiddenKey = [...hiddenList].sort((a, b) => a.localeCompare(b)).join(SEPARATOR);
+	const hidden = useMemo(
+		() => new Set(hiddenKey === '' ? [] : hiddenKey.split(SEPARATOR)),
+		[hiddenKey],
+	);
 
-	const toggle = useCallback(
-		(seriesId: string, metadata?: unknown) => {
-			if (!args.enabled) {
-				return;
-			}
+	const latest = useRef({ args, hidden, isControlled });
+	latest.current = { args, hidden, isControlled };
 
-			const currentlyHidden = new Set(isControlled ? (args.controlled ?? []) : internal);
-			const willBeVisible = currentlyHidden.has(seriesId);
+	const toggle = useCallback((seriesId: string, metadata?: unknown) => {
+		const current = latest.current;
+		if (!current.args.enabled) {
+			return;
+		}
+		const willBeVisible = current.hidden.has(seriesId);
 
-			if (!isControlled) {
-				setInternal(prev =>
-					prev.includes(seriesId) ? prev.filter(id => id !== seriesId) : [...prev, seriesId],
-				);
-			}
+		if (!current.isControlled) {
+			setInternal(prev =>
+				prev.includes(seriesId) ? prev.filter(id => id !== seriesId) : [...prev, seriesId],
+			);
+		}
 
-			args.onVisibilityChange?.({
-				type: 'visibilityChange',
-				seriesId,
-				visible: willBeVisible,
-				metadata: metadata as M,
-			});
-		},
-		[args, internal, isControlled],
-	);
+		current.args.onVisibilityChange?.({
+			type: 'visibilityChange',
+			seriesId,
+			visible: willBeVisible,
+			metadata: metadata as M,
+		});
+	}, []);
 
 	return { hidden, toggle, enabled: args.enabled };
 }

package/src/react/useChartStatus.ts

@@ -0,0 +1,85 @@
+/**
+ * What state the chart is in: validation, the app's declared status, and the
+ * one report a validation failure gets.
+ */
+import { useEffect, useMemo, useRef } from 'react';
+
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import type { DistributionValues } from '../contract/distribution';
+import { chartError, type ChartError, type ChartFailureHandler } from '../contract/errors';
+import { resolveStatus, type ChartStatus, type DeclarableChartStatus } from '../contract/state';
+import { releaseBudgetWarning, warnIfOverBudget } from '../validation/budgets';
+import { validateDatasource, type ValidationResult } from '../validation/validateDatasource';
+
+export interface UseChartStatusArgs<M> {
+	readonly datasource: ChartDatasource<M>;
+	readonly family: ChartFamily;
+	readonly chartId?: string;
+	/** `chartId`, or a generated id: what a once-per-chart warning is keyed on. */
+	readonly instanceKey: string;
+	readonly declared?: DeclarableChartStatus;
+	readonly onFailure?: ChartFailureHandler;
+	readonly distributionValues?: DistributionValues;
+}
+
+export interface ChartStatusResult {
+	readonly validation: ValidationResult;
+	readonly error: ChartError | undefined;
+	readonly status: ChartStatus;
+}
+
+export function useChartStatus<M>(args: UseChartStatusArgs<M>): ChartStatusResult {
+	const { datasource, family, chartId, instanceKey, distributionValues } = args;
+
+	const validation = useMemo(
+		() => validateDatasource(datasource, family, chartId, distributionValues),
+		[datasource, family, chartId, distributionValues],
+	);
+
+	// Warn once per chart instance, dev only, and release the key on unmount so
+	// a remount warns again. An effect, not a memo: a warning is a side effect,
+	// and React may run a memo's function more than once or discard its result.
+	useEffect(() => {
+		warnIfOverBudget(datasource, family, instanceKey);
+	}, [datasource, family, instanceKey]);
+	useEffect(() => () => releaseBudgetWarning(instanceKey), [instanceKey]);
+
+	const declaredError =
+		args.declared === 'error'
+			? chartError('declared', 'declaredByApp', { chartId, family })
+			: undefined;
+	const error = validation.error ?? declaredError;
+
+	const status = resolveStatus({
+		declared: args.declared,
+		isEmpty: validation.isEmpty,
+		isPartial: validation.isPartial,
+		error,
+	});
+
+	// A validation failure is reported through the same channel as a contained
+	// render exception, so consumers have one place to watch. `onFailure` is
+	// read through a ref: an inline callback would otherwise re-fire the report
+	// on every render.
+	const reportedRef = useRef<string | undefined>(undefined);
+	const onFailureRef = useRef(args.onFailure);
+	onFailureRef.current = args.onFailure;
+
+	useEffect(() => {
+		if (!validation.error) {
+			reportedRef.current = undefined;
+			return;
+		}
+		if (reportedRef.current === validation.error.code) {
+			return;
+		}
+		reportedRef.current = validation.error.code;
+		onFailureRef.current?.({
+			chartId: validation.error.chartId,
+			family: validation.error.family ?? family,
+			error: validation.error,
+		});
+	}, [validation.error, family]);
+
+	return { validation, error, status };
+}

package/src/render/Axis.tsx

@@ -43,26 +43,29 @@ export function XAxis({
 	ticks,
 	theme,
 	fontSize,
-	rotateLabels,
+	line = true,
 }: {
 	readonly plot: PlotRect;
 	readonly ticks: readonly Tick[];
 	readonly theme: ChartTheme;
 	readonly fontSize: number;
-	readonly rotateLabels?: boolean;
+	/** False for a heatmap: its columns are named, but there is no axis to draw. */
+	readonly line?: boolean;
 }) {
 	const baseline = plotBottom(plot);
 
 	return (
 		<G>
-			<Line
-				x1={plot.x}
-				y1={baseline}
-				x2={plotRight(plot)}
-				y2={baseline}
-				stroke={theme.axis}
-				strokeWidth={1}
-			/>
+			{line ? (
+				<Line
+					x1={plot.x}
+					y1={baseline}
+					x2={plotRight(plot)}
+					y2={baseline}
+					stroke={theme.axis}
+					strokeWidth={1}
+				/>
+			) : null}
 			{ticks.map(tick => (
 				<SvgText
 					key={`x-${tick.position}-${tick.label}`}
@@ -70,10 +73,7 @@ export function XAxis({
 					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
-					}
+					textAnchor="middle"
 				>
 					{tick.label}
 				</SvgText>
@@ -87,22 +87,26 @@ export function YAxis({
 	ticks,
 	theme,
 	fontSize,
+	line = true,
 }: {
 	readonly plot: PlotRect;
 	readonly ticks: readonly Tick[];
 	readonly theme: ChartTheme;
 	readonly fontSize: number;
+	readonly line?: boolean;
 }) {
 	return (
 		<G>
-			<Line
-				x1={plot.x}
-				y1={plot.y}
-				x2={plot.x}
-				y2={plotBottom(plot)}
-				stroke={theme.axis}
-				strokeWidth={1}
-			/>
+			{line ? (
+				<Line
+					x1={plot.x}
+					y1={plot.y}
+					x2={plot.x}
+					y2={plotBottom(plot)}
+					stroke={theme.axis}
+					strokeWidth={1}
+				/>
+			) : null}
 			{ticks.map(tick => (
 				<SvgText
 					key={`y-${tick.position}-${tick.label}`}

package/src/render/Marks.tsx

@@ -72,24 +72,17 @@ function fillFor(mark: MarkPath): string {
 	return mark.filled ? mark.color : 'none';
 }
 
-export function Marks({
-	paths,
-	selectedKeys,
-}: {
-	readonly paths: readonly MarkPath[];
-	readonly selectedKeys?: ReadonlySet<string>;
-}) {
+export function Marks({ paths }: { readonly paths: readonly MarkPath[] }) {
 	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}
+						strokeWidth={mark.filled ? 0 : 2}
 						strokeDasharray={mark.filled ? undefined : dashArrayFor(mark.pattern)}
 						strokeLinejoin="round"
 						strokeLinecap="round"

package/src/validation/budgets.ts

@@ -14,6 +14,8 @@
  * 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 {
@@ -63,6 +65,9 @@ export function checkBudget<M>(datasource: ChartDatasource<M>, family: ChartFami
 
 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.
@@ -71,11 +76,20 @@ export function warnIfOverBudget<M>(
 	datasource: ChartDatasource<M>,
 	family: ChartFamily,
 	instanceKey: string,
-): BudgetCheck {
+): void {
+	// Counting the dataset is dev work too: a release build skips it entirely.
+	if (!__DEV__ || warnedCharts.has(instanceKey)) {
+		return;
+	}
 	const check = checkBudget(datasource, family);
 
-	if (__DEV__ && !check.withinBudget && !warnedCharts.has(instanceKey)) {
+	if (!check.withinBudget) {
 		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 ` +
@@ -88,8 +102,6 @@ export function warnIfOverBudget<M>(
 				'in production builds.',
 		);
 	}
-
-	return check;
 }
 
 /** Called on unmount so a remounted chart can warn again. */

package/src/validation/validateDatasource.ts

@@ -13,6 +13,11 @@ import {
 	type ChartDatasource,
 	type ChartFamily,
 } from '../contract/datasource';
+import {
+	DISTRIBUTION_SUM_TOLERANCE,
+	resolveDistributionValues,
+	type DistributionValues,
+} from '../contract/distribution';
 import { validationError, type ChartError } from '../contract/errors';
 import { isKnown } from '../contract/value';
 
@@ -26,12 +31,12 @@ export interface ValidationResult {
 	readonly totalIncomplete: boolean;
 }
 
-const DISTRIBUTION_SUM_TOLERANCE = 0.001;
-
 export function validateDatasource<M>(
 	datasource: ChartDatasource<M>,
 	family: ChartFamily,
 	chartId?: string,
+	/** What a distribution's values mean, when the app says; inferred otherwise. */
+	distributionValues?: DistributionValues,
 ): ValidationResult {
 	const base = { isEmpty: true, isPartial: false, totalIncomplete: false };
 
@@ -110,6 +115,27 @@ export function validateDatasource<M>(
 				matrixColumns.add(point.position.column);
 			}
 
+			// V9 — a known value is a finite number, and so is an instant. NaN or
+			// Infinity used to be drawn at the origin without a word (CHT-10).
+			const finite =
+				(!isKnown(point.value) || Number.isFinite(point.value.value)) &&
+				(point.position.kind !== 'instant' || Number.isFinite(point.position.at));
+			if (!finite) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('nonFiniteValue', { chartId, family }),
+				};
+			}
+			// V10 — a share of a whole cannot be negative.
+			if (family === 'distribution' && isKnown(point.value) && point.value.value < 0) {
+				return {
+					...base,
+					isEmpty: false,
+					error: validationError('negativeDistributionValue', { chartId, family }),
+				};
+			}
+
 			totalPoints += 1;
 			if (isKnown(point.value)) {
 				knownPoints += 1;
@@ -138,7 +164,7 @@ export function validateDatasource<M>(
 	// and marks the total incomplete.
 	let totalIncomplete = knownPoints < totalPoints;
 	if (family === 'distribution' && totalPoints > 0) {
-		totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource);
+		totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource, distributionValues);
 	}
 
 	return {
@@ -149,25 +175,23 @@ export function validateDatasource<M>(
 }
 
 /**
- * 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.
+ * Only proportions can be checked for wholeness, and only when every point is
+ * known. Absolute values are a whole by definition once they sum to something.
  */
-function distributionSumsToWhole<M>(datasource: ChartDatasource<M>): boolean {
-	const values: number[] = [];
+function distributionSumsToWhole<M>(
+	datasource: ChartDatasource<M>,
+	declared?: DistributionValues,
+): boolean {
+	let sum = 0;
 	for (const series of datasource.series) {
 		for (const point of series.points) {
 			if (!isKnown(point.value)) {
 				return false;
 			}
-			values.push(point.value.value);
+			sum += 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.
+	if (resolveDistributionValues(datasource, declared) === 'absolute') {
 		return sum > 0;
 	}
 	return Math.abs(sum - 1) <= DISTRIBUTION_SUM_TOLERANCE;