@chipmobilesdk/rn-chart 0.1.0

package/src/react/ChartLegend.tsx

@@ -0,0 +1,177 @@
+/**
+ * Legend (FR-066).
+ *
+ * On by default for multi-series and multi-segment charts, disableable, and its
+ * model is exported so an app can render its own layout instead. Every entry
+ * carries a dash pattern as well as a colour, so series stay distinguishable
+ * without colour perception.
+ */
+import React from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import type { ChartDatasource } from '../contract/datasource';
+import { resolveSeriesColor, type ChartTheme, type LegendEntry } from '../contract/theme';
+
+/** Minimum tap target, per platform accessibility guidance (UX-003). */
+const MIN_TAP_TARGET = 44;
+
+export function buildLegendEntries<M>(
+	datasource: ChartDatasource<M>,
+	theme: ChartTheme,
+	hidden: ReadonlySet<string>,
+	toggleable: boolean,
+): LegendEntry[] {
+	return datasource.series.map((series, index) => ({
+		seriesId: series.id,
+		label: series.label,
+		color: resolveSeriesColor(theme, index, series.color),
+		pattern: series.pattern ?? 'solid',
+		visible: !hidden.has(series.id),
+		toggleable,
+	}));
+}
+
+function segmentCountFor(pattern: LegendEntry['pattern']): number {
+	switch (pattern) {
+		case 'dotted':
+			return 4;
+		case 'dashed':
+		case 'dashDot':
+			return 2;
+		default:
+			return 1;
+	}
+}
+
+function PatternSwatch({
+	entry,
+	theme,
+}: {
+	readonly entry: LegendEntry;
+	readonly theme: ChartTheme;
+}) {
+	// Dashes are drawn as gapped segments so the pattern reads at swatch size —
+	// this is what gives a series an identity beyond its colour (FR-064).
+	const segments = segmentCountFor(entry.pattern);
+	const gap = segments > 1 ? 1 : 0;
+
+	return (
+		<View style={styles.swatchRow}>
+			{Array.from({ length: segments }, (_, i) => (
+				<View
+					key={i}
+					style={[
+						styles.swatchSegment,
+						entry.visible ? styles.swatchVisible : styles.swatchHidden,
+						{
+							width: 12 / segments - gap,
+							marginRight: gap,
+							backgroundColor: entry.visible ? entry.color : theme.muted,
+						},
+					]}
+				/>
+			))}
+		</View>
+	);
+}
+
+export function ChartLegend({
+	entries,
+	theme,
+	onToggle,
+}: {
+	readonly entries: readonly LegendEntry[];
+	readonly theme: ChartTheme;
+	readonly onToggle?: (seriesId: string) => void;
+}) {
+	if (entries.length === 0) {
+		return null;
+	}
+
+	return (
+		<View style={styles.container} accessibilityRole="list">
+			{entries.map(entry => {
+				const content = (
+					<>
+						<PatternSwatch entry={entry} theme={theme} />
+						<Text
+							style={[
+								styles.label,
+								{
+									color: entry.visible
+										? theme.typography.legendLabel.color
+										: theme.muted,
+									fontSize: theme.typography.legendLabel.fontSize,
+								},
+							]}
+							numberOfLines={1}
+						>
+							{entry.label}
+						</Text>
+					</>
+				);
+
+				if (!entry.toggleable || !onToggle) {
+					return (
+						<View key={entry.seriesId} style={styles.entry} accessibilityRole="text">
+							{content}
+						</View>
+					);
+				}
+
+				return (
+					<Pressable
+						key={entry.seriesId}
+						onPress={() => onToggle(entry.seriesId)}
+						accessibilityRole="switch"
+						accessibilityState={{ checked: entry.visible }}
+						accessibilityLabel={entry.label}
+						accessibilityHint={
+							entry.visible ? 'Hides this series' : 'Shows this series'
+						}
+						style={[styles.entry, styles.tappable]}
+					>
+						{content}
+					</Pressable>
+				);
+			})}
+		</View>
+	);
+}
+
+const styles = StyleSheet.create({
+	container: {
+		flexDirection: 'row',
+		flexWrap: 'wrap',
+		alignItems: 'center',
+	},
+	entry: {
+		flexDirection: 'row',
+		alignItems: 'center',
+		marginRight: 12,
+		marginTop: 4,
+	},
+	tappable: {
+		minHeight: MIN_TAP_TARGET,
+		paddingVertical: 4,
+	},
+	swatchRow: {
+		flexDirection: 'row',
+		alignItems: 'center',
+		width: 12,
+		marginRight: 6,
+	},
+	swatchSegment: {
+		height: 3,
+		borderRadius: 2,
+	},
+	swatchVisible: {
+		opacity: 1,
+	},
+	swatchHidden: {
+		opacity: 0.4,
+	},
+	label: {
+		flexShrink: 1,
+	},
+});

package/src/react/ChartThemeProvider.tsx

@@ -0,0 +1,48 @@
+/**
+ * Theme resolution: prop -> context -> built-in default keyed on the OS scheme.
+ *
+ * The dependency is inverted on purpose. The package declares a `ChartTheme`
+ * value type and any design system can satisfy it, which is what keeps
+ * `@chipmobilesdk/rn-theme` and `react-native-unistyles` out of this package
+ * entirely (FR-065, LIB-004).
+ */
+import React, { createContext, useContext, useMemo } from 'react';
+import { useColorScheme } from 'react-native';
+
+import { defaultChartTheme, type ChartTheme } from '../contract/theme';
+
+const ChartThemeContext = createContext<ChartTheme | undefined>(undefined);
+
+export function ChartThemeProvider({
+	theme,
+	children,
+}: {
+	readonly theme: ChartTheme;
+	readonly children: React.ReactNode;
+}) {
+	return (
+		<ChartThemeContext.Provider value={theme}>
+			{children}
+		</ChartThemeContext.Provider>
+	);
+}
+
+/**
+ * An explicit prop wins, then context, then the built-in default for the
+ * current OS colour scheme — so a chart renders correctly with no theme
+ * configuration at all.
+ */
+export function useChartTheme(explicit?: ChartTheme): ChartTheme {
+	const fromContext = useContext(ChartThemeContext);
+	const scheme = useColorScheme();
+
+	return useMemo(() => {
+		if (explicit) {
+			return explicit;
+		}
+		if (fromContext) {
+			return fromContext;
+		}
+		return defaultChartTheme(scheme === 'dark' ? 'dark' : 'light');
+	}, [explicit, fromContext, scheme]);
+}

package/src/react/charts.tsx

@@ -0,0 +1,161 @@
+/**
+ * The five chart family components.
+ *
+ * Each is a thin wrapper over `ChartFrame` plus its own geometry builder, so
+ * validation, state handling, theming, selection, accessibility, and failure
+ * containment behave identically across every family.
+ *
+ * All five are wrapped in `React.memo`: value-identical props stop at the memo
+ * boundary and never reach geometry (FR-073, SC-017).
+ */
+import React, { useCallback } from 'react';
+
+import type { ChartDatasource } from '../contract/datasource';
+import type { BaseChartProps } from '../contract/props';
+import { buildBarGeometry, type BarGrouping } from '../geometry/bar';
+import {
+	buildDistributionGeometry,
+	type DistributionShape,
+} from '../geometry/distribution';
+import { buildHeatmapGeometry } from '../geometry/heatmap';
+import { buildProgressGeometry } from '../geometry/progress';
+import { buildTimeSeriesGeometry } from '../geometry/timeSeries';
+import type { GeometryInput } from '../geometry/types';
+import { ChartFrame } from './ChartFrame';
+
+export interface ProgressChartProps<M = unknown> extends BaseChartProps<M> {
+	readonly orientation?: 'horizontal' | 'vertical';
+}
+
+function ProgressChartImpl<M>(props: ProgressChartProps<M>) {
+	const build = useCallback(
+		(ds: ChartDatasource<M>, input: GeometryInput) =>
+			buildProgressGeometry(ds, input, { orientation: props.orientation }),
+		[props.orientation],
+	);
+
+	return (
+		<ChartFrame
+			{...props}
+			family="progress"
+			buildGeometry={build}
+			showAxes={false}
+			defaultLegend={false}
+		/>
+	);
+}
+
+export interface DistributionChartProps<M = unknown> extends BaseChartProps<M> {
+	readonly shape?: DistributionShape;
+	readonly innerRadiusRatio?: number;
+}
+
+function DistributionChartImpl<M>(props: DistributionChartProps<M>) {
+	const build = useCallback(
+		(ds: ChartDatasource<M>, input: GeometryInput) =>
+			buildDistributionGeometry(ds, input, {
+				shape: props.shape,
+				innerRadiusRatio: props.innerRadiusRatio,
+			}),
+		[props.shape, props.innerRadiusRatio],
+	);
+
+	return (
+		<ChartFrame
+			{...props}
+			family="distribution"
+			buildGeometry={build}
+			showAxes={false}
+			defaultLegend
+		/>
+	);
+}
+
+export interface TimeSeriesChartProps<M = unknown> extends BaseChartProps<M> {
+	/** A window the app supplies. Users cannot pan or zoom (out of scope). */
+	readonly range?: { readonly from: number; readonly to: number };
+}
+
+function TimeSeriesChartImpl<M>(props: TimeSeriesChartProps<M>) {
+	const build = useCallback(
+		(ds: ChartDatasource<M>, input: GeometryInput) =>
+			buildTimeSeriesGeometry(ds, input, { range: props.range }),
+		[props.range],
+	);
+
+	return (
+		<ChartFrame
+			{...props}
+			family="timeSeries"
+			buildGeometry={build}
+			// A user aims at a moment in time, not at a pixel on the line.
+			hitTestMode="byX"
+			defaultLegend
+		/>
+	);
+}
+
+export interface BarChartProps<M = unknown> extends BaseChartProps<M> {
+	readonly grouping?: BarGrouping;
+}
+
+function BarChartImpl<M>(props: BarChartProps<M>) {
+	const build = useCallback(
+		(ds: ChartDatasource<M>, input: GeometryInput) =>
+			buildBarGeometry(ds, input, { grouping: props.grouping }),
+		[props.grouping],
+	);
+
+	return (
+		<ChartFrame {...props} family="bar" buildGeometry={build} defaultLegend />
+	);
+}
+
+export interface HeatmapChartProps<M = unknown> extends BaseChartProps<M> {
+	readonly buckets?: number;
+}
+
+function HeatmapChartImpl<M>(props: HeatmapChartProps<M>) {
+	const build = useCallback(
+		(ds: ChartDatasource<M>, input: GeometryInput) =>
+			buildHeatmapGeometry(ds, input, { buckets: props.buckets }),
+		[props.buckets],
+	);
+
+	return (
+		<ChartFrame
+			{...props}
+			family="heatmap"
+			buildGeometry={build}
+			showAxes={false}
+			defaultLegend={false}
+		/>
+	);
+}
+
+/**
+ * `React.memo` erases the generic parameter, so each component is re-cast to a
+ * generic function type. This keeps `<BarChart<MyMeta> ... />` working for
+ * consumers while still getting the memo boundary.
+ */
+export const ProgressChart = React.memo(ProgressChartImpl) as <M = unknown>(
+	props: ProgressChartProps<M>,
+) => React.ReactElement;
+
+export const DistributionChart = React.memo(DistributionChartImpl) as <
+	M = unknown,
+>(
+	props: DistributionChartProps<M>,
+) => React.ReactElement;
+
+export const TimeSeriesChart = React.memo(TimeSeriesChartImpl) as <M = unknown>(
+	props: TimeSeriesChartProps<M>,
+) => React.ReactElement;
+
+export const BarChart = React.memo(BarChartImpl) as <M = unknown>(
+	props: BarChartProps<M>,
+) => React.ReactElement;
+
+export const HeatmapChart = React.memo(HeatmapChartImpl) as <M = unknown>(
+	props: HeatmapChartProps<M>,
+) => React.ReactElement;

package/src/react/useChartLayout.ts

@@ -0,0 +1,124 @@
+/**
+ * Container measurement and the geometry memo.
+ *
+ * `ResolvedGeometry` is memoized on datasource identity, plot rectangle, theme
+ * identity, and formatter identity — and deliberately **not** on selection, so
+ * highlighting a point repaints the highlight without recomputing scales or
+ * path strings (FR-073, SC-017).
+ *
+ * A consequence worth documenting for consumers: rebuilding the datasource
+ * object inline on every render defeats this. The README says so, and the demo
+ * app models the correct pattern.
+ */
+import { useCallback, useMemo, useState } from 'react';
+import { PixelRatio, type LayoutChangeEvent } from 'react-native';
+
+import type { ChartDatasource } from '../contract/datasource';
+import { resolveSeriesColor, type ChartTheme } from '../contract/theme';
+import {
+	EMPTY_PLOT,
+	isMeasurable,
+	resolvePlotRect,
+	type ContainerSize,
+	type PlotRect,
+} from '../geometry/layout';
+import { effectiveFontSize } from '../geometry/layout';
+import type { GeometryInput } from '../geometry/types';
+
+export interface ChartLayout {
+	readonly onLayout: (event: LayoutChangeEvent) => void;
+	readonly size: ContainerSize;
+	readonly measured: boolean;
+	readonly plot: PlotRect;
+	readonly fontSize: number;
+}
+
+export function useChartLayout(
+	theme: ChartTheme,
+	options: {
+		readonly height?: number;
+		readonly xLabels?: readonly string[];
+		readonly yLabels?: readonly string[];
+	} = {},
+): ChartLayout {
+	const [size, setSize] = useState<ContainerSize>({ width: 0, height: 0 });
+
+	const onLayout = useCallback((event: LayoutChangeEvent) => {
+		const { width, height } = event.nativeEvent.layout;
+		setSize(prev =>
+			// Avoid a state churn loop on sub-pixel layout jitter.
+			Math.abs(prev.width - width) < 0.5 && Math.abs(prev.height - height) < 0.5
+				? prev
+				: { width, height },
+		);
+	}, []);
+
+	const fontScale = PixelRatio.getFontScale();
+	const fontSize = effectiveFontSize(theme.typography.axisLabel.fontSize, fontScale);
+
+	const measured = isMeasurable(size);
+
+	const plot = useMemo(() => {
+		if (!measured) {
+			// Wait for a real measurement rather than computing a broken layout
+			// or throwing (FR-078).
+			return EMPTY_PLOT;
+		}
+		return resolvePlotRect({
+			container: size,
+			xLabels: options.xLabels,
+			yLabels: options.yLabels,
+			baseFontSize: theme.typography.axisLabel.fontSize,
+			fontScale,
+			padding: theme.spacing.xs,
+		});
+	}, [
+		measured,
+		size,
+		options.xLabels,
+		options.yLabels,
+		theme.typography.axisLabel.fontSize,
+		theme.spacing.xs,
+		fontScale,
+	]);
+
+	return { onLayout, size, measured, plot, fontSize };
+}
+
+/**
+ * Builds the geometry input, resolving per-series colours once so geometry
+ * modules never reach into the theme themselves.
+ */
+export function useGeometryInput<M>(
+	datasource: ChartDatasource<M>,
+	theme: ChartTheme,
+	layout: ChartLayout,
+	formatters: {
+		readonly formatValue: (value: number) => string;
+		readonly formatCategory: (raw: string) => string;
+		readonly formatInstant: (at: number) => string;
+	},
+): GeometryInput {
+	return useMemo(() => {
+		const seriesColors: Record<string, string> = {};
+		datasource.series.forEach((series, index) => {
+			seriesColors[series.id] = resolveSeriesColor(theme, index, series.color);
+			// Distribution segments are coloured per point rather than per series,
+			// so give each point a palette entry too.
+			series.points.forEach((point, pointIndex) => {
+				seriesColors[point.id] = resolveSeriesColor(theme, pointIndex);
+			});
+		});
+
+		return {
+			plot: layout.plot,
+			fontSize: layout.fontSize,
+			seriesColors,
+			nonValueTextures: theme.nonValue,
+			heatmapRamp: theme.heatmapRamp,
+			formatValue: formatters.formatValue,
+			formatCategory: formatters.formatCategory,
+			formatInstant: formatters.formatInstant,
+		};
+	}, [datasource, theme, layout.plot, layout.fontSize, formatters]);
+}

package/src/react/useChartSelection.ts

@@ -0,0 +1,170 @@
+/**
+ * Selection ownership: uncontrolled by default, controlled when the app
+ * supplies a value (FR-054a).
+ *
+ * Two properties matter and both 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).
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type {
+	PointInteractionEvent,
+	SelectionRef,
+	SeriesInteractionEvent,
+} from '../contract/interaction';
+import { sameSelection } from '../contract/interaction';
+import { findRegion, type HitRegion } from '../geometry/hitTest';
+
+export interface UseChartSelectionArgs<M> {
+	/** Present (including `null`) means the app owns the selection. */
+	readonly controlled?: SelectionRef | null;
+	readonly onSelectionChange?: (
+		next: SelectionRef | null,
+		event: PointInteractionEvent<M> | null,
+	) => void;
+	readonly onSelectionUnresolvable?: (ref: SelectionRef) => void;
+	readonly hitRegions: readonly HitRegion[];
+	/** Non-ready statuses suppress selection entirely (FR-053). */
+	readonly interactionSuppressed: boolean;
+	/**
+	 * False until the container has been measured and geometry exists.
+	 *
+	 * Without this, a chart that has not laid out yet has no hit regions, and a
+	 * perfectly valid app-controlled selection would be reported as
+	 * unresolvable on first paint — telling the app its state is wrong when it
+	 * is not.
+	 */
+	readonly geometryReady: 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;
+}
+
+export function useChartSelection<M>(
+	args: UseChartSelectionArgs<M>,
+): ChartSelectionApi<M> {
+	const isControlled = args.controlled !== undefined;
+	const [internal, setInternal] = useState<SelectionRef | null>(null);
+
+	const selection = isControlled ? args.controlled ?? null : internal;
+
+	// Resolve fresh every render. A stale reference resolves to `undefined` and
+	// simply is not drawn.
+	const resolved =
+		selection && !args.interactionSuppressed
+			? findRegion(args.hitRegions, selection.seriesId, selection.pointId)
+			: undefined;
+
+	// Tell a controlling app when its selection stopped resolving, rather than
+	// silently ignoring it. Uncontrolled selections are cleared instead.
+	const reportedRef = useRef<string | null>(null);
+	useEffect(() => {
+		if (
+			!selection ||
+			resolved ||
+			args.interactionSuppressed ||
+			!args.geometryReady
+		) {
+			reportedRef.current = null;
+			return;
+		}
+
+		const key = `${selection.seriesId}:${selection.pointId ?? ''}`;
+		if (reportedRef.current === key) {
+			return;
+		}
+		reportedRef.current = key;
+
+		if (isControlled) {
+			args.onSelectionUnresolvable?.(selection);
+		} else {
+			setInternal(null);
+		}
+	}, [selection, resolved, isControlled, args, args.geometryReady]);
+
+	const select = useCallback(
+		(ref: SelectionRef | null, event: PointInteractionEvent<M> | null) => {
+			if (args.interactionSuppressed) {
+				return;
+			}
+			if (!isControlled) {
+				setInternal(prev => (sameSelection(prev, ref) ? null : ref));
+			}
+			args.onSelectionChange?.(ref, event);
+		},
+		[args, isControlled],
+	);
+
+	return { resolved, selection, select };
+}
+
+export interface UseSeriesVisibilityArgs<M> {
+	/** Present means the app owns visibility. */
+	readonly controlled?: readonly string[];
+	readonly onVisibilityChange?: (event: SeriesInteractionEvent<M>) => void;
+	/** Toggling stays off unless the app opts in (FR-049). */
+	readonly enabled: boolean;
+	/** Series marked hidden in the datasource itself. */
+	readonly initiallyHidden: readonly string[];
+}
+
+export interface SeriesVisibilityApi {
+	readonly hidden: ReadonlySet<string>;
+	readonly toggle: (seriesId: string, metadata?: unknown) => void;
+	readonly enabled: boolean;
+}
+
+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 toggle = useCallback(
+		(seriesId: string, metadata?: unknown) => {
+			if (!args.enabled) {
+				return;
+			}
+
+			const currentlyHidden = new Set(
+				isControlled ? args.controlled ?? [] : internal,
+			);
+			const willBeVisible = currentlyHidden.has(seriesId);
+
+			if (!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],
+	);
+
+	return { hidden, toggle, enabled: args.enabled };
+}