@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/package.json

@@ -1,49 +1,49 @@
-{
-	"name": "@chipmobilesdk/rn-chart",
-	"version": "0.2.0",
-	"private": false,
-	"license": "UNLICENSED",
-	"main": "src/index.ts",
-	"types": "src/index.ts",
-	"exports": {
-		".": {
-			"types": "./src/index.ts",
-			"react-native": "./src/index.ts",
-			"default": "./src/index.ts"
-		}
-	},
-	"files": [
-		"src/index.ts",
-		"src/a11y",
-		"src/contract",
-		"src/geometry",
-		"src/react",
-		"src/render",
-		"src/validation",
-		"skills",
-		"README.md",
-		"CHANGELOG.md"
-	],
-	"sideEffects": false,
-	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
-	},
-	"peerDependencies": {
-		"react": ">=19",
-		"react-native": ">=0.85",
-		"react-native-svg": ">=15.15"
-	},
-	"peerDependenciesMeta": {
-		"react-native-svg": {
-			"optional": false
-		}
-	},
-	"engines": {
-		"node": ">=22.11.0"
-	},
-	"publishConfig": {
-		"access": "public",
-		"registry": "https://registry.npmjs.org/"
-	}
-}
+{
+	"name": "@chipmobilesdk/rn-chart",
+	"version": "0.3.0",
+	"private": false,
+	"license": "UNLICENSED",
+	"main": "src/index.ts",
+	"types": "src/index.ts",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"react-native": "./src/index.ts",
+			"default": "./src/index.ts"
+		}
+	},
+	"files": [
+		"src/index.ts",
+		"src/a11y",
+		"src/contract",
+		"src/geometry",
+		"src/react",
+		"src/render",
+		"src/validation",
+		"skills",
+		"README.md",
+		"CHANGELOG.md"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+		"pack:check": "npm pack --dry-run"
+	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
+	},
+	"peerDependencies": {
+		"react": ">=19",
+		"react-native": ">=0.85",
+		"react-native-svg": ">=15.15"
+	},
+	"peerDependenciesMeta": {
+		"react-native-svg": {
+			"optional": false
+		}
+	},
+	"publishConfig": {
+		"access": "public",
+		"registry": "https://registry.npmjs.org/"
+	}
+}

package/skills/sdk-rn-chart/SKILL.md

@@ -1,69 +1,68 @@
----
-name: sdk-rn-chart
-description: "Charts via @chipmobilesdk/rn-chart: datasource contract, series theming, legends, selection, dataset budgets, chart accessibility. Use when rendering a chart, wiring chart data, theming series, or hitting a dataset size limit."
-metadata:
-  package: "@chipmobilesdk/rn-chart"
-  packageVersion: "0.1.0"
-user-invocable: true
-disable-model-invocation: false
----
-
-# @chipmobilesdk/rn-chart
-
-Chart rendering with an explicit datasource contract, its own theme provider,
-accessibility support and enforced dataset budgets.
-
-## Use this when
-
-- Rendering any chart or adding a series
-- Shaping data to the datasource contract
-- Theming series colors or building a legend
-- Handling selection / interaction on a chart
-- A chart refuses to render a large dataset
-
-## Check what it deliberately does not do
-
-The README opens with `## What it does not do`. Read that first — it prevents building
-a feature this package intentionally excludes.
-
-## Datasets are budgeted
-
-`DATASET_BUDGETS` and `checkBudget` enforce size limits so charts stay at 60 FPS on
-low-end devices. When a budget is exceeded, aggregate or window the data — do not raise
-the budget. See `## Dataset budgets`.
-
-## Chart theming is separate from app theming
-
-Charts use `ChartThemeProvider` / `useChartTheme`, not the app-wide theme provider from
-`sdk-rn-theme`. Series colors come from `resolveSeriesColor`, never from hardcoded values.
-
-## Public API (v0.2.0)
-
-Runtime:
-
-- `ChartThemeProvider`, `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
-- `ChartLegend`, `buildLegendEntries`
-- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
-- `DATASET_BUDGETS`, `checkBudget`
-- `isChartError`
-
-Types: `MarkerKind`, `ProgressReading`, `ReferenceMarker`, `BudgetCheck`, `DatasetBudget`
-
-Use `sameSelection` for selection equality — comparing selection objects by reference
-causes redundant re-renders.
-
-## Where the detail lives
-
-Read one section of `node_modules/@chipmobilesdk/rn-chart/README.md` (~360 lines):
-
-| Need | Section |
-|---|---|
-| Scope check | `## What it does not do` |
-| First integration | `## Install`, `## Quick start` |
-| Shaping data | `## The datasource contract`, `## Value semantics` |
-| Loading/empty/error rendering | `## States` |
-| Touch and selection | `## Interaction` |
-| Colors and legends | `## Theming` |
-| Axis/label formatting | `## Formatting` |
-| Screen reader support | `## Accessibility` |
-| Size limits | `## Dataset budgets` |
+---
+name: sdk-rn-chart
+description: "Charts via @chipmobilesdk/rn-chart: datasource contract, series theming, legends, selection, dataset budgets, chart accessibility. Use when rendering a chart, wiring chart data, theming series, or hitting a dataset size limit."
+metadata:
+  package: "@chipmobilesdk/rn-chart"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# @chipmobilesdk/rn-chart
+
+Chart rendering with an explicit datasource contract, its own theme provider,
+accessibility support and enforced dataset budgets.
+
+## Use this when
+
+- Rendering any chart or adding a series
+- Shaping data to the datasource contract
+- Theming series colors or building a legend
+- Handling selection / interaction on a chart
+- A chart refuses to render a large dataset
+
+## Check what it deliberately does not do
+
+The README opens with `## What it does not do`. Read that first — it prevents building
+a feature this package intentionally excludes.
+
+## Datasets are budgeted
+
+`DATASET_BUDGETS` and `checkBudget` enforce size limits so charts stay at 60 FPS on
+low-end devices. When a budget is exceeded, aggregate or window the data — do not raise
+the budget. See `## Dataset budgets`.
+
+## Chart theming is separate from app theming
+
+Charts use `ChartThemeProvider` / `useChartTheme`, not the app-wide theme provider from
+`sdk-rn-theme`. Series colors come from `resolveSeriesColor`, never from hardcoded values.
+
+## Public API
+
+Runtime:
+
+- `ChartThemeProvider`, `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
+- `ChartLegend`, `buildLegendEntries`
+- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
+- `DATASET_BUDGETS`, `checkBudget`
+- `isChartError`
+
+Types: `MarkerKind`, `ProgressReading`, `ReferenceMarker`, `BudgetCheck`, `DatasetBudget`
+
+Use `sameSelection` for selection equality — comparing selection objects by reference
+causes redundant re-renders.
+
+## Where the detail lives
+
+Read one section of `node_modules/@chipmobilesdk/rn-chart/README.md` (~360 lines):
+
+| Need | Section |
+|---|---|
+| Scope check | `## What it does not do` |
+| First integration | `## Install`, `## Quick start` |
+| Shaping data | `## The datasource contract`, `## Value semantics` |
+| Loading/empty/error rendering | `## States` |
+| Touch and selection | `## Interaction` |
+| Colors and legends | `## Theming` |
+| Axis/label formatting | `## Formatting` |
+| Screen reader support | `## Accessibility` |
+| Size limits | `## Dataset budgets` |

package/src/a11y/summary.ts

@@ -1,177 +1,190 @@
-/**
- * Composed accessible summaries (FR-067, FR-068, FR-069, FR-072).
- *
- * Exposing 2,500 individual points to a screen reader would be unusable even
- * if it were cheap. A composed summary covers the same need: what the chart is,
- * what it shows, where the extremes are, and what any target says.
- *
- * Withheld values never enter a summary — that would leak exactly what the
- * withheld class exists to protect (FR-033).
- */
-import type { ChartDatasource, ChartFamily } from '../contract/datasource';
-import type { ReferenceMarker } from '../contract/marker';
-import type { ChartStatus } from '../contract/state';
-import { isKnown, sumKnown, type ValueState } from '../contract/value';
-
-const FAMILY_NOUN: Record<ChartFamily, string> = {
-	progress: 'progress chart',
-	distribution: 'distribution chart',
-	timeSeries: 'time series chart',
-	bar: 'bar chart',
-	heatmap: 'heatmap',
-};
-
-/**
- * What a screen reader hears when the chart is not showing data. Announcing
- * the state beats silence, and beats announcing a stale value as if current.
- */
-const STATUS_PHRASE: Record<ChartStatus, string | undefined> = {
-	loading: 'Loading data.',
-	empty: 'No data yet.',
-	error: 'Data could not be shown.',
-	stale: 'Showing data that may be out of date.',
-	noPermission: 'This data is not available to you.',
-	partial: 'Some data is missing.',
-	ready: undefined,
-};
-
-export interface SummaryInput<M = unknown> {
-	readonly datasource: ChartDatasource<M>;
-	readonly family: ChartFamily;
-	readonly status: ChartStatus;
-	readonly title?: string;
-	readonly formatValue: (value: ValueState) => string;
-	readonly incomplete?: boolean;
-}
-
-function describeExtremes<M>(
-	datasource: ChartDatasource<M>,
-	formatValue: (v: ValueState) => string,
-): string {
-	let min: { label: string; value: number } | undefined;
-	let max: { label: string; value: number } | undefined;
-
-	for (const series of datasource.series) {
-		for (const point of series.points) {
-			// Withheld and unknown values are skipped entirely.
-			if (!isKnown(point.value)) {
-				continue;
-			}
-			const label =
-				point.position.kind === 'category'
-					? point.position.category
-					: point.position.kind === 'matrix'
-					? `${point.position.row} ${point.position.column}`
-					: series.label;
-
-			if (!min || point.value.value < min.value) {
-				min = { label, value: point.value.value };
-			}
-			if (!max || point.value.value > max.value) {
-				max = { label, value: point.value.value };
-			}
-		}
-	}
-
-	if (!min || !max) {
-		return '';
-	}
-	if (min.label === max.label) {
-		return `Value ${formatValue({ kind: 'known', value: max.value })}.`;
-	}
-
-	return (
-		`Highest ${max.label} at ${formatValue({ kind: 'known', value: max.value })}. ` +
-		`Lowest ${min.label} at ${formatValue({ kind: 'known', value: min.value })}.`
-	);
-}
-
-function describeMarkers(
-	markers: readonly ReferenceMarker[] | undefined,
-	formatValue: (v: ValueState) => string,
-): string {
-	if (!markers || markers.length === 0) {
-		return '';
-	}
-
-	const parts: string[] = [];
-	for (const marker of markers) {
-		if (!isKnown(marker.value)) {
-			continue;
-		}
-		const name = marker.label ?? marker.kind;
-		parts.push(`${name} ${formatValue(marker.value)}`);
-	}
-
-	return parts.length > 0 ? `${parts.join('. ')}.` : '';
-}
-
-/**
- * Builds the label read aloud for the chart as a whole.
- *
- * Non-ready statuses replace the data description rather than appending to it,
- * so a loading chart never announces figures it is not showing.
- */
-export function buildChartSummary<M>(input: SummaryInput<M>): string {
-	const noun = FAMILY_NOUN[input.family];
-	const heading = input.title ? `${input.title}, ${noun}.` : `${noun}.`;
-
-	const statusPhrase = STATUS_PHRASE[input.status];
-	if (input.status !== 'ready' && input.status !== 'partial' && input.status !== 'stale') {
-		return `${heading} ${statusPhrase ?? ''}`.trim();
-	}
-
-	const seriesCount = input.datasource.series.length;
-	const pointCount = input.datasource.series.reduce(
-		(acc, s) => acc + s.points.length,
-		0,
-	);
-
-	const scale =
-		seriesCount > 1
-			? `${seriesCount} series, ${pointCount} points.`
-			: `${pointCount} points.`;
-
-	const parts = [
-		heading,
-		statusPhrase,
-		scale,
-		describeExtremes(input.datasource, input.formatValue),
-		describeMarkers(input.datasource.markers, input.formatValue),
-		input.incomplete
-			? 'Some values are missing, so totals are incomplete.'
-			: '',
-	];
-
-	return parts.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
-}
-
-/** Announced for the currently selected point on an adjustable chart. */
-export function buildPointAnnouncement(
-	seriesLabel: string,
-	positionLabel: string,
-	value: ValueState,
-	formatValue: (v: ValueState) => string,
-): string {
-	if (value.kind === 'withheld') {
-		return `${positionLabel}, ${seriesLabel}, not available.`;
-	}
-	if (!isKnown(value)) {
-		return `${positionLabel}, ${seriesLabel}, no data.`;
-	}
-	return `${positionLabel}, ${seriesLabel}, ${formatValue(value)}.`;
-}
-
-/** Total plus an explicit note when it is not the whole picture (FR-013). */
-export function buildTotalAnnouncement<M>(
-	datasource: ChartDatasource<M>,
-	formatValue: (v: ValueState) => string,
-): string {
-	const values = datasource.series.flatMap(s => s.points.map(p => p.value));
-	const total = sumKnown(values);
-
-	const text = `Total ${formatValue({ kind: 'known', value: total.total })}`;
-	return total.incomplete
-		? `${text}, excluding ${total.excludedPoints} values that are not available.`
-		: `${text}.`;
-}
+/**
+ * Composed accessible summaries (FR-067, FR-068, FR-069, FR-072).
+ *
+ * Exposing 2,500 individual points to a screen reader would be unusable even
+ * if it were cheap. A composed summary covers the same need: what the chart is,
+ * what it shows, where the extremes are, and what any target says.
+ *
+ * Withheld values never enter a summary — that would leak exactly what the
+ * withheld class exists to protect (FR-033).
+ */
+import type { ChartDatasource, ChartFamily } from '../contract/datasource';
+import type { ReferenceMarker } from '../contract/marker';
+import type { ChartStatus } from '../contract/state';
+import { formatMessage } from '@chipmobilesdk/rn-core';
+
+import { chartStrings, type ChartStrings } from '../contract/strings';
+import { isKnown, sumKnown, type ValueState } from '../contract/value';
+
+const FAMILY_NOUN: Record<ChartFamily, keyof ChartStrings> = {
+	progress: 'chart.family.progress',
+	distribution: 'chart.family.distribution',
+	timeSeries: 'chart.family.timeSeries',
+	bar: 'chart.family.bar',
+	heatmap: 'chart.family.heatmap',
+};
+
+/**
+ * What a screen reader hears when the chart is not showing data. Announcing
+ * the state beats silence, and beats announcing a stale value as if current.
+ */
+const STATUS_PHRASE: Record<ChartStatus, keyof ChartStrings | undefined> = {
+	loading: 'chart.status.loading',
+	empty: 'chart.status.empty',
+	error: 'chart.status.error',
+	stale: 'chart.status.stale',
+	noPermission: 'chart.status.noPermission',
+	partial: 'chart.status.partial',
+	ready: undefined,
+};
+
+export interface SummaryInput<M = unknown> {
+	readonly datasource: ChartDatasource<M>;
+	readonly family: ChartFamily;
+	readonly status: ChartStatus;
+	readonly title?: string;
+	readonly formatValue: (value: ValueState) => string;
+	readonly incomplete?: boolean;
+	/** The texts to speak; the English defaults when omitted. */
+	readonly strings?: ChartStrings;
+}
+
+function describeExtremes<M>(
+	datasource: ChartDatasource<M>,
+	formatValue: (v: ValueState) => string,
+	strings: ChartStrings,
+): string {
+	let min: { label: string; value: number } | undefined;
+	let max: { label: string; value: number } | undefined;
+
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			// Withheld and unknown values are skipped entirely.
+			if (!isKnown(point.value)) {
+				continue;
+			}
+			const label =
+				point.position.kind === 'category'
+					? point.position.category
+					: point.position.kind === 'matrix'
+						? `${point.position.row} ${point.position.column}`
+						: series.label;
+
+			if (!min || point.value.value < min.value) {
+				min = { label, value: point.value.value };
+			}
+			if (!max || point.value.value > max.value) {
+				max = { label, value: point.value.value };
+			}
+		}
+	}
+
+	if (!min || !max) {
+		return '';
+	}
+	const maxText = formatValue({ kind: 'known', value: max.value });
+	if (min.label === max.label) {
+		return formatMessage(strings['chart.summary.single'], { value: maxText });
+	}
+
+	return formatMessage(strings['chart.summary.extremes'], {
+		maxLabel: max.label,
+		max: maxText,
+		minLabel: min.label,
+		min: formatValue({ kind: 'known', value: min.value }),
+	});
+}
+
+function describeMarkers(
+	markers: readonly ReferenceMarker[] | undefined,
+	formatValue: (v: ValueState) => string,
+	strings: ChartStrings,
+): string {
+	if (!markers || markers.length === 0) {
+		return '';
+	}
+
+	const parts: string[] = [];
+	for (const marker of markers) {
+		if (!isKnown(marker.value)) {
+			continue;
+		}
+		const name = marker.label ?? marker.kind;
+		parts.push(
+			formatMessage(strings['chart.summary.marker'], { name, value: formatValue(marker.value) }),
+		);
+	}
+
+	return parts.length > 0 ? `${parts.join('. ')}.` : '';
+}
+
+/**
+ * Builds the label read aloud for the chart as a whole.
+ *
+ * Non-ready statuses replace the data description rather than appending to it,
+ * so a loading chart never announces figures it is not showing.
+ */
+export function buildChartSummary<M>(input: SummaryInput<M>): string {
+	const strings = input.strings ?? chartStrings.defaults;
+	const noun = strings[FAMILY_NOUN[input.family]];
+	const heading = input.title
+		? formatMessage(strings['chart.summary.heading'], { title: input.title, noun })
+		: formatMessage(strings['chart.summary.headingUntitled'], { noun });
+
+	const statusKey = STATUS_PHRASE[input.status];
+	const statusPhrase = statusKey ? strings[statusKey] : undefined;
+	if (input.status !== 'ready' && input.status !== 'partial' && input.status !== 'stale') {
+		return `${heading} ${statusPhrase ?? ''}`.trim();
+	}
+
+	const seriesCount = input.datasource.series.length;
+	const pointCount = input.datasource.series.reduce((acc, s) => acc + s.points.length, 0);
+
+	const scale =
+		seriesCount > 1
+			? formatMessage(strings['chart.summary.scale'], { series: seriesCount, points: pointCount })
+			: formatMessage(strings['chart.summary.scaleSingle'], { points: pointCount });
+
+	const parts = [
+		heading,
+		statusPhrase,
+		scale,
+		describeExtremes(input.datasource, input.formatValue, strings),
+		describeMarkers(input.datasource.markers, input.formatValue, strings),
+		input.incomplete ? strings['chart.summary.incomplete'] : '',
+	];
+
+	return parts.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
+}
+
+/** Announced for the currently selected point on an adjustable chart. */
+export function buildPointAnnouncement(
+	seriesLabel: string,
+	positionLabel: string,
+	value: ValueState,
+	formatValue: (v: ValueState) => string,
+	strings: ChartStrings = chartStrings.defaults,
+): string {
+	const vars = { position: positionLabel, series: seriesLabel };
+	if (value.kind === 'withheld') {
+		return formatMessage(strings['chart.point.withheld'], vars);
+	}
+	if (!isKnown(value)) {
+		return formatMessage(strings['chart.point.noData'], vars);
+	}
+	return formatMessage(strings['chart.point.value'], { ...vars, value: formatValue(value) });
+}
+
+/** Total plus an explicit note when it is not the whole picture (FR-013). */
+export function buildTotalAnnouncement<M>(
+	datasource: ChartDatasource<M>,
+	formatValue: (v: ValueState) => string,
+	strings: ChartStrings = chartStrings.defaults,
+): string {
+	const values = datasource.series.flatMap(s => s.points.map(p => p.value));
+	const total = sumKnown(values);
+	const value = formatValue({ kind: 'known', value: total.total });
+	return total.incomplete
+		? formatMessage(strings['chart.total.incomplete'], { value, count: total.excludedPoints })
+		: formatMessage(strings['chart.total'], { value });
+}