@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/react/charts.tsx

@@ -1,161 +1,154 @@
-/**
- * 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;
+/**
+ * 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

@@ -1,124 +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, ChartFamily } from '../contract/datasource';
-import { resolveSegmentColors, 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;
-	},
-	family?: ChartFamily,
-): GeometryInput {
-	return useMemo(() => {
-		const seriesColors: Record<string, string> = {};
-		datasource.series.forEach((series, index) => {
-			seriesColors[series.id] = resolveSeriesColor(theme, index, series.color);
-		});
-
-		return {
-			plot: layout.plot,
-			fontSize: layout.fontSize,
-			seriesColors,
-			// Per point only where segments exist; resolving one per point for
-			// every family cost a colour per data point at the time-series budget.
-			segmentColors:
-				family === 'distribution' ? resolveSegmentColors(datasource, theme) : undefined,
-			nonValueTextures: theme.nonValue,
-			heatmapRamp: theme.heatmapRamp,
-			formatValue: formatters.formatValue,
-			formatCategory: formatters.formatCategory,
-			formatInstant: formatters.formatInstant,
-		};
-	}, [datasource, theme, layout.plot, layout.fontSize, formatters, family]);
-}
+/**
+ * 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, ChartFamily } from '../contract/datasource';
+import { resolveSegmentColors, 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;
+	},
+	family?: ChartFamily,
+): GeometryInput {
+	return useMemo(() => {
+		const seriesColors: Record<string, string> = {};
+		datasource.series.forEach((series, index) => {
+			seriesColors[series.id] = resolveSeriesColor(theme, index, series.color);
+		});
+
+		return {
+			plot: layout.plot,
+			fontSize: layout.fontSize,
+			seriesColors,
+			// Per point only where segments exist; resolving one per point for
+			// every family cost a colour per data point at the time-series budget.
+			segmentColors:
+				family === 'distribution' ? resolveSegmentColors(datasource, theme) : undefined,
+			nonValueTextures: theme.nonValue,
+			heatmapRamp: theme.heatmapRamp,
+			formatValue: formatters.formatValue,
+			formatCategory: formatters.formatCategory,
+			formatInstant: formatters.formatInstant,
+		};
+	}, [datasource, theme, layout.plot, layout.fontSize, formatters, family]);
+}