@chipmobilesdk/rn-chart 0.3.0 → 0.5.0

package/src/index.ts

@@ -62,6 +62,8 @@ export {
 	resolveUnit,
 } from './contract/datasource';
 
+export type { DistributionValues } from './contract/distribution';
+
 export type { MarkerKind, ProgressReading, ReferenceMarker } from './contract/marker';
 export { findTarget, isUsableTarget, readProgress } from './contract/marker';
 
@@ -149,7 +151,8 @@ export {
 	TimeSeriesChart,
 } from './react/charts';
 
-export { ChartLegend, buildLegendEntries } from './react/ChartLegend';
+export { ChartLegend, ColorScaleLegend, buildLegendEntries } from './react/ChartLegend';
+export type { ColorScale } from './geometry/types';
 export { ChartThemeProvider, useChartTheme } from './react/ChartThemeProvider';
 
 // ---------------------------------------------------------------------------

package/src/react/ChartFrame.tsx

@@ -3,45 +3,38 @@
  *
  * Every family routes through here, so validation, status resolution, budget
  * checks, theming, layout, selection, accessibility, and failure containment
- * are written once and behave identically across all five.
+ * are written once and behave identically across all five. The pieces live in
+ * their own hooks and components; this file is the order they run in.
  *
  * Layout note (FR-039): the frame imposes **no outer margin**. Insight text is
  * out of scope for this package, so apps render their own text directly above
  * or below a chart and must not have to fight a margin they cannot control.
  */
-import React, { useEffect, useId, useMemo, useRef } from 'react';
+import React, { useId, useMemo } from 'react';
 import { Pressable, StyleSheet, Text, View, type GestureResponderEvent } from 'react-native';
 import Svg from 'react-native-svg';
 
 import type { ChartDatasource, ChartFamily } from '../contract/datasource';
-import type { ChartError } from '../contract/errors';
-import { chartError } from '../contract/errors';
-import { formatPositionDefault, formatValueDefault, safeFormat } from '../contract/format';
-import type { PointInteractionEvent } from '../contract/interaction';
+import type { DistributionValues } from '../contract/distribution';
 import type { BaseChartProps } from '../contract/props';
-import { drawsData, resolveStatus, suppressesInteraction } from '../contract/state';
-import type { ValueState } from '../contract/value';
+import { drawsData, suppressesInteraction } from '../contract/state';
+import { chartStrings } from '../contract/strings';
 import { hitTest, hitTestByX } from '../geometry/hitTest';
 import { containsPoint } from '../geometry/layout';
 import type { GeometryInput, ResolvedGeometry } from '../geometry/types';
 import { EMPTY_GEOMETRY } from '../geometry/types';
-import { releaseBudgetWarning, warnIfOverBudget } from '../validation/budgets';
-import { validateDatasource } from '../validation/validateDatasource';
-import { buildChartSummary, buildPointAnnouncement } from '../a11y/summary';
-import { chartStrings, type ChartStrings } from '../contract/strings';
-import { Grid, XAxis, YAxis } from '../render/Axis';
-import {
-	GeometryLabels,
-	MarkerLines,
-	Marks,
-	NonValueTextures,
-	SelectionHighlight,
-} from '../render/Marks';
+import { SelectionHighlight } from '../render/Marks';
 import { ChartBoundary } from './ChartBoundary';
-import { ChartLegend, buildLegendEntries } from './ChartLegend';
+import { ChartLegend, ColorScaleLegend, buildLegendEntries } from './ChartLegend';
+import { ChartPlot, type ChartAxes } from './ChartPlot';
+import { ChartFailureOverlay, ChartStateOverlay } from './ChartStateOverlay';
 import { useChartTheme } from './ChartThemeProvider';
+import { pointEventFor } from './pointEvent';
+import { useChartA11y } from './useChartA11y';
+import { useChartFormatters } from './useChartFormatters';
 import { useChartLayout, useGeometryInput } from './useChartLayout';
 import { useChartSelection, useSeriesVisibility } from './useChartSelection';
+import { useChartStatus } from './useChartStatus';
 
 export interface ChartFrameProps<M> extends BaseChartProps<M> {
 	readonly family: ChartFamily;
@@ -51,8 +44,11 @@ export interface ChartFrameProps<M> extends BaseChartProps<M> {
 	) => ResolvedGeometry;
 	/** Time-series selection tracks the x axis; other families use proximity. */
 	readonly hitTestMode?: 'nearest' | 'byX';
-	readonly showAxes?: boolean;
+	/** `full` by default: axis lines, grid and tick labels. */
+	readonly axes?: ChartAxes;
 	readonly defaultLegend?: boolean;
+	/** What a distribution's values mean, when the app says. */
+	readonly distributionValues?: DistributionValues;
 }
 
 const DEFAULT_HEIGHT = 220;
@@ -64,101 +60,24 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 	const generatedId = useId();
 	const instanceKey = props.chartId ?? generatedId;
 
-	// Warn once per chart instance, dev only; release the key on unmount so a
-	// remount warns again.
-	useEffect(() => () => releaseBudgetWarning(instanceKey), [instanceKey]);
-
-	const validation = useMemo(
-		() => validateDatasource(props.datasource, props.family, props.chartId),
-		[props.datasource, props.family, props.chartId],
-	);
-
-	useMemo(
-		() => warnIfOverBudget(props.datasource, props.family, instanceKey),
-		[props.datasource, props.family, instanceKey],
-	);
-
-	const declaredError =
-		props.status === 'error'
-			? chartError('declared', 'declaredByApp', {
-					chartId: props.chartId,
-					family: props.family,
-				})
-			: undefined;
-
-	const error = validation.error ?? declaredError;
-
-	const status = resolveStatus({
+	const { validation, error, status } = useChartStatus<M>({
+		datasource: props.datasource,
+		family,
+		chartId: props.chartId,
+		instanceKey,
 		declared: props.status,
-		isEmpty: validation.isEmpty,
-		isPartial: validation.isPartial,
-		error,
+		onFailure: props.onFailure,
+		distributionValues: props.distributionValues,
 	});
 
-	// Report a validation failure through the same channel as a contained
-	// render exception, so consumers have one place to watch.
-	//
-	// `onFailure` is held in a ref rather than listed as a dependency: an
-	// inline callback would otherwise re-fire the report on every render.
-	const reportedRef = useRef<string | undefined>(undefined);
-	const onFailureRef = useRef(props.onFailure);
-	onFailureRef.current = props.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]);
-
-	const formatValue = useMemo(() => {
-		const custom = props.formatters?.value;
-		return (v: ValueState): string =>
-			custom
-				? safeFormat(
-						() => custom(v, { slot: 'value', hint: props.datasource.format }),
-						() => formatValueDefault(v, { slot: 'value', hint: props.datasource.format }),
-						'value',
-						instanceKey,
-					)
-				: formatValueDefault(v, { slot: 'value', hint: props.datasource.format });
-	}, [props.formatters, props.datasource.format, instanceKey]);
-
-	const geometryFormatters = useMemo(
-		() => ({
-			formatValue: (n: number) => formatValue({ kind: 'known', value: n }),
-			formatCategory: (raw: string) => raw,
-			formatInstant: (at: number) => {
-				const custom = props.formatters?.axisLabel;
-				const position = { kind: 'instant' as const, at };
-				return custom
-					? safeFormat(
-							() => custom(position, { slot: 'axis' }),
-							() => formatPositionDefault(position),
-							'axis',
-							instanceKey,
-						)
-					: formatPositionDefault(position);
-			},
-		}),
-		[formatValue, props.formatters, instanceKey],
-	);
+	const formatters = useChartFormatters(props.formatters, props.datasource.format, instanceKey);
 
 	const layout = useChartLayout(theme, { height: props.height });
 	const geometryInput = useGeometryInput(
 		props.datasource,
 		theme,
 		layout,
-		geometryFormatters,
+		formatters.geometry,
 		family,
 	);
 
@@ -176,25 +95,18 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 
 	// Runtime visibility has to reach the geometry, not just the legend —
 	// otherwise toggling a series greys out its swatch while the line keeps
-	// drawing (FR-049).
-	//
-	// Keyed on a sorted string rather than the Set, because `useSeriesVisibility`
-	// builds a fresh Set every render and depending on it would invalidate the
-	// geometry memo constantly. With nothing hidden the original datasource is
-	// returned by identity, so the common case costs nothing.
-	const hiddenKey = Array.from(visibility.hidden)
-		.sort((a, b) => a.localeCompare(b))
-		.join(',');
+	// drawing (FR-049). With nothing hidden the original datasource is returned
+	// by identity, so the common case costs nothing.
+	const hidden = visibility.hidden;
 	const datasource = useMemo(() => {
-		if (hiddenKey === '') {
+		if (hidden.size === 0) {
 			return props.datasource;
 		}
-		const hidden = new Set(hiddenKey.split(','));
 		return {
 			...props.datasource,
 			series: props.datasource.series.map(s => (hidden.has(s.id) ? { ...s, hidden: true } : s)),
 		};
-	}, [props.datasource, hiddenKey]);
+	}, [props.datasource, hidden]);
 
 	// The single memoized artefact.
 	//
@@ -233,194 +145,62 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 			props.hitTestMode === 'byX'
 				? hitTestByX(geometry.hitRegions, locationX)
 				: hitTest(geometry.hitRegions, locationX, locationY);
-
 		if (!hit) {
 			selection.select(null, null);
 			return;
 		}
 
-		const series = props.datasource.series.find(s => s.id === hit.seriesId);
-		const point = series?.points.find(p => p.id === hit.pointId);
-		if (!series || !point) {
-			return;
+		const pointEvent = pointEventFor(props.datasource, hit.seriesId, hit.pointId);
+		if (pointEvent) {
+			selection.select({ seriesId: hit.seriesId, pointId: hit.pointId }, pointEvent);
 		}
-
-		const interactionEvent: PointInteractionEvent<M> = {
-			type: 'pointSelect',
-			seriesId: series.id,
-			pointId: point.id,
-			value: point.value,
-			position: point.position,
-			metadata: point.metadata,
-		};
-
-		selection.select({ seriesId: series.id, pointId: point.id }, interactionEvent);
 	};
 
-	/**
-	 * Screen-reader traversal: increment and decrement walk the selectable
-	 * points, giving assistive-technology users the same point-by-point access
-	 * that touch provides (FR-052, FR-072).
-	 */
-	const handleAccessibilityAction = (event: { nativeEvent: { actionName: string } }) => {
-		const regions = geometry.hitRegions.filter(r => r.selectable);
-		if (regions.length === 0) {
-			return;
-		}
-
-		const step = event.nativeEvent.actionName === 'increment' ? 1 : -1;
-		const current = regions.findIndex(
-			r =>
-				r.seriesId === selection.selection?.seriesId && r.pointId === selection.selection?.pointId,
-		);
-		const next = regions[current < 0 ? 0 : (current + step + regions.length) % regions.length];
-
-		const series = props.datasource.series.find(s => s.id === next.seriesId);
-		const point = series?.points.find(p => p.id === next.pointId);
-		if (!series || !point) {
-			return;
-		}
-
-		selection.select(
-			{ seriesId: series.id, pointId: point.id },
-			{
-				type: 'pointSelect',
-				seriesId: series.id,
-				pointId: point.id,
-				value: point.value,
-				position: point.position,
-				metadata: point.metadata,
-			},
-		);
-	};
+	const incomplete = geometry.incomplete || validation.totalIncomplete;
+	const interactive = props.accessibility?.interactive ?? Boolean(props.onSelectionChange);
 
-	const summary = useMemo(() => {
-		if (props.accessibility?.label) {
-			return props.accessibility.label;
-		}
-		// The app's own composer, when given (CHT-04): it was declared and never used.
-		const custom = props.accessibility?.summaryFormatter;
-		if (custom) {
-			return custom(props.datasource, { slot: 'summary', hint: props.datasource.format });
-		}
-		return buildChartSummary({
-			datasource: props.datasource,
-			family: props.family,
-			status,
-			title: props.title,
-			formatValue,
-			incomplete: geometry.incomplete || validation.totalIncomplete,
-			strings,
-		});
-	}, [
-		strings,
-		props.accessibility,
-		props.datasource,
-		props.family,
-		props.title,
+	const a11y = useChartA11y<M>({
+		datasource: props.datasource,
+		family,
 		status,
-		formatValue,
-		geometry.incomplete,
-		validation.totalIncomplete,
-	]);
-
-	const selectedPoint = useMemo(() => {
-		if (!selection.resolved) {
-			return undefined;
-		}
-		const series = props.datasource.series.find(s => s.id === selection.resolved!.seriesId);
-		const point = series?.points.find(p => p.id === selection.resolved!.pointId);
-		return series && point ? { series, point } : undefined;
-	}, [selection.resolved, props.datasource.series]);
-
-	const interactive = props.accessibility?.interactive ?? Boolean(props.onSelectionChange);
+		title: props.title,
+		accessibility: props.accessibility,
+		interactive,
+		incomplete,
+		hitRegions: geometry.hitRegions,
+		selection,
+		formatters,
+		strings,
+	});
 
 	const legendEnabled =
 		props.legend === undefined ? (props.defaultLegend ?? false) : props.legend !== false;
-
+	const legendPosition = typeof props.legend === 'object' ? props.legend.position : 'bottom';
+	const legendLabel = formatters.legendLabel;
 	const legendEntries = useMemo(
 		() =>
 			legendEnabled
-				? buildLegendEntries(props.datasource, theme, visibility.hidden, visibility.enabled, family)
+				? buildLegendEntries(
+						props.datasource,
+						theme,
+						hidden,
+						visibility.enabled,
+						family,
+						legendLabel,
+					)
 				: [],
-		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled, family],
+		[legendEnabled, props.datasource, theme, hidden, visibility.enabled, family, legendLabel],
 	);
+	const legend = legendEnabled ? (
+		<ChartLegend
+			entries={legendEntries}
+			theme={theme}
+			onToggle={visibility.enabled ? visibility.toggle : undefined}
+			strings={strings}
+		/>
+	) : null;
 
-	const legendPosition = typeof props.legend === 'object' ? props.legend.position : 'bottom';
-
-	const renderStateOverlay = (currentError?: ChartError) => {
-		const supplied = props.stateContent?.[status];
-		if (supplied !== undefined) {
-			return <View style={styles.overlay}>{supplied}</View>;
-		}
-		// Minimal built-in wording, deliberately terse. Apps are expected to
-		// supply their own copy — the package must not impose product voice.
-		const fallback = builtInStateText(status, strings, currentError);
-		if (!fallback) {
-			return null;
-		}
-		return (
-			<View style={styles.overlay}>
-				<Text
-					style={{
-						color: theme.muted,
-						fontSize: theme.typography.valueLabel.fontSize,
-					}}
-				>
-					{fallback}
-				</Text>
-			</View>
-		);
-	};
-
-	const body = (currentError?: ChartError) => (
-		<View
-			style={[styles.plotArea, { height: props.height ?? DEFAULT_HEIGHT }]}
-			onLayout={layout.onLayout}
-		>
-			{layout.measured && showData ? (
-				<Pressable
-					onPress={handlePress}
-					disabled={!props.onSelectionChange}
-					style={StyleSheet.absoluteFill}
-					accessible={false}
-					importantForAccessibility="no-hide-descendants"
-				>
-					<Svg width={layout.size.width} height={layout.size.height}>
-						<NonValueTextures theme={theme} />
-						{props.showAxes !== false && (
-							<>
-								<Grid plot={geometry.plot} yTicks={geometry.yTicks} theme={theme} />
-								<YAxis
-									plot={geometry.plot}
-									ticks={geometry.yTicks}
-									theme={theme}
-									fontSize={layout.fontSize}
-								/>
-								<XAxis
-									plot={geometry.plot}
-									ticks={geometry.xTicks}
-									theme={theme}
-									fontSize={layout.fontSize}
-								/>
-							</>
-						)}
-						<Marks paths={geometry.paths} />
-						<MarkerLines markers={geometry.markers} theme={theme} />
-						<GeometryLabels labels={geometry.labels} theme={theme} fontSize={layout.fontSize} />
-						{selection.resolved && (
-							<SelectionHighlight
-								x={selection.resolved.x}
-								y={selection.resolved.y}
-								color={theme.onSurface}
-							/>
-						)}
-					</Svg>
-				</Pressable>
-			) : null}
-			{!showData || currentError ? renderStateOverlay(currentError) : null}
-		</View>
-	);
+	const plotHeight = useMemo(() => ({ height: props.height ?? DEFAULT_HEIGHT }), [props.height]);
 
 	const content = (
 		<>
@@ -439,65 +219,73 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 				</Text>
 			) : null}
 
-			{legendEnabled && legendPosition === 'top' ? (
-				<ChartLegend
-					entries={legendEntries}
-					theme={theme}
-					onToggle={visibility.enabled ? visibility.toggle : undefined}
-					strings={strings}
-				/>
-			) : null}
+			{legendPosition === 'top' ? legend : null}
 
 			<View
 				accessible
 				accessibilityRole={interactive ? 'adjustable' : 'image'}
-				accessibilityLabel={summary}
-				accessibilityValue={
-					interactive && selectedPoint
-						? {
-								text: buildPointAnnouncement(
-									selectedPoint.series.label,
-									formatPositionDefault(selectedPoint.point.position),
-									selectedPoint.point.value,
-									formatValue,
-									strings,
-								),
-							}
-						: undefined
-				}
-				accessibilityActions={
-					interactive
-						? [
-								{ name: 'increment', label: strings['chart.action.next'] },
-								{ name: 'decrement', label: strings['chart.action.previous'] },
-							]
-						: undefined
-				}
-				onAccessibilityAction={interactive ? handleAccessibilityAction : undefined}
+				accessibilityLabel={a11y.summary}
+				accessibilityValue={a11y.value}
+				accessibilityActions={a11y.actions}
+				onAccessibilityAction={a11y.onAction}
 			>
-				{body(error)}
+				<View style={[styles.plotArea, plotHeight]} onLayout={layout.onLayout}>
+					{layout.measured && showData ? (
+						<Pressable
+							onPress={handlePress}
+							disabled={!props.onSelectionChange}
+							style={StyleSheet.absoluteFill}
+							accessible={false}
+							importantForAccessibility="no-hide-descendants"
+						>
+							<Svg width={layout.size.width} height={layout.size.height}>
+								<ChartPlot
+									geometry={geometry}
+									theme={theme}
+									fontSize={layout.fontSize}
+									axes={props.axes ?? 'full'}
+								/>
+								{selection.resolved && (
+									<SelectionHighlight
+										x={selection.resolved.x}
+										y={selection.resolved.y}
+										color={theme.onSurface}
+									/>
+								)}
+							</Svg>
+						</Pressable>
+					) : null}
+					{!showData || error ? (
+						<ChartStateOverlay
+							status={status}
+							supplied={props.stateContent?.[status]}
+							strings={strings}
+							theme={theme}
+							error={error}
+						/>
+					) : null}
+				</View>
 			</View>
 
-			{legendEnabled && legendPosition === 'bottom' ? (
-				<ChartLegend
-					entries={legendEntries}
+			{legendPosition === 'bottom' ? legend : null}
+
+			{geometry.colorScale && props.legend !== false ? (
+				<ColorScaleLegend
+					scale={geometry.colorScale}
 					theme={theme}
-					onToggle={visibility.enabled ? visibility.toggle : undefined}
+					formatValue={formatters.geometry.formatValue}
 					strings={strings}
 				/>
 			) : null}
 
-			{geometry.incomplete || validation.totalIncomplete ? (
+			{incomplete ? (
 				<Text
 					style={[
 						styles.note,
-						{
-							color: theme.muted,
-							fontSize: theme.typography.axisLabel.fontSize,
-						},
+						{ color: theme.muted, fontSize: theme.typography.axisLabel.fontSize },
 					]}
 				>
-					Some values are unavailable, so totals are incomplete.
+					{strings['chart.note.incomplete']}
 				</Text>
 			) : null}
 
@@ -523,21 +311,14 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 					<View
 						accessible
 						accessibilityRole="image"
-						accessibilityLabel={summary}
-						style={[styles.plotArea, { height: props.height ?? DEFAULT_HEIGHT }]}
+						accessibilityLabel={a11y.summary}
+						style={[styles.plotArea, plotHeight]}
 					>
-						<View style={styles.overlay}>
-							{props.stateContent?.error ?? (
-								<Text
-									style={{
-										color: theme.muted,
-										fontSize: theme.typography.valueLabel.fontSize,
-									}}
-								>
-									{containedError.message}
-								</Text>
-							)}
-						</View>
+						<ChartFailureOverlay
+							supplied={props.stateContent?.error}
+							theme={theme}
+							error={containedError}
+						/>
 					</View>
 				)}
 			>
@@ -547,25 +328,6 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 	);
 }
 
-function builtInStateText(
-	status: ReturnType<typeof resolveStatus>,
-	strings: ChartStrings,
-	error?: ChartError,
-): string | undefined {
-	switch (status) {
-		case 'loading':
-			return strings['chart.state.loading'];
-		case 'empty':
-			return strings['chart.state.empty'];
-		case 'error':
-			return error?.message ?? strings['chart.state.error'];
-		case 'noPermission':
-			return strings['chart.state.noPermission'];
-		default:
-			return undefined;
-	}
-}
-
 const styles = StyleSheet.create({
 	// No outer margin: app content must be able to sit flush against a chart.
 	container: {
@@ -579,15 +341,6 @@ const styles = StyleSheet.create({
 		width: '100%',
 		position: 'relative',
 	},
-	overlay: {
-		position: 'absolute',
-		top: 0,
-		left: 0,
-		right: 0,
-		bottom: 0,
-		alignItems: 'center',
-		justifyContent: 'center',
-	},
 	// Colour and type size are applied inline from ChartTheme, so they follow
 	// the consuming app's tokens and the system text scale (UX-001).
 	note: {