@chipmobilesdk/rn-chart 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @chipmobilesdk/rn-chart
 
+## 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

@@ -285,6 +285,16 @@ 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' }} />
+```
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-chart",
-	"version": "0.2.1",
+	"version": "0.3.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/src/a11y/summary.ts

@@ -11,27 +11,30 @@
 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, 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,
 };
 
@@ -42,11 +45,14 @@ export interface SummaryInput<M = unknown> {
 	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;
@@ -76,19 +82,23 @@ function describeExtremes<M>(
 	if (!min || !max) {
 		return '';
 	}
+	const maxText = formatValue({ kind: 'known', value: max.value });
 	if (min.label === max.label) {
-		return `Value ${formatValue({ kind: 'known', value: max.value })}.`;
+		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 +110,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 +125,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 +141,17 @@ 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),
+		describeMarkers(input.datasource.markers, input.formatValue, strings),
+		input.incomplete ? strings['chart.summary.incomplete'] : '',
 	];
 
 	return parts.filter(Boolean).join(' ').replace(/\s+/g, ' ').trim();
@@ -145,26 +163,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/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/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;

package/src/contract/strings.ts

@@ -0,0 +1,48 @@
+/**
+ * Every text the package itself speaks or shows (CHT-05): screen-reader
+ * summaries and announcements, adjustable-action labels, built-in state text and
+ * legend hints. English defaults; an app translates them by passing `strings`
+ * (or by registering `chartStrings.user` with rn-i18n and passing the translated
+ * texts). `{name}` marks a variable.
+ */
+import { defineMessages } from '@chipmobilesdk/rn-core';
+
+export const chartStrings = defineMessages({
+	user: {
+		'chart.family.progress': 'progress chart',
+		'chart.family.distribution': 'distribution chart',
+		'chart.family.timeSeries': 'time series chart',
+		'chart.family.bar': 'bar chart',
+		'chart.family.heatmap': 'heatmap',
+		'chart.status.loading': 'Loading data.',
+		'chart.status.empty': 'No data yet.',
+		'chart.status.error': 'Data could not be shown.',
+		'chart.status.stale': 'Showing data that may be out of date.',
+		'chart.status.noPermission': 'This data is not available to you.',
+		'chart.status.partial': 'Some data is missing.',
+		'chart.summary.heading': '{title}, {noun}.',
+		'chart.summary.headingUntitled': '{noun}.',
+		'chart.summary.scale': '{series} series, {points} points.',
+		'chart.summary.scaleSingle': '{points} points.',
+		'chart.summary.single': 'Value {value}.',
+		'chart.summary.extremes': 'Highest {maxLabel} at {max}. Lowest {minLabel} at {min}.',
+		'chart.summary.marker': '{name} {value}',
+		'chart.summary.incomplete': 'Some values are missing, so totals are incomplete.',
+		'chart.point.withheld': '{position}, {series}, not available.',
+		'chart.point.noData': '{position}, {series}, no data.',
+		'chart.point.value': '{position}, {series}, {value}.',
+		'chart.total': 'Total {value}.',
+		'chart.total.incomplete': 'Total {value}, excluding {count} values that are not available.',
+		'chart.action.next': 'Next data point',
+		'chart.action.previous': 'Previous data point',
+		'chart.state.loading': 'Loading…',
+		'chart.state.empty': 'No data yet',
+		'chart.state.error': 'Unable to show this chart',
+		'chart.state.noPermission': 'Not available',
+		'chart.legend.hide': 'Hides this series',
+		'chart.legend.show': 'Shows this series',
+	},
+});
+
+export type ChartStrings = typeof chartStrings.defaults;
+export type ChartStringKey = keyof ChartStrings;

package/src/index.ts

@@ -156,3 +156,7 @@ export { ChartThemeProvider, useChartTheme } from './react/ChartThemeProvider';
 // Accessibility helpers
 // ---------------------------------------------------------------------------
 export { buildChartSummary, buildPointAnnouncement, buildTotalAnnouncement } from './a11y/summary';
+
+// The package's own texts, for translation (CHT-05).
+export { chartStrings } from './contract/strings';
+export type { ChartStringKey, ChartStrings } from './contract/strings';

package/src/react/ChartBoundary.tsx

@@ -69,7 +69,7 @@ export class ChartBoundary extends React.Component<Props, State> {
 		return { error: chartError('render', 'renderException') };
 	}
 
-	componentDidCatch(error: unknown, info: { componentStack?: string }): void {
+	override componentDidCatch(error: unknown, info: { componentStack?: string }): void {
 		const report = toFailureReport(
 			this.props.family,
 			error,
@@ -87,7 +87,7 @@ export class ChartBoundary extends React.Component<Props, State> {
 		this.props.onFailure?.(report);
 	}
 
-	render(): React.ReactNode {
+	override render(): React.ReactNode {
 		if (this.state.error) {
 			return this.props.renderFallback(this.state.error);
 		}

package/src/react/ChartFrame.tsx

@@ -28,6 +28,7 @@ import { EMPTY_GEOMETRY } from '../geometry/types';
 import { releaseBudgetWarning, warnIfOverBudget } from '../validation/budgets';
 import { validateDatasource } from '../validation/validateDatasource';
 import { buildChartSummary, buildPointAnnouncement } from '../a11y/summary';
+import { chartStrings, type ChartStrings } from '../contract/strings';
 import { Grid, XAxis, YAxis } from '../render/Axis';
 import {
 	GeometryLabels,
@@ -59,6 +60,7 @@ const DEFAULT_HEIGHT = 220;
 export function ChartFrame<M>(props: ChartFrameProps<M>) {
 	const family = props.family;
 	const theme = useChartTheme(props.theme);
+	const strings = useMemo(() => chartStrings.resolve(props.strings), [props.strings]);
 	const generatedId = useId();
 	const instanceKey = props.chartId ?? generatedId;
 
@@ -296,6 +298,11 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 		if (props.accessibility?.label) {
 			return props.accessibility.label;
 		}
+		// The app's own composer, when given (CHT-04): it was declared and never used.
+		const custom = props.accessibility?.summaryFormatter;
+		if (custom) {
+			return custom(props.datasource, { slot: 'summary', hint: props.datasource.format });
+		}
 		return buildChartSummary({
 			datasource: props.datasource,
 			family: props.family,
@@ -303,8 +310,10 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 			title: props.title,
 			formatValue,
 			incomplete: geometry.incomplete || validation.totalIncomplete,
+			strings,
 		});
 	}, [
+		strings,
 		props.accessibility,
 		props.datasource,
 		props.family,
@@ -346,7 +355,7 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 		}
 		// Minimal built-in wording, deliberately terse. Apps are expected to
 		// supply their own copy — the package must not impose product voice.
-		const fallback = builtInStateText(status, currentError);
+		const fallback = builtInStateText(status, strings, currentError);
 		if (!fallback) {
 			return null;
 		}
@@ -435,6 +444,7 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 					entries={legendEntries}
 					theme={theme}
 					onToggle={visibility.enabled ? visibility.toggle : undefined}
+					strings={strings}
 				/>
 			) : null}
 
@@ -450,6 +460,7 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 									formatPositionDefault(selectedPoint.point.position),
 									selectedPoint.point.value,
 									formatValue,
+									strings,
 								),
 							}
 						: undefined
@@ -457,8 +468,8 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 				accessibilityActions={
 					interactive
 						? [
-								{ name: 'increment', label: 'Next data point' },
-								{ name: 'decrement', label: 'Previous data point' },
+								{ name: 'increment', label: strings['chart.action.next'] },
+								{ name: 'decrement', label: strings['chart.action.previous'] },
 							]
 						: undefined
 				}
@@ -472,6 +483,7 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 					entries={legendEntries}
 					theme={theme}
 					onToggle={visibility.enabled ? visibility.toggle : undefined}
+					strings={strings}
 				/>
 			) : null}
 
@@ -537,17 +549,18 @@ export function ChartFrame<M>(props: ChartFrameProps<M>) {
 
 function builtInStateText(
 	status: ReturnType<typeof resolveStatus>,
+	strings: ChartStrings,
 	error?: ChartError,
 ): string | undefined {
 	switch (status) {
 		case 'loading':
-			return 'Loading…';
+			return strings['chart.state.loading'];
 		case 'empty':
-			return 'No data yet';
+			return strings['chart.state.empty'];
 		case 'error':
-			return error?.message ?? 'Unable to show this chart';
+			return error?.message ?? strings['chart.state.error'];
 		case 'noPermission':
-			return 'Not available';
+			return strings['chart.state.noPermission'];
 		default:
 			return undefined;
 	}

package/src/react/ChartLegend.tsx

@@ -6,6 +6,7 @@
  * carries a dash pattern as well as a colour, so series stay distinguishable
  * without colour perception.
  */
+import { chartStrings, type ChartStrings } from '../contract/strings';
 import React from 'react';
 import { Pressable, StyleSheet, Text, View } from 'react-native';
 
@@ -117,10 +118,12 @@ export function ChartLegend({
 	entries,
 	theme,
 	onToggle,
+	strings = chartStrings.defaults,
 }: {
 	readonly entries: readonly LegendEntry[];
 	readonly theme: ChartTheme;
 	readonly onToggle?: (seriesId: string) => void;
+	readonly strings?: ChartStrings;
 }) {
 	if (entries.length === 0) {
 		return null;
@@ -162,7 +165,9 @@ export function ChartLegend({
 						accessibilityRole="switch"
 						accessibilityState={{ checked: entry.visible }}
 						accessibilityLabel={entry.label}
-						accessibilityHint={entry.visible ? 'Hides this series' : 'Shows this series'}
+						accessibilityHint={
+							entry.visible ? strings['chart.legend.hide'] : strings['chart.legend.show']
+						}
 						style={[styles.entry, styles.tappable]}
 					>
 						{content}

package/src/validation/budgets.ts

@@ -14,6 +14,8 @@
  * specs/007-rn-chart-package/research.md R2 — element count scales with series,
  * not with points, so these budgets are about JS work rather than view count.
  */
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
 import type { ChartDatasource, ChartFamily } from '../contract/datasource';
 
 export interface DatasetBudget {
@@ -63,6 +65,9 @@ export function checkBudget<M>(datasource: ChartDatasource<M>, family: ChartFami
 
 const warnedCharts = new Set<string>();
 
+/** Chart diagnostics also reach the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<'over_budget'>('rn-chart');
+
 /**
  * Warns once per chart instance per mount. De-duplicating matters: a scrolling
  * dashboard would otherwise flood the console on every frame.
@@ -76,6 +81,11 @@ export function warnIfOverBudget<M>(
 
 	if (__DEV__ && !check.withinBudget && !warnedCharts.has(instanceKey)) {
 		warnedCharts.add(instanceKey);
+		channel.emit('over_budget', 'warn', {
+			family,
+			series: check.seriesCount,
+			maxPoints: check.maxPointsInAnySeries,
+		});
 		const budget = DATASET_BUDGETS[family];
 		console.warn(
 			`[rn-chart] ${family} chart "${instanceKey}" exceeds its documented dataset budget ` +