Distribution

1'use client';
2 
3import * as React from 'react';
4 
5// @interlace/distribution v1.1.0 — Interlace design system.
6// Docs, props and live preview: https://ds.interlace.tools/c/distribution
7// What changed since: https://ds.interlace.tools/c/distribution#history
8// Generated banner — keep it, the upgrade diff reads this version.
9 
10/**
11 * @interlace/ui — Distribution
12 *
13 * One quantity spread across a fixed set of bins — hours of the day, days of
14 * the week, cohorts, buckets — with an optional REFERENCE distribution drawn
15 * over it.
16 *
17 * ## Why this is not `TimeSeries` with three more props
18 *
19 * It was attempted that way first. Every part of `TimeSeries` is chronological
20 * in a way that cannot be parameterised out:
21 *
22 *   - its axis keys are `day(t)`, sorted — a calendar. Bins are NAMES, and
23 *     sorting `['Thu','Fri','Sat']` gives `['Fri','Sat','Thu']`, which is a
24 *     week that does not exist;
25 *   - a LINE asserts that the metric passed through every value between two
26 *     samples. Between "readers awake at 14:00" and "readers awake at 15:00"
27 *     there is nothing to pass through — the quantity is an aggregate OF the
28 *     bin, not a sample at an instant;
29 *   - `delta()` — first → last — is the sentence `TimeSeries` speaks, and on a
30 *     cyclical axis the first and last bins are neighbours. "Down 40% from
31 *     00:00 to 23:00" is arithmetic performed on a circle.
32 *
33 * So the marks are BARS from a zero baseline (see `bandScales` for why the
34 * axis cannot be truncated), the axis order is the caller's, and the summary
35 * sentence answers where the peak is rather than which way it went.
36 *
37 * ## The reference is the whole point, and it shares one domain
38 *
39 * A distribution on its own answers "when did this happen". The question worth
40 * asking is almost always "when did this happen *against what was available*"
41 * — reading against readers awake, incidents against traffic, deploys against
42 * working hours. The gap between the bars and the reference IS the finding.
43 *
44 * Both series therefore share ONE y domain, exactly as in `TimeSeries`, and for
45 * the same reason: two axes let an author slide one against the other until
46 * they cross where the argument needs them to. That means the reference must
47 * be in the SAME unit as the bars — usually both as shares of their own
48 * denominator ("% of the week's reading" vs "% of readers awake"). A reference
49// … truncated