@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

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;
+}

package/src/contract/value.ts

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