@chipmobilesdk/rn-chart 0.2.0 → 0.2.1

package/src/contract/props.ts

@@ -1,60 +1,57 @@
-/**
- * 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;
+/**
+ * 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;

package/src/contract/state.ts

@@ -1,94 +1,88 @@
-/**
- * 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>>;
+/**
+ * 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

@@ -1,177 +1,169 @@
-/**
- * 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;
-	/** Set on distribution entries, which describe one segment rather than a series. */
-	readonly pointId?: 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];
-}
-
-/** Key of one distribution segment: point ids are only unique within a series. */
-export function segmentKey(seriesId: string, pointId: string): string {
-	return `${seriesId}/${pointId}`;
-}
-
-/**
- * Colours for distribution segments, keyed by `segmentKey`. The single source
- * for both the arcs and the legend, so the two cannot disagree (CHT-02).
- *
- * Segments take palette entries in order across the whole datasource, so one
- * series of four points and four series of one point both give four colours.
- * A point's own `color` wins; a series with a single point is that segment, so
- * the series `color` applies to it.
- */
-export function resolveSegmentColors(
-	datasource: {
-		readonly series: readonly {
-			readonly id: string;
-			readonly color?: string;
-			readonly points: readonly { readonly id: string; readonly color?: string }[];
-		}[];
-	},
-	theme: ChartTheme,
-): Record<string, string> {
-	const colors: Record<string, string> = {};
-	let index = 0;
-	for (const series of datasource.series) {
-		for (const point of series.points) {
-			const override = point.color ?? (series.points.length === 1 ? series.color : undefined);
-			colors[segmentKey(series.id, point.id)] = resolveSeriesColor(theme, index, override);
-			index += 1;
-		}
-	}
-	return colors;
-}
+/**
+ * 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;
+	/** Set on distribution entries, which describe one segment rather than a series. */
+	readonly pointId?: 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];
+}
+
+/** Key of one distribution segment: point ids are only unique within a series. */
+export function segmentKey(seriesId: string, pointId: string): string {
+	return `${seriesId}/${pointId}`;
+}
+
+/**
+ * Colours for distribution segments, keyed by `segmentKey`. The single source
+ * for both the arcs and the legend, so the two cannot disagree (CHT-02).
+ *
+ * Segments take palette entries in order across the whole datasource, so one
+ * series of four points and four series of one point both give four colours.
+ * A point's own `color` wins; a series with a single point is that segment, so
+ * the series `color` applies to it.
+ */
+export function resolveSegmentColors(
+	datasource: {
+		readonly series: readonly {
+			readonly id: string;
+			readonly color?: string;
+			readonly points: readonly { readonly id: string; readonly color?: string }[];
+		}[];
+	},
+	theme: ChartTheme,
+): Record<string, string> {
+	const colors: Record<string, string> = {};
+	let index = 0;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			const override = point.color ?? (series.points.length === 1 ? series.color : undefined);
+			colors[segmentKey(series.id, point.id)] = resolveSeriesColor(theme, index, override);
+			index += 1;
+		}
+	}
+	return colors;
+}