@chipmobilesdk/rn-chart 0.1.1 → 0.2.1

package/README.md

@@ -1,197 +1,214 @@
-# @chipmobilesdk/rn-chart
-
+# @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`
+- **Version**: see [CHANGELOG](CHANGELOG.md)
 - **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)}
-/>
-```
-
+
+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.
+
+### Reference markers
+
+`datasource.markers` holds targets, baselines and thresholds. Those with a known
+value are drawn as dashed lines:
+
+- `BarChart` and `TimeSeriesChart` draw each one across the plot, with its
+  `label` at the right end. The value axis is stretched to include it, so a
+  threshold above every data point is still on the chart.
+- `ProgressChart` draws the target on each row's bar. A value past its target
+  is drawn as overshoot beyond that line, inside the plot: the track is scaled
+  so the target sits at `1 / min(largest proportion, 1.25)` of its width.
+- `DistributionChart` and `HeatmapChart` ignore markers.
+
+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.
+
+## 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.
 
@@ -206,110 +223,116 @@ you supply `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.
-
+
+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.
+
+`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;
+a series with a single point is that segment, so its series `color` applies.
+The legend has one entry per segment, in the same colour as its arc.
+
+## 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.
-
+
+`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.
@@ -330,29 +353,29 @@ The single entrypoint exports these public groups:
   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
+
+**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 --workspace @chipmobilesdk/rn-chart
+npm run pack:check --workspace @chipmobilesdk/rn-chart
+npm run validate   # all of the above
 ```
 
 The demo integration lives in `src/screens/ChartDemoScreen.tsx`.