@chipmobilesdk/rn-chart 0.2.0 → 0.2.1

package/src/react/ChartFrame.tsx

@@ -1,622 +1,583 @@
-/**
- * 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,
-		family,
-	);
-
-	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,
-						family,
-				  )
-				: [],
-		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled, family],
-	);
-
-	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,
-	},
-});
+/**
+ * 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,
+		family,
+	);
+
+	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, family)
+				: [],
+		[legendEnabled, props.datasource, theme, visibility.hidden, visibility.enabled, family],
+	);
+
+	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,
+	},
+});