@chipmobilesdk/rn-chart 0.2.1 → 0.4.0

package/src/react/ChartLegend.tsx

@@ -6,10 +6,13 @@
  * carries a dash pattern as well as a colour, so series stay distinguishable
  * without colour perception.
  */
+import { formatMessage } from '@chipmobilesdk/rn-core';
 import React from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
 
 import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import type { SeriesRef } from '../contract/format';
+import { chartStrings, type ChartStrings } from '../contract/strings';
 import {
 	resolveSegmentColors,
 	resolveSeriesColor,
@@ -17,6 +20,7 @@ import {
 	type ChartTheme,
 	type LegendEntry,
 } from '../contract/theme';
+import type { ColorScale } from '../geometry/types';
 
 /** Minimum tap target, per platform accessibility guidance (UX-003). */
 const MIN_TAP_TARGET = 44;
@@ -32,13 +36,15 @@ export function buildLegendEntries<M>(
 	hidden: ReadonlySet<string>,
 	toggleable: boolean,
 	family?: ChartFamily,
+	/** The app's `legendLabel` formatter, when it has one. */
+	formatLabel: (series: SeriesRef) => string = series => series.label,
 ): LegendEntry[] {
 	if (family === 'distribution') {
 		const colors = resolveSegmentColors(datasource, theme);
 		return datasource.series.flatMap(series =>
 			series.points.map(point => {
 				const single = series.points.length === 1;
-				let label = series.label;
+				let label = formatLabel({ id: series.id, label: series.label });
 				if (!single) {
 					label = point.position.kind === 'category' ? point.position.category : point.id;
 				}
@@ -57,7 +63,7 @@ export function buildLegendEntries<M>(
 	}
 	return datasource.series.map((series, index) => ({
 		seriesId: series.id,
-		label: series.label,
+		label: formatLabel({ id: series.id, label: series.label }),
 		color: resolveSeriesColor(theme, index, series.color),
 		pattern: series.pattern ?? 'solid',
 		visible: !hidden.has(series.id),
@@ -117,10 +123,12 @@ export function ChartLegend({
 	entries,
 	theme,
 	onToggle,
+	strings = chartStrings.defaults,
 }: {
 	readonly entries: readonly LegendEntry[];
 	readonly theme: ChartTheme;
 	readonly onToggle?: (seriesId: string) => void;
+	readonly strings?: ChartStrings;
 }) {
 	if (entries.length === 0) {
 		return null;
@@ -162,7 +170,9 @@ export function ChartLegend({
 						accessibilityRole="switch"
 						accessibilityState={{ checked: entry.visible }}
 						accessibilityLabel={entry.label}
-						accessibilityHint={entry.visible ? 'Hides this series' : 'Shows this series'}
+						accessibilityHint={
+							entry.visible ? strings['chart.legend.hide'] : strings['chart.legend.show']
+						}
 						style={[styles.entry, styles.tappable]}
 					>
 						{content}
@@ -173,7 +183,59 @@ export function ChartLegend({
 	);
 }
 
+/**
+ * The key to a colour ramp: its lowest and highest value around the colours
+ * between them. Without it a heatmap's shades meant nothing (CHT-15).
+ */
+export function ColorScaleLegend({
+	scale,
+	theme,
+	formatValue,
+	strings = chartStrings.defaults,
+}: {
+	readonly scale: ColorScale;
+	readonly theme: ChartTheme;
+	readonly formatValue: (value: number) => string;
+	readonly strings?: ChartStrings;
+}) {
+	const min = formatValue(scale.min);
+	const max = formatValue(scale.max);
+	const text = {
+		color: theme.typography.legendLabel.color,
+		fontSize: theme.typography.legendLabel.fontSize,
+	};
+	return (
+		<View
+			style={styles.scale}
+			accessible
+			accessibilityRole="text"
+			accessibilityLabel={formatMessage(strings['chart.legend.scale'], { min, max })}
+		>
+			<Text style={text}>{min}</Text>
+			<View style={styles.scaleRamp}>
+				{scale.colors.map((color, index) => (
+					<View key={`${index}-${color}`} style={[styles.scaleStep, { backgroundColor: color }]} />
+				))}
+			</View>
+			<Text style={text}>{max}</Text>
+		</View>
+	);
+}
+
 const styles = StyleSheet.create({
+	scale: {
+		flexDirection: 'row',
+		alignItems: 'center',
+		marginTop: 4,
+	},
+	scaleRamp: {
+		flexDirection: 'row',
+		marginHorizontal: 8,
+	},
+	scaleStep: {
+		width: 16,
+		height: 8,
+	},
 	container: {
 		flexDirection: 'row',
 		flexWrap: 'wrap',

package/src/react/ChartPlot.tsx

@@ -0,0 +1,57 @@
+/**
+ * Everything the chart draws from its geometry.
+ *
+ * Memoized on the geometry: selecting a point re-renders the frame and moves
+ * the highlight, and this subtree — the long path strings — is skipped
+ * (CHT-08). It used to be reconciled again on every tap.
+ */
+import React from 'react';
+
+import type { ChartTheme } from '../contract/theme';
+import type { ResolvedGeometry } from '../geometry/types';
+import { Grid, XAxis, YAxis } from '../render/Axis';
+import { GeometryLabels, MarkerLines, Marks, NonValueTextures } from '../render/Marks';
+
+/** `labels` names rows and columns without drawing axis lines or a grid. */
+export type ChartAxes = 'full' | 'labels' | 'none';
+
+export const ChartPlot = React.memo(function ChartPlot({
+	geometry,
+	theme,
+	fontSize,
+	axes,
+}: {
+	readonly geometry: ResolvedGeometry;
+	readonly theme: ChartTheme;
+	readonly fontSize: number;
+	readonly axes: ChartAxes;
+}) {
+	const lines = axes === 'full';
+	return (
+		<>
+			<NonValueTextures theme={theme} />
+			{axes !== 'none' && (
+				<>
+					{lines && <Grid plot={geometry.plot} yTicks={geometry.yTicks} theme={theme} />}
+					<YAxis
+						plot={geometry.plot}
+						ticks={geometry.yTicks}
+						theme={theme}
+						fontSize={fontSize}
+						line={lines}
+					/>
+					<XAxis
+						plot={geometry.plot}
+						ticks={geometry.xTicks}
+						theme={theme}
+						fontSize={fontSize}
+						line={lines}
+					/>
+				</>
+			)}
+			<Marks paths={geometry.paths} />
+			<MarkerLines markers={geometry.markers} theme={theme} />
+			<GeometryLabels labels={geometry.labels} theme={theme} fontSize={fontSize} />
+		</>
+	);
+});

package/src/react/ChartStateOverlay.tsx

@@ -0,0 +1,94 @@
+/**
+ * What a chart shows in place of data: the app's own content for the state,
+ * or a terse built-in line. Apps are expected to supply their own copy — the
+ * package must not impose product voice.
+ */
+import React from 'react';
+import { StyleSheet, Text, View } from 'react-native';
+
+import type { ChartError } from '../contract/errors';
+import type { ChartStatus } from '../contract/state';
+import type { ChartStrings } from '../contract/strings';
+import type { ChartTheme } from '../contract/theme';
+
+function builtInStateText(
+	status: ChartStatus,
+	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;
+	}
+}
+
+export function ChartStateOverlay({
+	status,
+	supplied,
+	strings,
+	theme,
+	error,
+}: {
+	readonly status: ChartStatus;
+	/** The app's content for this state, when it gave any. */
+	readonly supplied?: React.ReactNode;
+	readonly strings: ChartStrings;
+	readonly theme: ChartTheme;
+	readonly error?: ChartError;
+}) {
+	if (supplied !== undefined) {
+		return <View style={styles.overlay}>{supplied}</View>;
+	}
+	const fallback = builtInStateText(status, strings, error);
+	if (!fallback) {
+		return null;
+	}
+	return (
+		<View style={styles.overlay}>
+			<Text style={{ color: theme.muted, fontSize: theme.typography.valueLabel.fontSize }}>
+				{fallback}
+			</Text>
+		</View>
+	);
+}
+
+/** The message a contained render failure shows where the plot was. */
+export function ChartFailureOverlay({
+	supplied,
+	theme,
+	error,
+}: {
+	readonly supplied?: React.ReactNode;
+	readonly theme: ChartTheme;
+	readonly error: ChartError;
+}) {
+	return (
+		<View style={styles.overlay}>
+			{supplied ?? (
+				<Text style={{ color: theme.muted, fontSize: theme.typography.valueLabel.fontSize }}>
+					{error.message}
+				</Text>
+			)}
+		</View>
+	);
+}
+
+const styles = StyleSheet.create({
+	overlay: {
+		position: 'absolute',
+		top: 0,
+		left: 0,
+		right: 0,
+		bottom: 0,
+		alignItems: 'center',
+		justifyContent: 'center',
+	},
+});

package/src/react/charts.tsx

@@ -11,6 +11,7 @@
 import React, { useCallback } from 'react';
 
 import type { ChartDatasource } from '../contract/datasource';
+import type { DistributionValues } from '../contract/distribution';
 import type { BaseChartProps } from '../contract/props';
 import { buildBarGeometry, type BarGrouping } from '../geometry/bar';
 import { buildDistributionGeometry, type DistributionShape } from '../geometry/distribution';
@@ -20,15 +21,12 @@ 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';
-}
+export type ProgressChartProps<M = unknown> = BaseChartProps<M>;
 
 function ProgressChartImpl<M>(props: ProgressChartProps<M>) {
 	const build = useCallback(
-		(ds: ChartDatasource<M>, input: GeometryInput) =>
-			buildProgressGeometry(ds, input, { orientation: props.orientation }),
-		[props.orientation],
+		(ds: ChartDatasource<M>, input: GeometryInput) => buildProgressGeometry(ds, input),
+		[],
 	);
 
 	return (
@@ -36,7 +34,7 @@ function ProgressChartImpl<M>(props: ProgressChartProps<M>) {
 			{...props}
 			family="progress"
 			buildGeometry={build}
-			showAxes={false}
+			axes="none"
 			defaultLegend={false}
 		/>
 	);
@@ -45,6 +43,13 @@ function ProgressChartImpl<M>(props: ProgressChartProps<M>) {
 export interface DistributionChartProps<M = unknown> extends BaseChartProps<M> {
 	readonly shape?: DistributionShape;
 	readonly innerRadiusRatio?: number;
+	/**
+	 * What the values mean. `proportions`: shares of a whole in 0..1, drawn short
+	 * and marked incomplete when they do not reach 1. `absolute`: counts or
+	 * amounts, normalised by their total. Inferred from the data when omitted;
+	 * say it when small counts (1 and 1) could be read as shares.
+	 */
+	readonly valuesAre?: DistributionValues;
 }
 
 function DistributionChartImpl<M>(props: DistributionChartProps<M>) {
@@ -53,8 +58,9 @@ function DistributionChartImpl<M>(props: DistributionChartProps<M>) {
 			buildDistributionGeometry(ds, input, {
 				shape: props.shape,
 				innerRadiusRatio: props.innerRadiusRatio,
+				valuesAre: props.valuesAre,
 			}),
-		[props.shape, props.innerRadiusRatio],
+		[props.shape, props.innerRadiusRatio, props.valuesAre],
 	);
 
 	return (
@@ -62,7 +68,8 @@ function DistributionChartImpl<M>(props: DistributionChartProps<M>) {
 			{...props}
 			family="distribution"
 			buildGeometry={build}
-			showAxes={false}
+			distributionValues={props.valuesAre}
+			axes="none"
 			defaultLegend
 		/>
 	);
@@ -74,10 +81,17 @@ export interface TimeSeriesChartProps<M = unknown> extends BaseChartProps<M> {
 }
 
 function TimeSeriesChartImpl<M>(props: TimeSeriesChartProps<M>) {
+	// By value: `range={{ from, to }}` written inline is a new object each render.
+	const from = props.range?.from;
+	const to = props.range?.to;
 	const build = useCallback(
 		(ds: ChartDatasource<M>, input: GeometryInput) =>
-			buildTimeSeriesGeometry(ds, input, { range: props.range }),
-		[props.range],
+			buildTimeSeriesGeometry(
+				ds,
+				input,
+				from === undefined || to === undefined ? {} : { range: { from, to } },
+			),
+		[from, to],
 	);
 
 	return (
@@ -122,7 +136,8 @@ function HeatmapChartImpl<M>(props: HeatmapChartProps<M>) {
 			{...props}
 			family="heatmap"
 			buildGeometry={build}
-			showAxes={false}
+			// Rows and columns are named; there is no axis line or grid to draw.
+			axes="labels"
 			defaultLegend={false}
 		/>
 	);

package/src/react/pointEvent.ts

@@ -0,0 +1,40 @@
+/**
+ * The event a selected point is reported with. One place builds it, for a tap
+ * and for a screen-reader step alike.
+ */
+import type { ChartDatasource, DataPoint, Series } from '../contract/datasource';
+import type { PointInteractionEvent } from '../contract/interaction';
+
+export interface ResolvedPoint<M> {
+	readonly series: Series<M>;
+	readonly point: DataPoint<M>;
+}
+
+export function findPoint<M>(
+	datasource: ChartDatasource<M>,
+	seriesId: string,
+	pointId: string | undefined,
+): ResolvedPoint<M> | undefined {
+	const series = datasource.series.find(s => s.id === seriesId);
+	const point = series?.points.find(p => p.id === pointId);
+	return series && point ? { series, point } : undefined;
+}
+
+export function pointEventFor<M>(
+	datasource: ChartDatasource<M>,
+	seriesId: string,
+	pointId: string,
+): PointInteractionEvent<M> | undefined {
+	const found = findPoint(datasource, seriesId, pointId);
+	if (!found) {
+		return undefined;
+	}
+	return {
+		type: 'pointSelect',
+		seriesId: found.series.id,
+		pointId: found.point.id,
+		value: found.point.value,
+		position: found.point.position,
+		metadata: found.point.metadata,
+	};
+}

package/src/react/useChartA11y.ts

@@ -0,0 +1,113 @@
+/**
+ * What a screen reader gets: the composed summary, the announcement for the
+ * selected point, and increment/decrement to walk the points (FR-052, FR-067,
+ * FR-072).
+ */
+import { useMemo } from 'react';
+
+import { buildChartSummary, buildPointAnnouncement } from '../a11y/summary';
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import type { ChartAccessibility } from '../contract/props';
+import type { ChartStatus } from '../contract/state';
+import type { ChartStrings } from '../contract/strings';
+import type { HitRegion } from '../geometry/hitTest';
+import { findPoint, pointEventFor } from './pointEvent';
+import type { ResolvedFormatters } from './useChartFormatters';
+import type { ChartSelectionApi } from './useChartSelection';
+
+export interface UseChartA11yArgs<M> {
+	readonly datasource: ChartDatasource<M>;
+	readonly family: ChartFamily;
+	readonly status: ChartStatus;
+	readonly title?: string;
+	readonly accessibility?: ChartAccessibility<M>;
+	readonly interactive: boolean;
+	readonly incomplete: boolean;
+	readonly hitRegions: readonly HitRegion[];
+	readonly selection: ChartSelectionApi<M>;
+	readonly formatters: ResolvedFormatters;
+	readonly strings: ChartStrings;
+}
+
+export interface ChartA11y {
+	readonly summary: string;
+	readonly value: { readonly text: string } | undefined;
+	readonly actions: readonly { readonly name: string; readonly label: string }[] | undefined;
+	readonly onAction: ((event: { nativeEvent: { actionName: string } }) => void) | undefined;
+}
+
+export function useChartA11y<M>(args: UseChartA11yArgs<M>): ChartA11y {
+	const { datasource, family, status, title, incomplete, formatters, strings, selection } = args;
+	const label = args.accessibility?.label;
+	const summaryFormatter = args.accessibility?.summaryFormatter;
+
+	const summary = useMemo(() => {
+		if (label) {
+			return label;
+		}
+		// The app's own composer, when given.
+		if (summaryFormatter) {
+			return summaryFormatter(datasource, { slot: 'summary', hint: datasource.format });
+		}
+		return buildChartSummary({
+			datasource,
+			family,
+			status,
+			title,
+			formatValue: formatters.formatSummaryValue,
+			formatPosition: formatters.formatPosition,
+			incomplete,
+			strings,
+		});
+	}, [label, summaryFormatter, datasource, family, status, title, formatters, incomplete, strings]);
+
+	if (!args.interactive) {
+		return { summary, value: undefined, actions: undefined, onAction: undefined };
+	}
+
+	const selected = selection.resolved
+		? findPoint(datasource, selection.resolved.seriesId, selection.resolved.pointId)
+		: undefined;
+
+	return {
+		summary,
+		value: selected
+			? {
+					text: buildPointAnnouncement(
+						selected.series.label,
+						// The app's own wording for a position: a raw epoch number is
+						// not something to read aloud (CHT-07).
+						formatters.formatPosition(selected.point.position),
+						selected.point.value,
+						formatters.formatSummaryValue,
+						strings,
+					),
+				}
+			: undefined,
+		actions: [
+			{ name: 'increment', label: strings['chart.action.next'] },
+			{ name: 'decrement', label: strings['chart.action.previous'] },
+		],
+		onAction: event => {
+			const regions = args.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 pointEvent = pointEventFor(datasource, next.seriesId, next.pointId);
+			if (!pointEvent) {
+				return;
+			}
+			// Stepping moves the selection; it never clears it.
+			selection.select({ seriesId: next.seriesId, pointId: next.pointId }, pointEvent, {
+				toggle: false,
+			});
+		},
+	};
+}

package/src/react/useChartFormatters.ts

@@ -0,0 +1,105 @@
+/**
+ * The app's formatters, resolved once into the functions the chart calls.
+ *
+ * The memo depends on each formatter **function**, not on the `formatters`
+ * object that carries them. `formatters={{ value: formatMoney }}` written
+ * inline is a new object every render; depending on it rebuilt every scale and
+ * path each time the parent rendered (CHT-08, PERF-11). A formatter function
+ * that is itself created inline still counts as a change — it may format
+ * differently — so keep those stable (module scope, or `useCallback`).
+ */
+import { useMemo } from 'react';
+
+import type { Position } from '../contract/datasource';
+import {
+	formatPositionDefault,
+	formatValueDefault,
+	safeFormat,
+	type ChartFormatters,
+	type FormatHint,
+	type SeriesRef,
+} from '../contract/format';
+import type { ValueState } from '../contract/value';
+
+export interface GeometryFormatters {
+	readonly formatValue: (value: number) => string;
+	readonly formatCategory: (raw: string) => string;
+	readonly formatInstant: (at: number) => string;
+}
+
+export interface ResolvedFormatters {
+	/** A value as the chart draws it. */
+	readonly formatValue: (value: ValueState) => string;
+	/** A value as the chart speaks it; the app's `summary` formatter when given. */
+	readonly formatSummaryValue: (value: ValueState) => string;
+	/** A position as the chart speaks it; the app's `axisLabel` formatter when given. */
+	readonly formatPosition: (position: Position) => string;
+	/** Present only when the app supplies `legendLabel`. */
+	readonly legendLabel?: (series: SeriesRef) => string;
+	readonly geometry: GeometryFormatters;
+}
+
+export function useChartFormatters(
+	formatters: ChartFormatters | undefined,
+	hint: FormatHint | undefined,
+	instanceKey: string,
+): ResolvedFormatters {
+	const value = formatters?.value;
+	const axisLabel = formatters?.axisLabel;
+	const legend = formatters?.legendLabel;
+	const summary = formatters?.summary;
+
+	return useMemo(() => {
+		const formatValue = (v: ValueState): string =>
+			value
+				? safeFormat(
+						() => value(v, { slot: 'value', hint }),
+						() => formatValueDefault(v, { slot: 'value', hint }),
+						'value',
+						instanceKey,
+					)
+				: formatValueDefault(v, { slot: 'value', hint });
+
+		const formatSummaryValue = (v: ValueState): string =>
+			summary
+				? safeFormat(
+						() => summary(v, { slot: 'summary', hint }),
+						() => formatValue(v),
+						'summary',
+						instanceKey,
+					)
+				: formatValue(v);
+
+		const formatPosition = (position: Position): string =>
+			axisLabel
+				? safeFormat(
+						() => axisLabel(position, { slot: 'axis' }),
+						() => formatPositionDefault(position),
+						'axis',
+						instanceKey,
+					)
+				: formatPositionDefault(position);
+
+		return {
+			formatValue,
+			formatSummaryValue,
+			formatPosition,
+			...(legend
+				? {
+						legendLabel: (series: SeriesRef) =>
+							safeFormat(
+								() => legend(series, { slot: 'legend' }),
+								() => series.label,
+								'legend',
+								instanceKey,
+							),
+					}
+				: {}),
+			geometry: {
+				formatValue: (n: number) => formatValue({ kind: 'known', value: n }),
+				formatCategory: (raw: string) => raw,
+				formatInstant: (at: number) => formatPosition({ kind: 'instant', at }),
+			},
+		};
+	}, [value, axisLabel, legend, summary, hint, instanceKey]);
+}

package/src/react/useChartLayout.ts

@@ -11,7 +11,7 @@
  * app models the correct pattern.
  */
 import { useCallback, useMemo, useState } from 'react';
-import { PixelRatio, type LayoutChangeEvent } from 'react-native';
+import { useWindowDimensions, type LayoutChangeEvent } from 'react-native';
 
 import type { ChartDatasource, ChartFamily } from '../contract/datasource';
 import { resolveSegmentColors, resolveSeriesColor, type ChartTheme } from '../contract/theme';
@@ -53,7 +53,9 @@ export function useChartLayout(
 		);
 	}, []);
 
-	const fontScale = PixelRatio.getFontScale();
+	// Reactive: a change of the system text size re-renders the chart. A value
+	// read once from PixelRatio kept the old size until something else rendered.
+	const { fontScale } = useWindowDimensions();
 	const fontSize = effectiveFontSize(theme.typography.axisLabel.fontSize, fontScale);
 
 	const measured = isMeasurable(size);
@@ -116,6 +118,7 @@ export function useGeometryInput<M>(
 				family === 'distribution' ? resolveSegmentColors(datasource, theme) : undefined,
 			nonValueTextures: theme.nonValue,
 			heatmapRamp: theme.heatmapRamp,
+			radius: theme.radius,
 			formatValue: formatters.formatValue,
 			formatCategory: formatters.formatCategory,
 			formatInstant: formatters.formatInstant,