@chipmobilesdk/rn-chart 0.1.0

package/src/react/ChartFrame.tsx

@@ -0,0 +1,620 @@
+/**
+ * The shared chart shell.
+ *
+ * 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.
+ *
+ * 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 {
+	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 { BaseChartProps } from '../contract/props';
+import { drawsData, resolveStatus, suppressesInteraction } from '../contract/state';
+import type { ValueState } from '../contract/value';
+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 { Grid, XAxis, YAxis } from '../render/Axis';
+import {
+	GeometryLabels,
+	MarkerLines,
+	Marks,
+	NonValueTextures,
+	SelectionHighlight,
+} from '../render/Marks';
+import { ChartBoundary } from './ChartBoundary';
+import { ChartLegend, buildLegendEntries } from './ChartLegend';
+import { useChartTheme } from './ChartThemeProvider';
+import { useChartLayout, useGeometryInput } from './useChartLayout';
+import { useChartSelection, useSeriesVisibility } from './useChartSelection';
+
+export interface ChartFrameProps<M> extends BaseChartProps<M> {
+	readonly family: ChartFamily;
+	readonly buildGeometry: (
+		datasource: ChartDatasource<M>,
+		input: GeometryInput,
+	) => ResolvedGeometry;
+	/** Time-series selection tracks the x axis; other families use proximity. */
+	readonly hitTestMode?: 'nearest' | 'byX';
+	readonly showAxes?: boolean;
+	readonly defaultLegend?: boolean;
+}
+
+const DEFAULT_HEIGHT = 220;
+
+export function ChartFrame<M>(props: ChartFrameProps<M>) {
+	const family = props.family;
+	const theme = useChartTheme(props.theme);
+	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({
+		declared: props.status,
+		isEmpty: validation.isEmpty,
+		isPartial: validation.isPartial,
+		error,
+	});
+
+	// 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 layout = useChartLayout(theme, { height: props.height });
+	const geometryInput = useGeometryInput(
+		props.datasource,
+		theme,
+		layout,
+		geometryFormatters,
+	);
+
+	const showData = drawsData(status);
+
+	const visibility = useSeriesVisibility<M>({
+		controlled: props.hiddenSeriesIds,
+		onVisibilityChange: props.onVisibilityChange,
+		enabled: props.seriesToggleEnabled === true,
+		initiallyHidden: useMemo(
+			() => props.datasource.series.filter(s => s.hidden).map(s => s.id),
+			[props.datasource.series],
+		),
+	});
+
+	// 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(',');
+	const datasource = useMemo(() => {
+		if (hiddenKey === '') {
+			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]);
+
+	// The single memoized artefact.
+	//
+	// The dependency list is narrow on purpose. Depending on the whole `props`
+	// object would invalidate the memo whenever any callback identity changed —
+	// and inline arrow callbacks are the norm in app code, so that would defeat
+	// FR-073 in exactly the case it exists for. Selection is absent for the same
+	// reason: highlighting repaints the highlight, it does not rebuild scales.
+	const buildGeometry = props.buildGeometry;
+	const geometry = useMemo(() => {
+		if (!layout.measured || !showData) {
+			return EMPTY_GEOMETRY;
+		}
+		return buildGeometry(datasource, geometryInput);
+	}, [layout.measured, showData, buildGeometry, datasource, geometryInput]);
+
+	const selection = useChartSelection<M>({
+		controlled: props.selection,
+		onSelectionChange: props.onSelectionChange,
+		onSelectionUnresolvable: props.onSelectionUnresolvable,
+		hitRegions: geometry.hitRegions,
+		interactionSuppressed: suppressesInteraction(status),
+		geometryReady: layout.measured && showData && geometry.hitRegions.length > 0,
+	});
+
+	const handlePress = (event: GestureResponderEvent) => {
+		if (suppressesInteraction(status) || !props.onSelectionChange) {
+			return;
+		}
+		const { locationX, locationY } = event.nativeEvent;
+		if (!containsPoint(geometry.plot, locationX, locationY)) {
+			return;
+		}
+
+		const hit =
+			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 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 summary = useMemo(() => {
+		if (props.accessibility?.label) {
+			return props.accessibility.label;
+		}
+		return buildChartSummary({
+			datasource: props.datasource,
+			family: props.family,
+			status,
+			title: props.title,
+			formatValue,
+			incomplete: geometry.incomplete || validation.totalIncomplete,
+		});
+	}, [
+		props.accessibility,
+		props.datasource,
+		props.family,
+		props.title,
+		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);
+
+	const legendEnabled =
+		props.legend === undefined
+			? (props.defaultLegend ?? false)
+			: props.legend !== false;
+
+	const legendEntries = useMemo(
+		() =>
+			legendEnabled
+				? buildLegendEntries(
+						props.datasource,
+						theme,
+						visibility.hidden,
+						visibility.enabled,
+				  )
+				: [],
+		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled],
+	);
+
+	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, 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 content = (
+		<>
+			{props.title ? (
+				<Text
+					style={[
+						styles.title,
+						{
+							color: theme.typography.valueLabel.color,
+							fontSize: theme.typography.valueLabel.fontSize,
+						},
+					]}
+					accessibilityRole="header"
+				>
+					{props.title}
+				</Text>
+			) : null}
+
+			{legendEnabled && legendPosition === 'top' ? (
+				<ChartLegend
+					entries={legendEntries}
+					theme={theme}
+					onToggle={visibility.enabled ? visibility.toggle : undefined}
+				/>
+			) : 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,
+								),
+						  }
+						: undefined
+				}
+				accessibilityActions={
+					interactive
+						? [
+								{ name: 'increment', label: 'Next data point' },
+								{ name: 'decrement', label: 'Previous data point' },
+						  ]
+						: undefined
+				}
+				onAccessibilityAction={interactive ? handleAccessibilityAction : undefined}
+			>
+				{body(error)}
+			</View>
+
+			{legendEnabled && legendPosition === 'bottom' ? (
+				<ChartLegend
+					entries={legendEntries}
+					theme={theme}
+					onToggle={visibility.enabled ? visibility.toggle : undefined}
+				/>
+			) : null}
+
+			{geometry.incomplete || validation.totalIncomplete ? (
+				<Text
+					style={[
+						styles.note,
+						{
+							color: theme.muted,
+							fontSize: theme.typography.axisLabel.fontSize,
+						},
+					]}
+				>
+					Some values are unavailable, so totals are incomplete.
+				</Text>
+			) : null}
+
+			{props.footer}
+		</>
+	);
+
+	return (
+		<View
+			style={[styles.container, { backgroundColor: theme.surface }, props.style]}
+		>
+			{/*
+			  The boundary wraps the chart's whole subtree, not just the plot.
+			  A defect anywhere inside — geometry, the SVG substrate, or content
+			  the app passed in as state copy or a footer — must collapse this one
+			  chart and leave its siblings and the surrounding screen alive
+			  (FR-031, FR-038a).
+			*/}
+			<ChartBoundary
+				family={props.family}
+				chartId={props.chartId}
+				onFailure={props.onFailure}
+				resetKey={props.datasource}
+				renderFallback={containedError => (
+					<View
+						accessible
+						accessibilityRole="image"
+						accessibilityLabel={summary}
+						style={[styles.plotArea, { height: props.height ?? DEFAULT_HEIGHT }]}
+					>
+						<View style={styles.overlay}>
+							{props.stateContent?.error ?? (
+								<Text
+									style={{
+										color: theme.muted,
+										fontSize: theme.typography.valueLabel.fontSize,
+									}}
+								>
+									{containedError.message}
+								</Text>
+							)}
+						</View>
+					</View>
+				)}
+			>
+				{content}
+			</ChartBoundary>
+		</View>
+	);
+}
+
+function builtInStateText(
+	status: ReturnType<typeof resolveStatus>,
+	error?: ChartError,
+): string | undefined {
+	switch (status) {
+		case 'loading':
+			return 'Loading…';
+		case 'empty':
+			return 'No data yet';
+		case 'error':
+			return error?.message ?? 'Unable to show this chart';
+		case 'noPermission':
+			return 'Not available';
+		default:
+			return undefined;
+	}
+}
+
+const styles = StyleSheet.create({
+	// No outer margin: app content must be able to sit flush against a chart.
+	container: {
+		width: '100%',
+	},
+	title: {
+		fontWeight: '600',
+		marginBottom: 4,
+	},
+	plotArea: {
+		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: {
+		marginTop: 4,
+	},
+});