@chipmobilesdk/rn-chart 0.1.0

package/src/contract/datasource.ts

@@ -0,0 +1,134 @@
+/**
+ * The shared datasource contract (FR-007, FR-007a).
+ *
+ * One contract spans every chart family: each point carries the same envelope —
+ * identity, value state, optional unit and format hint, opaque metadata — and
+ * only its **position** varies by kind. Families that accept the same position
+ * kind consume one another's datasources unchanged; anything else is a
+ * validation error rather than a rendering guess.
+ *
+ * See specs/007-rn-chart-package/data-model.md §2–§6.
+ */
+import type { FormatHint } from './format';
+import type { ReferenceMarker } from './marker';
+import type { ValueState } from './value';
+
+export type ChartFamily =
+	| 'progress'
+	| 'distribution'
+	| 'timeSeries'
+	| 'bar'
+	| 'heatmap';
+
+/** A named bucket: a category axis, a distribution segment, a progress metric. */
+export interface CategoryPosition {
+	readonly kind: 'category';
+	readonly category: string;
+}
+
+/**
+ * An absolute instant as epoch milliseconds, UTC.
+ *
+ * A number rather than a `Date` or an ISO string: cheap to compare and
+ * memoize, no per-render parsing across hundreds of points, no identity churn
+ * that would defeat the re-render guarantee, and no ambiguous offset. All
+ * date wording comes from app formatters (FR-016).
+ */
+export interface InstantPosition {
+	readonly kind: 'instant';
+	readonly at: number;
+}
+
+/** A cell in a row-by-column matrix, for heatmaps. */
+export interface MatrixPosition {
+	readonly kind: 'matrix';
+	readonly row: string;
+	readonly column: string;
+}
+
+export type Position = CategoryPosition | InstantPosition | MatrixPosition;
+export type PositionKind = Position['kind'];
+
+/** Non-colour encoding for a series, so meaning never rides on hue alone (FR-064). */
+export type SeriesPattern = 'solid' | 'dashed' | 'dotted' | 'dashDot';
+
+export interface DataPoint<M = unknown> {
+	/** Stable and unique within its series. Duplicates are a validation error. */
+	readonly id: string;
+	readonly position: Position;
+	readonly value: ValueState;
+	/** Overrides the series unit. */
+	readonly unit?: string;
+	/** Overrides the series format hint. */
+	readonly format?: FormatHint;
+	/** Opaque to the package: never read, never logged, returned unchanged. */
+	readonly metadata?: M;
+}
+
+export interface Series<M = unknown> {
+	/** Stable and unique within the datasource. */
+	readonly id: string;
+	readonly label: string;
+	readonly points: readonly DataPoint<M>[];
+	readonly unit?: string;
+	readonly format?: FormatHint;
+	/** Explicit colour override; otherwise the theme palette assigns one. */
+	readonly color?: string;
+	readonly pattern?: SeriesPattern;
+	/** Initial visibility. Runtime toggling is controlled separately. */
+	readonly hidden?: boolean;
+	readonly metadata?: M;
+}
+
+export interface ChartDatasource<M = unknown> {
+	/** Declared once, then validated against every point and the receiving family. */
+	readonly positionKind: PositionKind;
+	readonly series: readonly Series<M>[];
+	readonly markers?: readonly ReferenceMarker[];
+	readonly unit?: string;
+	readonly format?: FormatHint;
+	readonly metadata?: M;
+}
+
+/**
+ * Which position kinds each family accepts.
+ *
+ * Bar accepting both `category` and `instant` is what makes swapping a
+ * time-series chart for a bar chart free — the datasource does not change.
+ */
+export const FAMILY_POSITION_KINDS: Readonly<
+	Record<ChartFamily, readonly PositionKind[]>
+> = {
+	progress: ['category'],
+	distribution: ['category'],
+	bar: ['category', 'instant'],
+	timeSeries: ['instant'],
+	heatmap: ['matrix'],
+};
+
+export function familyAcceptsPositionKind(
+	family: ChartFamily,
+	kind: PositionKind,
+): boolean {
+	return FAMILY_POSITION_KINDS[family].includes(kind);
+}
+
+/**
+ * Resolves unit and format through the documented precedence:
+ * point -> series -> datasource -> undefined (caller falls back to its default).
+ */
+export function resolveFormat<M>(
+	point: DataPoint<M> | undefined,
+	series: Series<M> | undefined,
+	datasource: ChartDatasource<M>,
+): FormatHint | undefined {
+	return point?.format ?? series?.format ?? datasource.format;
+}
+
+export function resolveUnit<M>(
+	point: DataPoint<M> | undefined,
+	series: Series<M> | undefined,
+	datasource: ChartDatasource<M>,
+): string | undefined {
+	return point?.unit ?? series?.unit ?? datasource.unit;
+}

package/src/contract/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Typed error taxonomy and failure reporting (FR-038, FR-038a, FR-038b).
+ *
+ * Messages come from a **fixed catalogue with no interpolated data**. That is
+ * what makes the redaction guarantee structural rather than a rule someone has
+ * to remember: because the package never builds a message out of a value or a
+ * label, a failure report cannot carry patient data or account balances into a
+ * consuming app's crash reporting.
+ */
+import type { ChartFamily, PositionKind } from './datasource';
+
+export type ChartErrorCategory = 'validation' | 'declared' | 'render';
+
+export type ChartErrorCode =
+	| 'duplicateSeriesId'
+	| 'duplicatePointId'
+	| 'positionKindMismatch'
+	| 'familyPositionKindUnsupported'
+	| 'inconsistentMatrix'
+	| 'distributionNotWhole'
+	| 'declaredByApp'
+	| 'renderException';
+
+/**
+ * Fixed message catalogue. Every entry is a constant string — no template
+ * holes, so no data can leak through a message.
+ */
+const MESSAGES: Readonly<Record<ChartErrorCode, string>> = {
+	duplicateSeriesId:
+		'Datasource contains duplicate series identifiers. Series ids must be unique.',
+	duplicatePointId:
+		'A series contains duplicate point identifiers. Point ids must be unique within their series.',
+	positionKindMismatch:
+		'A data point position kind does not match the datasource positionKind.',
+	familyPositionKindUnsupported:
+		'This chart family does not accept the datasource position kind.',
+	inconsistentMatrix:
+		'Matrix datasource rows and columns are inconsistent across points.',
+	distributionNotWhole:
+		'Distribution segments do not sum to the whole. The chart marks the total incomplete rather than rescaling.',
+	declaredByApp: 'The application declared this chart to be in an error state.',
+	renderException:
+		'The chart failed while rendering and was contained. See the report for details.',
+};
+
+export interface ChartError {
+	readonly category: ChartErrorCategory;
+	readonly code: ChartErrorCode;
+	readonly message: string;
+	readonly chartId?: string;
+	readonly family?: ChartFamily;
+	/**
+	 * Structural detail that is safe to expose: counts and kinds only, never a
+	 * value or a label.
+	 */
+	readonly detail?: {
+		readonly expectedKind?: PositionKind;
+		readonly actualKind?: PositionKind;
+		readonly occurrences?: number;
+	};
+}
+
+export interface ChartFailureReport {
+	readonly chartId?: string;
+	readonly family: ChartFamily;
+	readonly error: ChartError;
+	readonly componentStack?: string;
+}
+
+export type ChartFailureHandler = (report: ChartFailureReport) => void;
+
+export function chartError(
+	category: ChartErrorCategory,
+	code: ChartErrorCode,
+	extra?: Omit<ChartError, 'category' | 'code' | 'message'>,
+): ChartError {
+	return {
+		category,
+		code,
+		message: MESSAGES[code],
+		...extra,
+	};
+}
+
+export function validationError(
+	code: ChartErrorCode,
+	extra?: Omit<ChartError, 'category' | 'code' | 'message'>,
+): ChartError {
+	return chartError('validation', code, extra);
+}
+
+export function isChartError(e: unknown): e is ChartError {
+	if (typeof e !== 'object' || e === null) {
+		return false;
+	}
+	const candidate = e as Partial<ChartError>;
+	return (
+		typeof candidate.code === 'string' &&
+		typeof candidate.message === 'string' &&
+		(candidate.category === 'validation' ||
+			candidate.category === 'declared' ||
+			candidate.category === 'render')
+	);
+}
+
+/**
+ * Builds the report handed to the app after a contained render exception.
+ *
+ * A `ChartError` thrown by the package keeps its catalogue message. Anything
+ * else — a defect in the rendering library, say — is reported under the generic
+ * `renderException` message. We do **not** copy a third-party exception's own
+ * message into the report, because we cannot promise it is free of data.
+ */
+export function toFailureReport(
+	family: ChartFamily,
+	thrown: unknown,
+	chartId?: string,
+	componentStack?: string,
+): ChartFailureReport {
+	const error: ChartError = isChartError(thrown)
+		? { ...thrown, chartId, family }
+		: chartError('render', 'renderException', { chartId, family });
+
+	return { chartId, family, error, componentStack };
+}
+
+/**
+ * Stable identity for a failure, used to de-duplicate reports so an unrelated
+ * parent re-render does not re-report the same problem.
+ */
+export function failureSignature(report: ChartFailureReport): string {
+	return `${report.chartId ?? 'anon'}:${report.family}:${report.error.code}`;
+}

package/src/contract/format.ts

@@ -0,0 +1,168 @@
+/**
+ * Formatting contract (FR-055 to FR-059).
+ *
+ * The package never invents or converts a business unit. It accepts a hint,
+ * applies a documented locale-neutral default, and uses app-supplied formatter
+ * output verbatim whenever one is given.
+ */
+import type { Position, Series } from './datasource';
+import { isKnown, type ValueState } from './value';
+
+export type FormatHint =
+	| { readonly kind: 'number'; readonly decimals?: number }
+	| { readonly kind: 'percent'; readonly decimals?: number }
+	| { readonly kind: 'currency'; readonly currency: string }
+	| {
+			readonly kind: 'duration';
+			readonly unit: 'ms' | 's' | 'min' | 'h';
+	  }
+	| { readonly kind: 'count' }
+	| { readonly kind: 'custom'; readonly unit: string };
+
+export interface FormatContext {
+	readonly hint?: FormatHint;
+	readonly unit?: string;
+	/** Where the text will appear, so a formatter can adapt its verbosity. */
+	readonly slot: 'axis' | 'value' | 'legend' | 'summary';
+}
+
+export interface SeriesRef {
+	readonly id: string;
+	readonly label: string;
+}
+
+export interface ChartFormatters {
+	readonly axisLabel?: (
+		v: ValueState | Position,
+		ctx: FormatContext,
+	) => string;
+	readonly value?: (v: ValueState, ctx: FormatContext) => string;
+	readonly legendLabel?: (series: SeriesRef, ctx: FormatContext) => string;
+	readonly summary?: (v: ValueState, ctx: FormatContext) => string;
+}
+
+/**
+ * Placeholders for the three non-value classes. Deliberately not "0" and not
+ * an empty string, so a reader can tell a gap from a zero at a glance.
+ */
+export const NON_VALUE_TEXT: Readonly<Record<string, string>> = {
+	unknown: '—',
+	notApplicable: 'n/a',
+	withheld: '••',
+};
+
+function trimTrailingZeros(text: string): string {
+	return text.includes('.') ? text.replace(/\.?0+$/, '') : text;
+}
+
+/**
+ * Locale-neutral default formatting (FR-057).
+ *
+ * Deliberately plain: no thousands separators, no currency symbol lookup, no
+ * month names. Anything locale-dependent belongs to the consuming app, which
+ * owns an i18n system the package does not.
+ */
+export function formatValueDefault(
+	v: ValueState,
+	ctx: FormatContext = { slot: 'value' },
+): string {
+	if (!isKnown(v)) {
+		return NON_VALUE_TEXT[v.kind] ?? NON_VALUE_TEXT.unknown;
+	}
+
+	const hint = ctx.hint;
+	const n = v.value;
+
+	switch (hint?.kind) {
+		case 'percent': {
+			const decimals = hint.decimals ?? 0;
+			return `${(n * 100).toFixed(decimals)}%`;
+		}
+		case 'currency':
+			// Code rather than symbol: symbol placement is locale-dependent and
+			// therefore the app's decision.
+			return `${n.toFixed(2)} ${hint.currency}`;
+		case 'duration':
+			return `${trimTrailingZeros(n.toFixed(2))}${hint.unit}`;
+		case 'count':
+			return String(Math.round(n));
+		case 'custom':
+			return `${trimTrailingZeros(n.toFixed(2))} ${hint.unit}`;
+		case 'number':
+			return hint.decimals === undefined
+				? trimTrailingZeros(n.toFixed(2))
+				: n.toFixed(hint.decimals);
+		default:
+			return trimTrailingZeros(n.toFixed(2));
+	}
+}
+
+export function formatPositionDefault(p: Position): string {
+	switch (p.kind) {
+		case 'category':
+			return p.category;
+		case 'matrix':
+			return `${p.row} / ${p.column}`;
+		case 'instant':
+			// Epoch milliseconds as-is. Any human-readable date belongs to an app
+			// formatter, which alone knows the locale and the display timezone
+			// (FR-016).
+			return String(p.at);
+	}
+}
+
+export function formatLegendDefault(series: SeriesRef): string {
+	return series.label;
+}
+
+/**
+ * Runs an app formatter, falling back to the package default for that single
+ * label if it throws (FR-059). One bad formatter must not take down a screen.
+ *
+ * The dev-only warning is intentionally value-free: it names the slot, never
+ * the data.
+ */
+export function safeFormat(
+	run: () => string,
+	fallback: () => string,
+	slot: FormatContext['slot'],
+	onceKey?: string,
+): string {
+	try {
+		return run();
+	} catch (e) {
+		if (__DEV__) {
+			warnFormatterFailureOnce(slot, onceKey, e);
+		}
+		return fallback();
+	}
+}
+
+const warnedFormatters = new Set<string>();
+
+function warnFormatterFailureOnce(
+	slot: FormatContext['slot'],
+	onceKey: string | undefined,
+	error: unknown,
+): void {
+	const key = `${slot}:${onceKey ?? 'default'}`;
+	if (warnedFormatters.has(key)) {
+		return;
+	}
+	warnedFormatters.add(key);
+	const reason = error instanceof Error ? error.message : 'unknown error';
+	console.warn(
+		`[rn-chart] A supplied "${slot}" formatter threw (${reason}). ` +
+			'Falling back to the built-in default for that label. ' +
+			'This warning appears once per formatter slot and never in production builds.',
+	);
+}
+
+/** Test-only reset so warning-once behaviour can be asserted repeatedly. */
+export function __resetFormatterWarnings(): void {
+	warnedFormatters.clear();
+}
+
+export function seriesRef<M>(series: Series<M>): SeriesRef {
+	return { id: series.id, label: series.label };
+}

package/src/contract/interaction.ts

@@ -0,0 +1,71 @@
+/**
+ * Interaction contract (FR-048 to FR-054a).
+ *
+ * The package reports what the user touched and does nothing else: no
+ * navigation, no fetching, no datasource mutation, no business rules.
+ *
+ * Selection is **uncontrolled by default and controlled when the app supplies a
+ * value** — the standard React pattern. The same callbacks fire either way, so
+ * a consumer can move between the two without rewriting handlers.
+ */
+import type { Position } from './datasource';
+import type { ValueState } from './value';
+
+export interface SelectionRef {
+	readonly seriesId: string;
+	/** Absent for a whole-series selection. */
+	readonly pointId?: string;
+}
+
+export interface PointInteractionEvent<M = unknown> {
+	readonly type: 'pointSelect' | 'segmentPress';
+	readonly seriesId: string;
+	readonly pointId: string;
+	readonly value: ValueState;
+	readonly position: Position;
+	readonly metadata?: M;
+}
+
+export interface SeriesInteractionEvent<M = unknown> {
+	readonly type: 'seriesSelect' | 'visibilityChange';
+	readonly seriesId: string;
+	readonly visible?: boolean;
+	readonly metadata?: M;
+}
+
+export type ChartInteractionEvent<M = unknown> =
+	| PointInteractionEvent<M>
+	| SeriesInteractionEvent<M>;
+
+export interface InteractionProps<M = unknown> {
+	/**
+	 * Omit for uncontrolled selection. Supply — including `null` — to take
+	 * ownership; the chart then renders exactly what this says.
+	 */
+	readonly selection?: SelectionRef | null;
+	readonly onSelectionChange?: (
+		next: SelectionRef | null,
+		event: PointInteractionEvent<M> | null,
+	) => void;
+	/**
+	 * Fires when an app-controlled selection no longer resolves against the
+	 * current datasource, so the app can correct its own state rather than
+	 * having the package silently ignore it.
+	 */
+	readonly onSelectionUnresolvable?: (ref: SelectionRef) => void;
+	/** Omit for uncontrolled visibility. Supply to take ownership. */
+	readonly hiddenSeriesIds?: readonly string[];
+	readonly onVisibilityChange?: (event: SeriesInteractionEvent<M>) => void;
+	/** Series toggling stays off unless the app opts in (FR-049). */
+	readonly seriesToggleEnabled?: boolean;
+}
+
+export function sameSelection(
+	a: SelectionRef | null | undefined,
+	b: SelectionRef | null | undefined,
+): boolean {
+	if (!a || !b) {
+		return !a && !b;
+	}
+	return a.seriesId === b.seriesId && a.pointId === b.pointId;
+}

package/src/contract/marker.ts

@@ -0,0 +1,75 @@
+/**
+ * Reference markers: targets, baselines, and thresholds (FR-008, FR-021, FR-022).
+ *
+ * The important rule lives here: a marker whose value is not `known`, or whose
+ * target is zero or negative, produces **no completion proportion**. A chart
+ * shows the current value alone rather than inventing a percentage.
+ */
+import type { FormatHint } from './format';
+import { isKnown, type ValueState } from './value';
+
+export type MarkerKind = 'target' | 'baseline' | 'threshold';
+
+export interface ReferenceMarker {
+	readonly id: string;
+	readonly kind: MarkerKind;
+	readonly value: ValueState;
+	readonly label?: string;
+	readonly format?: FormatHint;
+}
+
+/**
+ * A target only supports a proportion when it is known and strictly positive.
+ * Zero and negative targets make "percent complete" meaningless, so we decline
+ * to compute one rather than divide and produce a nonsense figure.
+ */
+export function isUsableTarget(marker: ReferenceMarker | undefined): boolean {
+	if (!marker || marker.kind !== 'target') {
+		return false;
+	}
+	return isKnown(marker.value) && marker.value.value > 0;
+}
+
+export interface ProgressReading {
+	/** The current value, when known. */
+	readonly current: ValueState;
+	/** The target, when one was supplied. */
+	readonly target?: ReferenceMarker;
+	/**
+	 * Completion as a ratio of current to target. `undefined` whenever no
+	 * proportion can honestly be computed — this is never defaulted to 0 or 1.
+	 */
+	readonly proportion?: number;
+	/** True when the current value exceeds the target: shown, never clamped. */
+	readonly overshoot: boolean;
+}
+
+export function readProgress(
+	current: ValueState,
+	target: ReferenceMarker | undefined,
+): ProgressReading {
+	if (!isKnown(current) || !isUsableTarget(target) || !target) {
+		return { current, target, proportion: undefined, overshoot: false };
+	}
+
+	// isUsableTarget already proved the target is known and positive.
+	const targetValue = (target.value as { value: number }).value;
+	const proportion = current.value / targetValue;
+
+	return {
+		current,
+		target,
+		proportion,
+		overshoot: proportion > 1,
+	};
+}
+
+export function findTarget(
+	markers: readonly ReferenceMarker[] | undefined,
+	id?: string,
+): ReferenceMarker | undefined {
+	if (!markers) {
+		return undefined;
+	}
+	return markers.find(m => m.kind === 'target' && (!id || m.id === id));
+}

package/src/contract/props.ts

@@ -0,0 +1,60 @@
+/**
+ * Props shared by every chart family.
+ *
+ * See specs/007-rn-chart-package/contracts/public-api.md §2 for the contract
+ * behind each field.
+ */
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import type { ChartDatasource } from './datasource';
+import type { ChartFailureHandler } from './errors';
+import type { ChartFormatters, FormatContext } from './format';
+import type { InteractionProps } from './interaction';
+import type { ChartStateContent, DeclarableChartStatus } from './state';
+import type { ChartTheme } from './theme';
+import type { ValueState } from './value';
+
+export interface ChartAccessibility<M = unknown> {
+	/** Replaces the composed summary entirely. */
+	readonly label?: string;
+	readonly summaryFormatter?: (
+		datasource: ChartDatasource<M>,
+		ctx: FormatContext,
+	) => string;
+	/** Defaults to true when `onSelectionChange` is supplied. */
+	readonly interactive?: boolean;
+}
+
+export interface BaseChartProps<M = unknown> extends InteractionProps<M> {
+	/**
+	 * Must be referentially stable across renders, or memoization is defeated.
+	 * Hold it in state or a memo rather than building it inline.
+	 */
+	readonly datasource: ChartDatasource<M>;
+
+	/**
+	 * `empty` and `partial` are derived from the data and are not accepted here
+	 * (FR-036).
+	 */
+	readonly status?: DeclarableChartStatus;
+	readonly stateContent?: ChartStateContent;
+
+	readonly chartId?: string;
+	readonly onFailure?: ChartFailureHandler;
+
+	readonly theme?: ChartTheme;
+	readonly formatters?: ChartFormatters;
+	readonly title?: string;
+	readonly legend?: boolean | { readonly position: 'top' | 'bottom' };
+
+	readonly accessibility?: ChartAccessibility<M>;
+
+	/** Width always comes from the container. */
+	readonly height?: number;
+	readonly style?: StyleProp<ViewStyle>;
+	/** Rendered below the plot, inside the chart's own bounds. */
+	readonly footer?: ReactNode;
+}
+
+export type ValueFormatter = (value: ValueState) => string;