Data State

1import * as React from 'react';
2 
3// @interlace/data-state v1.1.0 — Interlace design system.
4// Docs, props and live preview: https://ds.interlace.tools/c/data-state
5// What changed since: https://ds.interlace.tools/c/data-state#history
6// Generated banner — keep it, the upgrade diff reads this version.
7 
8/**
9 * @interlace/ui — DataState
10 *
11 * The single conditional swap point for a data surface, and the place the
12 * design system says what an ABSENCE is.
13 *
14 * It started as the four-state ladder every fetch site otherwise re-writes:
15 *
16 *   {isLoading ? <Skeleton /> :
17 *    error    ? <ErrorState /> :
18 *    !data?.length ? <EmptyState /> :
19 *    <ListOfThings items={data} />}
20 *
21 * becomes:
22 *
23 *   <DataState
24 *     loading={isLoading}
25 *     error={error}
26 *     empty={!data?.length}
27 *     skeletonVariant="article-card"
28 *     emptyState={<EmptyState>No articles yet</EmptyState>}
29 *   >
30 *     {() => <ListOfThings items={data!} />}
31 *   </DataState>
32 *
33 * The render-prop child only runs when the surface has real data, so consumers
34 * can `data!.map(...)` inside without a null guard.
35 *
36 * ## Four states was not enough, and the missing five were the interesting ones
37 *
38 * Six published artifacts were catalogued for phase 10, and every one of them
39 * had hand-rolled a vocabulary this component did not have. Not decoration —
40 * distinctions that change what the reader is entitled to conclude:
41 *
42 *   - **`not-counted`** — no run happened. Drawn as a diagonal hatch, because
43 *     a run that returned zero and a run that never happened must not look the
44 *     same. This is the state `charts/scale.ts` has always encoded as `null`.
45 *   - **`not-applicable`** — the metric has no meaning for this subject. It
46 *     recedes: it was never going to have a value, so it should not compete
47 *     with the cells that do.
48 *   - **`partial`** — some sources did not report. Every count below is a
49 *     FLOOR, not a total. Ranked above `truncated` because it is invisible:
50 *     a reader can see a list stop, but cannot see a source that never replied.
51 *   - **`truncated`** — the list is cut. Never a denominator.
52 *   - **`first-measurement`** — a reading exists, a prior does not. This is the
53 *     one absence that gets the accent colour and a dashed outline, because it
54 *     is the only one a reader can act on. It exists so a metric with no prior
55 *     shows "first measurement" instead of `+0%`.
56 *
57// … truncated