@hackcove/ui-react 0.10.4 → 0.10.5

package/dist/StackedBar.d.ts

@@ -9,6 +9,8 @@ import { type TextTone } from "./typography.js";
  * five `TextTone` names; a chart with more than five parts is why these two live here.
  */
 export type VizTone = TextTone | "neutral" | "violet";
+/** Tone → text utility, painted as a fill. The five `TextTone` colours are shared; the two extra ones are remapped by every theme. */
+export declare const VIZ_TONE: Record<VizTone, string>;
 /** One part of a `StackedBar`: its `label`, its `value` (its share is `value` over the sum) and its colour. */
 export type StackedSegment = {
     label: string;

package/dist/StackedBar.js

@@ -3,7 +3,7 @@ import { cx } from "./cx.js";
 import { announcedPercent, BAR_TRACK, sharePercent } from "./ProgressBar.js";
 import { TEXT_TONE } from "./typography.js";
 /** Tone → text utility, painted as a fill. The five `TextTone` colours are shared; the two extra ones are remapped by every theme. */
-const VIZ_TONE = {
+export const VIZ_TONE = {
     ...TEXT_TONE,
     neutral: "text-neutral-500",
     violet: "text-purple-700",

package/dist/StatTile.d.ts

@@ -5,9 +5,10 @@ export type StatTileTone = "neutral" | "positive" | "warn" | "negative";
 /**
  * One headline figure: an uppercase caption over a large tabular-nums value, with an optional
  * hint line beneath. `tone` colours the value; `accent` adds a bar across the top edge in the same
- * tone. Pass the value already formatted.
+ * tone. `trend` draws a small line under the value in the same colour. Pass the value already
+ * formatted.
  */
-export declare function StatTile({ label, value, hint, tone, accent, ...rest }: {
+export declare function StatTile({ label, value, hint, tone, accent, trend, ...rest }: {
     /** The small uppercase caption over the value. */
     label: ReactNode;
     /** The figure, already formatted, large and in tabular figures. */
@@ -18,4 +19,9 @@ export declare function StatTile({ label, value, hint, tone, accent, ...rest }:
     tone?: StatTileTone;
     /** A bar across the top edge in the tone's colour. */
     accent?: boolean;
+    /**
+     * The figure over time, oldest first: a sparkline under the value, in its colour, on a scale
+     * from 0. It is decoration, so say the trend in `hint` as well.
+     */
+    trend?: readonly number[];
 } & Unstyled<Omit<HTMLAttributes<HTMLDivElement>, "children">>): ReactElement;

package/dist/StatTile.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from "./cx.js";
 import { BAR_FILL } from "./ProgressBar.js";
+import { drawn, largest, plotY, runs, scaleMax } from "./trend.js";
 import { Overline } from "./typography.js";
 const VALUE = {
     neutral: "text-slate-900",
@@ -17,8 +18,18 @@ const BAR = {
 /**
  * One headline figure: an uppercase caption over a large tabular-nums value, with an optional
  * hint line beneath. `tone` colours the value; `accent` adds a bar across the top edge in the same
- * tone. Pass the value already formatted.
+ * tone. `trend` draws a small line under the value in the same colour. Pass the value already
+ * formatted.
  */
-export function StatTile({ label, value, hint, tone = "neutral", accent = false, ...rest }) {
-    return (_jsxs("div", { ...rest, className: "relative overflow-hidden rounded-xl border border-slate-200/70 bg-white p-5 shadow-sm", children: [accent && (_jsx("span", { "aria-hidden": "true", className: cx("absolute inset-x-0 top-0 h-1", BAR[tone]) })), _jsx(Overline, { as: "p", children: label }), _jsx("p", { className: cx("mt-2 text-3xl font-bold tabular-nums", VALUE[tone]), children: value }), hint != null && _jsx("p", { className: "mt-1 text-xs text-slate-500", children: hint })] }));
+export function StatTile({ label, value, hint, tone = "neutral", accent = false, trend, ...rest }) {
+    return (_jsxs("div", { ...rest, className: "relative overflow-hidden rounded-xl border border-slate-200/70 bg-white p-5 shadow-sm", children: [accent && (_jsx("span", { "aria-hidden": "true", className: cx("absolute inset-x-0 top-0 h-1", BAR[tone]) })), _jsx(Overline, { as: "p", children: label }), _jsx("p", { className: cx("mt-2 text-3xl font-bold tabular-nums", VALUE[tone]), children: value }), trend !== undefined && trend.length > 0 && _jsx(Sparkline, { values: trend, tone: tone }), hint != null && _jsx("p", { className: "mt-1 text-xs text-slate-500", children: hint })] }));
+}
+/** The tile's trend line: edge to edge, `h-8`, in the value's colour. Hidden from assistive tech. */
+function Sparkline({ values, tone, }) {
+    const max = scaleMax(largest([values]));
+    const step = values.length > 1 ? 100 / (values.length - 1) : 0;
+    return (_jsx("svg", { "aria-hidden": "true", viewBox: "0 0 100 100", preserveAspectRatio: "none", className: cx("mt-3 block h-8 w-full overflow-visible", VALUE[tone]), children: runs(values.map((value, i) => {
+            const y = drawn(value);
+            return y === null ? null : { x: values.length > 1 ? step * i : 50, y: plotY(y, max) };
+        })).map((points) => (_jsx("polyline", { points: points, fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke" }, points))) }));
 }

package/dist/TrendChart.d.ts

@@ -0,0 +1,34 @@
+import type { ReactElement } from "react";
+import type { Passthrough } from "./props.js";
+import { type VizTone } from "./StackedBar.js";
+/**
+ * One series of a `TrendChart`: its `label` (the table's column, the Legend's entry), its colour,
+ * and one value per bucket in the buckets' order. A `null`, or a list shorter than the buckets, is
+ * a missing value.
+ */
+export type TrendSeries = {
+    label: string;
+    tone: VizTone;
+    values: readonly (number | null)[];
+};
+/**
+ * A chart of one or two series over ordered buckets (weeks, months), as bars or a line, on a
+ * y-axis from 0. The y-axis is labelled 0, half and a rounded maximum; the x-axis names the
+ * buckets. A screen reader gets the same figures as a table.
+ */
+export declare function TrendChart({ label, buckets, series, kind, ...rest }: {
+    /** What the chart shows: its accessible name and the caption of its table. */
+    label: string;
+    /** The x-axis labels, in order (`"W12"`, `"Mar"`). */
+    buckets: readonly string[];
+    /**
+     * One or two series, each `{ label, tone, values }`. A `null` value, or a `values` list shorter
+     * than `buckets`, is missing. Two series draw a Legend under the chart.
+     */
+    series: readonly [TrendSeries] | readonly [TrendSeries, TrendSeries];
+    /**
+     * `bar` for a count in each bucket, `line` for a level over time.
+     * @default bar
+     */
+    kind?: "bar" | "line";
+} & Passthrough): ReactElement;

package/dist/TrendChart.js

@@ -0,0 +1,51 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Legend, VIZ_TONE } from "./StackedBar.js";
+import { drawn, largest, plotY, round, runs, scaleMax } from "./trend.js";
+/** The most x labels drawn; past it, every k-th label is, starting with the first. */
+const MAX_X_LABELS = 8;
+/** Share of a bucket's width the bars of one bucket take, centred; the rest is the gap between buckets. */
+const BAR_SPAN = 0.7;
+const FORMAT = new Intl.NumberFormat("en-US");
+/** A value as the table says it: as given, or blank when missing. */
+const spoken = (value) => value == null || !Number.isFinite(value) ? null : FORMAT.format(value);
+/**
+ * A chart of one or two series over ordered buckets (weeks, months), as bars or a line, on a
+ * y-axis from 0. The y-axis is labelled 0, half and a rounded maximum; the x-axis names the
+ * buckets. A screen reader gets the same figures as a table.
+ */
+export function TrendChart({ label, buckets, series, kind = "bar", ...rest }) {
+    const values = series.map((s) => buckets.map((_, i) => drawn(s.values[i])));
+    const max = scaleMax(largest(values));
+    const ticks = [max, max / 2, 0];
+    return (_jsxs("figure", { ...rest, "aria-label": label, className: "flex flex-col gap-3", children: [_jsxs("div", { "aria-hidden": "true", className: "flex gap-2 pt-2 text-xs tabular-nums text-slate-500", children: [_jsx(YAxis, { ticks: ticks, max: max }), _jsxs("div", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: [_jsxs("div", { className: "relative h-48", children: [ticks.map((tick) => (_jsx("span", { className: "absolute inset-x-0 border-t border-slate-200", style: { top: `${plotY(tick, max)}%` } }, tick))), _jsx("svg", { viewBox: "0 0 100 100", preserveAspectRatio: "none", className: "absolute inset-0 size-full overflow-visible", children: kind === "bar" ? (_jsx(Bars, { series: series, values: values, max: max })) : (_jsx(Lines, { series: series, values: values, max: max })) })] }), _jsx(XAxis, { buckets: buckets })] })] }), series.length === 2 && (_jsx(Legend, { items: series.map((s) => ({ label: s.label, tone: s.tone })) })), _jsx(FigureTable, { label: label, buckets: buckets, series: series })] }));
+}
+/** The y labels, each centred on its gridline; the widest (the top) sets the column's width. */
+function YAxis({ ticks, max }) {
+    return (_jsxs("div", { className: "relative h-48 shrink-0 text-right", children: [_jsx("span", { className: "invisible block", children: FORMAT.format(max) }), ticks.map((tick) => (_jsx("span", { className: "absolute right-0 -translate-y-1/2", style: { top: `${plotY(tick, max)}%` }, children: FORMAT.format(tick) }, tick)))] }));
+}
+/** One equal column per bucket; past 8 buckets, every k-th label from the first. */
+function XAxis({ buckets }) {
+    const every = Math.max(1, Math.ceil(buckets.length / MAX_X_LABELS));
+    return (_jsx("div", { className: "grid text-center", style: { gridTemplateColumns: `repeat(${buckets.length}, minmax(0, 1fr))` }, children: buckets.map((bucket, i) => (_jsx("span", { className: "whitespace-nowrap", children: i % every === 0 ? bucket : null }, `${bucket}-${i}`))) }));
+}
+/** A rect per present value, the series side by side in each bucket. */
+function Bars({ series, values, max }) {
+    const width = 100 / Math.max(1, values[0]?.length ?? 1);
+    const bar = (width * BAR_SPAN) / series.length;
+    const inset = (width * (1 - BAR_SPAN)) / 2;
+    return (_jsx(_Fragment, { children: series.map((s, si) => values[si]?.map((value, i) => {
+            if (value === null)
+                return null;
+            const y = plotY(value, max);
+            return (_jsx("rect", { "data-bucket": i, className: VIZ_TONE[s.tone], fill: "currentColor", x: round(width * i + inset + bar * si), y: round(y), width: round(bar), height: round(100 - y) }, `${si}-${i}`));
+        })) }));
+}
+/** A polyline per run of present values, through the middle of each bucket. */
+function Lines({ series, values, max }) {
+    const width = 100 / Math.max(1, values[0]?.length ?? 1);
+    return (_jsx(_Fragment, { children: series.map((s, si) => runs((values[si] ?? []).map((value, i) => value === null ? null : { x: width * (i + 0.5), y: plotY(value, max) })).map((points) => (_jsx("polyline", { className: VIZ_TONE[s.tone], points: points, fill: "none", stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round", vectorEffect: "non-scaling-stroke" }, `${si}-${points}`)))) }));
+}
+/** The chart's figures for a screen reader: a row per bucket, a column per series. */
+function FigureTable({ label, buckets, series, }) {
+    return (_jsxs("table", { className: "sr-only", children: [_jsx("caption", { children: label }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("td", {}), series.map((s, si) => (_jsx("th", { scope: "col", children: s.label }, si)))] }) }), _jsx("tbody", { children: buckets.map((bucket, i) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: bucket }), series.map((s, si) => (_jsx("td", { children: spoken(s.values[i]) }, si)))] }, `${bucket}-${i}`))) })] }));
+}

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { StatTile, type StatTileTone } from "./StatTile.js";
 export { ProgressBar, type BarSize, type BarTone } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Legend, StackedBar, type LegendItem, type StackedSegment, type VizTone, } from "./StackedBar.js";
+export { TrendChart, type TrendSeries } from "./TrendChart.js";
 export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, type AppShellBreakpoint, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";

package/dist/index.js

@@ -6,6 +6,7 @@ export { StatTile } from "./StatTile.js";
 export { ProgressBar } from "./ProgressBar.js";
 export { SplitBar } from "./SplitBar.js";
 export { Legend, StackedBar, } from "./StackedBar.js";
+export { TrendChart } from "./TrendChart.js";
 export { Markdown } from "./Markdown.js";
 export { AppShell, AppShellBrand, AppShellHideBelow, appShellRootClassFor, } from "./AppShell.js";
 export { Container } from "./Container.js";

package/dist/trend.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The scale shared by `TrendChart` and the `StatTile` sparkline. Internal: not exported from
+ * `index.ts`.
+ */
+/**
+ * The top of a y-axis that starts at 0: the smallest of 2, 4 or 10 times a whole power of ten
+ * (1, 10, 100, …) that is at least `top`. Its half is then a whole number: 1 gives 2, 3 gives
+ * 4, 5 gives 10, 13 gives 20. Nothing above 0 gives 2.
+ */
+export declare function scaleMax(top: number): number;
+/** A value as drawn: a negative one is 0, and a missing or non-finite one is `null`. */
+export declare function drawn(value: number | null | undefined): number | null;
+/** The largest drawn value of every list, or 0. */
+export declare function largest(lists: readonly (readonly (number | null)[])[]): number;
+/** `value` as a height on a 0 to 100 plot, measured down from the top (SVG's y). */
+export declare function plotY(value: number, max: number): number;
+/**
+ * The polylines of a line through `points`, broken at every missing one: one `points` string per
+ * run of present values. A run of one point repeats it, so a round cap draws it as a dot.
+ */
+export declare function runs(points: readonly ({
+    x: number;
+    y: number;
+} | null)[]): string[];
+/** Four decimals, so the markup stays short and stable. */
+export declare function round(n: number): number;

package/dist/trend.js

@@ -0,0 +1,64 @@
+/**
+ * The scale shared by `TrendChart` and the `StatTile` sparkline. Internal: not exported from
+ * `index.ts`.
+ */
+/**
+ * The top of a y-axis that starts at 0: the smallest of 2, 4 or 10 times a whole power of ten
+ * (1, 10, 100, …) that is at least `top`. Its half is then a whole number: 1 gives 2, 3 gives
+ * 4, 5 gives 10, 13 gives 20. Nothing above 0 gives 2.
+ */
+export function scaleMax(top) {
+    for (let power = 1;; power *= 10) {
+        for (const step of [2, 4, 10]) {
+            if (step * power >= top)
+                return step * power;
+        }
+    }
+}
+/** A value as drawn: a negative one is 0, and a missing or non-finite one is `null`. */
+export function drawn(value) {
+    if (value == null || !Number.isFinite(value))
+        return null;
+    return Math.max(0, value);
+}
+/** The largest drawn value of every list, or 0. */
+export function largest(lists) {
+    let top = 0;
+    for (const list of lists) {
+        for (const value of list)
+            top = Math.max(top, drawn(value) ?? 0);
+    }
+    return top;
+}
+/** `value` as a height on a 0 to 100 plot, measured down from the top (SVG's y). */
+export function plotY(value, max) {
+    return 100 - (value / max) * 100;
+}
+/**
+ * The polylines of a line through `points`, broken at every missing one: one `points` string per
+ * run of present values. A run of one point repeats it, so a round cap draws it as a dot.
+ */
+export function runs(points) {
+    const out = [];
+    let run = [];
+    const close = () => {
+        const [only] = run;
+        if (run.length === 1 && only !== undefined)
+            run.push(only);
+        if (run.length > 0)
+            out.push(run.join(" "));
+        run = [];
+    };
+    for (const point of points) {
+        if (point === null)
+            close();
+        else
+            run.push(`${round(point.x)},${round(point.y)}`);
+    }
+    close();
+    return out;
+}
+/** Four decimals, so the markup stays short and stable. */
+export function round(n) {
+    return Math.round(n * 10000) / 10000;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hackcove/ui-react",
-  "version": "0.10.4",
+  "version": "0.10.5",
   "description": "Hack Cove React components: primitives, typography roles and a safe Markdown renderer, written against Tailwind v4 utilities. Pair with a theme from @hackcove/themes.",
   "keywords": [
     "components",