@chipmobilesdk/rn-chart 0.2.0 → 0.2.1

package/src/contract/format.ts

@@ -1,168 +1,162 @@
-/**
- * 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 };
-}
+/**
+ * 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

@@ -1,71 +1,70 @@
-/**
- * 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;
-}
+/**
+ * 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

@@ -1,75 +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));
-}
+/**
+ * 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));
+}