@chipmobilesdk/rn-chart 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to `@chipmobilesdk/rn-chart` are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this package adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - Unreleased
+
+### Added
+
+Initial release. A domain-agnostic charting package for ChipMobileSdk-family
+apps.
+
+- **One datasource contract** across five chart families, with a shared point
+  envelope and a discriminated `Position` (category, instant, matrix). Families
+  accepting the same position kind interchange without changing the datasource.
+- **Four-way value semantics** — `known` (including a real zero), `unknown`,
+  `notApplicable`, `withheld` — carried as a discriminated union with no numeric
+  field on the three non-value cases, so a gap cannot be coerced to zero.
+- **Chart families**: `ProgressChart`, `DistributionChart`, `TimeSeriesChart`,
+  `BarChart`, `HeatmapChart`, plus `ChartLegend`.
+- **Seven chart states** per family — loading, empty, ready, error, stale,
+  no-permission, partial — with per-chart failure containment and an
+  app-supplied failure-report callback that carries no data values.
+- **Interaction callbacks** for point selection, series selection, segment
+  press, and series visibility. Uncontrolled by default; app-controlled when
+  the corresponding value prop is supplied. The package never navigates,
+  fetches, or mutates.
+- **Theming** through a `ChartTheme` value type resolved from prop, context, or
+  a built-in light/dark default. No dependency on `@chipmobilesdk/rn-theme` or
+  `react-native-unistyles`.
+- **Formatting** through app-supplied formatters for axis labels, values,
+  legend entries, and summaries, with documented locale-neutral defaults.
+- **Accessibility**: composed per-chart summaries, state announcements, and
+  `adjustable` selection traversal for assistive technology.
+- **Dataset budgets** (`DATASET_BUDGETS`) with a dev-only, once-per-chart
+  over-budget warning. Over-budget datasets still render.
+
+### Release notes for consuming apps
+
+What a team adopting this package needs to know and do:
+
+- **Install two things, not one.** `@chipmobilesdk/rn-chart` and its required
+  peer `react-native-svg` (>= 15.15), then `pod install` on iOS.
+- **No permissions, no manifest changes, no store-declaration changes.** The
+  package requests nothing and collects nothing. Note that its *no-permission
+  chart state* is an app-level data-access concept, not an OS permission.
+- **Screenshots may need updating** wherever charts change how a screen looks.
+  No other store metadata is affected.
+- **If you chart sensitive data**, read the data-behaviour note in the README
+  before completing Apple App Privacy or Google Play Data Safety. The package
+  introduces no collection of its own, but anything your app transmits is yours
+  to declare.
+- **If you render narrative or AI-sourced text near a chart**, moderation and
+  content obligations are entirely yours — this package ships no free-text
+  surface.
+- **One API habit to adopt**: keep your datasource referentially stable (state
+  or `useMemo`). Rebuilding it inline every render defeats the package's
+  memoization, and no library can fix that from the inside.
+
+### Notes
+
+- **Peer dependencies**: `react` >= 19, `react-native` >= 0.85,
+  `react-native-svg` >= 15.15. No runtime dependencies.
+- **Native code**: none is authored in this package. `react-native-svg` is a
+  native-backed peer; see the README for install and setup.
+- **Stability**: the value, datasource, state, error, and interaction contracts
+  are stable. `ChartTheme`, `LegendEntry`, family-specific props, and the
+  `DATASET_BUDGETS` values are experimental and may change in a minor release —
+  see `specs/007-rn-chart-package/contracts/public-api.md` §6.
+- **Out of scope, reserved for a future additive minor**: insight/narrative
+  presentation and composable chart primitives. Neither will change the
+  datasource, state, or interaction contracts when it lands.

package/README.md

@@ -0,0 +1,358 @@
+# @chipmobilesdk/rn-chart
+
+Domain-agnostic charts for ChipMobileSdk-family React Native apps.
+
+> **License:** `UNLICENSED`. Published publicly for use by the owner's
+> applications; no open-source license is granted.
+
+- **Version**: `0.1.0`
+- **Entrypoint**: `@chipmobilesdk/rn-chart`
+
+One datasource contract spans five chart families. The package knows nothing
+about nutrition, finance, health, or productivity — you hand it aggregated,
+normalised data and it draws it.
+
+## What it does not do
+
+Worth stating up front, because these are deliberate:
+
+- **No insight or narrative surface.** The package draws charts. Render your own
+  explanatory text above or below a chart; it imposes no outer margin that would
+  fight your layout.
+- **No data fetching, no database access, no AI calls, no network of any kind.**
+  Everything arrives as props.
+- **No aggregation.** Your domain layer decides what the numbers mean.
+- **No navigation.** Interactions call back; what happens next is yours.
+
+## Install
+
+```bash
+npm install @chipmobilesdk/rn-chart react-native-svg
+cd ios && pod install
+```
+
+`react-native-svg` is a required peer. There is no degraded no-SVG mode.
+
+No permissions, entitlements, `Info.plist` usage strings, or Android manifest
+changes are needed. Note that this package's **no-permission chart state** is an
+app-level data-access concept, not an operating-system permission.
+
+## Compatibility
+
+| | Supported |
+|---|---|
+| React | 19.2+ |
+| React Native | 0.85+ |
+| `react-native-svg` | 15.15+ |
+| Android | `minSdkVersion` 24, `targetSdkVersion` 36 |
+| iOS | 15.1+ |
+
+## Quick start
+
+```tsx
+import { BarChart, known, unknown, type ChartDatasource } from '@chipmobilesdk/rn-chart';
+
+const datasource: ChartDatasource = {
+  positionKind: 'category',
+  series: [{
+    id: 'weekly',
+    label: 'Weekly total',
+    points: [
+      { id: 'mon', position: { kind: 'category', category: 'Mon' }, value: known(12) },
+      { id: 'tue', position: { kind: 'category', category: 'Tue' }, value: known(0) },
+      { id: 'wed', position: { kind: 'category', category: 'Wed' }, value: unknown() },
+    ],
+  }],
+};
+
+export function Example() {
+  return <BarChart datasource={datasource} height={220} title="This week" />;
+}
+```
+
+Monday draws a bar. Tuesday draws a **zero-height bar that reads as a real
+zero**. Wednesday draws **nothing and is marked as a gap** — never a zero.
+
+> **Keep your datasource referentially stable.** Hold it in state or a `useMemo`.
+> Rebuilding the object inline on every render defeats the memoization the
+> package relies on, and that is not something a library can fix for you.
+
+## Value semantics
+
+The most important part of the contract. Four classes, and only one carries a
+number:
+
+```ts
+known(42)          // a real observation, including known(0)
+unknown()          // we do not know
+notApplicable()    // does not apply here
+withheld()         // hidden: permission, or not enough data
+```
+
+There is no `value` property on the three non-value cases, so `value ?? 0`
+cannot compile. That is the point — turning a gap into a zero is the single most
+damaging thing a charting library can do to someone's data.
+
+Consequences you can rely on:
+
+- An unknown value is never rendered as zero and never interpolated across. In a
+  line chart the gap ends the subpath, so there is physically no segment to
+  bridge it.
+- `notApplicable` and `withheld` are excluded from totals, and any total that
+  excluded something is reported as incomplete.
+- A withheld value never appears in a rendering, a label, an accessible summary,
+  or an interaction callback.
+- Each non-value class renders as its own **texture**, not a colour difference,
+  so they stay distinguishable in greyscale.
+
+## The datasource contract
+
+Every point shares one envelope — identity, value, optional unit and format
+hint, opaque metadata — and only its **position** varies:
+
+```ts
+{ kind: 'category', category: 'Mon' }
+{ kind: 'instant', at: 1767225600000 }        // epoch ms, UTC
+{ kind: 'matrix', row: 'week-1', column: 'Mon' }
+```
+
+Which families accept which:
+
+| Family | `category` | `instant` | `matrix` |
+|---|:---:|:---:|:---:|
+| `ProgressChart` | ✓ | | |
+| `DistributionChart` | ✓ | | |
+| `BarChart` | ✓ | ✓ | |
+| `TimeSeriesChart` | | ✓ | |
+| `HeatmapChart` | | | ✓ |
+
+Bar accepting both is what makes swapping a time-series chart for a bar chart
+free — same datasource, different component. Any other pairing is a **validation
+error**, not a rendering guess.
+
+Time is epoch milliseconds and carries no timezone. All date wording comes from
+your formatters.
+
+## States
+
+Seven, and the package derives the two that only the data can determine:
+
+| Status | Who decides |
+|---|---|
+| `empty`, `partial` | derived from your datasource |
+| `loading`, `stale`, `noPermission`, `error` | you declare via `status` |
+
+Precedence: `noPermission > error > loading > empty > stale > partial > ready`.
+`noPermission` outranks everything so restricted values cannot slip through
+another state.
+
+Supply your own copy — the package's built-in wording is a terse placeholder,
+not product voice:
+
+```tsx
+<BarChart
+  datasource={ds}
+  status="loading"
+  stateContent={{
+    empty: <Text>Log your first meal to see this chart</Text>,
+    loading: <Spinner />,
+  }}
+/>
+```
+
+### Failure containment
+
+Each chart contains its own render exceptions. One bad datasource collapses one
+chart, never the dashboard around it:
+
+```tsx
+<BarChart datasource={ds} chartId="calories" onFailure={report => crashReporter.log(report)} />
+```
+
+Failure reports carry the chart identity, family, and a catalogue message —
+**never data values or series labels**. This matters if you chart health or
+financial data, because a report is the easiest accidental path from a chart
+into a third-party crash reporting service.
+
+## Interaction
+
+Uncontrolled by default. Supply a `selection` value (including `null`) to take
+ownership; the same callbacks fire either way.
+
+```tsx
+// Uncontrolled: the chart tracks its own selection.
+<BarChart datasource={ds} onSelectionChange={(ref, event) => log(event)} />
+
+// Controlled: you are the source of truth.
+<BarChart
+  datasource={ds}
+  selection={selection}
+  onSelectionChange={setSelectionFromRef}
+  onSelectionUnresolvable={ref => setSelection(null)}
+/>
+```
+
+Every payload carries the point id, series id, value, position, and whatever
+metadata you attached. The package never navigates, fetches, or mutates.
+
+Legends can also toggle series visibility. The state is uncontrolled unless
+you supply `hiddenSeriesIds`:
+
+```tsx
+<BarChart
+  datasource={ds}
+  seriesToggleEnabled
+  hiddenSeriesIds={hiddenSeriesIds}
+  onVisibilityChange={event => updateHiddenSeries(event.seriesId)}
+/>
+```
+
+Pan, pinch-zoom, and brush-to-select are out of scope. `range` on
+`TimeSeriesChart` is a window **you** supply, not one the user draws.
+
+## Theming
+
+The package defines its own `ChartTheme` value type and takes no dependency on
+`@chipmobilesdk/rn-theme` or `react-native-unistyles`. Any design system can
+satisfy it:
+
+```tsx
+import { ChartThemeProvider, defaultChartTheme } from '@chipmobilesdk/rn-chart';
+
+const chartTheme = {
+  ...defaultChartTheme(scheme),
+  palette: myTokens.dataviz,
+  surface: myTokens.surface,
+};
+
+<ChartThemeProvider theme={chartTheme}>{children}</ChartThemeProvider>
+```
+
+Resolution order: explicit `theme` prop → provider context → built-in default
+keyed on `useColorScheme()`. With no configuration at all, charts still render
+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.
+
+## Formatting
+
+```tsx
+<TimeSeriesChart
+  datasource={ds}
+  formatters={{
+    value: v => (v.kind === 'known' ? intl.number(v.value) : '—'),
+    axisLabel: p => ('at' in p ? intl.date(p.at) : String(p)),
+  }}
+/>
+```
+
+Your output is used verbatim. With no formatter, a documented locale-neutral
+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.
+
+## Accessibility
+
+Each chart is a single accessible element with a composed summary: what it is,
+what it shows, where the extremes are, what any target says. With selection
+enabled the root becomes `adjustable`, so increment and decrement walk the data
+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.
+
+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.
+
+## Dataset budgets
+
+| Family | Budget |
+|---|---|
+| Time series | 5 series × 500 points |
+| Bar | 5 series × 60 categories |
+| Distribution | 12 segments |
+| 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
+downsampling above these sizes is your call — the package will not silently
+decide what data to discard.
+
+Element count scales with series, not points: an at-budget time-series chart
+emits about six SVG elements, not 2,500.
+
+## Data behaviour (for App Privacy and Data Safety)
+
+For consuming apps completing Apple App Privacy or Google Play Data Safety
+declarations:
+
+- The package holds the values and labels you pass it **in memory only**, for the
+  lifetime of the rendered component.
+- It collects nothing, generates nothing, persists nothing, transmits nothing,
+  and shares nothing with third parties.
+- It logs no data point value and no series label in production builds,
+  including inside failure reports.
+- It requests no permissions and reads no device identifiers.
+
+**This package introduces no data-collection declaration of its own.** If your
+app sends charted data anywhere, that collection is yours to declare.
+
+If you render your own narrative text near a chart — particularly text from an
+AI service or from users — moderation and content obligations are entirely
+yours. The package ships no free-text surface at all.
+
+## Public API
+
+`src/index.ts` is the only entrypoint. Geometry, scales, layout maths, path
+builders, the chart shell, and the SVG adapter are private so they can change
+without a breaking release.
+
+**Stable**: value semantics, `Position`, the datasource types, the five chart
+components and their base props, `ChartStatus`, the error types, interaction
+events.
+
+The single entrypoint exports these public groups:
+
+- Components: `BarChart`, `DistributionChart`, `HeatmapChart`,
+  `ProgressChart`, `TimeSeriesChart`, `ChartLegend`, `ChartThemeProvider`,
+  `useChartTheme`, `buildLegendEntries`, and their props
+- Values and datasource: `known`, `unknown`, `notApplicable`, `withheld`,
+  `isKnown`, `isWithheld`, `sumKnown`, position/series/datasource types,
+  marker helpers, and format resolution helpers
+- State and validation: `resolveStatus`, `drawsData`, `suppressesInteraction`,
+  `STATUS_PRECEDENCE`, `DATASET_BUDGETS`, `checkBudget`, error/failure types,
+  and `isChartError`
+- Interaction: selection and series interaction types plus `sameSelection`
+- Theme and formatting: `defaultChartTheme`, `resolveSeriesColor`, default
+  formatter helpers, `NON_VALUE_TEXT`, and public theme/formatter contracts
+- Accessibility: `buildChartSummary`, `buildPointAnnouncement`, and
+  `buildTotalAnnouncement`
+
+**Experimental** — may change in a minor: `ChartTheme` token set, `LegendEntry`,
+family-specific props (`shape`, `grouping`, `buckets`), and the
+`DATASET_BUDGETS` figures.
+
+**Reserved for a future additive minor**: an insight presentation surface and
+composable chart primitives. Neither will change the datasource, state, or
+interaction contracts when it lands.
+
+## Contributing
+
+The one architectural rule worth knowing: **nothing under `src/geometry/` may
+import React or `react-native-svg`.** It is pure functions over plain data,
+enforced by an ESLint override and by `geometryPurity.test.ts`. That is what
+keeps the geometry testable without a renderer and the drawing substrate
+replaceable.
+
+```bash
+npm run lint
+npm test
+npm run typecheck:chart
+npm run pack:chart
+npm run validate:chart   # all of the above
+```
+
+The demo integration lives in `src/screens/ChartDemoScreen.tsx`.

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@chipmobilesdk/rn-chart",
+	"version": "0.1.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",
+		"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/"
+	}
+}

package/src/a11y/summary.ts

@@ -0,0 +1,177 @@
+/**
+ * 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}.`;
+}