@nanisoft/prism-ui 0.10.2 → 0.15.0

package/dist/components/ui/chart-frame.js

@@ -0,0 +1,286 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils.js';
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow, } from './table.js';
+/** The fill a series is drawn in, from the role the caller assigned it. */
+const FILL = {
+    'chart-1': 'bg-chart-1',
+    'chart-2': 'bg-chart-2',
+    'chart-3': 'bg-chart-3',
+    'chart-4': 'bg-chart-4',
+    'chart-5': 'bg-chart-5',
+};
+/** The stroke a line is drawn in, from the same role and no other. */
+const STROKE = {
+    'chart-1': 'stroke-chart-1',
+    'chart-2': 'stroke-chart-2',
+    'chart-3': 'stroke-chart-3',
+    'chart-4': 'stroke-chart-4',
+    'chart-5': 'stroke-chart-5',
+};
+/**
+ * Where a category label is nudged to sit, so a label never hangs off the plot.
+ *
+ * A label is centred on its category, which puts the first and the last half
+ * outside the field. The edge labels are pinned to the edge instead, so a line
+ * whose first and last points are on the boundary have their labels on it too.
+ * A bar's categories are column centres with room on both sides, so every label
+ * is centred.
+ */
+const LABEL_ALIGN = {
+    first: 'translate-x-0',
+    last: '-translate-x-full',
+    middle: '-translate-x-1/2',
+};
+/**
+ * The step a gridline is drawn at: one, two, five or ten times a power of ten.
+ *
+ * The point is that the axis reads 0, 50, 100 rather than 0, 37, 74. A reader
+ * who has to do arithmetic to place a value on an axis is doing the chart's job,
+ * and a gridline at an arbitrary fraction of the range is the first thing that
+ * makes two charts look like they were built by two people.
+ */
+function niceStep(rough) {
+    if (!Number.isFinite(rough) || rough <= 0)
+        return 1;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    const normalised = rough / magnitude;
+    const step = normalised <= 1 ? 1 : normalised <= 2 ? 2 : normalised <= 5 ? 5 : 10;
+    return step * magnitude;
+}
+/** A value that has been through a floor, a multiply and an add, back to a readable number. */
+function tidy(value) {
+    return Number(value.toFixed(10));
+}
+/**
+ * The vertical scale, derived from the values that have somewhere to be drawn.
+ *
+ * **The floor is zero, and that is a claim about bars rather than about lines.**
+ * A bar's length is only a measurement when it starts at a shared baseline, so
+ * the scale always includes zero. The cost is that a line whose values sit
+ * between 900 and 1,000 is drawn almost flat, and the answer to that is a scale
+ * the caller chooses, not a floor this Component drops: a reader who needs to
+ * see the shape of a narrow range reads the table, which carries the numbers at
+ * full precision.
+ *
+ * **A negative value gets a real region below the baseline** rather than a
+ * zero-height bar. A profit-and-loss chart that drew a loss as nothing is a
+ * chart that is confidently wrong, and the cost of the region is one more
+ * gridline. Zero is always one of the lines, because both ends are multiples of
+ * the step, so the baseline is always on the axis and always labelled.
+ *
+ * **A series whose values are all the same number, or all zero, has no range to
+ * divide by.** It is given one step of scale so the field has a top and a
+ * bottom and every mark inside it is a position rather than a NaN.
+ */
+function scaleOf(values) {
+    let lowest = 0;
+    let highest = 0;
+    for (const value of values) {
+        if (!Number.isFinite(value))
+            continue;
+        if (value < lowest)
+            lowest = value;
+        if (value > highest)
+            highest = value;
+    }
+    const step = niceStep((highest - lowest) / 4);
+    const first = Math.floor(lowest / step) * step;
+    // Ceiled rather than rounded, because a rounded count can leave the largest
+    // value above the top gridline, and a mark drawn above its own axis is a mark
+    // off the plot. The epsilon absorbs the float error that would otherwise add a
+    // whole extra gridline to an axis that already lands on one exactly.
+    const count = Math.max(1, Math.ceil((highest - first) / step - 1e-9));
+    const last = first + count * step;
+    const span = last - first;
+    const at = (value) => {
+        const clamped = Math.min(Math.max(value, first), last);
+        return ((last - clamped) / span) * 100;
+    };
+    return {
+        low: first,
+        high: last,
+        lines: Array.from({ length: count + 1 }, (_, index) => tidy(first + index * step)),
+        at,
+        // The bar spans between the value and the zero line, which are the same
+        // point when the value is zero. `at` counts from the top, so the top edge is
+        // whichever of the two is nearer the top and the height is the distance
+        // between them; a positive value therefore grows downward from its own top
+        // edge and a negative one hangs below the baseline.
+        bar: (value) => {
+            const here = at(value);
+            const baseline = at(0);
+            return { top: Math.min(here, baseline), height: Math.abs(here - baseline) };
+        },
+    };
+}
+/**
+ * Where a category sits on the horizontal axis, as a percentage of the field.
+ *
+ * A line's points run from the first category to the last, so the axis is the
+ * gap between them; a single category has no gap to divide by and sits in the
+ * middle, which is the only place a lone category can be read against anything.
+ * A bar's category is a column rather than a point, so its position is the
+ * column's centre, and that is the same reason a bar chart's first bar is not
+ * flush with the axis.
+ */
+function categoryAt(index, total, mark) {
+    if (mark === 'bar')
+        return ((index + 0.5) / total) * 100;
+    if (total <= 1)
+        return 50;
+    return (index / (total - 1)) * 100;
+}
+/** Where a category label is nudged to sit, so no label hangs off the plot. */
+function labelAlign(index, total, mark) {
+    if (mark === 'bar' || total < 2)
+        return LABEL_ALIGN.middle;
+    if (index === 0)
+        return LABEL_ALIGN.first;
+    if (index === total - 1)
+        return LABEL_ALIGN.last;
+    return LABEL_ALIGN.middle;
+}
+/** The default reading of a value: the number itself. */
+function identity(value) {
+    return String(value);
+}
+/**
+ * A chart: the frame every chart in a product shares, and the numbers behind it.
+ *
+ * **One frame is the design.** Five charts that each draw their own axes are
+ * five sets of numbers that do not line up, and a dashboard where two plots
+ * disagree by six pixels looks broken in a way nobody can name, because the
+ * reader cannot see the six pixels: they can only see that the two charts do not
+ * agree. So the axis gutter, the field's height, the gridline spacing and the
+ * category row are all fixed here, and two charts in a row have the same plot box
+ * whatever their data says. The gutter in particular is a fixed width rather than
+ * a width that fits the longest label, because a gutter that grows with the
+ * numbers is the mechanism by which two charts stop aligning.
+ *
+ * **The colour is assigned by the caller and drawn from the token contract.**
+ * `chart-1` through `chart-5` arrive as the five semantic utilities, and there
+ * is no hex, no ramp step and no `rgb()` anywhere in this Component. A series
+ * colour is a claim about what a thing is, so the Component that knows nothing
+ * about the caller's product has no business choosing one.
+ *
+ * **The table is part of the frame, not a prop beside it, and that is the other
+ * half of the design.** A chart whose accessible representation is a sibling
+ * prop is a chart whose table a consumer wrote once and updated when the data
+ * changed, which is to say a chart whose table says last quarter. Here the marks
+ * and the cells are two renderings of one `series` array, so they cannot drift:
+ * there is no second copy to fall behind. The table is always in the document,
+ * and `table` decides whether it is also seen.
+ *
+ * **The legend is always drawn.** It is the only place the series-to-colour
+ * assignment is stated in words, and it is not optional because two of the five
+ * roles measure below 3:1 against a light card: `chart-2` at 2.49:1 and
+ * `chart-3` at 2.15:1 in the default pack. A mark in either is found by its
+ * position and its shape, not by its colour, so the name beside it is what makes
+ * it a series rather than a shape. Past about three series, hue is the only
+ * channel left and the table is the answer, which is a fact about the data and
+ * not about this Component.
+ *
+ * **It is a server Component.** No hook, no state, no effect and no event
+ * handler: the plot is arithmetic over props and the table is a table. A chart
+ * that animated its draw-in would be refused by this system's motion rules, and
+ * the one motion here is a bar resizing when its value changes, which is state
+ * feedback and is the only kind this system allows.
+ *
+ * **What this is not.** There is no scale beyond the one described above, no
+ * tick generation to choose, no hover tooltip, no crosshair, no zoom, no
+ * stacking, no curve interpolation, and no draw-in animation. A tooltip would be
+ * a hover affordance over a picture, and a picture a reader cannot query is the
+ * failure the table exists to prevent, so the exact value is answered by the
+ * table rather than by a surface that appears under a pointer. A consumer that
+ * needs any of those is reaching for a charting library, and this Component is
+ * the frame that library's marks should sit in rather than the library.
+ */
+function ChartFrame({ categories, series, mark = 'line', label, title, tableCaption, categoryHeading, table = 'visible', format = identity, tableFormat = identity, empty, className, ...props }) {
+    // The scale is built from the values that have a category to be drawn against.
+    // A value past the end of the categories is neither drawn nor tabulated, and
+    // letting one into the scale would stretch the axis around a mark that is not
+    // in the picture, which is the quietest way a chart can be wrong.
+    const plotted = series.flatMap((entry) => categories
+        .map((_, index) => entry.values[index])
+        .filter((value) => typeof value === 'number' && Number.isFinite(value)));
+    const heading = title === undefined ? null : (_jsx("figcaption", { "data-slot": "chart-title", className: "text-sm font-medium", children: title }));
+    if (plotted.length === 0) {
+        // The empty state keeps the height of the field it replaces. A chart whose
+        // empty state is one line of text is a row on a dashboard that changes height
+        // when its data arrives, and the row that moves is the row the reader was
+        // looking at.
+        return (_jsxs("figure", { "data-slot": "chart-frame", "aria-label": label, className: cn('flex w-full flex-col gap-3', className), ...props, children: [heading, _jsx("div", { "data-slot": "chart-empty", className: "text-muted-foreground flex h-48 items-center justify-center rounded-md border border-dashed text-sm", children: empty ?? null })] }));
+    }
+    const scale = scaleOf(plotted);
+    const total = categories.length;
+    return (_jsxs("figure", { "data-slot": "chart-frame", "aria-label": label, className: cn('flex w-full flex-col gap-3', className), ...props, children: [heading, _jsxs("div", { "data-slot": "chart-plot", className: "flex flex-col gap-3", children: [_jsxs("div", { "data-slot": "chart-plot-row", className: "flex items-stretch gap-2", children: [_jsx("div", { "data-slot": "chart-axis-y", className: "relative w-14 shrink-0", children: scale.lines.map((value) => (_jsx("span", { "data-slot": "chart-tick", className: "text-muted-foreground absolute right-0 -translate-y-1/2 text-xs tabular-nums", style: { top: `${scale.at(value)}%` }, children: format(value) }, value))) }), _jsxs("div", { "data-slot": "chart-field", className: "relative h-48 flex-1", children: [scale.lines.map((value) => (_jsx("span", { "data-slot": "chart-gridline", "aria-hidden": "true", className: "border-border absolute inset-x-0 border-t", style: { top: `${scale.at(value)}%` } }, value))), mark === 'bar' ? (
+                                    /*
+                                     * One column per category, each holding one bar per series, so the
+                                     * series are side by side inside a category rather than stacked
+                                     * across the whole field. The column is a flex child, so a plot 600
+                                     * pixels wide and a plot 240 pixels wide divide the same way, which
+                                     * is the other half of the alignment claim.
+                                     */
+                                    _jsx("div", { "data-slot": "chart-columns", "aria-hidden": "true", className: "absolute inset-0 flex", children: categories.map((_, column) => (_jsx("div", { "data-slot": "chart-column", className: "relative flex-1", children: series.map((entry, seriesIndex) => {
+                                                const value = entry.values[column];
+                                                if (typeof value !== 'number' || !Number.isFinite(value))
+                                                    return null;
+                                                const { top, height } = scale.bar(value);
+                                                const slot = 100 / series.length;
+                                                return (_jsx("span", { "data-slot": "chart-bar", "data-series": entry.id, "aria-hidden": "true", className: cn('absolute transition-[top,height] duration-base ease-out', value < 0 ? 'rounded-b-sm' : 'rounded-t-sm', FILL[entry.color]), style: {
+                                                        // The one-pixel inset on each side is the gap between
+                                                        // neighbouring series. A pixel rather than a
+                                                        // percentage, because a percentage of a narrow column
+                                                        // is less than a pixel, and a gap nobody can see is a
+                                                        // grouping the colour has to carry on its own.
+                                                        left: `calc(${seriesIndex * slot}% + 1px)`,
+                                                        width: `calc(${slot}% - 2px)`,
+                                                        top: `${top}%`,
+                                                        height: `${height}%`,
+                                                    } }, entry.id));
+                                            }) }, column))) })) : (series.map((entry) => {
+                                        const points = categories
+                                            .map((_, index) => ({ index, value: entry.values[index] }))
+                                            .filter((point) => typeof point.value === 'number' && Number.isFinite(point.value));
+                                        if (points.length === 0)
+                                            return null;
+                                        const place = (point) => ({
+                                            x: categoryAt(point.index, total, mark),
+                                            y: scale.at(point.value),
+                                        });
+                                        return (_jsxs("div", { "data-slot": "chart-line", "data-series": entry.id, className: "contents", children: [points.length > 1 ? (
+                                                /*
+                                                 * The stroke is drawn as one `line` per pair of points, in
+                                                 * percentages of the plot box, inside an `svg` with no
+                                                 * `viewBox`. That is deliberate on both counts. No `viewBox`
+                                                 * means no coordinate system to stretch, so a 2-pixel stroke
+                                                 * is 2 pixels rather than 2 units in a box that was scaled
+                                                 * unevenly, and it is why no `vector-effect` is needed
+                                                 * either. Percentages mean a mark's position is a share of
+                                                 * the plot box and not a number the caller has to agree on.
+                                                 *
+                                                 * One `line` per pair rather than a `polyline` is the
+                                                 * other half, and it is a constraint rather than a
+                                                 * preference: a Component here ships no reader-facing
+                                                 * string, and a polyline's `points` is a list of coordinate
+                                                 * pairs joined by a space, which is a word-shaped literal in
+                                                 * a Component. Rounded caps on each segment meet at the
+                                                 * joints as a 2-pixel circle, which is what a rounded line
+                                                 * join draws anyway.
+                                                 */
+                                                _jsx("svg", { "aria-hidden": "true", className: "pointer-events-none absolute inset-0 size-full overflow-visible", children: points.slice(1).map((point, index) => {
+                                                        const from = place(points[index]);
+                                                        const to = place(point);
+                                                        return (_jsx("line", { x1: `${from.x}%`, y1: `${from.y}%`, x2: `${to.x}%`, y2: `${to.y}%`, className: STROKE[entry.color], strokeWidth: 2, strokeLinecap: "round" }, point.index));
+                                                    }) })) : null, points.map((point) => (_jsx("span", { "data-slot": "chart-point", "data-series": entry.id, "aria-hidden": "true", className: cn('absolute size-2 -translate-x-1/2 -translate-y-1/2 rounded-full', FILL[entry.color]), style: {
+                                                        left: `${categoryAt(point.index, total, mark)}%`,
+                                                        top: `${scale.at(point.value)}%`,
+                                                    } }, point.index)))] }, entry.id));
+                                    }))] })] }), _jsxs("div", { "data-slot": "chart-axis-x-row", className: "flex items-stretch gap-2", children: [_jsx("span", { "data-slot": "chart-axis-x-gutter", "aria-hidden": "true", className: "w-14 shrink-0" }), _jsx("div", { "data-slot": "chart-axis-x", className: "relative h-4 flex-1", children: categories.map((category, index) => (_jsx("span", { "data-slot": "chart-category", className: cn('text-muted-foreground absolute top-0 max-w-20 truncate text-xs', labelAlign(index, total, mark)), style: { left: `${categoryAt(index, total, mark)}%` }, children: category }, index))) })] })] }), _jsx("ul", { "data-slot": "chart-legend", className: "text-muted-foreground flex flex-wrap gap-x-4 gap-y-1 text-xs", children: series.map((entry) => (_jsxs("li", { "data-slot": "chart-legend-entry", className: "flex items-center gap-1.5", children: [_jsx("span", { "data-slot": "chart-swatch", "aria-hidden": "true", className: cn('size-2.5 shrink-0 rounded-sm', FILL[entry.color]) }), entry.label] }, entry.id))) }), _jsx("div", { "data-slot": "chart-table", className: table === 'visible' ? undefined : 'sr-only', children: _jsxs(Table, { children: [_jsx(TableCaption, { children: tableCaption }), _jsx(TableHeader, { children: _jsxs(TableRow, { children: [_jsx(TableHead, { className: "w-32", children: categoryHeading }), series.map((entry) => (_jsx(TableHead, { className: "text-right tabular-nums", children: entry.label }, entry.id)))] }) }), _jsx(TableBody, { children: categories.map((category, index) => (_jsxs(TableRow, { children: [_jsx(TableHead, { scope: "row", className: "font-medium", children: category }), series.map((entry) => {
+                                        const value = entry.values[index];
+                                        return (_jsx(TableCell, { className: "text-right tabular-nums", "data-series": entry.id, children: typeof value === 'number' && Number.isFinite(value)
+                                                ? tableFormat(value)
+                                                : null }, entry.id));
+                                    })] }, index))) })] }) })] }));
+}
+export { ChartFrame };

package/dist/components/ui/chart.d.ts

@@ -0,0 +1,334 @@
+import type { ReactNode } from 'react';
+import type { ChartColor } from './chart-frame.js';
+/**
+ * The marks this Component draws.
+ *
+ * This is the one place in the package where the word is a prop rather than a
+ * catalogue unit, and the shape of the type is the reason that is allowed.
+ * DESIGN.md's export surface says a component takes `variant` and `size` props
+ * and that what it will not publish is a variant recipe: a raw map of class
+ * strings is a CSS recipe wearing a component's name, and a consumer who
+ * receives one has been handed a styling API to memorise. So the value is a
+ * closed set of four marks, each a machine value the drawing branches on, and
+ * the class strings stay here where the drawing is. A caller picks a mark; a
+ * caller does not pick a colour, a radius, a shadow and a border width to get
+ * one.
+ *
+ * `bar` and `line` are the pair `ChartFrame` already separates, and the
+ * separation is about what the reader compares rather than about taste. A line
+ * is for a value that moves continuously across the categories, where the shape
+ * between two points is the point. A bar is for a value read against a shared
+ * baseline, where the length is the measurement and the gap between two bars
+ * means nothing. `area` is the line with the region under it filled, which
+ * changes what the reader is asked to do: a line asks where it went and an area
+ * asks how much there was. `donut` is a part-to-whole, and it is the narrowest
+ * of the four; read `Chart` for why it is here at all.
+ *
+ * **The type is `ChartForm` and the prop is `variant`, and the two names
+ * differing is the gate working rather than a slip.** `check-surface.mjs` refuses
+ * to let a public entry export a name ending in `Variant`, because in this
+ * package that shape means a cva map: a recipe a consumer could read and compose
+ * with. This union is not a recipe, it is the closed set of marks a drawing
+ * branches on, and it is named for the marks rather than for the prop. The prop
+ * keeps the name `variant` because a Component is allowed to take one, which is
+ * the distinction `DESIGN.md`'s export surface draws: the prop is an input, a
+ * `*Variants` export is an API. `MeterTone`, `StatusTone` and `AnnouncementTone`
+ * are named the same way for the same reason.
+ */
+export type ChartForm = 'bar' | 'line' | 'area' | 'donut';
+/**
+ * One series: what it is called, its values, and the role it is drawn in.
+ *
+ * `tone` is `ChartColor`, imported from `chart-frame` rather than redeclared
+ * here, and that import is the whole contract. `chart-1` through `chart-5` is
+ * the only five-way colour set the token contract publishes, so a consumer who
+ * wants a particular series in a particular colour names the role and gets it
+ * in every pack and both modes. A Prism-specific alias spelled differently here
+ * would be a wider type, a wider type would be a wider palette, and a wider
+ * palette is a second source of truth for something the tokens already own.
+ * `chart-frame.tsx` states the same reasoning on its own type and this file
+ * takes the same answer rather than a parallel one, which is the only way two
+ * Components in one package end up agreeing about what `chart-3` is.
+ *
+ * **The name is `ChartData` and not `ChartSeries`, and the reason is a collision
+ * rather than a preference.** `chart-frame.tsx` already exports a `ChartSeries`,
+ * a time series with nullable points, and it shipped: it is in the catalogue at
+ * `0.13.0` and a consumer reaches it at
+ * `@nanisoft/prism-ui/components/chart-frame`. A published type cannot be
+ * renamed cheaply, so this file took the other name. `ChartData` says what an
+ * entry is, which is a measured column with a name and a tone, and the two types
+ * are close enough that a reader who meets both will assume they are the same
+ * one. They are not, and the honest place to say so is here.
+ */
+export type ChartData = {
+    /**
+     * The name of the series, in the caller's words.
+     *
+     * It appears in the legend and in the head of the table's column, and nowhere
+     * else. This is the string that makes a colour a name: a chart drawn in
+     * `chart-2` and `chart-5` is unreadable to anyone who cannot separate teal
+     * from red, and `chart-2` measures 2.49:1 against a light card, which is a
+     * second reason the legend is not decoration.
+     */
+    name: string;
+    /**
+     * One value per category, in the order the categories are given.
+     *
+     * `labels` on `Chart` is the array that says what a category is, and a value
+     * with no label is a value drawn against nothing. A series longer than the
+     * labels is drawn past the last category and clipped by its own field, and it
+     * does not widen the field either, because a value with no category has
+     * nowhere to be drawn.
+     */
+    values: number[];
+    /**
+     * The role this series is drawn in. Omitted, the series is drawn in the
+     * supporting ink rather than in a series role.
+     *
+     * The default is not `chart-1` and the reason is `chart-frame`'s: a series
+     * colour is a claim about what a thing is, and a Component that picked by
+     * position would be making that claim on the caller's behalf and getting it
+     * wrong on every chart after the first. Handing out the five roles in order
+     * would put five names on a chart whose caller never named any of them, and a
+     * reader who has learned that `chart-1` is revenue in one product would carry
+     * that into the next. So an unnamed series takes `muted-foreground`, which is
+     * the ink for a mark that supports a claim rather than making one, and a
+     * chart whose series all omit `tone` is visibly a shape rather than five
+     * things. Naming the tone is how a caller says the series are meant to be
+     * told apart, and the cost of that is stated on the prop: two of the five
+     * roles measure below 3:1 against a light card, so a name beside every mark is
+     * not optional once hue is doing work.
+     */
+    tone?: ChartColor;
+};
+/** The props the Chart accepts. */
+export interface ChartProps {
+    /** The series drawn, in the order their marks are drawn and their names are read. */
+    series: readonly ChartData[];
+    /**
+     * The mark the series are drawn with.
+     *
+     * Required, and defaulted by nothing, because the mark is the claim the chart
+     * makes about the data and a default would be this Component making it. A
+     * chart of weekly signups drawn as bars invites a comparison of lengths that
+     * only means something when the value starts at zero, and a caller who never
+     * thought about the mark is exactly the caller who gets that wrong.
+     */
+    variant: ChartForm;
+    /**
+     * The categories along the horizontal axis, in order. The caller's words.
+     *
+     * A month name, a release name, a region name, a build number. This is the
+     * array that makes a chart a claim about the caller's own domain rather than
+     * about a design system, which is why it is a prop and not a date range the
+     * Component generates: a chart that named its own months would be wrong in
+     * every product but the one it was written for. It is drawn for `bar` and
+     * `line` only, and read on the table for every variant.
+     */
+    labels?: readonly string[];
+    /**
+     * The accessible name of the figure, and the only name the marks carry.
+     *
+     * Required rather than defaulted, because two charts on a dashboard are two
+     * figures a reader cannot tell apart, and because the name is the only thing
+     * that states what is being plotted. A figure named "Chart" is a Component
+     * shipping a sentence about a product it knows nothing about.
+     */
+    label: string;
+    /**
+     * The height of the plot field, in pixels. @defaultValue 240
+     *
+     * The default is `h-60` on the authored scale, so the figure a caller gets by
+     * passing nothing lands on the spacing and type scale rather than beside it.
+     * A number rather than a `size` prop because the value is the plot box's
+     * proportion rather than a size of the component: the same component at three
+     * heights is one component, and a `size` that doubled the plot and the gutter
+     * together would be a different claim.
+     */
+    height?: number;
+    /**
+     * Whether the legend is drawn. @defaultValue true when there is more than one series
+     *
+     * The default is a function of the series count rather than a constant,
+     * because the legend has two jobs and only one of them is a key. With one
+     * series there is nothing to tell apart, so the legend would be a name beside
+     * a caption and it is left off. With two or more it is the only statement of
+     * the series-to-colour assignment anywhere on the figure, and that is not
+     * optional: `chart-2` measures 2.49:1 and `chart-3` 2.15:1 against a light
+     * card in the default pack, so a mark in either is found by its position and
+     * its shape rather than by its colour, and the name beside it is what makes it
+     * a series. Pass `false` to put the legend somewhere else: `ChartLegend` is
+     * its own export for exactly that, and a legend under a legend is a
+     * component's fixed layout costing a layout the caller wanted.
+     */
+    legend?: boolean;
+    /**
+     * The sentence the chart needs underneath it.
+     *
+     * The caller's words, because the sentence is a claim about the data and only
+     * the caller knows which one is true: a fall, a seasonal dip, a collection
+     * that changed, a filter that matched nothing. This Component ships none, and
+     * a chart whose meaning is in a sentence the Component wrote is a chart whose
+     * meaning is wrong in every product but one.
+     */
+    caption?: ReactNode;
+    /**
+     * The top of the vertical axis, for `bar`, `line` and `area`. Omitted, the
+     * axis is derived from the data.
+     *
+     * The opt-in exists because one case genuinely needs it: a line whose values
+     * sit between 900 and 1,000 is drawn almost flat when the floor is zero, and
+     * the reader wants the shape. What it costs is named in `Chart`, and it is not
+     * only the flatness it fixes. A caller who normalises a dataset to start the
+     * axis themselves has two chances to get the axis wrong rather than one, and
+     * a mislabelled axis is a lie with a typeface on it: the numbers come from the
+     * caller, the words on the axis are the ones a reader reads, and nothing joins
+     * them. So this is one number and not a pair, the floor stays at zero, and a
+     * value above the ceiling is drawn clamped to the top gridline and counted on
+     * the element as `data-clamped`, so a ceiling that is too low is a fact in the
+     * markup rather than a mark floating above its own axis.
+     */
+    yMax?: number;
+    /**
+     * The content at the centre of a `donut`, which is where the total goes.
+     *
+     * A `ReactNode` rather than a number because the number is usually not the
+     * total: it is the total in a currency, the total as a percentage of a target,
+     * or the total with a unit and a comparison beside it. Computing any of those
+     * here would be this Component shipping a sentence about a product it knows
+     * nothing about, so it takes the caller's rendering and positions it in the
+     * hole. It is drawn over the ring rather than inside the `<svg>`, so type in a
+     * scaled viewBox is not a thing anyone has to think about.
+     */
+    centreLabel?: ReactNode;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}
+/**
+ * A chart: the marks, the axes, and the numbers behind them.
+ *
+ * **The chart is never the only way to read the numbers.** That is the
+ * constraint worth making, and it is a constraint on the caller as much as on
+ * this Component. The argument is the one `carousel.tsx` makes about everything
+ * a carousel shows: everything this Component draws, a reader must be able to
+ * reach some other way, because a chart is a picture whose entire content is a
+ * position, and a position is the one thing a screen reader, a crawler and a
+ * print stylesheet cannot read. There is a concrete failure behind each of
+ * them. A screen reader given a `<figure>` full of rectangles is read a list of
+ * nothing. A crawler sees the labels and the marks and no values at all, so
+ * every figure a product site publishes is invisible to the thing that indexes
+ * it. A print stylesheet loses the channel the series were separated by, and
+ * two of the five roles measure below 3:1 on a light card and go to the same
+ * grey, so a printed chart is a chart where the legend is the only difference
+ * between two lines.
+ *
+ * So the marks and the cells are two renderings of one `series` array rather
+ * than a chart and a table a caller kept in step, and the table is in the
+ * document whether or not anybody can see it. A `<table>` with a `<caption>`,
+ * a row head for each category and a column head for each series, so a reader
+ * navigates it by row and by cell and hears the figures the marks are drawn
+ * from. The alternative was a `table` prop, and the reasoning against it is
+ * `chart-frame`'s: a chart whose accessible representation is a sibling prop is
+ * a chart whose table a consumer wrote once and updated when the data changed,
+ * which is to say a chart whose table says last quarter. There is no prop that
+ * turns it off, because a prop is a default and the default would be off and
+ * the failure would be invisible.
+ *
+ * **There is no hover tooltip, and that is the same argument from the other
+ * side.** A tooltip is the usual answer to the exact value, and it answers a
+ * question a pointer asked, which is a question a keyboard never asks and a
+ * print stylesheet cannot receive. A picture a reader cannot query is the
+ * failure the table exists to prevent, so the exact value is answered by the
+ * table rather than by a surface that appears under a pointer.
+ *
+ * **The geometry does not move.** There is no draw-in, no bar that grows, no
+ * transition on any of the marks, and the reason is that the motion law refuses
+ * entrance effects outright, so a chart would not need an argument to be
+ * refused: a bar arriving is decoration, and the reader was not waiting for it.
+ * There is also no reason for one. A bar's height is its value, and a value
+ * that changes is the caller rendering a different number, so a transition
+ * between two values is a transition between two facts, and a reader watching
+ * one arrive has learned nothing they could not have read from the second one.
+ * This is a server Component: no hook, no state, no effect, and the whole
+ * figure is arithmetic over props, which is why `check-client-budget` has no
+ * reason to know it exists.
+ *
+ * **The axis is derived and a caller's maximum is opt-in.** Prism does not take
+ * a vertical maximum by default, and the reason is specific: a caller who
+ * pre-normalises has two chances to get the axis wrong rather than one. They
+ * compute the maximum, and then they label the gridlines, and a mistake in
+ * either step is invisible in the rendered chart because the picture is drawn
+ * perfectly faithfully to the wrong number. A mislabelled axis is a lie with a
+ * typeface on it, and it is a worse lie than a flat line because a flat line
+ * looks like a flat line. `yMax` exists for the one case that genuinely needs
+ * it, a line in a narrow band high on the scale that the reader wants to see
+ * the shape of, and it costs what the prop says: the caller owns the top, a
+ * value above it is clamped to the top gridline and counted on the element as
+ * `data-clamped`, and a ceiling that is not a multiple of the step leaves a
+ * shorter band at the top. The floor stays at zero whatever is passed, because
+ * a bar measured from anywhere but the baseline is not a measurement.
+ *
+ * **The donut is here for one shape of data, and the shape is named.** A bar
+ * chart is the honest default: it is read as lengths against a common baseline,
+ * it is the mark that survives greyscale, and it holds up at eight parts where a
+ * ring does not. What it is bad at is a part-to-whole with two or three parts,
+ * because there the reader is not comparing lengths, they are reading a
+ * proportion, and two lengths that must be mentally added are the harder task.
+ * A ring answers "what share is this" in one glance where the bars answer it
+ * after a division, and the centre answers the total the reader then wants
+ * anyway. So the variant exists for that condition and refuses everything else:
+ * `donut` takes exactly two series with one value each, or one series with a
+ * single value, which is the same claim with nothing to divide. At three parts
+ * the ring stops being read as a proportion and starts being read as a puzzle,
+ * and a ring that a reader has to count the segments of is worse than three
+ * bars. Naming the condition is the point: an unmarked donut prop would let the
+ * choice be casual, and a casual donut is a pie with nine slices in a
+ * dashboard.
+ *
+ * **The five series roles are the token contract's, not this file's.** `tone` is
+ * `ChartColor` from `chart-frame`, for the reason that type's own documentation
+ * gives: `chart-1` through `chart-5` is the only five-way set the contract
+ * publishes, so a wider type here would be a wider palette and a second source
+ * of truth for something the tokens already own. Every stroke and every fill
+ * below is one of those roles, `muted-foreground`, `muted`, `foreground` or
+ * `border`, named as a utility so a scoped `data-pack` boundary above the
+ * figure restyles all of it through the cascade. The gridlines are `border`,
+ * which is the contract's own low emphasis, rather than a lighter value invented
+ * here, and there is no gradient: a gradient of contract stops would be allowed
+ * and there is no decision behind one.
+ *
+ * **What this is not.** There is no axis a caller can log, no second axis, no
+ * stacking, no curve interpolation, no zoom, no crosshair, and no per-point
+ * mark on a line. A distribution, a ranking, a correlation and a histogram are
+ * a charting library's work, and this Component is the frame and the table that
+ * library's marks should sit inside rather than the library.
+ */
+declare function Chart({ series, variant, labels, label, height, legend, caption, yMax, centreLabel, className, }: ChartProps): import("react").JSX.Element;
+/**
+ * A legend: a swatch and a name for each series, and nothing else.
+ *
+ * Its own export rather than a fixed position under the plot, because a legend
+ * is a layout decision the surrounding design usually has an opinion about. A
+ * chart in a dashboard card, in a full-width figure between two paragraphs, and
+ * beside a key in a table of figures are three different places, and a Component
+ * that fixed one of them made the other two a workaround. So `Chart` draws it
+ * where the figure puts it and a caller who needs it elsewhere passes
+ * `legend={false}` and renders this with the same `series` array, which is the
+ * only reason the swatch and the mark cannot disagree.
+ *
+ * It is a `<ul>` rather than a `<div>` of spans, so a reader moving by list
+ * item is told how many series there are, and each entry is a swatch and a name
+ * with the swatch hidden, because a screen reader has no use for a colour and
+ * announcing one would replace the name with the thing the name is there to
+ * avoid. The same warning applies to a printed legend: two of the five roles go
+ * to the same grey on paper, so the legend is what tells a printed chart's
+ * series apart rather than an addition to it.
+ */
+declare function ChartLegend({ series, className, }: {
+    /** The series to name, in the order their marks are drawn. */
+    series: readonly ChartData[];
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+}): import("react").JSX.Element;
+export { Chart, ChartLegend };
+//# sourceMappingURL=chart.d.ts.map

package/dist/components/ui/chart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chart.d.ts","sourceRoot":"","sources":["../../../src/components/ui/chart.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAW/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB;;;;;;;;OAQG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;;;;OAQG;IACH,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;;;;;;;;;;;;;;;OAiBG;IACH,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB,CAAA;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU;IACzB,qFAAqF;IACrF,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B;;;;;;;;OAQG;IACH,OAAO,EAAE,SAAS,CAAA;IAClB;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;;;;;;OAOG;IACH,KAAK,EAAE,MAAM,CAAA;IACb;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;;;;;;;;;;OAeG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAySD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkGG;AACH,iBAAS,KAAK,CAAC,EACb,MAAM,EACN,OAAO,EACP,MAAM,EACN,KAAK,EACL,MAAY,EACZ,MAAM,EACN,OAAO,EACP,IAAI,EACJ,WAAW,EACX,SAAS,GACV,EAAE,UAAU,+BA6SZ;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,iBAAS,WAAW,CAAC,EACnB,MAAM,EACN,SAAS,GACV,EAAE;IACD,8DAA8D;IAC9D,MAAM,EAAE,SAAS,SAAS,EAAE,CAAA;IAC5B,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,+BAkBA;AAED,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,CAAA"}