@nanisoft/prism-ui 0.8.0 → 0.10.0

package/dist/components/ui/pulse-graph.js

@@ -0,0 +1,212 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils';
+/**
+ * The canvas the graph draws into, in its own user units.
+ *
+ * A fixed canvas rather than a viewBox derived from the caller's numbers, for
+ * the reason `Diagram` gives: type inside a scaled SVG is sized in the SVG's
+ * own user units, so a viewBox derived from a caller's coordinates would make
+ * the label size a function of how large a number the caller happened to use.
+ */
+const CANVAS_WIDTH = 640;
+const CANVAS_HEIGHT = 360;
+/**
+ * The band left empty around the fitted points, in user units.
+ *
+ * Wider than `Diagram`'s, and the extra is on the bottom rather than split. A
+ * pulse graph is read as a sequence running left to right, so the bottom band
+ * carries the rail, the lane marks and the stage names set under them, and all
+ * three are horizontal extents that a graph with more vertical spread would
+ * collide with. Reserving it once here is cheaper than every caller learning
+ * where not to put a node.
+ */
+const PADDING = 56;
+/** The node mark's radius. A circle, so no corner radius for the pack to move. */
+const NODE_RADIUS = 6;
+/**
+ * Type sizes, in user units rather than in `rem`.
+ *
+ * The authored type scale is in `rem` and cannot be used inside a viewBox, where
+ * a font size is a coordinate and not a length on the page. These are geometry,
+ * the one thing Tailwind stays authoritative for.
+ */
+const NODE_NAME_SIZE = 13;
+const NODE_NAME_OFFSET = 22;
+const NODE_NOTE_SIZE = 10;
+const NODE_NOTE_OFFSET = 35;
+/**
+ * The rail the marker rides, in user units, measured from the bottom of the
+ * fitted area.
+ *
+ * It is a separate element from the edges because it is a different claim: the
+ * edges say what connects to what, and the rail says there is an order. A graph
+ * whose nodes are not in lanes has no rail, which is why this is drawn from the
+ * lane count rather than always being present.
+ */
+const RAIL_OFFSET = 74;
+const RAIL_THICKNESS = 1.5;
+/**
+ * The caller's points, fitted into the canvas with their aspect ratio kept and
+ * the leftover shared out evenly.
+ *
+ * A caller whose points span one axis only, or who passes a single node, gets
+ * the other axis centred rather than a division by zero.
+ */
+function fit(nodes) {
+    if (nodes.length === 0)
+        return () => ({ x: CANVAS_WIDTH / 2, y: CANVAS_HEIGHT / 2 });
+    const xs = nodes.map((node) => node.x);
+    const ys = nodes.map((node) => node.y);
+    const minX = Math.min(...xs);
+    const minY = Math.min(...ys);
+    const spanX = Math.max(...xs) - minX;
+    const spanY = Math.max(...ys) - minY;
+    const roomX = CANVAS_WIDTH - PADDING * 2;
+    const roomY = CANVAS_HEIGHT - PADDING * 2;
+    const scale = Math.min(spanX === 0 ? Number.POSITIVE_INFINITY : roomX / spanX, spanY === 0 ? Number.POSITIVE_INFINITY : roomY / spanY);
+    const unit = Number.isFinite(scale) && scale > 0 ? scale : 1;
+    const offsetX = PADDING + (roomX - spanX * unit) / 2 - minX * unit;
+    const offsetY = PADDING + (roomY - spanY * unit) / 2 - minY * unit;
+    return (node) => ({ x: node.x * unit + offsetX, y: node.y * unit + offsetY });
+}
+/**
+ * The lanes present, in ascending order.
+ *
+ * A lane number is the caller's own indexing and is not required to start at
+ * zero or to be contiguous, so the set is derived and sorted rather than
+ * assumed. A caller that skipped a lane gets a rail with the lanes it named
+ * and no invented one between them, which is the only answer that does not
+ * draw a stage that is not there.
+ */
+function lanesOf(nodes) {
+    return [...new Set(nodes.flatMap((node) => (node.lane === undefined ? [] : [node.lane])))].sort((a, b) => a - b);
+}
+/**
+ * A three-stop stagger for the ambient cycles.
+ *
+ * A figure of nodes that all breathe on the same beat is a heartbeat, and a
+ * heartbeat is decoration: it is the same signal everywhere and so it carries
+ * no information about this system. Offsetting by lane means the rhythm runs
+ * along the rail instead, which is a claim about the sequence. The classes are
+ * the three the stylesheet publishes, chosen by lane position rather than by
+ * anything about the node, so a caller cannot accidentally author an
+ * unsynchronised field.
+ */
+function stagger(lane) {
+    return ['prism-ambient-delay-1', 'prism-ambient-delay-2', 'prism-ambient-delay-3'][Math.abs(lane) % 3];
+}
+/**
+ * A graph of named things, the relations between them, and a marker travelling
+ * the sequence.
+ *
+ * This is the Component the four NaniSoft product sites each lost when they
+ * moved off the retired line, rebuilt rather than recovered. Their old heroes
+ * drew the right thing, in the wrong way: a `<canvas>` with a
+ * `requestAnimationFrame` loop, its colours read out of the DOM once at mount,
+ * and numbers invented by a sine hash so the drawing would have something to
+ * show. Every part of that was a defect with a real cost, and this file is the
+ * argument for each of them in turn.
+ *
+ * **It is a server Component.** No `'use client'`, no hook, no effect, no
+ * context, no runtime. The motion is CSS on the server-rendered markup, so a
+ * consumer gets a running figure in a static export with zero bytes of
+ * JavaScript, and `check-client-budget.mjs` keeps it off the client roster. The
+ * old heroes needed a client runtime on a static-export site; this one needs
+ * nothing.
+ *
+ * **It is SVG, not a canvas, and that is the pack-boundary reason.** A canvas
+ * paints pixels it has already resolved, and a `data-pack` boundary is an
+ * attribute on an ancestor, so a resolved value does not move when the pack
+ * beneath it does. Every stroke and fill below names a semantic token as a
+ * utility, so a scoped pack boundary above the drawing restyles it through the
+ * cascade exactly as it restyles a heading. This is why `check-vector-ink.mjs`
+ * scans this file.
+ *
+ * **Nothing is hidden and nothing waits.** No rule sets `opacity: 0`; the
+ * figure is complete and fully legible at first paint; and the animation only
+ * moves things that are already visible. A reader with scripting off, a slow
+ * connection, a print stylesheet, or a crawler sees the whole drawing. The
+ * reduced-motion block in the stylesheet is one `animation: none`, and because
+ * every element's resting state is its full form, that reader gets the same
+ * figure, still. This is the `hidden-state` gate's requirement met by the
+ * design rather than by an exception, which is why a consumer needs no
+ * exception to enable it.
+ *
+ * **The motion is the token scale's.** Every `prism-ambient-*` class reads its
+ * length from `var(--ambient-*)`; nothing in this file states a duration, an
+ * easing, or a keyframe name in a shorthand. The one distance this file does set
+ * is a geometry length in user units, because the keyframe that consumes it
+ * translates by a distance and that distance is a property of this drawing's
+ * coordinates rather than a timing.
+ *
+ * **What it will not do.** It does not invent data. The old canvas filled itself
+ * with a sine hash, and every site that shipped it inherited a chart of numbers
+ * nobody collected; a reader who screenshotted one and read the axis got a lie
+ * with a real typeface on it. Here, a node is a node a caller named, an edge is
+ * an edge a caller declared, and an empty graph is an empty graph. The motion
+ * says a system is running. It does not say what the numbers were.
+ *
+ * **The rail.** Nodes carrying a `lane` are stages of one sequence, and the
+ * graph draws a rail under them with a marker travelling it, so the order is
+ * visible as an order rather than inferred from left-to-right spacing. Nodes
+ * with no lane are a field: no rail, no marker, and every node present from the
+ * first frame. A graph may have both, and the rail then describes only the lanes
+ * that exist.
+ *
+ * **Accessibility.** `role="img"` with the `label` the caller passes, the same
+ * contract `Diagram` holds. Everything inside a `role="img"` is presentational,
+ * so node names and notes are drawn for sighted readers and the surrounding
+ * sentence is what a screen reader gets. Pass `decorative` when that sentence
+ * already says what the drawing shows.
+ *
+ * Positions are the caller's. The Component fits and draws, and it does not lay
+ * out a graph, so it cannot know that two labels will not collide. A relation
+ * naming a node that is not in `nodes` is dropped and counted on the element.
+ */
+function PulseGraph({ nodes, relations = [], label, decorative = false, className, }) {
+    const place = fit(nodes);
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const lanes = lanesOf(nodes);
+    const drawn = relations.flatMap((relation) => {
+        const from = byId.get(relation.from);
+        const to = byId.get(relation.to);
+        return from && to ? [{ relation, from: place(from), to: place(to) }] : [];
+    });
+    /**
+     * The rail's two ends, taken from the lanes that exist rather than from the
+     * canvas. A rail as wide as the canvas regardless of where the nodes are would
+     * say the sequence continues past its first and last stage, which is a claim
+     * about a caller's data that the caller did not make.
+     */
+    const railNodes = nodes.filter((node) => node.lane !== undefined);
+    const railAt = railNodes.length
+        ? {
+            x0: Math.min(...railNodes.map((node) => place(node).x)) - NODE_RADIUS - 10,
+            x1: Math.max(...railNodes.map((node) => place(node).x)) + NODE_RADIUS + 10,
+        }
+        : null;
+    const railY = CANVAS_HEIGHT - RAIL_OFFSET;
+    return (_jsxs("svg", { "data-slot": "pulse-graph", "data-unresolved-relations": relations.length - drawn.length, "data-lanes": lanes.length, viewBox: `0 0 ${CANVAS_WIDTH} ${CANVAS_HEIGHT}`, xmlns: "http://www.w3.org/2000/svg", role: decorative ? undefined : 'img', "aria-label": decorative ? undefined : label, "aria-hidden": decorative || undefined, className: cn('h-auto w-full', className), children: [railAt ? (_jsxs("g", { "data-slot": "pulse-graph-rail", children: [_jsx("line", { "data-slot": "pulse-graph-rail-line", x1: railAt.x0, y1: railY, x2: railAt.x1, y2: railY, strokeWidth: RAIL_THICKNESS, className: "stroke-border" }), _jsx("g", { "data-slot": "pulse-graph-marker", className: "prism-ambient-travel prism-ambient-delay-1", style: { '--ambient-travel-distance': `${railAt.x1 - railAt.x0}px` }, children: _jsx("rect", { x: railAt.x0 - 2.5, y: railY - 2.5, width: 5, height: 5, rx: 2.5, className: "fill-brand-ink" }) })] })) : null, drawn.map(({ relation, from, to }) => (_jsxs("g", { "data-slot": "pulse-graph-relation", "data-relation": `${relation.from}-${relation.to}`, "data-carries": relation.carries || undefined, children: [_jsx("line", { x1: from.x, y1: from.y, x2: to.x, y2: to.y, strokeWidth: 1, strokeDasharray: relation.indirect ? '4 4' : undefined, className: "stroke-muted-foreground/50 fill-none" }), relation.carries
+                        ? (() => {
+                            const dx = to.x - from.x;
+                            const dy = to.y - from.y;
+                            const length = Math.hypot(dx, dy);
+                            if (length === 0)
+                                return null;
+                            // The head sits back from the target mark so it never overlaps
+                            // it, and is scaled to the line's own length so a short edge and
+                            // a long one get the same size head rather than a stretched one.
+                            const inset = NODE_RADIUS + 4;
+                            const ux = dx / length;
+                            const uy = dy / length;
+                            const hx = to.x - ux * inset;
+                            const hy = to.y - uy * inset;
+                            const head = 5;
+                            return (_jsx("path", { "data-slot": "pulse-graph-flow", d: `M ${hx - uy * head} ${hy + ux * head} L ${hx} ${hy} L ${hx + uy * head} ${hy - ux * head}`, strokeWidth: 1.5, fill: "none", className: "stroke-brand-ink" }));
+                        })()
+                        : null] }, `${relation.from}-${relation.to}`))), nodes.map((node) => {
+                const at = place(node);
+                return (_jsxs("g", { "data-slot": "pulse-graph-node", "data-node": node.id, "data-emphasis": node.emphasis || undefined, "data-lane": node.lane, children: [node.emphasis ? (_jsx("circle", { "data-slot": "pulse-graph-halo", cx: at.x, cy: at.y, r: NODE_RADIUS, strokeWidth: 0, className: cn('fill-brand-ink/25', 'prism-ambient-pulse', stagger(node.lane ?? 0)) })) : null, _jsx("circle", { cx: at.x, cy: at.y, r: NODE_RADIUS, strokeWidth: node.emphasis ? 2 : 1, className: cn(node.emphasis ? 'fill-accent stroke-brand-ink' : 'fill-card stroke-border') }), _jsx("text", { x: at.x, y: at.y + NODE_NAME_OFFSET, fontSize: NODE_NAME_SIZE, textAnchor: "middle", className: "fill-foreground font-mono", children: node.name }), node.note ? (_jsx("text", { x: at.x, y: at.y + NODE_NOTE_OFFSET, fontSize: NODE_NOTE_SIZE, textAnchor: "middle", className: "fill-muted-foreground font-mono", children: node.note })) : null] }, node.id));
+            })] }));
+}
+export { PulseGraph };

package/dist/components/ui/pulse-series.d.ts

@@ -0,0 +1,123 @@
+/**
+ * One column in a PulseSeries.
+ *
+ * `value` is a magnitude in the caller's own units and the Component scales it
+ * against the tallest column, so a caller passes the numbers it has rather than
+ * percentages of a maximum it had to compute first. The reason is honesty: a
+ * caller that pre-normalises has two chances to get the axis wrong, and a
+ * mislabelled axis is a lie with a typeface on it.
+ *
+ * `emphasis` marks the column the reader is meant to land on, and it is the one
+ * difference a column may carry. The emphasised column takes the brand ink and
+ * takes a label; every other column takes muted ink and takes none. Two
+ * emphasised columns are a caller's mistake rather than a second level, because
+ * a figure with two focal points has none.
+ */
+export type PulseBar = {
+    /** A key unique within the series. It is carried on the markup as `data-column`. */
+    id: string;
+    /** The column's height, in the caller's own units. */
+    value: number;
+    /**
+     * The name printed under the column. Required on the emphasised column and
+     * optional elsewhere, because a label under every column of a wide series is
+     * the axis the caller would have drawn anyway, and this Component leaves room
+     * for it rather than making the caller draw one behind it.
+     */
+    label?: string;
+    /** Marks the column the drawing is about. See the Brand Ink Rule. */
+    emphasis?: boolean;
+};
+/**
+ * What both arms of `PulseSeriesProps` carry.
+ *
+ * The name is required unless the drawing is decorative, and it is forbidden
+ * when it is. That is a union rather than `label?: string` for the reason
+ * `Diagram` states: only a union lets the type system see the exception, because
+ * an optional label on one arm can only be optional on both.
+ */
+type PulseSeriesFigure = {
+    /**
+     * Hides the drawing from assistive technology and drops the name. Use it
+     * when the surrounding sentence already says what the series shows, and
+     * nothing inside the hidden tree is named either.
+     */
+    decorative: true;
+    label?: never;
+} | {
+    /** The name of the drawing, and the only thing a screen reader reads from it. */
+    label: string;
+    decorative?: false;
+};
+export type PulseSeriesProps = PulseSeriesFigure & {
+    /**
+     * The columns drawn, left to right in the order given. At least one: a series
+     * with nothing in it is a mistake in the caller's data rather than a state
+     * worth an empty message.
+     */
+    bars: PulseBar[];
+    /**
+     * The line the columns rise from: the zero of the caller's units, named so a
+     * reader is told what the columns are counted from rather than left to infer
+     * it from a shape. Optional, and omitted rather than defaulted, because a
+     * default here is a claim about the caller's units.
+     */
+    baseline?: string;
+    /**
+     * A reticle crossing the series once per cycle, marking which column is being
+     * read at this instant. This is the figure's only motion beyond the columns'
+     * own rise, and it is the part that makes a static bar chart read as a live
+     * view rather than a report.
+     */
+    scan?: boolean;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+};
+/**
+ * A series of columns, a reticle crossing them, and a baseline they rise from.
+ *
+ * This is the instrument the retired line drew on a canvas, rebuilt. Its
+ * predecessor read open interest out of a sine hash, so the drawing was of
+ * numbers that had never been collected, and a reader who screenshotted it and
+ * read the axis got a fabrication set in a real typeface. That defect is not
+ * repeated here and is not repeatable here: the columns are the caller's
+ * numbers, the tallest one sets the scale, and a caller with no numbers passes
+ * no bars.
+ *
+ * **A server Component with no runtime.** The rise and the scan are CSS on
+ * server-rendered markup, so a live view costs zero bytes of JavaScript and
+ * works in a static export. See `PulseGraph` for the full argument; the short
+ * form is that the old instrument needed a client runtime, a `requestAnimationFrame`
+ * loop and a colour read at mount, and this needs none of the three.
+ *
+ * **The columns are visible from the first frame.** The rise animation
+ * interpolates from the baseline, so at 0% the column has no height and the
+ * reader is looking at a baseline with labels on it. That is the one moment this
+ * figure is less informative than its resting state, and it lasts one cycle
+ * rather than persisting, it never hides a column permanently, and under
+ * `prefers-reduced-motion` it is not run at all. The figure is not gated on a
+ * script, an intersection or a scroll position, so a reader with scripting off
+ * and a print stylesheet both get every column at full height.
+ *
+ * **The scan is the honest part.** A reticle crossing the series says a column
+ * is being read at this instant, and it is drawn at a real position on the
+ * scale rather than sweeping an empty field: a sweep with nothing under it is
+ * atmosphere, and atmosphere was what the old heroes had too much of. Under
+ * reduced motion the scan is off and the columns stand, which is the correct
+ * still frame for a chart.
+ *
+ * **The emphasis is the caller's.** One column may be emphasised, and it is the
+ * one that takes the brand ink and the label. The reticle does not choose it,
+ * because the reticle is a claim about time and the emphasis is a claim about
+ * importance, and a component that conflated the two would be moving the
+ * reader's attention on a schedule.
+ *
+ * **Accessibility.** `role="img"` and the caller's `label`, the same contract
+ * the rest of the drawing set holds. The labels under columns are inside a
+ * `role="img"` and so are presentational; the surrounding sentence is what a
+ * screen reader gets. Pass `decorative` when it already says what the drawing
+ * shows.
+ */
+declare function PulseSeries({ bars, baseline, scan, label, decorative, className, }: PulseSeriesProps): import("react").JSX.Element;
+export { PulseSeries };
+//# sourceMappingURL=pulse-series.d.ts.map

package/dist/components/ui/pulse-series.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pulse-series.d.ts","sourceRoot":"","sources":["../../../src/components/ui/pulse-series.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,oFAAoF;IACpF,EAAE,EAAE,MAAM,CAAA;IACV,sDAAsD;IACtD,KAAK,EAAE,MAAM,CAAA;IACb;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;GAOG;AACH,KAAK,iBAAiB,GAClB;IACE;;;;OAIG;IACH,UAAU,EAAE,IAAI,CAAA;IAChB,KAAK,CAAC,EAAE,KAAK,CAAA;CACd,GACD;IACE,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE,KAAK,CAAA;CACnB,CAAA;AAEL,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG;IACjD;;;;OAIG;IACD,IAAI,EAAE,QAAQ,EAAE,CAAA;IAChB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAoCH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,iBAAS,WAAW,CAAC,EACnB,IAAI,EACJ,QAAQ,EACR,IAAY,EACZ,KAAK,EACL,UAAkB,EAClB,SAAS,GACV,EAAE,gBAAgB,+BAsIlB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/pulse-series.js

@@ -0,0 +1,94 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from '../../lib/utils';
+/**
+ * The canvas the series draws into, in its own user units.
+ *
+ * Shorter than `PulseGraph`'s and for the reason a bar chart is not a graph: a
+ * series reads its height against its baseline, so a canvas with more vertical
+ * room than it needs pushes the baseline up and makes every column look
+ * shorter than it is.
+ */
+const CANVAS_WIDTH = 640;
+const CANVAS_HEIGHT = 300;
+/**
+ * The band left empty around the columns, in user units.
+ *
+ * The bottom band carries the baseline and the labels, so it is generous, and
+ * the top band is small because a column that reaches the top of the canvas has
+ * no headroom to breathe in and reads as clipped rather than as tall.
+ */
+const PADDING = 52;
+const PADDING_TOP = 28;
+/** The widest a column is drawn, in user units, before the series narrows them. */
+const MAX_BAR_WIDTH = 18;
+/** The gap between two columns, as a fraction of a column's own width. */
+const BAR_GAP = 0.45;
+/**
+ * Type sizes, in user units rather than in `rem`, for the reason every figure in
+ * this package states: a font size inside a viewBox is a coordinate.
+ */
+const LABEL_SIZE = 11;
+const BASELINE_SIZE = 10;
+/**
+ * A series of columns, a reticle crossing them, and a baseline they rise from.
+ *
+ * This is the instrument the retired line drew on a canvas, rebuilt. Its
+ * predecessor read open interest out of a sine hash, so the drawing was of
+ * numbers that had never been collected, and a reader who screenshotted it and
+ * read the axis got a fabrication set in a real typeface. That defect is not
+ * repeated here and is not repeatable here: the columns are the caller's
+ * numbers, the tallest one sets the scale, and a caller with no numbers passes
+ * no bars.
+ *
+ * **A server Component with no runtime.** The rise and the scan are CSS on
+ * server-rendered markup, so a live view costs zero bytes of JavaScript and
+ * works in a static export. See `PulseGraph` for the full argument; the short
+ * form is that the old instrument needed a client runtime, a `requestAnimationFrame`
+ * loop and a colour read at mount, and this needs none of the three.
+ *
+ * **The columns are visible from the first frame.** The rise animation
+ * interpolates from the baseline, so at 0% the column has no height and the
+ * reader is looking at a baseline with labels on it. That is the one moment this
+ * figure is less informative than its resting state, and it lasts one cycle
+ * rather than persisting, it never hides a column permanently, and under
+ * `prefers-reduced-motion` it is not run at all. The figure is not gated on a
+ * script, an intersection or a scroll position, so a reader with scripting off
+ * and a print stylesheet both get every column at full height.
+ *
+ * **The scan is the honest part.** A reticle crossing the series says a column
+ * is being read at this instant, and it is drawn at a real position on the
+ * scale rather than sweeping an empty field: a sweep with nothing under it is
+ * atmosphere, and atmosphere was what the old heroes had too much of. Under
+ * reduced motion the scan is off and the columns stand, which is the correct
+ * still frame for a chart.
+ *
+ * **The emphasis is the caller's.** One column may be emphasised, and it is the
+ * one that takes the brand ink and the label. The reticle does not choose it,
+ * because the reticle is a claim about time and the emphasis is a claim about
+ * importance, and a component that conflated the two would be moving the
+ * reader's attention on a schedule.
+ *
+ * **Accessibility.** `role="img"` and the caller's `label`, the same contract
+ * the rest of the drawing set holds. The labels under columns are inside a
+ * `role="img"` and so are presentational; the surrounding sentence is what a
+ * screen reader gets. Pass `decorative` when it already says what the drawing
+ * shows.
+ */
+function PulseSeries({ bars, baseline, scan = false, label, decorative = false, className, }) {
+    const roomX = CANVAS_WIDTH - PADDING * 2;
+    const roomY = CANVAS_HEIGHT - PADDING - PADDING_TOP;
+    const baselineY = PADDING + roomY;
+    const tallest = Math.max(...bars.map((bar) => bar.value), 0);
+    const slot = bars.length ? roomX / bars.length : roomX;
+    const barWidth = Math.max(2, Math.min(MAX_BAR_WIDTH, slot * (1 / (1 + BAR_GAP))));
+    return (_jsxs("svg", { "data-slot": "pulse-series", "data-columns": bars.length, "data-scan": scan || undefined, viewBox: `0 0 ${CANVAS_WIDTH} ${CANVAS_HEIGHT}`, xmlns: "http://www.w3.org/2000/svg", role: decorative ? undefined : 'img', "aria-label": decorative ? undefined : label, "aria-hidden": decorative || undefined, className: cn('h-auto w-full', className), children: [scan ? (_jsx("g", { "data-slot": "pulse-series-scan", "aria-hidden": true, children: _jsxs("g", { className: "prism-ambient-scan", style: { '--ambient-scan-distance': `${roomX + slot}px` }, children: [_jsx("rect", { "data-slot": "pulse-series-scan-wash", x: PADDING - slot, y: PADDING_TOP - 12, width: slot, height: roomY + 12, className: "fill-brand-ink/10" }), _jsx("line", { "data-slot": "pulse-series-scan-line", x1: 0, y1: PADDING_TOP - 12, x2: 0, y2: baselineY, strokeWidth: 1, className: "stroke-brand-ink/60" })] }) })) : null, bars.map((bar, index) => {
+                const centre = PADDING + slot * (index + 0.5);
+                // A column of value zero is drawn as a hairline rather than as nothing,
+                // because a gap in a series is a missing reading and a missing reading
+                // that looks identical to a value of zero is a data claim the drawing
+                // cannot support.
+                const height = tallest === 0 ? 1 : Math.max(1, (bar.value / tallest) * roomY);
+                return (_jsxs("g", { "data-slot": "pulse-series-column", "data-column": bar.id, "data-emphasis": bar.emphasis || undefined, children: [_jsx("rect", { x: centre - barWidth / 2, y: baselineY - height, width: barWidth, height: height, rx: Math.min(2, barWidth / 2), className: cn('origin-bottom', 'prism-ambient-rise', bar.emphasis ? 'fill-brand-ink' : 'fill-muted-foreground/35', `prism-ambient-delay-${(index % 3) + 1}`) }), bar.label ? (_jsx("text", { x: centre, y: baselineY + 18, fontSize: LABEL_SIZE, textAnchor: "middle", className: cn('font-mono', bar.emphasis ? 'fill-foreground' : 'fill-muted-foreground'), children: bar.label })) : null] }, bar.id));
+            }), _jsxs("g", { "data-slot": "pulse-series-baseline", children: [_jsx("line", { x1: PADDING - 12, y1: baselineY, x2: CANVAS_WIDTH - PADDING + 12, y2: baselineY, strokeWidth: 1, className: "stroke-border" }), baseline ? (_jsx("text", { x: PADDING - 12, y: baselineY - 8, fontSize: BASELINE_SIZE, textAnchor: "start", className: "fill-muted-foreground font-mono", children: baseline })) : null] })] }));
+}
+export { PulseSeries };

package/dist/components/ui/signal-field.d.ts

@@ -0,0 +1,66 @@
+/**
+ * How many marks a field draws, and how they are arranged.
+ *
+ * A field is atmosphere, and atmosphere is the one thing in this system that is
+ * allowed to be a number rather than data. The count is a prop rather than a
+ * constant because a hero panel beside a two-column hero and a full-bleed
+ * background behind a title want very different densities, and a fixed count
+ * would have one of them too sparse or the other too busy.
+ */
+export type SignalFieldProps = {
+    /**
+     * How many marks the field draws. Read as a suggestion and clamped to a small
+     * range, because a field is a texture and a texture with four hundred marks is
+     * a chart that lost its labels.
+     */
+    count?: number;
+    /**
+     * A mark the drawing is about, given as a fraction of the field. The field
+     * centres the emphasis and dims the rest, which is what makes a field read as
+     * a system with a focus rather than as scattered dots.
+     */
+    emphasisAt?: number;
+    /** The name of the drawing, or `decorative`. See `PulseGraphProps`. */
+    label?: string;
+    decorative?: boolean;
+    /**
+     * Whether the marks drift. Off by default: a field behind a reading passage
+     * is the worst place for movement a reader did not ask for, and the drift is
+     * the first thing a reader with vestibular sensitivity will ask to have gone.
+     */
+    drift?: boolean;
+    /** Layout only, exactly as on every Component. */
+    className?: string;
+};
+/**
+ * A field of marks: the atmosphere a figure is drawn over, and the one thing in
+ * this system that is allowed to be nothing more than texture.
+ *
+ * The retired line drew this as a canvas behind the hero type, and the defect
+ * was never the idea: it was that the canvas was opaque, animated continuously,
+ * and had to be redrawn by a `requestAnimationFrame` loop to keep a decorative
+ * sweep moving. This is the same idea with the three costs removed. It is SVG,
+ * so it scales, prints and costs no runtime; it is `aria-hidden` by default,
+ * because a field of dots is not information and a screen reader being made to
+ * read one is a cost with no reader attached; and its movement is off unless a
+ * caller asks for it.
+ *
+ * **It is atmosphere, and it is labelled as such.** The reason it exists is that
+ * a hero with a hard flat ground behind it reads as a document, and a hero with
+ * a field behind it reads as a product with a surface. Everything else about it
+ * is restraint: no mark is emphasised by default, no two marks are the same
+ * colour, and nothing in the field moves unless `drift` is set. It is the
+ * weakest mark in the system and the easiest one to overdo, and the props are
+ * shaped to make the restrained version the easy one.
+ *
+ * **It never carries the meaning.** A field is `aria-hidden` unless a caller
+ * deliberately names it, and the default is that it names nothing, because a
+ * caller reaching for this has atmosphere and not data. When a figure needs to
+ * say what it is showing, that figure is `PulseGraph` or `PulseSeries`, both of
+ * which require a name and both of which a screen reader can be given.
+ *
+ * **It is a server Component.** No hook, no client runtime, nothing to hydrate.
+ */
+declare function SignalField({ count, emphasisAt, label, decorative, drift, className, }: SignalFieldProps): import("react").JSX.Element;
+export { SignalField };
+//# sourceMappingURL=signal-field.d.ts.map

package/dist/components/ui/signal-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-field.d.ts","sourceRoot":"","sources":["../../../src/components/ui/signal-field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,CAAA;AAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iBAAS,WAAW,CAAC,EACnB,KAAU,EACV,UAAU,EACV,KAAK,EACL,UAAiB,EACjB,KAAa,EACb,SAAS,GACV,EAAE,gBAAgB,+BA0ClB;AAED,OAAO,EAAE,WAAW,EAAE,CAAA"}

package/dist/components/ui/signal-field.js

@@ -0,0 +1,77 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from '../../lib/utils';
+/**
+ * The canvas the field draws into, in its own user units.
+ *
+ * Deliberately oversized relative to the panel it usually fills, because a field
+ * that ends where the panel ends is a grid and a grid reads as content. The
+ * marks are placed on a low-discrepancy walk rather than at random, so no two
+ * fields ever look alike and none of them looks hand-scattered, while remaining
+ * reproducible between server render and client hydration. A field that changed
+ * on every render would be a hydration mismatch, which is a correctness bug
+ * dressed as variety.
+ */
+const CANVAS_WIDTH = 1200;
+const CANVAS_HEIGHT = 700;
+/** The largest a mark is drawn, in user units. */
+const MAX_MARK = 3;
+/**
+ * The marks, placed by a golden-angle walk.
+ *
+ * A golden angle is the one arrangement that looks uncorrelated while being
+ * fully determined by its index, which is what this needs: reproducible
+ * without a seed, and evenly spread without a grid. The modulus keeps every
+ * mark inside the canvas without a rejection loop, so the count is honoured
+ * exactly rather than approximately.
+ */
+function marks(count) {
+    const golden = 2.399963229728653;
+    return Array.from({ length: count }, (_, index) => {
+        const t = (index + 0.5) / count;
+        return {
+            x: ((index * golden) % 1) * CANVAS_WIDTH,
+            y: t * CANVAS_HEIGHT,
+            r: MAX_MARK * (0.5 + ((index * 7919) % 5) / 10),
+        };
+    });
+}
+/**
+ * A field of marks: the atmosphere a figure is drawn over, and the one thing in
+ * this system that is allowed to be nothing more than texture.
+ *
+ * The retired line drew this as a canvas behind the hero type, and the defect
+ * was never the idea: it was that the canvas was opaque, animated continuously,
+ * and had to be redrawn by a `requestAnimationFrame` loop to keep a decorative
+ * sweep moving. This is the same idea with the three costs removed. It is SVG,
+ * so it scales, prints and costs no runtime; it is `aria-hidden` by default,
+ * because a field of dots is not information and a screen reader being made to
+ * read one is a cost with no reader attached; and its movement is off unless a
+ * caller asks for it.
+ *
+ * **It is atmosphere, and it is labelled as such.** The reason it exists is that
+ * a hero with a hard flat ground behind it reads as a document, and a hero with
+ * a field behind it reads as a product with a surface. Everything else about it
+ * is restraint: no mark is emphasised by default, no two marks are the same
+ * colour, and nothing in the field moves unless `drift` is set. It is the
+ * weakest mark in the system and the easiest one to overdo, and the props are
+ * shaped to make the restrained version the easy one.
+ *
+ * **It never carries the meaning.** A field is `aria-hidden` unless a caller
+ * deliberately names it, and the default is that it names nothing, because a
+ * caller reaching for this has atmosphere and not data. When a figure needs to
+ * say what it is showing, that figure is `PulseGraph` or `PulseSeries`, both of
+ * which require a name and both of which a screen reader can be given.
+ *
+ * **It is a server Component.** No hook, no client runtime, nothing to hydrate.
+ */
+function SignalField({ count = 28, emphasisAt, label, decorative = true, drift = false, className, }) {
+    const placed = marks(Math.max(4, Math.min(120, Math.round(count))));
+    const emphasised = emphasisAt === undefined ? -1 : Math.round(emphasisAt * (placed.length - 1));
+    return (_jsx("svg", { "data-slot": "signal-field", "data-marks": placed.length, viewBox: `0 0 ${CANVAS_WIDTH} ${CANVAS_HEIGHT}`, xmlns: "http://www.w3.org/2000/svg", role: decorative ? undefined : 'img', "aria-label": decorative ? undefined : label, "aria-hidden": decorative || undefined, preserveAspectRatio: "xMidYMid slice", className: cn('h-full w-full', className), children: placed.map((mark, index) => (_jsx("circle", { "data-slot": "signal-field-mark", "data-emphasis": index === emphasised || undefined, cx: mark.x, cy: mark.y, r: index === emphasised ? mark.r * 1.9 : mark.r, strokeWidth: 0, className: cn(index === emphasised ? 'fill-brand-ink/45' : 'fill-foreground/12', drift && index % 3 === 0 ? 'prism-ambient-drift' : undefined, drift && index % 3 === 1 ? 'prism-ambient-delay-1' : undefined, drift && index % 3 === 2 ? 'prism-ambient-delay-2' : undefined), style: drift
+                ? {
+                    '--ambient-drift-x': `${(index % 2 === 0 ? 1 : -1) * (0.4 + (index % 5) * 0.15)}rem`,
+                    '--ambient-drift-y': `${(index % 3 === 0 ? 1 : -1) * 0.35}rem`,
+                }
+                : undefined }))) }));
+}
+export { SignalField };