@chipmobilesdk/rn-chart 0.2.0 → 0.2.1

package/src/contract/datasource.ts

@@ -1,136 +1,126 @@
-/**
- * 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;
-	/** Colour of this point's segment in a distribution chart. Ignored elsewhere. */
-	readonly color?: string;
-	/** 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;
-}
+/**
+ * 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;
+	/** Colour of this point's segment in a distribution chart. Ignored elsewhere. */
+	readonly color?: string;
+	/** 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

@@ -1,133 +1,129 @@
-/**
- * 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}`;
-}
+/**
+ * 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}`;
+}