@chipmobilesdk/rn-chart 0.1.0

package/src/geometry/timeSeries.ts

@@ -0,0 +1,158 @@
+/**
+ * Time-series geometry: one stroked path per series over an instant domain.
+ *
+ * Gaps are the interesting part. A non-known value contributes `null` to the
+ * point list, `linePath` lifts the pen there, and the line simply does not
+ * exist across the gap (FR-012).
+ *
+ * PURE. No React, no SVG.
+ */
+import type { ChartDatasource, Series } from '../contract/datasource';
+import { isKnown, isWithheld } from '../contract/value';
+import type { HitRegion } from './hitTest';
+import { plotBottom, plotRight } from './layout';
+import { linePath, type MaybePt } from './path';
+import { domainFrom, linearScale, timeScale } from './scale';
+import { niceTickValues, thinTicks, type Tick } from './ticks';
+import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
+
+export interface TimeSeriesOptions {
+	/** Window supplied by the app. Users cannot draw one (pan/zoom out of scope). */
+	readonly range?: { readonly from: number; readonly to: number };
+}
+
+function visiblePoints<M>(series: Series<M>, range?: TimeSeriesOptions['range']) {
+	const points = [...series.points]
+		.filter(p => p.position.kind === 'instant')
+		// Out-of-order input must still produce a correct axis.
+		.sort((a, b) => {
+			const at = a.position.kind === 'instant' ? a.position.at : 0;
+			const bt = b.position.kind === 'instant' ? b.position.at : 0;
+			return at - bt;
+		});
+
+	if (!range) {
+		return points;
+	}
+	return points.filter(p => {
+		const at = p.position.kind === 'instant' ? p.position.at : 0;
+		return at >= range.from && at <= range.to;
+	});
+}
+
+export function buildTimeSeriesGeometry<M>(
+	datasource: ChartDatasource<M>,
+	input: GeometryInput,
+	options: TimeSeriesOptions = {},
+): ResolvedGeometry {
+	const { plot } = input;
+
+	const instants: number[] = [];
+	const values: number[] = [];
+	let excluded = 0;
+
+	for (const series of datasource.series) {
+		for (const point of visiblePoints(series, options.range)) {
+			if (point.position.kind === 'instant') {
+				instants.push(point.position.at);
+			}
+			if (isKnown(point.value)) {
+				values.push(point.value.value);
+			} else {
+				excluded += 1;
+			}
+		}
+	}
+
+	if (instants.length === 0) {
+		return {
+			plot,
+			paths: [],
+			markers: [],
+			labels: [],
+			xTicks: [],
+			yTicks: [],
+			hitRegions: [],
+			incomplete: excluded > 0,
+		};
+	}
+
+	const x = timeScale(domainFrom(instants), {
+		min: plot.x,
+		max: plotRight(plot),
+	});
+	const y = linearScale(domainFrom(values, { padFraction: 0.1 }), {
+		min: plotBottom(plot),
+		max: plot.y,
+	});
+
+	const paths: MarkPath[] = [];
+	const hitRegions: HitRegion[] = [];
+
+	for (const series of datasource.series) {
+		if (series.hidden) {
+			continue;
+		}
+
+		const pts: MaybePt[] = [];
+
+		for (const point of visiblePoints(series, options.range)) {
+			const at = point.position.kind === 'instant' ? point.position.at : 0;
+			const px = x.project(at);
+
+			if (!isKnown(point.value)) {
+				// The gap. No coordinate is produced, so no segment can span it.
+				pts.push(null);
+				continue;
+			}
+
+			const py = y.project(point.value.value);
+			pts.push({ x: px, y: py });
+
+			hitRegions.push({
+				seriesId: series.id,
+				pointId: point.id,
+				x: px,
+				y: py,
+				// Withheld values are never selectable, so a callback can never
+				// carry one (FR-053).
+				selectable: !isWithheld(point.value),
+			});
+		}
+
+		const d = linePath(pts);
+		if (d.length > 0) {
+			paths.push({
+				key: `line-${series.id}`,
+				seriesId: series.id,
+				d,
+				color: input.seriesColors[series.id],
+				pattern: series.pattern ?? 'solid',
+				filled: false,
+			});
+		}
+	}
+
+	const xTicks: Tick[] = niceTickValues(x.domain, 4).map(v => ({
+		value: v,
+		position: x.project(v),
+		label: input.formatInstant(v),
+	}));
+
+	const yTicks: Tick[] = niceTickValues(y.domain, 4).map(v => ({
+		value: v,
+		position: y.project(v),
+		label: input.formatValue(v),
+	}));
+
+	return {
+		plot,
+		paths,
+		markers: [],
+		labels: [],
+		xTicks: thinTicks(xTicks, input.fontSize, plot.width),
+		yTicks,
+		hitRegions,
+		incomplete: excluded > 0,
+	};
+}

package/src/geometry/types.ts

@@ -0,0 +1,88 @@
+/**
+ * The single memoized artefact each chart produces.
+ *
+ * `ResolvedGeometry` is keyed on datasource identity, plot rectangle, theme
+ * identity, and formatter identity — and deliberately **not** on selection.
+ * Highlighting a point must repaint the highlight, not recompute every scale
+ * and path string (research.md R3, FR-073).
+ *
+ * PURE. No React, no SVG.
+ */
+import type { SeriesPattern } from '../contract/datasource';
+import type { NonValueTexture } from '../contract/theme';
+import type { HitRegion } from './hitTest';
+import type { PlotRect } from './layout';
+import type { Tick } from './ticks';
+
+/** One drawable group. Element count scales with these, never with points. */
+export interface MarkPath {
+	readonly key: string;
+	readonly seriesId: string;
+	readonly d: string;
+	readonly color: string;
+	readonly pattern: SeriesPattern;
+	/** Filled shapes (bars, arcs, cells) versus stroked ones (lines). */
+	readonly filled: boolean;
+	/** Set on marks standing in for a non-value class: texture, not hue. */
+	readonly texture?: NonValueTexture;
+	readonly opacity?: number;
+}
+
+/** A target, baseline, or threshold drawn across the plot. */
+export interface MarkerLine {
+	readonly id: string;
+	readonly d: string;
+	readonly label?: string;
+	readonly kind: 'target' | 'baseline' | 'threshold';
+}
+
+/** Text the chart draws itself, such as progress values or segment labels. */
+export interface GeometryLabel {
+	readonly key: string;
+	readonly text: string;
+	readonly x: number;
+	readonly y: number;
+	readonly anchor: 'start' | 'middle' | 'end';
+	readonly muted?: boolean;
+}
+
+export interface ResolvedGeometry {
+	readonly plot: PlotRect;
+	readonly paths: readonly MarkPath[];
+	readonly markers: readonly MarkerLine[];
+	readonly labels: readonly GeometryLabel[];
+	readonly xTicks: readonly Tick[];
+	readonly yTicks: readonly Tick[];
+	readonly hitRegions: readonly HitRegion[];
+	/**
+	 * True when something was excluded from a total or proportion, so the chart
+	 * can say so rather than presenting a partial figure as whole (FR-013).
+	 */
+	readonly incomplete: boolean;
+}
+
+export const EMPTY_GEOMETRY: ResolvedGeometry = {
+	plot: { x: 0, y: 0, width: 0, height: 0 },
+	paths: [],
+	markers: [],
+	labels: [],
+	xTicks: [],
+	yTicks: [],
+	hitRegions: [],
+	incomplete: false,
+};
+
+/** Inputs every family geometry builder needs. */
+export interface GeometryInput {
+	readonly plot: PlotRect;
+	readonly fontSize: number;
+	/** Resolved per series, so geometry never reaches into the theme itself. */
+	readonly seriesColors: Readonly<Record<string, string>>;
+	readonly nonValueTextures: Readonly<
+		Record<'unknown' | 'notApplicable' | 'withheld', NonValueTexture>
+	>;
+	readonly heatmapRamp: readonly string[];
+	readonly formatValue: (value: number) => string;
+	readonly formatCategory: (raw: string) => string;
+	readonly formatInstant: (at: number) => string;
+}

package/src/index.ts

@@ -0,0 +1,176 @@
+/**
+ * @chipmobilesdk/rn-chart — domain-agnostic charting for ChipMobileSdk-family
+ * React Native apps.
+ *
+ * This is the single public entrypoint (LIB-003). Modules under `geometry/`,
+ * `render/`, `validation/`, and the internals of `react/` are private; import
+ * them only through this file. Keeping them private is what lets the geometry,
+ * the layout maths, and the rendering substrate change without a breaking
+ * release.
+ *
+ * The package makes no network request, calls no AI service, reads no
+ * database, persists nothing, and logs no data value or series label. It
+ * renders numeric data and app-supplied labels — nothing else.
+ *
+ * There is deliberately **no insight, message, or narrative surface**: apps
+ * render their own text around a chart, and a chart imposes no outer margin
+ * that would fight that layout.
+ */
+
+// ---------------------------------------------------------------------------
+// Value semantics — the foundation of the contract
+// ---------------------------------------------------------------------------
+export type {
+	KnownValue,
+	NotApplicableValue,
+	TotalResult,
+	UnknownValue,
+	ValueKind,
+	ValueState,
+	WithheldValue,
+} from './contract/value';
+export {
+	isKnown,
+	isWithheld,
+	known,
+	notApplicable,
+	participatesInTotals,
+	sumKnown,
+	unknown,
+	withheld,
+} from './contract/value';
+
+// ---------------------------------------------------------------------------
+// Datasource contract
+// ---------------------------------------------------------------------------
+export type {
+	CategoryPosition,
+	ChartDatasource,
+	ChartFamily,
+	DataPoint,
+	InstantPosition,
+	MatrixPosition,
+	Position,
+	PositionKind,
+	Series,
+	SeriesPattern,
+} from './contract/datasource';
+export {
+	FAMILY_POSITION_KINDS,
+	familyAcceptsPositionKind,
+	resolveFormat,
+	resolveUnit,
+} from './contract/datasource';
+
+export type { MarkerKind, ProgressReading, ReferenceMarker } from './contract/marker';
+export { findTarget, isUsableTarget, readProgress } from './contract/marker';
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+export type {
+	ChartFormatters,
+	FormatContext,
+	FormatHint,
+	SeriesRef,
+} from './contract/format';
+export {
+	NON_VALUE_TEXT,
+	formatLegendDefault,
+	formatPositionDefault,
+	formatValueDefault,
+	seriesRef,
+} from './contract/format';
+
+// ---------------------------------------------------------------------------
+// State and errors
+// ---------------------------------------------------------------------------
+export type {
+	ChartStateContent,
+	ChartStatus,
+	DeclarableChartStatus,
+	StatusInputs,
+} from './contract/state';
+export {
+	STATUS_PRECEDENCE,
+	drawsData,
+	resolveStatus,
+	suppressesInteraction,
+} from './contract/state';
+
+export type {
+	ChartError,
+	ChartErrorCategory,
+	ChartErrorCode,
+	ChartFailureHandler,
+	ChartFailureReport,
+} from './contract/errors';
+export { isChartError } from './contract/errors';
+
+// ---------------------------------------------------------------------------
+// Interaction
+// ---------------------------------------------------------------------------
+export type {
+	ChartInteractionEvent,
+	InteractionProps,
+	PointInteractionEvent,
+	SelectionRef,
+	SeriesInteractionEvent,
+} from './contract/interaction';
+export { sameSelection } from './contract/interaction';
+
+// ---------------------------------------------------------------------------
+// Theme
+// ---------------------------------------------------------------------------
+export type {
+	ChartTheme,
+	LegendEntry,
+	NonValueTexture,
+	TextStyleTokens,
+} from './contract/theme';
+export { defaultChartTheme, resolveSeriesColor } from './contract/theme';
+
+// ---------------------------------------------------------------------------
+// Props and accessibility
+// ---------------------------------------------------------------------------
+export type {
+	BaseChartProps,
+	ChartAccessibility,
+	ValueFormatter,
+} from './contract/props';
+
+// ---------------------------------------------------------------------------
+// Dataset budgets
+// ---------------------------------------------------------------------------
+export type { BudgetCheck, DatasetBudget } from './validation/budgets';
+export { DATASET_BUDGETS, checkBudget } from './validation/budgets';
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+export type {
+	BarChartProps,
+	DistributionChartProps,
+	HeatmapChartProps,
+	ProgressChartProps,
+	TimeSeriesChartProps,
+} from './react/charts';
+export {
+	BarChart,
+	DistributionChart,
+	HeatmapChart,
+	ProgressChart,
+	TimeSeriesChart,
+} from './react/charts';
+
+export { ChartLegend, buildLegendEntries } from './react/ChartLegend';
+export { ChartThemeProvider, useChartTheme } from './react/ChartThemeProvider';
+
+// ---------------------------------------------------------------------------
+// Accessibility helpers
+// ---------------------------------------------------------------------------
+export {
+	buildChartSummary,
+	buildPointAnnouncement,
+	buildTotalAnnouncement,
+} from './a11y/summary';

package/src/react/ChartBoundary.tsx

@@ -0,0 +1,96 @@
+/**
+ * Per-chart render-failure containment (FR-038a, FR-038b).
+ *
+ * React 19 still has no hook equivalent of an error boundary —
+ * `getDerivedStateFromError` and `componentDidCatch` remain class-only — so
+ * this is a class. Forty lines beats adding a dependency for it.
+ *
+ * Three behaviours are deliberate:
+ *
+ *  - **Reset only on a real change.** The boundary clears its error when the
+ *    datasource identity or chart key changes, never on an unrelated parent
+ *    re-render. A deterministic geometry defect therefore cannot pin the CPU in
+ *    a render-fail-render loop.
+ *  - **Report once per distinct failure.** De-duplicated by signature, so a
+ *    chart re-rendered by a sibling's state change does not re-report.
+ *  - **Redact.** The report carries the chart identity and a catalogue message.
+ *    A third-party exception's own text is never copied in, because we cannot
+ *    promise it is free of data (POL-011).
+ */
+import React from 'react';
+
+import type { ChartFamily } from '../contract/datasource';
+import {
+	chartError,
+	failureSignature,
+	toFailureReport,
+	type ChartError,
+	type ChartFailureHandler,
+} from '../contract/errors';
+
+interface Props {
+	readonly family: ChartFamily;
+	readonly chartId?: string;
+	readonly onFailure?: ChartFailureHandler;
+	/** Changing this clears a contained failure. */
+	readonly resetKey: unknown;
+	readonly renderFallback: (error: ChartError) => React.ReactNode;
+	readonly children: React.ReactNode;
+}
+
+interface State {
+	readonly error?: ChartError;
+	readonly resetKey: unknown;
+	readonly reportedSignature?: string;
+}
+
+export class ChartBoundary extends React.Component<Props, State> {
+	constructor(props: Props) {
+		super(props);
+		this.state = { resetKey: props.resetKey };
+	}
+
+	static getDerivedStateFromProps(props: Props, state: State): State | null {
+		if (props.resetKey !== state.resetKey) {
+			// New data: give the chart another chance.
+			return { resetKey: props.resetKey, error: undefined };
+		}
+		return null;
+	}
+
+	static getDerivedStateFromError(): Partial<State> {
+		// This must set the error, not just acknowledge it. Returning an empty
+		// object leaves render() showing the children again, they throw again,
+		// and React escalates past the boundary — which is exactly the
+		// screen-blanking failure this class exists to prevent.
+		//
+		// componentDidCatch then refines this into a report carrying the chart
+		// identity and family.
+		return { error: chartError('render', 'renderException') };
+	}
+
+	componentDidCatch(error: unknown, info: { componentStack?: string }): void {
+		const report = toFailureReport(
+			this.props.family,
+			error,
+			this.props.chartId,
+			info?.componentStack ?? undefined,
+		);
+
+		const signature = failureSignature(report);
+		if (this.state.reportedSignature === signature) {
+			this.setState({ error: report.error });
+			return;
+		}
+
+		this.setState({ error: report.error, reportedSignature: signature });
+		this.props.onFailure?.(report);
+	}
+
+	render(): React.ReactNode {
+		if (this.state.error) {
+			return this.props.renderFallback(this.state.error);
+		}
+		return this.props.children;
+	}
+}