@chipmobilesdk/rn-chart 0.2.0 → 0.3.0

package/src/contract/props.ts

@@ -1,60 +1,64 @@
-/**
- * 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 { 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>;
-
-	/** 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;
+/**
+ * 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;

package/src/contract/state.ts

@@ -1,94 +1,88 @@
-/**
- * Chart status contract (FR-029 to FR-038).
- *
- * Ownership is split on a simple principle: the package derives what only the
- * data can determine, and the app declares what only the app can know.
- *
- *   empty, partial     -> derived from the datasource
- *   loading, stale,    -> declared by the app: it alone knows about its own
- *   noPermission,         fetches, cache age, access rules, and failures
- *   error
- */
-import type { ReactNode } from 'react';
-
-import type { ChartError } from './errors';
-
-export type ChartStatus =
-	| 'loading'
-	| 'empty'
-	| 'ready'
-	| 'error'
-	| 'stale'
-	| 'noPermission'
-	| 'partial';
-
-/** The statuses an app may declare. `empty` and `partial` are derived. */
-export type DeclarableChartStatus = Exclude<ChartStatus, 'empty' | 'partial'>;
-
-/**
- * Resolution precedence, highest first.
- *
- * `noPermission` outranks everything so restricted values can never slip
- * through some other state. `stale` and `partial` sit below the blocking
- * states because they are modifiers on a chart that still draws its data.
- */
-export const STATUS_PRECEDENCE: readonly ChartStatus[] = [
-	'noPermission',
-	'error',
-	'loading',
-	'empty',
-	'stale',
-	'partial',
-	'ready',
-];
-
-export interface StatusInputs {
-	/** What the app declared, if anything. */
-	readonly declared?: DeclarableChartStatus;
-	/** True when the datasource carries no points at all. */
-	readonly isEmpty: boolean;
-	/** True when some points are valid and others are unknown/n-a/withheld. */
-	readonly isPartial: boolean;
-	/** A validation failure or a contained render exception. */
-	readonly error?: ChartError;
-}
-
-export function resolveStatus(inputs: StatusInputs): ChartStatus {
-	const candidates = new Set<ChartStatus>(['ready']);
-
-	if (inputs.declared) {
-		candidates.add(inputs.declared);
-	}
-	if (inputs.error) {
-		candidates.add('error');
-	}
-	if (inputs.isEmpty) {
-		candidates.add('empty');
-	}
-	if (inputs.isPartial) {
-		candidates.add('partial');
-	}
-
-	for (const status of STATUS_PRECEDENCE) {
-		if (candidates.has(status)) {
-			return status;
-		}
-	}
-	return 'ready';
-}
-
-/** Statuses in which the chart draws its data (possibly with an indicator). */
-export function drawsData(status: ChartStatus): boolean {
-	return status === 'ready' || status === 'stale' || status === 'partial';
-}
-
-/**
- * Statuses in which no data-selection callback may fire, because the chart is
- * not displaying the values a callback would carry (FR-053).
- */
-export function suppressesInteraction(status: ChartStatus): boolean {
-	return !drawsData(status);
-}
-
-/** Per-status content the app supplies, replacing any package wording (FR-035). */
-export type ChartStateContent = Partial<Record<ChartStatus, ReactNode>>;
+/**
+ * Chart status contract (FR-029 to FR-038).
+ *
+ * Ownership is split on a simple principle: the package derives what only the
+ * data can determine, and the app declares what only the app can know.
+ *
+ *   empty, partial     -> derived from the datasource
+ *   loading, stale,    -> declared by the app: it alone knows about its own
+ *   noPermission,         fetches, cache age, access rules, and failures
+ *   error
+ */
+import type { ReactNode } from 'react';
+
+import type { ChartError } from './errors';
+
+export type ChartStatus =
+	'loading' | 'empty' | 'ready' | 'error' | 'stale' | 'noPermission' | 'partial';
+
+/** The statuses an app may declare. `empty` and `partial` are derived. */
+export type DeclarableChartStatus = Exclude<ChartStatus, 'empty' | 'partial'>;
+
+/**
+ * Resolution precedence, highest first.
+ *
+ * `noPermission` outranks everything so restricted values can never slip
+ * through some other state. `stale` and `partial` sit below the blocking
+ * states because they are modifiers on a chart that still draws its data.
+ */
+export const STATUS_PRECEDENCE: readonly ChartStatus[] = [
+	'noPermission',
+	'error',
+	'loading',
+	'empty',
+	'stale',
+	'partial',
+	'ready',
+];
+
+export interface StatusInputs {
+	/** What the app declared, if anything. */
+	readonly declared?: DeclarableChartStatus;
+	/** True when the datasource carries no points at all. */
+	readonly isEmpty: boolean;
+	/** True when some points are valid and others are unknown/n-a/withheld. */
+	readonly isPartial: boolean;
+	/** A validation failure or a contained render exception. */
+	readonly error?: ChartError;
+}
+
+export function resolveStatus(inputs: StatusInputs): ChartStatus {
+	const candidates = new Set<ChartStatus>(['ready']);
+
+	if (inputs.declared) {
+		candidates.add(inputs.declared);
+	}
+	if (inputs.error) {
+		candidates.add('error');
+	}
+	if (inputs.isEmpty) {
+		candidates.add('empty');
+	}
+	if (inputs.isPartial) {
+		candidates.add('partial');
+	}
+
+	for (const status of STATUS_PRECEDENCE) {
+		if (candidates.has(status)) {
+			return status;
+		}
+	}
+	return 'ready';
+}
+
+/** Statuses in which the chart draws its data (possibly with an indicator). */
+export function drawsData(status: ChartStatus): boolean {
+	return status === 'ready' || status === 'stale' || status === 'partial';
+}
+
+/**
+ * Statuses in which no data-selection callback may fire, because the chart is
+ * not displaying the values a callback would carry (FR-053).
+ */
+export function suppressesInteraction(status: ChartStatus): boolean {
+	return !drawsData(status);
+}
+
+/** Per-status content the app supplies, replacing any package wording (FR-035). */
+export type ChartStateContent = Partial<Record<ChartStatus, ReactNode>>;

package/src/contract/strings.ts

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