@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/index.ts

@@ -1,176 +1,162 @@
-/**
- * @chipmobilesdk/rn-chart — domain-agnostic charting for ChipMobileSdk-family
- * React Native apps.
- *
- * This is the single public entrypoint (LIB-003). Modules under `geometry/`,
- * `render/`, `validation/`, and the internals of `react/` are private; import
- * them only through this file. Keeping them private is what lets the geometry,
- * the layout maths, and the rendering substrate change without a breaking
- * release.
- *
- * The package makes no network request, calls no AI service, reads no
- * database, persists nothing, and logs no data value or series label. It
- * renders numeric data and app-supplied labels — nothing else.
- *
- * There is deliberately **no insight, message, or narrative surface**: apps
- * render their own text around a chart, and a chart imposes no outer margin
- * that would fight that layout.
- */
-
-// ---------------------------------------------------------------------------
-// Value semantics — the foundation of the contract
-// ---------------------------------------------------------------------------
-export type {
-	KnownValue,
-	NotApplicableValue,
-	TotalResult,
-	UnknownValue,
-	ValueKind,
-	ValueState,
-	WithheldValue,
-} from './contract/value';
-export {
-	isKnown,
-	isWithheld,
-	known,
-	notApplicable,
-	participatesInTotals,
-	sumKnown,
-	unknown,
-	withheld,
-} from './contract/value';
-
-// ---------------------------------------------------------------------------
-// Datasource contract
-// ---------------------------------------------------------------------------
-export type {
-	CategoryPosition,
-	ChartDatasource,
-	ChartFamily,
-	DataPoint,
-	InstantPosition,
-	MatrixPosition,
-	Position,
-	PositionKind,
-	Series,
-	SeriesPattern,
-} from './contract/datasource';
-export {
-	FAMILY_POSITION_KINDS,
-	familyAcceptsPositionKind,
-	resolveFormat,
-	resolveUnit,
-} from './contract/datasource';
-
-export type { MarkerKind, ProgressReading, ReferenceMarker } from './contract/marker';
-export { findTarget, isUsableTarget, readProgress } from './contract/marker';
-
-// ---------------------------------------------------------------------------
-// Formatting
-// ---------------------------------------------------------------------------
-export type {
-	ChartFormatters,
-	FormatContext,
-	FormatHint,
-	SeriesRef,
-} from './contract/format';
-export {
-	NON_VALUE_TEXT,
-	formatLegendDefault,
-	formatPositionDefault,
-	formatValueDefault,
-	seriesRef,
-} from './contract/format';
-
-// ---------------------------------------------------------------------------
-// State and errors
-// ---------------------------------------------------------------------------
-export type {
-	ChartStateContent,
-	ChartStatus,
-	DeclarableChartStatus,
-	StatusInputs,
-} from './contract/state';
-export {
-	STATUS_PRECEDENCE,
-	drawsData,
-	resolveStatus,
-	suppressesInteraction,
-} from './contract/state';
-
-export type {
-	ChartError,
-	ChartErrorCategory,
-	ChartErrorCode,
-	ChartFailureHandler,
-	ChartFailureReport,
-} from './contract/errors';
-export { isChartError } from './contract/errors';
-
-// ---------------------------------------------------------------------------
-// Interaction
-// ---------------------------------------------------------------------------
-export type {
-	ChartInteractionEvent,
-	InteractionProps,
-	PointInteractionEvent,
-	SelectionRef,
-	SeriesInteractionEvent,
-} from './contract/interaction';
-export { sameSelection } from './contract/interaction';
-
-// ---------------------------------------------------------------------------
-// Theme
-// ---------------------------------------------------------------------------
-export type {
-	ChartTheme,
-	LegendEntry,
-	NonValueTexture,
-	TextStyleTokens,
-} from './contract/theme';
-export { defaultChartTheme, resolveSeriesColor } from './contract/theme';
-
-// ---------------------------------------------------------------------------
-// Props and accessibility
-// ---------------------------------------------------------------------------
-export type {
-	BaseChartProps,
-	ChartAccessibility,
-	ValueFormatter,
-} from './contract/props';
-
-// ---------------------------------------------------------------------------
-// Dataset budgets
-// ---------------------------------------------------------------------------
-export type { BudgetCheck, DatasetBudget } from './validation/budgets';
-export { DATASET_BUDGETS, checkBudget } from './validation/budgets';
-
-// ---------------------------------------------------------------------------
-// Components
-// ---------------------------------------------------------------------------
-export type {
-	BarChartProps,
-	DistributionChartProps,
-	HeatmapChartProps,
-	ProgressChartProps,
-	TimeSeriesChartProps,
-} from './react/charts';
-export {
-	BarChart,
-	DistributionChart,
-	HeatmapChart,
-	ProgressChart,
-	TimeSeriesChart,
-} from './react/charts';
-
-export { ChartLegend, buildLegendEntries } from './react/ChartLegend';
-export { ChartThemeProvider, useChartTheme } from './react/ChartThemeProvider';
-
-// ---------------------------------------------------------------------------
-// Accessibility helpers
-// ---------------------------------------------------------------------------
-export {
-	buildChartSummary,
-	buildPointAnnouncement,
-	buildTotalAnnouncement,
-} from './a11y/summary';
+/**
+ * @chipmobilesdk/rn-chart — domain-agnostic charting for ChipMobileSdk-family
+ * React Native apps.
+ *
+ * This is the single public entrypoint (LIB-003). Modules under `geometry/`,
+ * `render/`, `validation/`, and the internals of `react/` are private; import
+ * them only through this file. Keeping them private is what lets the geometry,
+ * the layout maths, and the rendering substrate change without a breaking
+ * release.
+ *
+ * The package makes no network request, calls no AI service, reads no
+ * database, persists nothing, and logs no data value or series label. It
+ * renders numeric data and app-supplied labels — nothing else.
+ *
+ * There is deliberately **no insight, message, or narrative surface**: apps
+ * render their own text around a chart, and a chart imposes no outer margin
+ * that would fight that layout.
+ */
+
+// ---------------------------------------------------------------------------
+// Value semantics — the foundation of the contract
+// ---------------------------------------------------------------------------
+export type {
+	KnownValue,
+	NotApplicableValue,
+	TotalResult,
+	UnknownValue,
+	ValueKind,
+	ValueState,
+	WithheldValue,
+} from './contract/value';
+export {
+	isKnown,
+	isWithheld,
+	known,
+	notApplicable,
+	participatesInTotals,
+	sumKnown,
+	unknown,
+	withheld,
+} from './contract/value';
+
+// ---------------------------------------------------------------------------
+// Datasource contract
+// ---------------------------------------------------------------------------
+export type {
+	CategoryPosition,
+	ChartDatasource,
+	ChartFamily,
+	DataPoint,
+	InstantPosition,
+	MatrixPosition,
+	Position,
+	PositionKind,
+	Series,
+	SeriesPattern,
+} from './contract/datasource';
+export {
+	FAMILY_POSITION_KINDS,
+	familyAcceptsPositionKind,
+	resolveFormat,
+	resolveUnit,
+} from './contract/datasource';
+
+export type { MarkerKind, ProgressReading, ReferenceMarker } from './contract/marker';
+export { findTarget, isUsableTarget, readProgress } from './contract/marker';
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+export type { ChartFormatters, FormatContext, FormatHint, SeriesRef } from './contract/format';
+export {
+	NON_VALUE_TEXT,
+	formatLegendDefault,
+	formatPositionDefault,
+	formatValueDefault,
+	seriesRef,
+} from './contract/format';
+
+// ---------------------------------------------------------------------------
+// State and errors
+// ---------------------------------------------------------------------------
+export type {
+	ChartStateContent,
+	ChartStatus,
+	DeclarableChartStatus,
+	StatusInputs,
+} from './contract/state';
+export {
+	STATUS_PRECEDENCE,
+	drawsData,
+	resolveStatus,
+	suppressesInteraction,
+} from './contract/state';
+
+export type {
+	ChartError,
+	ChartErrorCategory,
+	ChartErrorCode,
+	ChartFailureHandler,
+	ChartFailureReport,
+} from './contract/errors';
+export { isChartError } from './contract/errors';
+
+// ---------------------------------------------------------------------------
+// Interaction
+// ---------------------------------------------------------------------------
+export type {
+	ChartInteractionEvent,
+	InteractionProps,
+	PointInteractionEvent,
+	SelectionRef,
+	SeriesInteractionEvent,
+} from './contract/interaction';
+export { sameSelection } from './contract/interaction';
+
+// ---------------------------------------------------------------------------
+// Theme
+// ---------------------------------------------------------------------------
+export type { ChartTheme, LegendEntry, NonValueTexture, TextStyleTokens } from './contract/theme';
+export { defaultChartTheme, resolveSeriesColor } from './contract/theme';
+
+// ---------------------------------------------------------------------------
+// Props and accessibility
+// ---------------------------------------------------------------------------
+export type { BaseChartProps, ChartAccessibility, ValueFormatter } from './contract/props';
+
+// ---------------------------------------------------------------------------
+// Dataset budgets
+// ---------------------------------------------------------------------------
+export type { BudgetCheck, DatasetBudget } from './validation/budgets';
+export { DATASET_BUDGETS, checkBudget } from './validation/budgets';
+
+// ---------------------------------------------------------------------------
+// Components
+// ---------------------------------------------------------------------------
+export type {
+	BarChartProps,
+	DistributionChartProps,
+	HeatmapChartProps,
+	ProgressChartProps,
+	TimeSeriesChartProps,
+} from './react/charts';
+export {
+	BarChart,
+	DistributionChart,
+	HeatmapChart,
+	ProgressChart,
+	TimeSeriesChart,
+} from './react/charts';
+
+export { ChartLegend, buildLegendEntries } from './react/ChartLegend';
+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

@@ -1,96 +1,96 @@
-/**
- * Per-chart render-failure containment (FR-038a, FR-038b).
- *
- * React 19 still has no hook equivalent of an error boundary —
- * `getDerivedStateFromError` and `componentDidCatch` remain class-only — so
- * this is a class. Forty lines beats adding a dependency for it.
- *
- * Three behaviours are deliberate:
- *
- *  - **Reset only on a real change.** The boundary clears its error when the
- *    datasource identity or chart key changes, never on an unrelated parent
- *    re-render. A deterministic geometry defect therefore cannot pin the CPU in
- *    a render-fail-render loop.
- *  - **Report once per distinct failure.** De-duplicated by signature, so a
- *    chart re-rendered by a sibling's state change does not re-report.
- *  - **Redact.** The report carries the chart identity and a catalogue message.
- *    A third-party exception's own text is never copied in, because we cannot
- *    promise it is free of data (POL-011).
- */
-import React from 'react';
-
-import type { ChartFamily } from '../contract/datasource';
-import {
-	chartError,
-	failureSignature,
-	toFailureReport,
-	type ChartError,
-	type ChartFailureHandler,
-} from '../contract/errors';
-
-interface Props {
-	readonly family: ChartFamily;
-	readonly chartId?: string;
-	readonly onFailure?: ChartFailureHandler;
-	/** Changing this clears a contained failure. */
-	readonly resetKey: unknown;
-	readonly renderFallback: (error: ChartError) => React.ReactNode;
-	readonly children: React.ReactNode;
-}
-
-interface State {
-	readonly error?: ChartError;
-	readonly resetKey: unknown;
-	readonly reportedSignature?: string;
-}
-
-export class ChartBoundary extends React.Component<Props, State> {
-	constructor(props: Props) {
-		super(props);
-		this.state = { resetKey: props.resetKey };
-	}
-
-	static getDerivedStateFromProps(props: Props, state: State): State | null {
-		if (props.resetKey !== state.resetKey) {
-			// New data: give the chart another chance.
-			return { resetKey: props.resetKey, error: undefined };
-		}
-		return null;
-	}
-
-	static getDerivedStateFromError(): Partial<State> {
-		// This must set the error, not just acknowledge it. Returning an empty
-		// object leaves render() showing the children again, they throw again,
-		// and React escalates past the boundary — which is exactly the
-		// screen-blanking failure this class exists to prevent.
-		//
-		// componentDidCatch then refines this into a report carrying the chart
-		// identity and family.
-		return { error: chartError('render', 'renderException') };
-	}
-
-	componentDidCatch(error: unknown, info: { componentStack?: string }): void {
-		const report = toFailureReport(
-			this.props.family,
-			error,
-			this.props.chartId,
-			info?.componentStack ?? undefined,
-		);
-
-		const signature = failureSignature(report);
-		if (this.state.reportedSignature === signature) {
-			this.setState({ error: report.error });
-			return;
-		}
-
-		this.setState({ error: report.error, reportedSignature: signature });
-		this.props.onFailure?.(report);
-	}
-
-	render(): React.ReactNode {
-		if (this.state.error) {
-			return this.props.renderFallback(this.state.error);
-		}
-		return this.props.children;
-	}
-}
+/**
+ * Per-chart render-failure containment (FR-038a, FR-038b).
+ *
+ * React 19 still has no hook equivalent of an error boundary —
+ * `getDerivedStateFromError` and `componentDidCatch` remain class-only — so
+ * this is a class. Forty lines beats adding a dependency for it.
+ *
+ * Three behaviours are deliberate:
+ *
+ *  - **Reset only on a real change.** The boundary clears its error when the
+ *    datasource identity or chart key changes, never on an unrelated parent
+ *    re-render. A deterministic geometry defect therefore cannot pin the CPU in
+ *    a render-fail-render loop.
+ *  - **Report once per distinct failure.** De-duplicated by signature, so a
+ *    chart re-rendered by a sibling's state change does not re-report.
+ *  - **Redact.** The report carries the chart identity and a catalogue message.
+ *    A third-party exception's own text is never copied in, because we cannot
+ *    promise it is free of data (POL-011).
+ */
+import React from 'react';
+
+import type { ChartFamily } from '../contract/datasource';
+import {
+	chartError,
+	failureSignature,
+	toFailureReport,
+	type ChartError,
+	type ChartFailureHandler,
+} from '../contract/errors';
+
+interface Props {
+	readonly family: ChartFamily;
+	readonly chartId?: string;
+	readonly onFailure?: ChartFailureHandler;
+	/** Changing this clears a contained failure. */
+	readonly resetKey: unknown;
+	readonly renderFallback: (error: ChartError) => React.ReactNode;
+	readonly children: React.ReactNode;
+}
+
+interface State {
+	readonly error?: ChartError;
+	readonly resetKey: unknown;
+	readonly reportedSignature?: string;
+}
+
+export class ChartBoundary extends React.Component<Props, State> {
+	constructor(props: Props) {
+		super(props);
+		this.state = { resetKey: props.resetKey };
+	}
+
+	static getDerivedStateFromProps(props: Props, state: State): State | null {
+		if (props.resetKey !== state.resetKey) {
+			// New data: give the chart another chance.
+			return { resetKey: props.resetKey, error: undefined };
+		}
+		return null;
+	}
+
+	static getDerivedStateFromError(): Partial<State> {
+		// This must set the error, not just acknowledge it. Returning an empty
+		// object leaves render() showing the children again, they throw again,
+		// and React escalates past the boundary — which is exactly the
+		// screen-blanking failure this class exists to prevent.
+		//
+		// componentDidCatch then refines this into a report carrying the chart
+		// identity and family.
+		return { error: chartError('render', 'renderException') };
+	}
+
+	override componentDidCatch(error: unknown, info: { componentStack?: string }): void {
+		const report = toFailureReport(
+			this.props.family,
+			error,
+			this.props.chartId,
+			info?.componentStack ?? undefined,
+		);
+
+		const signature = failureSignature(report);
+		if (this.state.reportedSignature === signature) {
+			this.setState({ error: report.error });
+			return;
+		}
+
+		this.setState({ error: report.error, reportedSignature: signature });
+		this.props.onFailure?.(report);
+	}
+
+	override render(): React.ReactNode {
+		if (this.state.error) {
+			return this.props.renderFallback(this.state.error);
+		}
+		return this.props.children;
+	}
+}