@chipmobilesdk/rn-chart 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @chipmobilesdk/rn-chart
 
+## 0.4.0
+
+### Minor Changes
+
+- Props and formatters that were declared but never read now have an effect. `formatters.legendLabel` labels legend entries, `formatters.summary` words the values a screen reader hears, and `theme.radius` rounds bars and heatmap cells. `accessibility.summaryFormatter` already worked; `ProgressChart.orientation`, which did nothing, is gone, and the `segmentPress` and `seriesSelect` event kinds, which were never emitted, are gone from the interaction types. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Tapping the selected point again clears the selection and now reports `(null, null)` instead of the point the chart just stopped highlighting. Screen-reader stepping moves the selection rather than toggling it, so a chart with one point stays on that point. A screen reader hears a position in the app's own words through `formatters.axisLabel` rather than a raw epoch number, and the summary names the highest and lowest points by when or where they are — a single time series used to report one value and lose its lowest.
+
+  Values are checked rather than guessed at. `NaN` or `Infinity` in a known value or an instant is a `nonFiniteValue` validation error instead of a mark drawn at the origin, and a negative distribution segment is a `negativeDistributionValue` one. `DistributionChart` takes `valuesAre` to say whether its numbers are proportions or absolute amounts; inference no longer reads two counts of 1 as two full circles. A donut or pie segment is hit by the angle and radius under the finger, so the edge of a large segment selects that segment.
+
+  `HeatmapChart` draws the names of its rows and columns, and a key to its colours — the lowest and highest value with the ramp between them, as one accessible element. `ColorScaleLegend` and `ColorScale` are exported for apps that lay it out themselves. Bar charts label their value axis in round steps and put instant categories in time order, as the time-series chart does.
+
+### Patch Changes
+
+- Charts keep their memoization under the way apps actually write props. `formatters` and `TimeSeriesChart`'s `range` are compared by what they carry rather than by object identity, so writing either inline no longer rebuilds every scale and path string on each parent render. The hidden-series set, the selection callbacks and the legend toggle keep one identity, the drawn geometry is memoized apart from the selection so highlighting a point no longer reconciles the whole SVG tree, and the dataset budget is measured only in development builds. Text size is read reactively, so changing the system font size re-lays-out the chart immediately. ([#19](https://github.com/operationd8979/chip-mobile-sdk/pull/19))
+
+  Internally, the chart shell is split into `useChartStatus`, `useChartFormatters`, `useChartA11y`, `ChartPlot` and `ChartStateOverlay` instead of one 600-line component; the budget warning runs in an effect rather than during render; and the bar, time-series and heatmap builders each make one pass over their points where they made several.
+
+## 0.3.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- Every package's own copy is an rn-core message catalog that an app can translate. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-i18n: new `runtimeEntriesFromCatalog(catalog)` registers any SDK catalog in one
+    line, converting `{name}` variables to `{{name}}`.
+  - rn-ai: new `messageKeyForError(error)` gives the copy for every error code, and
+    `aiMessageSet`. The input placeholder default is neutral ("Type a message…"), and
+    two keys were added for errors that had none (`ai.error.signIn`, `ai.error.generic`).
+  - rn-auth: new `authMessages`, the catalog split into user and developer copy.
+  - rn-payment: new `paymentMessages`.
+  - rn-chart: summaries, announcements, adjustable-action labels, built-in state text
+    and legend hints come from `chartStrings`; pass `strings` to translate them. The
+    `accessibility.summaryFormatter` prop, declared before, now replaces the summary.
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -150,6 +150,11 @@ Axis labels have room reserved for them: the plot shrinks to fit the widest
 value label on the left and one line of time or category labels below, so no
 label is clipped by the chart's edge.
 
+Every known value, and every instant, must be a **finite number**. `NaN` or
+`Infinity` is a validation error (`nonFiniteValue`) rather than a mark drawn at
+the origin: data that arrived broken is reported as broken. Use `unknown()` for
+a value you do not have.
+
 ## States
 
 Seven, and the package derives the two that only the data can determine:
@@ -212,6 +217,12 @@ ownership; the same callbacks fire either way.
 Every payload carries the point id, series id, value, position, and whatever
 metadata you attached. The package never navigates, fetches, or mutates.
 
+Tapping the selected point again clears the selection, and the callback is told
+so: `(null, null)`. Empty space clears it the same way. Screen-reader stepping
+moves the selection rather than toggling it, so a chart with one point stays on
+that point. A donut or pie is hit by the segment the finger is in — its angle
+and radius — not by distance to its label.
+
 Legends can also toggle series visibility. The state is uncontrolled unless
 you supply `hiddenSeriesIds`:
 
@@ -252,6 +263,18 @@ correctly in light and dark.
 Meaning never rides on colour alone: series carry dash patterns as well as
 colours, and non-value classes use textures.
 
+`DistributionChart` reads its numbers either as **proportions** (each in 0..1,
+summing to 1) or as **absolute** amounts it normalises by their own total. It
+infers which from the data, and a short sum of proportions is drawn short and
+reported incomplete rather than stretched to fill the circle. Two counts of `1`
+are ambiguous, so say what you mean when counts can be small:
+
+```tsx
+<DistributionChart datasource={ds} valuesAre="absolute" />
+```
+
+A negative segment is a validation error: a share of a whole cannot be negative.
+
 `DistributionChart` colours **segments**, not series. Palette entries are taken
 in order across every point, so one series of four points and four series of
 one point both give four colours. A point's own `color` overrides its segment;
@@ -275,6 +298,18 @@ default applies — the package never infers or converts a business unit. A
 formatter that throws degrades to the default **for that one label** and does
 not crash the screen.
 
+Four slots: `value` (drawn labels), `axisLabel` (axis ticks, and how a position
+is spoken to a screen reader), `legendLabel` (legend entries) and `summary` (the
+values inside the accessible summary; falls back to `value`).
+
+The `formatters` object itself may be written inline — the chart depends on the
+functions it carries, not on the object. The **functions** must be stable:
+define them at module scope or hold them in `useCallback`/`useMemo`, as with
+`datasource`. A formatter rebuilt every render rebuilds every scale and path
+string, which is the one thing `FR-073` exists to prevent. The same goes for
+`range` on `TimeSeriesChart`, which is compared by its `from` and `to`, so
+`range={{ from, to }}` inline is free.
+
 ## Accessibility
 
 Each chart is a single accessible element with a composed summary: what it is,
@@ -285,6 +320,21 @@ points — the same access touch gives.
 Non-ready charts announce their state rather than reading out figures they are
 not showing. Accessibility props you supply are never overridden.
 
+Everything the package says or shows itself (summaries, point announcements, the
+adjustable actions, built-in state text, legend hints) comes from `chartStrings`,
+with English defaults. Pass `strings` to speak the app's language; any key you
+leave out keeps its default. `accessibility.summaryFormatter` replaces the composed
+summary entirely, and `accessibility.label` replaces everything.
+
+```tsx
+<BarChart datasource={steps} title="Bước" strings={{ 'chart.family.bar': 'biểu đồ cột' }} />
+```
+
+`HeatmapChart` names its rows and columns along the edges of the plot and shows
+the key to its colours — the lowest and highest value with the ramp between them
+— below it, as one accessible element. Pass `legend={false}` to leave the key
+out.
+
 Axis labels are thinned to fit rather than overlapped, and scale with the system
 text size up to **1.6×**; beyond that the growth is capped so the plot area
 survives.
@@ -299,8 +349,9 @@ survives.
 | Progress | 8 metrics |
 | Heatmap | 1,000 cells |
 
-Over budget, a chart **still renders and drops nothing**. It warns once per
-chart in development builds, and never in production. Aggregating or
+Over budget, a chart **still renders and drops nothing**: nothing is enforced
+and nothing is refused. It warns once per chart in development builds, and in
+production the dataset is not even measured. Aggregating or
 downsampling above these sizes is your call — the package will not silently
 decide what data to discard.
 
@@ -349,6 +400,7 @@ The single entrypoint exports these public groups:
   `STATUS_PRECEDENCE`, `DATASET_BUDGETS`, `checkBudget`, error/failure types,
   and `isChartError`
 - Interaction: selection and series interaction types plus `sameSelection`
+- Heatmap colour key: `ColorScaleLegend` and `ColorScale`
 - Theme and formatting: `defaultChartTheme`, `resolveSeriesColor`, default
   formatter helpers, `NON_VALUE_TEXT`, and public theme/formatter contracts
 - Accessibility: `buildChartSummary`, `buildPointAnnouncement`, and

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-chart",
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -26,9 +26,12 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
+		"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",

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

@@ -18,18 +18,36 @@ accessibility support and enforced dataset budgets.
 - 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
+- A chart is slower than expected, or a dataset is larger than its budget
+- A formatter or a prop appears to have no effect
 
 ## 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 are a development warning, not a limit
 
-`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`.
+Nothing is enforced and nothing is refused: over budget a chart **still renders and
+drops nothing**, warns once per chart in development, and in production does not even
+measure the dataset. `DATASET_BUDGETS` and `checkBudget` are the figures and the check,
+for a consumer that wants to aggregate or window its own data. Do not debug a "chart
+refuses to render": no such behaviour exists. See `## Dataset budgets`.
+
+## Memoization has two requirements
+
+`datasource` must be referentially stable, and so must each **formatter function**
+(module scope, or `useCallback`). The `formatters` object itself may be inline, as may
+`range={{ from, to }}` — those are compared by what they carry. An unstable datasource
+or formatter rebuilds every scale and path string on each parent render.
+
+## What the numbers mean, where it is ambiguous
+
+`DistributionChart` reads values as proportions (0..1, summing to 1) or as absolute
+amounts, inferred from the data. Pass `valuesAre="absolute" | "proportions"` when counts
+could be read as shares (two counts of `1`). Known values and instants must be finite:
+`NaN` is a `nonFiniteValue` validation error, and a negative distribution segment is a
+`negativeDistributionValue` one. Use `unknown()` for data you do not have.
 
 ## Chart theming is separate from app theming
 
@@ -38,18 +56,35 @@ Charts use `ChartThemeProvider` / `useChartTheme`, not the app-wide theme provid
 
 ## Public API
 
-Runtime:
+Components — all five families are memoized, and all share `BaseChartProps`
+(`datasource`, `status`, `stateContent`, `title`, `legend`, `theme`, `formatters`,
+`strings`, `accessibility`, `height`, `style`, `footer`, selection and visibility
+props):
 
-- `ChartThemeProvider`, `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
-- `ChartLegend`, `buildLegendEntries`
-- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
-- `DATASET_BUDGETS`, `checkBudget`
-- `isChartError`
+- `BarChart` (`grouping`), `TimeSeriesChart` (`range`), `DistributionChart` (`shape`,
+  `innerRadiusRatio`, `valuesAre`), `ProgressChart`, `HeatmapChart` (`buckets`)
+- `ChartLegend`, `ColorScaleLegend`, `buildLegendEntries`, `ChartThemeProvider`
 
-Types: `MarkerKind`, `ProgressReading`, `ReferenceMarker`, `BudgetCheck`, `DatasetBudget`
+Runtime:
 
-Use `sameSelection` for selection equality — comparing selection objects by reference
-causes redundant re-renders.
+- `known`, `unknown`, `notApplicable`, `withheld`, `isKnown`, `isWithheld`, `sumKnown`,
+  `participatesInTotals`
+- `useChartTheme`, `defaultChartTheme`, `resolveSeriesColor`
+- `findTarget`, `isUsableTarget`, `readProgress`, `sameSelection`
+- `resolveStatus`, `drawsData`, `suppressesInteraction`, `STATUS_PRECEDENCE`
+- `formatValueDefault`, `formatPositionDefault`, `formatLegendDefault`, `seriesRef`,
+  `NON_VALUE_TEXT`
+- `buildChartSummary`, `buildPointAnnouncement`, `buildTotalAnnouncement`
+- `DATASET_BUDGETS`, `checkBudget`, `isChartError`, `chartStrings`
+- `FAMILY_POSITION_KINDS`, `familyAcceptsPositionKind`, `resolveFormat`, `resolveUnit`
+
+Types: `ValueState`, `ChartDatasource`, `Series`, `DataPoint`, `Position`, `ChartFamily`,
+`ChartStatus`, `ChartError`, `SelectionRef`, `PointInteractionEvent`, `ChartFormatters`,
+`ChartTheme`, `LegendEntry`, `ColorScale`, `DistributionValues`, `ChartStrings`,
+`BudgetCheck`, `DatasetBudget`
+
+Use `sameSelection` to compare two selections; comparing the objects by reference
+reports a change that did not happen.
 
 ## Where the detail lives
 

package/src/a11y/summary.ts

@@ -8,30 +8,34 @@
  * 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 { ChartDatasource, ChartFamily, Position } from '../contract/datasource';
+import { formatPositionDefault } from '../contract/format';
 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, string> = {
-	progress: 'progress chart',
-	distribution: 'distribution chart',
-	timeSeries: 'time series chart',
-	bar: 'bar chart',
-	heatmap: 'heatmap',
+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, 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.',
+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,
 };
 
@@ -41,15 +45,23 @@ export interface SummaryInput<M = unknown> {
 	readonly status: ChartStatus;
 	readonly title?: string;
 	readonly formatValue: (value: ValueState) => string;
+	/** How a position is spoken; the app's axis formatter when it has one. */
+	readonly formatPosition?: (position: Position) => 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,
+	formatPosition: (position: Position) => string,
 ): string {
-	let min: { label: string; value: number } | undefined;
-	let max: { label: string; value: number } | undefined;
+	type Extreme = { label: () => string; value: number; point: unknown };
+	let min: Extreme | undefined;
+	let max: Extreme | undefined;
+	const several = datasource.series.length > 1;
 
 	for (const series of datasource.series) {
 		for (const point of series.points) {
@@ -57,18 +69,25 @@ function describeExtremes<M>(
 			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;
+			// Named by where the point is. A time series used to name both
+			// extremes after the series, so a one-series chart reported a single
+			// value and lost its lowest (CHT-07). Built lazily: only two are read.
+			const label = (): string => {
+				if (point.position.kind === 'category') {
+					return point.position.category;
+				}
+				if (point.position.kind === 'matrix') {
+					return `${point.position.row} ${point.position.column}`;
+				}
+				const at = formatPosition(point.position);
+				return several ? `${series.label} ${at}` : at;
+			};
 
 			if (!min || point.value.value < min.value) {
-				min = { label, value: point.value.value };
+				min = { label, value: point.value.value, point };
 			}
 			if (!max || point.value.value > max.value) {
-				max = { label, value: point.value.value };
+				max = { label, value: point.value.value, point };
 			}
 		}
 	}
@@ -76,19 +95,24 @@ function describeExtremes<M>(
 	if (!min || !max) {
 		return '';
 	}
-	if (min.label === max.label) {
-		return `Value ${formatValue({ kind: 'known', value: max.value })}.`;
+	const maxText = formatValue({ kind: 'known', value: max.value });
+	// One figure only when the highest and the lowest are the same point.
+	if (min.point === max.point) {
+		return formatMessage(strings['chart.summary.single'], { value: maxText });
 	}
 
-	return (
-		`Highest ${max.label} at ${formatValue({ kind: 'known', value: max.value })}. ` +
-		`Lowest ${min.label} at ${formatValue({ kind: 'known', value: min.value })}.`
-	);
+	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 '';
@@ -100,7 +124,9 @@ function describeMarkers(
 			continue;
 		}
 		const name = marker.label ?? marker.kind;
-		parts.push(`${name} ${formatValue(marker.value)}`);
+		parts.push(
+			formatMessage(strings['chart.summary.marker'], { name, value: formatValue(marker.value) }),
+		);
 	}
 
 	return parts.length > 0 ? `${parts.join('. ')}.` : '';
@@ -113,10 +139,14 @@ function describeMarkers(
  * 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];
+	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();
 	}
@@ -125,15 +155,22 @@ export function buildChartSummary<M>(input: SummaryInput<M>): string {
 	const pointCount = input.datasource.series.reduce((acc, s) => acc + s.points.length, 0);
 
 	const scale =
-		seriesCount > 1 ? `${seriesCount} series, ${pointCount} points.` : `${pointCount} points.`;
+		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),
-		describeMarkers(input.datasource.markers, input.formatValue),
-		input.incomplete ? 'Some values are missing, so totals are incomplete.' : '',
+		describeExtremes(
+			input.datasource,
+			input.formatValue,
+			strings,
+			input.formatPosition ?? formatPositionDefault,
+		),
+		describeMarkers(input.datasource.markers, input.formatValue, strings),
+		input.incomplete ? strings['chart.summary.incomplete'] : '',
 	];
 
 	return parts.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
@@ -145,26 +182,28 @@ export function buildPointAnnouncement(
 	positionLabel: string,
 	value: ValueState,
 	formatValue: (v: ValueState) => string,
+	strings: ChartStrings = chartStrings.defaults,
 ): string {
+	const vars = { position: positionLabel, series: seriesLabel };
 	if (value.kind === 'withheld') {
-		return `${positionLabel}, ${seriesLabel}, not available.`;
+		return formatMessage(strings['chart.point.withheld'], vars);
 	}
 	if (!isKnown(value)) {
-		return `${positionLabel}, ${seriesLabel}, no data.`;
+		return formatMessage(strings['chart.point.noData'], vars);
 	}
-	return `${positionLabel}, ${seriesLabel}, ${formatValue(value)}.`;
+	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 text = `Total ${formatValue({ kind: 'known', value: total.total })}`;
+	const value = formatValue({ kind: 'known', value: total.total });
 	return total.incomplete
-		? `${text}, excluding ${total.excludedPoints} values that are not available.`
-		: `${text}.`;
+		? formatMessage(strings['chart.total.incomplete'], { value, count: total.excludedPoints })
+		: formatMessage(strings['chart.total'], { value });
 }

package/src/contract/distribution.ts

@@ -0,0 +1,44 @@
+/**
+ * What the numbers of a distribution mean (CHT-10).
+ *
+ * `proportions`: each value is already a share of the whole, in 0..1. A sum
+ * short of 1 is drawn short and reported incomplete. `absolute`: counts or
+ * amounts, normalised by their own total.
+ *
+ * Until 0.4.0 this was guessed from the values alone: anything in 0..1 was a
+ * proportion, so two segments counting 1 each drew two full circles on top of
+ * one another. The guess now also requires the shares to fit in one whole, and
+ * an app that knows can say so.
+ */
+import type { ChartDatasource } from './datasource';
+import { isKnown } from './value';
+
+export type DistributionValues = 'proportions' | 'absolute';
+
+export const DISTRIBUTION_SUM_TOLERANCE = 0.001;
+
+export function resolveDistributionValues<M>(
+	datasource: ChartDatasource<M>,
+	declared?: DistributionValues,
+): DistributionValues {
+	if (declared !== undefined) {
+		return declared;
+	}
+	if (datasource.format?.kind === 'percent') {
+		return 'proportions';
+	}
+	let sum = 0;
+	for (const series of datasource.series) {
+		for (const point of series.points) {
+			if (!isKnown(point.value)) {
+				continue;
+			}
+			const value = point.value.value;
+			if (value < 0 || value > 1) {
+				return 'absolute';
+			}
+			sum += value;
+		}
+	}
+	return sum <= 1 + DISTRIBUTION_SUM_TOLERANCE ? 'proportions' : 'absolute';
+}

package/src/contract/errors.ts

@@ -18,6 +18,8 @@ export type ChartErrorCode =
 	| 'familyPositionKindUnsupported'
 	| 'inconsistentMatrix'
 	| 'distributionNotWhole'
+	| 'nonFiniteValue'
+	| 'negativeDistributionValue'
 	| 'declaredByApp'
 	| 'renderException';
 
@@ -34,6 +36,10 @@ const MESSAGES: Readonly<Record<ChartErrorCode, string>> = {
 	inconsistentMatrix: 'Matrix datasource rows and columns are inconsistent across points.',
 	distributionNotWhole:
 		'Distribution segments do not sum to the whole. The chart marks the total incomplete rather than rescaling.',
+	nonFiniteValue:
+		'A known value or an instant is not a finite number. Use an unknown value for missing data.',
+	negativeDistributionValue:
+		'A distribution segment has a negative value. A share of a whole cannot be negative.',
 	declaredByApp: 'The application declared this chart to be in an error state.',
 	renderException:
 		'The chart failed while rendering and was contained. See the report for details.',

package/src/contract/format.ts

@@ -5,9 +5,14 @@
  * applies a documented locale-neutral default, and uses app-supplied formatter
  * output verbatim whenever one is given.
  */
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
 import type { Position, Series } from './datasource';
 import { isKnown, type ValueState } from './value';
 
+/** Chart diagnostics also reach the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<'formatter_threw'>('rn-chart');
+
 export type FormatHint =
 	| { readonly kind: 'number'; readonly decimals?: number }
 	| { readonly kind: 'percent'; readonly decimals?: number }
@@ -144,6 +149,7 @@ function warnFormatterFailureOnce(
 		return;
 	}
 	warnedFormatters.add(key);
+	channel.emit('formatter_threw', 'warn', { slot });
 	const reason = error instanceof Error ? error.message : 'unknown error';
 	console.warn(
 		`[rn-chart] A supplied "${slot}" formatter threw (${reason}). ` +

package/src/contract/interaction.ts

@@ -18,7 +18,7 @@ export interface SelectionRef {
 }
 
 export interface PointInteractionEvent<M = unknown> {
-	readonly type: 'pointSelect' | 'segmentPress';
+	readonly type: 'pointSelect';
 	readonly seriesId: string;
 	readonly pointId: string;
 	readonly value: ValueState;
@@ -27,7 +27,7 @@ export interface PointInteractionEvent<M = unknown> {
 }
 
 export interface SeriesInteractionEvent<M = unknown> {
-	readonly type: 'seriesSelect' | 'visibilityChange';
+	readonly type: 'visibilityChange';
 	readonly seriesId: string;
 	readonly visible?: boolean;
 	readonly metadata?: M;

package/src/contract/props.ts

@@ -4,6 +4,7 @@
  * See specs/007-rn-chart-package/contracts/public-api.md §2 for the contract
  * behind each field.
  */
+import type { ChartStrings } from './strings';
 import type { ReactNode } from 'react';
 import type { StyleProp, ViewStyle } from 'react-native';
 
@@ -46,6 +47,12 @@ export interface BaseChartProps<M = unknown> extends InteractionProps<M> {
 	readonly legend?: boolean | { readonly position: 'top' | 'bottom' };
 
 	readonly accessibility?: ChartAccessibility<M>;
+	/**
+	 * The package's own texts in the app's language: summaries, announcements,
+	 * action labels, built-in state text, legend hints (`chartStrings` holds the
+	 * keys and English defaults).
+	 */
+	readonly strings?: Partial<ChartStrings>;
 
 	/** Width always comes from the container. */
 	readonly height?: number;