Data State Model

1export const DATA_STATES = [
2  'loading',
3  'error',
4  'not-applicable',
5  'not-counted',
6  'empty',
7  'partial',
8  'truncated',
9  'first-measurement',
10  'idle',
11] as const;
12 
13export type DataStateName = (typeof DATA_STATES)[number];
14 
15/**
16 * States that REPLACE the body — there is no value to render underneath them.
17 *
18 * The complement (`partial`, `truncated`, `first-measurement`) qualifies a body
19 * that does render. `idle` is neither, and is excluded from both.
20 */
21export const REPLACING_STATES = new Set<DataStateName>([
22  'loading',
23  'error',
24  'not-applicable',
25  'not-counted',
26  'empty',
27]);
28 
29/** States that annotate a body which still renders. */
30export const QUALIFYING_STATES = new Set<DataStateName>([
31  'partial',
32  'truncated',
33  'first-measurement',
34]);
35 
36/** True when this state swaps out the content rather than annotating it. */
37export const replacesBody = (state: DataStateName): boolean =>
38  REPLACING_STATES.has(state);
39 
40/**
41 * The caller's flags, one per absence.
42 *
43 * `error` is `unknown` rather than `boolean` so a caught value can be passed
44 * through untouched — the value is never rendered from here, only its
45 * truthiness is read.
46 *
47 * Deliberately NOT a single `state` enum prop: the whole point is that these
48 * co-occur. A partially-covered, truncated list is two facts, and an enum
49 * would force the caller to pick one and drop the other on the floor.
50 */
51export interface DataStateFlags {
52  loading?: boolean;
53  error?: unknown;
54  empty?: boolean;
55  /** Some sources did not report. Every count below is a FLOOR, not a total. */
56  partial?: boolean;
57  /** The list is cut short. It must never become a denominator. */
58  truncated?: boolean;
59  /** The metric has no meaning for this subject. Not zero — inapplicable. */
60  notApplicable?: boolean;
61  /** No run happened. Not zero — unmeasured. This is the hatch. */
62  notCounted?: boolean;
63  /** A reading exists but no prior does. Never render this as `+0%`. */
64  firstMeasurement?: boolean;
65}
66 
67/** Flag key → state name, in the same order as `DATA_STATES`. */
68const FLAG_ORDER: readonly (readonly [keyof DataStateFlags, DataStateName])[] = [
69  ['loading', 'loading'],
70  ['error', 'error'],
71  ['notApplicable', 'not-applicable'],
72  ['notCounted', 'not-counted'],
73  ['empty', 'empty'],
74  ['partial', 'partial'],
75  ['truncated', 'truncated'],
76  ['firstMeasurement', 'first-measurement'],
77];
78 
79/**
80 * Context for the spoken sentence.
81 *
82// … truncated