@chipmobilesdk/rn-chart 0.4.0 → 0.5.0

package/lib/module/validation/validateDatasource.js

@@ -0,0 +1,184 @@
+"use strict";
+
+/**
+ * Datasource validation (FR-015, FR-017, FR-007a).
+ *
+ * Rules V1-V8 from specs/007-rn-chart-package/data-model.md §6. Every failure
+ * returns a `ChartError` built from the fixed message catalogue, so validation
+ * output can never carry a data value or a series label.
+ *
+ * Note V8: an empty datasource is **not** an error. It resolves to the empty
+ * state, which is a first-class outcome rather than a failure.
+ */
+import { familyAcceptsPositionKind } from "../contract/datasource.js";
+import { DISTRIBUTION_SUM_TOLERANCE, resolveDistributionValues } from "../contract/distribution.js";
+import { validationError } from "../contract/errors.js";
+import { isKnown } from "../contract/value.js";
+export function validateDatasource(datasource, family, chartId, /** What a distribution's values mean, when the app says; inferred otherwise. */
+distributionValues) {
+  const base = {
+    isEmpty: true,
+    isPartial: false,
+    totalIncomplete: false
+  };
+
+  // V4 — the receiving family must accept the declared position kind. Checked
+  // first because a mismatch here makes everything downstream meaningless.
+  if (!familyAcceptsPositionKind(family, datasource.positionKind)) {
+    return {
+      ...base,
+      isEmpty: false,
+      error: validationError('familyPositionKindUnsupported', {
+        chartId,
+        family,
+        detail: {
+          actualKind: datasource.positionKind
+        }
+      })
+    };
+  }
+
+  // V1 — series ids unique.
+  const seenSeriesIds = new Set();
+  for (const series of datasource.series) {
+    if (seenSeriesIds.has(series.id)) {
+      return {
+        ...base,
+        isEmpty: false,
+        error: validationError('duplicateSeriesId', {
+          chartId,
+          family,
+          detail: {
+            occurrences: seenSeriesIds.size
+          }
+        })
+      };
+    }
+    seenSeriesIds.add(series.id);
+  }
+  let totalPoints = 0;
+  let knownPoints = 0;
+  const matrixRows = new Set();
+  const matrixColumns = new Set();
+  for (const series of datasource.series) {
+    // V2 — point ids unique within their series.
+    const seenPointIds = new Set();
+    for (const point of series.points) {
+      if (seenPointIds.has(point.id)) {
+        return {
+          ...base,
+          isEmpty: false,
+          error: validationError('duplicatePointId', {
+            chartId,
+            family,
+            detail: {
+              occurrences: seenPointIds.size
+            }
+          })
+        };
+      }
+      seenPointIds.add(point.id);
+
+      // V3 — every point matches the declared position kind.
+      if (point.position.kind !== datasource.positionKind) {
+        return {
+          ...base,
+          isEmpty: false,
+          error: validationError('positionKindMismatch', {
+            chartId,
+            family,
+            detail: {
+              expectedKind: datasource.positionKind,
+              actualKind: point.position.kind
+            }
+          })
+        };
+      }
+      if (point.position.kind === 'matrix') {
+        matrixRows.add(point.position.row);
+        matrixColumns.add(point.position.column);
+      }
+
+      // V9 — a known value is a finite number, and so is an instant. NaN or
+      // Infinity used to be drawn at the origin without a word (CHT-10).
+      const finite = (!isKnown(point.value) || Number.isFinite(point.value.value)) && (point.position.kind !== 'instant' || Number.isFinite(point.position.at));
+      if (!finite) {
+        return {
+          ...base,
+          isEmpty: false,
+          error: validationError('nonFiniteValue', {
+            chartId,
+            family
+          })
+        };
+      }
+      // V10 — a share of a whole cannot be negative.
+      if (family === 'distribution' && isKnown(point.value) && point.value.value < 0) {
+        return {
+          ...base,
+          isEmpty: false,
+          error: validationError('negativeDistributionValue', {
+            chartId,
+            family
+          })
+        };
+      }
+      totalPoints += 1;
+      if (isKnown(point.value)) {
+        knownPoints += 1;
+      }
+    }
+  }
+
+  // V5 — a matrix must be rectangular: every row/column pair accounted for.
+  if (datasource.positionKind === 'matrix' && totalPoints > 0) {
+    const expected = matrixRows.size * matrixColumns.size;
+    if (totalPoints !== expected) {
+      return {
+        ...base,
+        isEmpty: false,
+        error: validationError('inconsistentMatrix', {
+          chartId,
+          family,
+          detail: {
+            occurrences: Math.abs(expected - totalPoints)
+          }
+        })
+      };
+    }
+  }
+
+  // V6 — distribution segments that do not sum to the whole are flagged, never
+  // rescaled. This is a flag rather than a rejection: the chart still renders
+  // and marks the total incomplete.
+  let totalIncomplete = knownPoints < totalPoints;
+  if (family === 'distribution' && totalPoints > 0) {
+    totalIncomplete = totalIncomplete || !distributionSumsToWhole(datasource, distributionValues);
+  }
+  return {
+    isEmpty: totalPoints === 0,
+    isPartial: totalPoints > 0 && knownPoints > 0 && knownPoints < totalPoints,
+    totalIncomplete
+  };
+}
+
+/**
+ * Only proportions can be checked for wholeness, and only when every point is
+ * known. Absolute values are a whole by definition once they sum to something.
+ */
+function distributionSumsToWhole(datasource, declared) {
+  let sum = 0;
+  for (const series of datasource.series) {
+    for (const point of series.points) {
+      if (!isKnown(point.value)) {
+        return false;
+      }
+      sum += point.value.value;
+    }
+  }
+  if (resolveDistributionValues(datasource, declared) === 'absolute') {
+    return sum > 0;
+  }
+  return Math.abs(sum - 1) <= DISTRIBUTION_SUM_TOLERANCE;
+}
+//# sourceMappingURL=validateDatasource.js.map

package/lib/module/validation/validateDatasource.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["familyAcceptsPositionKind","DISTRIBUTION_SUM_TOLERANCE","resolveDistributionValues","validationError","isKnown","validateDatasource","datasource","family","chartId","distributionValues","base","isEmpty","isPartial","totalIncomplete","positionKind","error","detail","actualKind","seenSeriesIds","Set","series","has","id","occurrences","size","add","totalPoints","knownPoints","matrixRows","matrixColumns","seenPointIds","point","points","position","kind","expectedKind","row","column","finite","value","Number","isFinite","at","expected","Math","abs","distributionSumsToWhole","declared","sum"],"sourceRoot":"../../../src","sources":["validation/validateDatasource.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/commonjs/a11y/summary.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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, Position } from '../contract/datasource';
+import type { ChartStatus } from '../contract/state';
+import { type ChartStrings } from '../contract/strings';
+import { type ValueState } from '../contract/value';
+export interface SummaryInput<M = unknown> {
+    readonly datasource: ChartDatasource<M>;
+    readonly family: ChartFamily;
+    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;
+}
+/**
+ * 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 declare function buildChartSummary<M>(input: SummaryInput<M>): string;
+/** Announced for the currently selected point on an adjustable chart. */
+export declare function buildPointAnnouncement(seriesLabel: string, positionLabel: string, value: ValueState, formatValue: (v: ValueState) => string, strings?: ChartStrings): string;
+/** Total plus an explicit note when it is not the whole picture (FR-013). */
+export declare function buildTotalAnnouncement<M>(datasource: ChartDatasource<M>, formatValue: (v: ValueState) => string, strings?: ChartStrings): string;
+//# sourceMappingURL=summary.d.ts.map

package/lib/typescript/commonjs/a11y/summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summary.d.ts","sourceRoot":"","sources":["../../../../src/a11y/summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAGrF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAwBvE,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,OAAO;IACxC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,MAAM,CAAC;IACpD,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC;IACzD,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC;CAChC;AAkFD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,CAoCnE;AAED,yEAAyE;AACzE,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,MAAM,EACtC,OAAO,GAAE,YAAoC,GAC3C,MAAM,CASR;AAED,6EAA6E;AAC7E,wBAAgB,sBAAsB,CAAC,CAAC,EACvC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,WAAW,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,MAAM,EACtC,OAAO,GAAE,YAAoC,GAC3C,MAAM,CAOR"}

package/lib/typescript/commonjs/contract/datasource.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The shared datasource contract (FR-007, FR-007a).
+ *
+ * One contract spans every chart family: each point carries the same envelope —
+ * identity, value state, optional unit and format hint, opaque metadata — and
+ * only its **position** varies by kind. Families that accept the same position
+ * kind consume one another's datasources unchanged; anything else is a
+ * validation error rather than a rendering guess.
+ *
+ * See specs/007-rn-chart-package/data-model.md §2–§6.
+ */
+import type { FormatHint } from './format';
+import type { ReferenceMarker } from './marker';
+import type { ValueState } from './value';
+export type ChartFamily = 'progress' | 'distribution' | 'timeSeries' | 'bar' | 'heatmap';
+/** A named bucket: a category axis, a distribution segment, a progress metric. */
+export interface CategoryPosition {
+    readonly kind: 'category';
+    readonly category: string;
+}
+/**
+ * An absolute instant as epoch milliseconds, UTC.
+ *
+ * A number rather than a `Date` or an ISO string: cheap to compare and
+ * memoize, no per-render parsing across hundreds of points, no identity churn
+ * that would defeat the re-render guarantee, and no ambiguous offset. All
+ * date wording comes from app formatters (FR-016).
+ */
+export interface InstantPosition {
+    readonly kind: 'instant';
+    readonly at: number;
+}
+/** A cell in a row-by-column matrix, for heatmaps. */
+export interface MatrixPosition {
+    readonly kind: 'matrix';
+    readonly row: string;
+    readonly column: string;
+}
+export type Position = CategoryPosition | InstantPosition | MatrixPosition;
+export type PositionKind = Position['kind'];
+/** Non-colour encoding for a series, so meaning never rides on hue alone (FR-064). */
+export type SeriesPattern = 'solid' | 'dashed' | 'dotted' | 'dashDot';
+export interface DataPoint<M = unknown> {
+    /** Stable and unique within its series. Duplicates are a validation error. */
+    readonly id: string;
+    readonly position: Position;
+    readonly value: ValueState;
+    /** Overrides the series unit. */
+    readonly unit?: string;
+    /** Overrides the series format hint. */
+    readonly format?: FormatHint;
+    /** Colour of this point's segment in a distribution chart. Ignored elsewhere. */
+    readonly color?: string;
+    /** Opaque to the package: never read, never logged, returned unchanged. */
+    readonly metadata?: M;
+}
+export interface Series<M = unknown> {
+    /** Stable and unique within the datasource. */
+    readonly id: string;
+    readonly label: string;
+    readonly points: readonly DataPoint<M>[];
+    readonly unit?: string;
+    readonly format?: FormatHint;
+    /** Explicit colour override; otherwise the theme palette assigns one. */
+    readonly color?: string;
+    readonly pattern?: SeriesPattern;
+    /** Initial visibility. Runtime toggling is controlled separately. */
+    readonly hidden?: boolean;
+    readonly metadata?: M;
+}
+export interface ChartDatasource<M = unknown> {
+    /** Declared once, then validated against every point and the receiving family. */
+    readonly positionKind: PositionKind;
+    readonly series: readonly Series<M>[];
+    readonly markers?: readonly ReferenceMarker[];
+    readonly unit?: string;
+    readonly format?: FormatHint;
+    readonly metadata?: M;
+}
+/**
+ * Which position kinds each family accepts.
+ *
+ * Bar accepting both `category` and `instant` is what makes swapping a
+ * time-series chart for a bar chart free — the datasource does not change.
+ */
+export declare const FAMILY_POSITION_KINDS: Readonly<Record<ChartFamily, readonly PositionKind[]>>;
+export declare function familyAcceptsPositionKind(family: ChartFamily, kind: PositionKind): boolean;
+/**
+ * Resolves unit and format through the documented precedence:
+ * point -> series -> datasource -> undefined (caller falls back to its default).
+ */
+export declare function resolveFormat<M>(point: DataPoint<M> | undefined, series: Series<M> | undefined, datasource: ChartDatasource<M>): FormatHint | undefined;
+export declare function resolveUnit<M>(point: DataPoint<M> | undefined, series: Series<M> | undefined, datasource: ChartDatasource<M>): string | undefined;
+//# sourceMappingURL=datasource.d.ts.map

package/lib/typescript/commonjs/contract/datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../../../src/contract/datasource.ts"],"names":[],"mappings":"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"}

package/lib/typescript/commonjs/contract/distribution.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export type DistributionValues = 'proportions' | 'absolute';
+export declare const DISTRIBUTION_SUM_TOLERANCE = 0.001;
+export declare function resolveDistributionValues<M>(datasource: ChartDatasource<M>, declared?: DistributionValues): DistributionValues;
+//# sourceMappingURL=distribution.d.ts.map

package/lib/typescript/commonjs/contract/distribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"distribution.d.ts","sourceRoot":"","sources":["../../../../src/contract/distribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAGpD,MAAM,MAAM,kBAAkB,GAAG,aAAa,GAAG,UAAU,CAAC;AAE5D,eAAO,MAAM,0BAA0B,QAAQ,CAAC;AAEhD,wBAAgB,yBAAyB,CAAC,CAAC,EAC1C,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC,EAC9B,QAAQ,CAAC,EAAE,kBAAkB,GAC3B,kBAAkB,CAqBpB"}

package/lib/typescript/commonjs/contract/errors.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Typed error taxonomy and failure reporting (FR-038, FR-038a, FR-038b).
+ *
+ * Messages come from a **fixed catalogue with no interpolated data**. That is
+ * what makes the redaction guarantee structural rather than a rule someone has
+ * to remember: because the package never builds a message out of a value or a
+ * label, a failure report cannot carry patient data or account balances into a
+ * consuming app's crash reporting.
+ */
+import type { ChartFamily, PositionKind } from './datasource';
+export type ChartErrorCategory = 'validation' | 'declared' | 'render';
+export type ChartErrorCode = 'duplicateSeriesId' | 'duplicatePointId' | 'positionKindMismatch' | 'familyPositionKindUnsupported' | 'inconsistentMatrix' | 'distributionNotWhole' | 'nonFiniteValue' | 'negativeDistributionValue' | 'declaredByApp' | 'renderException';
+export interface ChartError {
+    readonly category: ChartErrorCategory;
+    readonly code: ChartErrorCode;
+    readonly message: string;
+    readonly chartId?: string;
+    readonly family?: ChartFamily;
+    /**
+     * Structural detail that is safe to expose: counts and kinds only, never a
+     * value or a label.
+     */
+    readonly detail?: {
+        readonly expectedKind?: PositionKind;
+        readonly actualKind?: PositionKind;
+        readonly occurrences?: number;
+    };
+}
+export interface ChartFailureReport {
+    readonly chartId?: string;
+    readonly family: ChartFamily;
+    readonly error: ChartError;
+    readonly componentStack?: string;
+}
+export type ChartFailureHandler = (report: ChartFailureReport) => void;
+export declare function chartError(category: ChartErrorCategory, code: ChartErrorCode, extra?: Omit<ChartError, 'category' | 'code' | 'message'>): ChartError;
+export declare function validationError(code: ChartErrorCode, extra?: Omit<ChartError, 'category' | 'code' | 'message'>): ChartError;
+export declare function isChartError(e: unknown): e is ChartError;
+/**
+ * Builds the report handed to the app after a contained render exception.
+ *
+ * A `ChartError` thrown by the package keeps its catalogue message. Anything
+ * else — a defect in the rendering library, say — is reported under the generic
+ * `renderException` message. We do **not** copy a third-party exception's own
+ * message into the report, because we cannot promise it is free of data.
+ */
+export declare function toFailureReport(family: ChartFamily, thrown: unknown, chartId?: string, componentStack?: string): ChartFailureReport;
+/**
+ * Stable identity for a failure, used to de-duplicate reports so an unrelated
+ * parent re-render does not re-report the same problem.
+ */
+export declare function failureSignature(report: ChartFailureReport): string;
+//# sourceMappingURL=errors.d.ts.map

package/lib/typescript/commonjs/contract/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../../src/contract/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEtE,MAAM,MAAM,cAAc,GACvB,mBAAmB,GACnB,kBAAkB,GAClB,sBAAsB,GACtB,+BAA+B,GAC/B,oBAAoB,GACpB,sBAAsB,GACtB,gBAAgB,GAChB,2BAA2B,GAC3B,eAAe,GACf,iBAAiB,CAAC;AAwBrB,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,YAAY,CAAC,EAAE,YAAY,CAAC;QACrC,QAAQ,CAAC,UAAU,CAAC,EAAE,YAAY,CAAC;QACnC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACF;AAED,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;AAEvE,wBAAgB,UAAU,CACzB,QAAQ,EAAE,kBAAkB,EAC5B,IAAI,EAAE,cAAc,EACpB,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC,GACvD,UAAU,CAOZ;AAED,wBAAgB,eAAe,CAC9B,IAAI,EAAE,cAAc,EACpB,KAAK,CAAC,EAAE,IAAI,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC,GACvD,UAAU,CAEZ;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU,CAYxD;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC9B,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,OAAO,EACf,OAAO,CAAC,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,GACrB,kBAAkB,CAMpB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAEnE"}

package/lib/typescript/commonjs/contract/format.d.ts

@@ -0,0 +1,63 @@
+import type { Position, Series } from './datasource';
+import { type ValueState } from './value';
+export type FormatHint = {
+    readonly kind: 'number';
+    readonly decimals?: number;
+} | {
+    readonly kind: 'percent';
+    readonly decimals?: number;
+} | {
+    readonly kind: 'currency';
+    readonly currency: string;
+} | {
+    readonly kind: 'duration';
+    readonly unit: 'ms' | 's' | 'min' | 'h';
+} | {
+    readonly kind: 'count';
+} | {
+    readonly kind: 'custom';
+    readonly unit: string;
+};
+export interface FormatContext {
+    readonly hint?: FormatHint;
+    readonly unit?: string;
+    /** Where the text will appear, so a formatter can adapt its verbosity. */
+    readonly slot: 'axis' | 'value' | 'legend' | 'summary';
+}
+export interface SeriesRef {
+    readonly id: string;
+    readonly label: string;
+}
+export interface ChartFormatters {
+    readonly axisLabel?: (v: ValueState | Position, ctx: FormatContext) => string;
+    readonly value?: (v: ValueState, ctx: FormatContext) => string;
+    readonly legendLabel?: (series: SeriesRef, ctx: FormatContext) => string;
+    readonly summary?: (v: ValueState, ctx: FormatContext) => string;
+}
+/**
+ * Placeholders for the three non-value classes. Deliberately not "0" and not
+ * an empty string, so a reader can tell a gap from a zero at a glance.
+ */
+export declare const NON_VALUE_TEXT: Readonly<Record<string, string>>;
+/**
+ * Locale-neutral default formatting (FR-057).
+ *
+ * Deliberately plain: no thousands separators, no currency symbol lookup, no
+ * month names. Anything locale-dependent belongs to the consuming app, which
+ * owns an i18n system the package does not.
+ */
+export declare function formatValueDefault(v: ValueState, ctx?: FormatContext): string;
+export declare function formatPositionDefault(p: Position): string;
+export declare function formatLegendDefault(series: SeriesRef): string;
+/**
+ * Runs an app formatter, falling back to the package default for that single
+ * label if it throws (FR-059). One bad formatter must not take down a screen.
+ *
+ * The dev-only warning is intentionally value-free: it names the slot, never
+ * the data.
+ */
+export declare function safeFormat(run: () => string, fallback: () => string, slot: FormatContext['slot'], onceKey?: string): string;
+/** Test-only reset so warning-once behaviour can be asserted repeatedly. */
+export declare function __resetFormatterWarnings(): void;
+export declare function seriesRef<M>(series: Series<M>): SeriesRef;
+//# sourceMappingURL=format.d.ts.map

package/lib/typescript/commonjs/contract/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../src/contract/format.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAKnD,MAAM,MAAM,UAAU,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxD;IACA,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC;CACvC,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtD,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;CACvD;AAED,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,GAAG,QAAQ,EAAE,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;IAC9E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;IAC/D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,aAAa,KAAK,MAAM,CAAC;CACjE;AAED;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI3D,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,GAAE,aAAiC,GAAG,MAAM,CA8BhG;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAYzD;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAE7D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,GAAG,EAAE,MAAM,MAAM,EACjB,QAAQ,EAAE,MAAM,MAAM,EACtB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAC3B,OAAO,CAAC,EAAE,MAAM,GACd,MAAM,CASR;AAuBD,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAEzD"}

package/lib/typescript/commonjs/contract/interaction.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Interaction contract (FR-048 to FR-054a).
+ *
+ * The package reports what the user touched and does nothing else: no
+ * navigation, no fetching, no datasource mutation, no business rules.
+ *
+ * Selection is **uncontrolled by default and controlled when the app supplies a
+ * value** — the standard React pattern. The same callbacks fire either way, so
+ * a consumer can move between the two without rewriting handlers.
+ */
+import type { Position } from './datasource';
+import type { ValueState } from './value';
+export interface SelectionRef {
+    readonly seriesId: string;
+    /** Absent for a whole-series selection. */
+    readonly pointId?: string;
+}
+export interface PointInteractionEvent<M = unknown> {
+    readonly type: 'pointSelect';
+    readonly seriesId: string;
+    readonly pointId: string;
+    readonly value: ValueState;
+    readonly position: Position;
+    readonly metadata?: M;
+}
+export interface SeriesInteractionEvent<M = unknown> {
+    readonly type: 'visibilityChange';
+    readonly seriesId: string;
+    readonly visible?: boolean;
+    readonly metadata?: M;
+}
+export type ChartInteractionEvent<M = unknown> = PointInteractionEvent<M> | SeriesInteractionEvent<M>;
+export interface InteractionProps<M = unknown> {
+    /**
+     * Omit for uncontrolled selection. Supply — including `null` — to take
+     * ownership; the chart then renders exactly what this says.
+     */
+    readonly selection?: SelectionRef | null;
+    readonly onSelectionChange?: (next: SelectionRef | null, event: PointInteractionEvent<M> | null) => void;
+    /**
+     * Fires when an app-controlled selection no longer resolves against the
+     * current datasource, so the app can correct its own state rather than
+     * having the package silently ignore it.
+     */
+    readonly onSelectionUnresolvable?: (ref: SelectionRef) => void;
+    /** Omit for uncontrolled visibility. Supply to take ownership. */
+    readonly hiddenSeriesIds?: readonly string[];
+    readonly onVisibilityChange?: (event: SeriesInteractionEvent<M>) => void;
+    /** Series toggling stays off unless the app opts in (FR-049). */
+    readonly seriesToggleEnabled?: boolean;
+}
+export declare function sameSelection(a: SelectionRef | null | undefined, b: SelectionRef | null | undefined): boolean;
+//# sourceMappingURL=interaction.d.ts.map

package/lib/typescript/commonjs/contract/interaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interaction.d.ts","sourceRoot":"","sources":["../../../../src/contract/interaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB,CAAC,CAAC,GAAG,OAAO;IACjD,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACtB;AAED,MAAM,WAAW,sBAAsB,CAAC,CAAC,GAAG,OAAO;IAClD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,qBAAqB,CAAC,CAAC,GAAG,OAAO,IAC5C,qBAAqB,CAAC,CAAC,CAAC,GAAG,sBAAsB,CAAC,CAAC,CAAC,CAAC;AAEtD,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,OAAO;IAC5C;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAC5B,IAAI,EAAE,YAAY,GAAG,IAAI,EACzB,KAAK,EAAE,qBAAqB,CAAC,CAAC,CAAC,GAAG,IAAI,KAClC,IAAI,CAAC;IACV;;;;OAIG;IACH,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,GAAG,EAAE,YAAY,KAAK,IAAI,CAAC;IAC/D,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IACzE,iEAAiE;IACjE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,wBAAgB,aAAa,CAC5B,CAAC,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EAClC,CAAC,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAChC,OAAO,CAKT"}

package/lib/typescript/commonjs/contract/marker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Reference markers: targets, baselines, and thresholds (FR-008, FR-021, FR-022).
+ *
+ * The important rule lives here: a marker whose value is not `known`, or whose
+ * target is zero or negative, produces **no completion proportion**. A chart
+ * shows the current value alone rather than inventing a percentage.
+ */
+import type { FormatHint } from './format';
+import { type ValueState } from './value';
+export type MarkerKind = 'target' | 'baseline' | 'threshold';
+export interface ReferenceMarker {
+    readonly id: string;
+    readonly kind: MarkerKind;
+    readonly value: ValueState;
+    readonly label?: string;
+    readonly format?: FormatHint;
+}
+/**
+ * A target only supports a proportion when it is known and strictly positive.
+ * Zero and negative targets make "percent complete" meaningless, so we decline
+ * to compute one rather than divide and produce a nonsense figure.
+ */
+export declare function isUsableTarget(marker: ReferenceMarker | undefined): boolean;
+export interface ProgressReading {
+    /** The current value, when known. */
+    readonly current: ValueState;
+    /** The target, when one was supplied. */
+    readonly target?: ReferenceMarker;
+    /**
+     * Completion as a ratio of current to target. `undefined` whenever no
+     * proportion can honestly be computed — this is never defaulted to 0 or 1.
+     */
+    readonly proportion?: number;
+    /** True when the current value exceeds the target: shown, never clamped. */
+    readonly overshoot: boolean;
+}
+export declare function readProgress(current: ValueState, target: ReferenceMarker | undefined): ProgressReading;
+export declare function findTarget(markers: readonly ReferenceMarker[] | undefined, id?: string): ReferenceMarker | undefined;
+//# sourceMappingURL=marker.d.ts.map

package/lib/typescript/commonjs/contract/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../../../src/contract/marker.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAEnD,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,GAAG,OAAO,CAK3E;AAED,MAAM,WAAW,eAAe;IAC/B,qCAAqC;IACrC,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,4EAA4E;IAC5E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,YAAY,CAC3B,OAAO,EAAE,UAAU,EACnB,MAAM,EAAE,eAAe,GAAG,SAAS,GACjC,eAAe,CAejB;AAED,wBAAgB,UAAU,CACzB,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,SAAS,EAC/C,EAAE,CAAC,EAAE,MAAM,GACT,eAAe,GAAG,SAAS,CAK7B"}

package/lib/typescript/commonjs/contract/props.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Props shared by every chart family.
+ *
+ * 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';
+import type { ChartDatasource } from './datasource';
+import type { ChartFailureHandler } from './errors';
+import type { ChartFormatters, FormatContext } from './format';
+import type { InteractionProps } from './interaction';
+import type { ChartStateContent, DeclarableChartStatus } from './state';
+import type { ChartTheme } from './theme';
+import type { ValueState } from './value';
+export interface ChartAccessibility<M = unknown> {
+    /** Replaces the composed summary entirely. */
+    readonly label?: string;
+    readonly summaryFormatter?: (datasource: ChartDatasource<M>, ctx: FormatContext) => string;
+    /** Defaults to true when `onSelectionChange` is supplied. */
+    readonly interactive?: boolean;
+}
+export interface BaseChartProps<M = unknown> extends InteractionProps<M> {
+    /**
+     * Must be referentially stable across renders, or memoization is defeated.
+     * Hold it in state or a memo rather than building it inline.
+     */
+    readonly datasource: ChartDatasource<M>;
+    /**
+     * `empty` and `partial` are derived from the data and are not accepted here
+     * (FR-036).
+     */
+    readonly status?: DeclarableChartStatus;
+    readonly stateContent?: ChartStateContent;
+    readonly chartId?: string;
+    readonly onFailure?: ChartFailureHandler;
+    readonly theme?: ChartTheme;
+    readonly formatters?: ChartFormatters;
+    readonly title?: string;
+    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;
+    readonly style?: StyleProp<ViewStyle>;
+    /** Rendered below the plot, inside the chart's own bounds. */
+    readonly footer?: ReactNode;
+}
+export type ValueFormatter = (value: ValueState) => string;
+//# sourceMappingURL=props.d.ts.map