@chipmobilesdk/rn-chart 0.1.0

package/src/contract/state.ts

@@ -0,0 +1,94 @@
+/**
+ * Chart status contract (FR-029 to FR-038).
+ *
+ * Ownership is split on a simple principle: the package derives what only the
+ * data can determine, and the app declares what only the app can know.
+ *
+ *   empty, partial     -> derived from the datasource
+ *   loading, stale,    -> declared by the app: it alone knows about its own
+ *   noPermission,         fetches, cache age, access rules, and failures
+ *   error
+ */
+import type { ReactNode } from 'react';
+
+import type { ChartError } from './errors';
+
+export type ChartStatus =
+	| 'loading'
+	| 'empty'
+	| 'ready'
+	| 'error'
+	| 'stale'
+	| 'noPermission'
+	| 'partial';
+
+/** The statuses an app may declare. `empty` and `partial` are derived. */
+export type DeclarableChartStatus = Exclude<ChartStatus, 'empty' | 'partial'>;
+
+/**
+ * Resolution precedence, highest first.
+ *
+ * `noPermission` outranks everything so restricted values can never slip
+ * through some other state. `stale` and `partial` sit below the blocking
+ * states because they are modifiers on a chart that still draws its data.
+ */
+export const STATUS_PRECEDENCE: readonly ChartStatus[] = [
+	'noPermission',
+	'error',
+	'loading',
+	'empty',
+	'stale',
+	'partial',
+	'ready',
+];
+
+export interface StatusInputs {
+	/** What the app declared, if anything. */
+	readonly declared?: DeclarableChartStatus;
+	/** True when the datasource carries no points at all. */
+	readonly isEmpty: boolean;
+	/** True when some points are valid and others are unknown/n-a/withheld. */
+	readonly isPartial: boolean;
+	/** A validation failure or a contained render exception. */
+	readonly error?: ChartError;
+}
+
+export function resolveStatus(inputs: StatusInputs): ChartStatus {
+	const candidates = new Set<ChartStatus>(['ready']);
+
+	if (inputs.declared) {
+		candidates.add(inputs.declared);
+	}
+	if (inputs.error) {
+		candidates.add('error');
+	}
+	if (inputs.isEmpty) {
+		candidates.add('empty');
+	}
+	if (inputs.isPartial) {
+		candidates.add('partial');
+	}
+
+	for (const status of STATUS_PRECEDENCE) {
+		if (candidates.has(status)) {
+			return status;
+		}
+	}
+	return 'ready';
+}
+
+/** Statuses in which the chart draws its data (possibly with an indicator). */
+export function drawsData(status: ChartStatus): boolean {
+	return status === 'ready' || status === 'stale' || status === 'partial';
+}
+
+/**
+ * Statuses in which no data-selection callback may fire, because the chart is
+ * not displaying the values a callback would carry (FR-053).
+ */
+export function suppressesInteraction(status: ChartStatus): boolean {
+	return !drawsData(status);
+}
+
+/** Per-status content the app supplies, replacing any package wording (FR-035). */
+export type ChartStateContent = Partial<Record<ChartStatus, ReactNode>>;

package/src/contract/theme.ts

@@ -0,0 +1,139 @@
+/**
+ * Theme contract (FR-060 to FR-065).
+ *
+ * A plain value type rather than a dependency. The package declares what it
+ * needs and any design system can satisfy it — which is what keeps
+ * `@chipmobilesdk/rn-theme` and `react-native-unistyles` out of this package's
+ * dependency list entirely. The demo app owns the mapping adapter.
+ *
+ * Non-colour encodings are first-class here, because meaning must never ride on
+ * hue alone (FR-064).
+ */
+import type { ValueKind } from './value';
+
+export interface TextStyleTokens {
+	readonly fontSize: number;
+	readonly fontWeight?: '400' | '500' | '600' | '700';
+	readonly color: string;
+	readonly letterSpacing?: number;
+}
+
+/** How the three non-value classes are drawn: texture, never a hue difference. */
+export type NonValueTexture = 'gap' | 'hatch' | 'lockedHatch';
+
+export interface ChartTheme {
+	readonly colorScheme: 'light' | 'dark';
+	/** Categorical fallback, at least 8 entries, distinguishable in greyscale. */
+	readonly palette: readonly string[];
+	readonly surface: string;
+	readonly onSurface: string;
+	readonly axis: string;
+	readonly grid: string;
+	readonly muted: string;
+	readonly typography: {
+		readonly axisLabel: TextStyleTokens;
+		readonly legendLabel: TextStyleTokens;
+		readonly valueLabel: TextStyleTokens;
+	};
+	readonly spacing: {
+		readonly xs: number;
+		readonly sm: number;
+		readonly md: number;
+	};
+	readonly radius: {
+		readonly bar: number;
+		readonly cell: number;
+	};
+	readonly nonValue: Readonly<
+		Record<Exclude<ValueKind, 'known'>, NonValueTexture>
+	>;
+	/** Ramp for heatmap intensity, low to high. */
+	readonly heatmapRamp: readonly string[];
+}
+
+export interface LegendEntry {
+	readonly seriesId: string;
+	readonly label: string;
+	readonly color: string;
+	readonly pattern: 'solid' | 'dashed' | 'dotted' | 'dashDot';
+	readonly visible: boolean;
+	readonly toggleable: boolean;
+}
+
+/**
+ * Eight categorical colours per scheme.
+ *
+ * Chosen for separation in hue *and* lightness, so they stay distinguishable
+ * under both common colour-vision deficiencies and a greyscale review. Colour
+ * is never the only carrier of meaning regardless — series also differ by
+ * legend label and, for lines, by dash pattern.
+ */
+const LIGHT_PALETTE: readonly string[] = [
+	'#2563EB',
+	'#D97706',
+	'#059669',
+	'#DB2777',
+	'#7C3AED',
+	'#0891B2',
+	'#B45309',
+	'#4B5563',
+];
+
+const DARK_PALETTE: readonly string[] = [
+	'#60A5FA',
+	'#FBBF24',
+	'#34D399',
+	'#F472B6',
+	'#A78BFA',
+	'#22D3EE',
+	'#FCD34D',
+	'#9CA3AF',
+];
+
+const NON_VALUE_TEXTURES = {
+	unknown: 'gap',
+	notApplicable: 'hatch',
+	withheld: 'lockedHatch',
+} as const;
+
+export function defaultChartTheme(
+	colorScheme: 'light' | 'dark' = 'light',
+): ChartTheme {
+	const dark = colorScheme === 'dark';
+
+	const onSurface = dark ? '#F3F4F6' : '#111827';
+	const muted = dark ? '#9CA3AF' : '#6B7280';
+
+	return {
+		colorScheme,
+		palette: dark ? DARK_PALETTE : LIGHT_PALETTE,
+		surface: dark ? '#111827' : '#FFFFFF',
+		onSurface,
+		axis: dark ? '#4B5563' : '#D1D5DB',
+		grid: dark ? '#374151' : '#E5E7EB',
+		muted,
+		typography: {
+			axisLabel: { fontSize: 11, fontWeight: '400', color: muted },
+			legendLabel: { fontSize: 12, fontWeight: '500', color: onSurface },
+			valueLabel: { fontSize: 13, fontWeight: '600', color: onSurface },
+		},
+		spacing: { xs: 4, sm: 8, md: 16 },
+		radius: { bar: 3, cell: 2 },
+		nonValue: NON_VALUE_TEXTURES,
+		heatmapRamp: dark
+			? ['#1F2937', '#1E3A8A', '#1D4ED8', '#3B82F6', '#93C5FD']
+			: ['#EFF6FF', '#BFDBFE', '#60A5FA', '#2563EB', '#1E3A8A'],
+	};
+}
+
+/**
+ * Assigns a colour to a series: explicit override wins, otherwise the palette
+ * cycles by index so the remaining series stay distinguishable (FR-062, FR-063).
+ */
+export function resolveSeriesColor(
+	theme: ChartTheme,
+	index: number,
+	override?: string,
+): string {
+	return override ?? theme.palette[index % theme.palette.length];
+}

package/src/contract/value.ts

@@ -0,0 +1,125 @@
+/**
+ * Value semantics for @chipmobilesdk/rn-chart.
+ *
+ * The foundation of the whole contract. Four value classes, carried as a
+ * discriminated union with **no numeric field on the three non-value cases**.
+ *
+ * That shape is deliberate: with a nullable `number`, `value ?? 0` would
+ * compile, and turning a gap into a zero is the single most damaging thing a
+ * charting library can do to someone's data. Here there is simply no number to
+ * read unless the value is known.
+ *
+ * See specs/007-rn-chart-package/data-model.md §1 (FR-011, FR-012).
+ */
+
+/** A real observation, including a genuine `0`. */
+export interface KnownValue {
+	readonly kind: 'known';
+	readonly value: number;
+}
+
+/** We do not know this value. Never rendered as zero, never interpolated. */
+export interface UnknownValue {
+	readonly kind: 'unknown';
+}
+
+/** This value does not apply here. Excluded from totals and proportions. */
+export interface NotApplicableValue {
+	readonly kind: 'notApplicable';
+}
+
+/** Hidden from this viewer: permission, or not enough data to disclose. */
+export interface WithheldValue {
+	readonly kind: 'withheld';
+}
+
+export type ValueState =
+	| KnownValue
+	| UnknownValue
+	| NotApplicableValue
+	| WithheldValue;
+
+export type ValueKind = ValueState['kind'];
+
+const UNKNOWN: UnknownValue = { kind: 'unknown' };
+const NOT_APPLICABLE: NotApplicableValue = { kind: 'notApplicable' };
+const WITHHELD: WithheldValue = { kind: 'withheld' };
+
+export function known(value: number): KnownValue {
+	return { kind: 'known', value };
+}
+
+/**
+ * Note: shadows the `unknown` *type* keyword in value position only. TypeScript
+ * keeps type and value namespaces separate, so `x: unknown` still means the
+ * type even in modules that import this helper.
+ */
+export function unknown(): UnknownValue {
+	return UNKNOWN;
+}
+
+export function notApplicable(): NotApplicableValue {
+	return NOT_APPLICABLE;
+}
+
+export function withheld(): WithheldValue {
+	return WITHHELD;
+}
+
+export function isKnown(v: ValueState): v is KnownValue {
+	return v.kind === 'known';
+}
+
+/**
+ * True when the value must never reach a rendering, a label, a summary, or an
+ * interaction callback (FR-033, FR-053). Withheld values carry no number at
+ * all, so this is about intent rather than data hiding.
+ */
+export function isWithheld(v: ValueState): v is WithheldValue {
+	return v.kind === 'withheld';
+}
+
+/**
+ * True when the point takes part in totals, proportions, and axis domains.
+ * `notApplicable` and `withheld` are excluded; excluding either makes a total
+ * incomplete (FR-013).
+ */
+export function participatesInTotals(v: ValueState): boolean {
+	return v.kind === 'known';
+}
+
+export interface TotalResult {
+	readonly total: number;
+	/** True when any point was excluded, so the total is not the whole picture. */
+	readonly incomplete: boolean;
+	readonly countedPoints: number;
+	readonly excludedPoints: number;
+}
+
+/**
+ * Sums known values and reports whether anything was left out (FR-013).
+ *
+ * `unknown` also excludes and marks the total incomplete: we cannot claim a sum
+ * is complete when part of the data is missing.
+ */
+export function sumKnown(values: readonly ValueState[]): TotalResult {
+	let total = 0;
+	let counted = 0;
+	let excluded = 0;
+
+	for (const v of values) {
+		if (v.kind === 'known') {
+			total += v.value;
+			counted += 1;
+		} else {
+			excluded += 1;
+		}
+	}
+
+	return {
+		total,
+		incomplete: excluded > 0,
+		countedPoints: counted,
+		excludedPoints: excluded,
+	};
+}

package/src/geometry/bar.ts

@@ -0,0 +1,256 @@
+/**
+ * Bar geometry: one batched path per series, grouped or stacked.
+ *
+ * Bars measure length from zero, so the domain always includes it — otherwise
+ * a bar's length means nothing. Negative values place the baseline correctly
+ * rather than clamping to the plot floor.
+ *
+ * PURE. No React, no SVG.
+ */
+import type { ChartDatasource, Position, Series } from '../contract/datasource';
+import { isKnown, isWithheld } from '../contract/value';
+import type { HitRegion } from './hitTest';
+import { plotBottom, plotRight } from './layout';
+import { rectBatchPath, type RectSpec } from './path';
+import { bandScale, domainFrom, linearScale } from './scale';
+import { thinTicks, type Tick } from './ticks';
+import type { GeometryInput, MarkPath, ResolvedGeometry } from './types';
+
+export type BarGrouping = 'grouped' | 'stacked';
+
+export interface BarOptions {
+	readonly grouping?: BarGrouping;
+	readonly radius?: number;
+}
+
+/**
+ * Bars accept both category and instant positions — that dual acceptance is
+ * what makes swapping a time-series chart for a bar chart free. Both collapse
+ * to a string key for the band scale.
+ */
+function categoryKey(position: Position): string {
+	switch (position.kind) {
+		case 'category':
+			return position.category;
+		case 'instant':
+			return String(position.at);
+		default:
+			return '';
+	}
+}
+
+function countExcluded<M>(datasource: ChartDatasource<M>): number {
+	let excluded = 0;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (!isKnown(point.value)) {
+				excluded += 1;
+			}
+		}
+	}
+	return excluded;
+}
+
+function groupedDomainValues<M>(datasource: ChartDatasource<M>): number[] {
+	const values: number[] = [];
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (isKnown(point.value)) {
+				values.push(point.value.value);
+			}
+		}
+	}
+	return values;
+}
+
+/**
+ * A stacked axis must fit the stack totals, not the individual values.
+ * Positive and negative parts accumulate separately so a stack straddling zero
+ * still fits.
+ */
+function stackedDomainValues<M>(
+	categories: readonly string[],
+	visible: readonly Series<M>[],
+): number[] {
+	const values: number[] = [];
+
+	for (const category of categories) {
+		let positive = 0;
+		let negative = 0;
+
+		for (const series of visible) {
+			const point = series.points.find(
+				p => categoryKey(p.position) === category,
+			);
+			if (point && isKnown(point.value)) {
+				if (point.value.value >= 0) {
+					positive += point.value.value;
+				} else {
+					negative += point.value.value;
+				}
+			}
+		}
+		values.push(positive, negative);
+	}
+
+	return values;
+}
+
+function groupedBarX(
+	bandStart: number,
+	bandWidth: number,
+	seriesIndex: number,
+	seriesCount: number,
+): { barX: number; barWidth: number } {
+	const barWidth = bandWidth / Math.max(seriesCount, 1);
+	return { barX: bandStart + seriesIndex * barWidth, barWidth };
+}
+
+/** Grows from the zero baseline, upward or downward as the sign requires. */
+function groupedBarY(
+	value: number,
+	zeroY: number,
+	project: (v: number) => number,
+): { top: number; height: number } {
+	const valueY = project(value);
+	return { top: Math.min(zeroY, valueY), height: Math.abs(valueY - zeroY) };
+}
+
+/** Grows from wherever the running stack for this sign currently ends. */
+function stackedBarY(
+	value: number,
+	category: string,
+	stack: Map<string, number>,
+	project: (v: number) => number,
+): { top: number; height: number } {
+	const base = stack.get(category) ?? 0;
+	const from = project(base);
+	const to = project(base + value);
+	stack.set(category, base + value);
+	return { top: Math.min(from, to), height: Math.abs(to - from) };
+}
+
+export function buildBarGeometry<M>(
+	datasource: ChartDatasource<M>,
+	input: GeometryInput,
+	options: BarOptions = {},
+): ResolvedGeometry {
+	const { plot } = input;
+	const grouping: BarGrouping = options.grouping ?? 'grouped';
+
+	// Preserve first-seen order rather than sorting: the app chose this order.
+	const categories: string[] = [];
+	const seen = new Set<string>();
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			const key = categoryKey(point.position);
+			if (key && !seen.has(key)) {
+				seen.add(key);
+				categories.push(key);
+			}
+		}
+	}
+
+	const visible = datasource.series.filter(s => !s.hidden);
+	const excluded = countExcluded(datasource);
+	const values =
+		grouping === 'stacked'
+			? stackedDomainValues(categories, visible)
+			: groupedDomainValues(datasource);
+
+	const xBand = bandScale(categories, { min: plot.x, max: plotRight(plot) }, 0.25);
+	const y = linearScale(
+		domainFrom(values, { includeZero: true, padFraction: 0.05 }),
+		{ min: plotBottom(plot), max: plot.y },
+	);
+	const zeroY = y.project(0);
+
+	const paths: MarkPath[] = [];
+	const hitRegions: HitRegion[] = [];
+
+	// Running stack offsets, tracked separately per sign so negative bars grow
+	// downward from zero while positive bars grow upward.
+	const stackUp = new Map<string, number>();
+	const stackDown = new Map<string, number>();
+
+	visible.forEach((series, seriesIndex) => {
+		const rects: RectSpec[] = [];
+
+		for (const point of series.points) {
+			const category = categoryKey(point.position);
+			const bandStart = xBand.project(category);
+			if (bandStart === undefined || !isKnown(point.value)) {
+				continue;
+			}
+
+			const value = point.value.value;
+
+			const { barX, barWidth } =
+				grouping === 'grouped'
+					? groupedBarX(bandStart, xBand.bandWidth, seriesIndex, visible.length)
+					: { barX: bandStart, barWidth: xBand.bandWidth };
+
+			const stack = value >= 0 ? stackUp : stackDown;
+			const { top, height } =
+				grouping === 'stacked'
+					? stackedBarY(value, category, stack, y.project)
+					: groupedBarY(value, zeroY, y.project);
+
+			rects.push({
+				x: barX,
+				y: top,
+				width: barWidth,
+				height,
+				radius: options.radius,
+			});
+
+			hitRegions.push({
+				seriesId: series.id,
+				pointId: point.id,
+				x: barX + barWidth / 2,
+				y: top + height / 2,
+				bounds: { x: barX, y: top, width: barWidth, height },
+				selectable: !isWithheld(point.value),
+			});
+		}
+
+		if (rects.length > 0) {
+			paths.push({
+				key: `bars-${series.id}`,
+				seriesId: series.id,
+				d: rectBatchPath(rects),
+				color: input.seriesColors[series.id],
+				pattern: series.pattern ?? 'solid',
+				filled: true,
+			});
+		}
+	});
+
+	const xTicks: Tick[] = categories.map(c => ({
+		value: 0,
+		position: xBand.centerOf(c) ?? plot.x,
+		label:
+			datasource.positionKind === 'instant'
+				? input.formatInstant(Number(c))
+				: input.formatCategory(c),
+	}));
+
+	const yTicks: Tick[] = [y.domain.min, 0, y.domain.max]
+		.filter((v, i, arr) => arr.indexOf(v) === i)
+		.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,
+	};
+}