@quantumwake/terminal-ux-dashboard-components 0.1.28 → 0.1.30

package/README.md

@@ -49,10 +49,35 @@ SQL service `/query`; a read-only host against DuckDB-WASM `read_parquet`).
 - ⏳ Components (landing in tranches): views/, `SqlConsole`,
   `ChartBuilder`, `DashboardRenderer`, `DataExplorer`
 
+## Value formatting (`yFormat`, `formatBytes`)
+
+`LineView`, `BarView` and `SparklineView` accept a `yFormat?: (value: number) =>
+string` prop that formats every numeric value rendered for the user — y-axis
+tick labels, hover/tooltip values, in-bar labels (`BarView`), and the
+latest-value readout (`SparklineView`). It's unset by default, so nothing
+changes for existing callers: ticks keep `Number(value).toLocaleString()` and
+the tooltip/label keep Nivo's own default formatting.
+
+`BarView`'s value axis follows `layout` — vertical puts it on the left,
+horizontal on the bottom — `yFormat` applies to whichever axis that is.
+
+```tsx
+import { LineView, BarView, formatBytes } from '@quantumwake/terminal-ux-dashboard-components';
+
+<LineView records={records} xColumn="t" yColumn="bytes_per_sec" yFormat={(v) => formatBytes(v, true)} />
+<BarView records={records} groupColumn="host" valueColumn="bytes" yFormat={formatBytes} />
+```
+
+`formatBytes(value, perSecond?)` is the shared unit rule for byte-ish series:
+B under 1024, then KB/MB/GB/TB with one decimal place (`"1.5 MB"`), capped at
+TB. Pass `perSecond: true` to append `/s` for a throughput series
+(`"2.0 GB/s"`).
+
 ## Build
 
 ```
 npm install
 npm run build   # tsup → dist (esm + cjs + d.ts)
 npm run lint    # tsc --noEmit
+npm run test    # vitest run
 ```

package/dist/index.cjs

@@ -436,6 +436,23 @@ var aggregate = (records, column, fn) => {
       return records.length;
   }
 };
+
+// src/format.ts
+var BYTE_UNITS = ["KB", "MB", "GB", "TB"];
+function formatBytes(value, perSecond = false) {
+  const suffix = perSecond ? "/s" : "";
+  if (!Number.isFinite(value)) return `\u2014 B${suffix}`;
+  const sign = value < 0 ? "-" : "";
+  const abs = Math.abs(value);
+  if (abs < 1024) return `${sign}${Math.round(abs)} B${suffix}`;
+  let scaled = abs / 1024;
+  let unit = 0;
+  while (scaled >= 1024 && unit < BYTE_UNITS.length - 1) {
+    scaled /= 1024;
+    unit++;
+  }
+  return `${sign}${scaled.toFixed(1)} ${BYTE_UNITS[unit]}${suffix}`;
+}
 var HEAT_STATS = ["count", "sum", "avg", "min", "max", "median"];
 var cellKey = (row, col) => `${row}\0${col}`;
 var normalizePartition = (cells, method, vmin, vmax) => {
@@ -508,8 +525,8 @@ function MetricView({ records, config, value: presetValue }) {
 function InsightView({ config }) {
   return /* @__PURE__ */ jsxRuntime.jsx("div", { className: "h-full p-4 overflow-auto", children: /* @__PURE__ */ jsxRuntime.jsx("p", { className: "text-sm text-midnight-text-body leading-relaxed whitespace-pre-wrap", children: config.text }) });
 }
-function formatVal(value, s, numeric) {
-  let str = numeric ? Number(value).toLocaleString() : String(value);
+function formatVal(value, s, numeric, custom) {
+  let str = custom ? custom(value) : numeric ? Number(value).toLocaleString() : String(value);
   if (s.tickTruncate > 0 && str.length > s.tickTruncate) str = `${str.slice(0, s.tickTruncate)}\u2026`;
   return str;
 }
@@ -558,7 +575,7 @@ function makeAxis(style, axis, columnName, opts2 = {}) {
   }
   if (s.tickWrap) {
     out.renderTick = (tick) => {
-      const lines = wrapText(formatVal(tick.value, s, numeric), s.tickWrapWidth);
+      const lines = wrapText(formatVal(tick.value, s, numeric, opts2.format), s.tickWrapWidth);
       const firstDy = isX ? "0" : `${-((lines.length - 1) * 0.55)}em`;
       return /* @__PURE__ */ jsxRuntime.jsxs("g", { transform: `translate(${tick.x},${tick.y})`, children: [
         /* @__PURE__ */ jsxRuntime.jsx("line", { x2: isX ? 0 : -5, y2: isX ? 5 : 0, style: { stroke: s.textColor, strokeWidth: 1, opacity: 0.3 } }),
@@ -576,13 +593,13 @@ function makeAxis(style, axis, columnName, opts2 = {}) {
     };
   } else {
     out.tickRotation = rotate;
-    out.format = (v) => formatVal(v, s, numeric);
+    out.format = (v) => formatVal(v, s, numeric, opts2.format);
   }
   const maxTicks = isX ? s.maxXTicks : s.maxYTicks;
   if (numeric && maxTicks > 0) out.tickValues = maxTicks;
   return out;
 }
-function BarView({ records, groupColumn, valueColumn, aggFn = "count", data: presetData, layout = "vertical", style }) {
+function BarView({ records, groupColumn, valueColumn, aggFn = "count", data: presetData, layout = "vertical", style, yFormat }) {
   const computed = react.useMemo(() => {
     if (presetData || !records) return [];
     const groups = groupBy(records, groupColumn);
@@ -593,8 +610,9 @@ function BarView({ records, groupColumn, valueColumn, aggFn = "count", data: pre
   const { frameClass, frameStyle, margin } = chartSizing(style, { top: 20, right: 20, bottom: 60, left: 60 });
   const horizontal = layout === "horizontal";
   const plotted = horizontal ? [...data].reverse() : data;
-  const axisBottom = horizontal ? makeAxis(style, "x", valueColumn, { numeric: true }) : makeAxis(style, "x", groupColumn);
-  const axisLeft = horizontal ? makeAxis(style, "y", groupColumn) : makeAxis(style, "y", valueColumn, { numeric: true });
+  const valueFormat = yFormat ? (v) => yFormat(Number(v)) : void 0;
+  const axisBottom = horizontal ? makeAxis(style, "x", valueColumn, { numeric: true, format: valueFormat }) : makeAxis(style, "x", groupColumn);
+  const axisLeft = horizontal ? makeAxis(style, "y", groupColumn) : makeAxis(style, "y", valueColumn, { numeric: true, format: valueFormat });
   return /* @__PURE__ */ jsxRuntime.jsx("div", { className: frameClass, style: frameStyle, children: /* @__PURE__ */ jsxRuntime.jsx(
     bar.ResponsiveBar,
     {
@@ -608,6 +626,7 @@ function BarView({ records, groupColumn, valueColumn, aggFn = "count", data: pre
       borderColor: { from: "color", modifiers: [["darker", 1.6]] },
       axisBottom,
       axisLeft,
+      valueFormat,
       enableLabel: s.barLabels,
       labelSkipWidth: 12,
       labelSkipHeight: 12,
@@ -656,7 +675,11 @@ function PieView({ records, groupColumn, data: presetData, style }) {
     }
   ) });
 }
-function LineView({ records, xColumn, yColumn, data: presetData, style }) {
+var fmtClock = (d) => d.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23" });
+var toDate = (x) => x instanceof Date ? x : new Date(x);
+function LineView({ records, xColumn, yColumn, data: presetData, style, xScale = "point", xFormat, xDomain, yFormat }) {
+  const timed = xScale === "time";
+  const clock = xFormat ?? fmtClock;
   const computed = react.useMemo(() => {
     if (presetData || !records) return [];
     const sorted = [...records].filter((r) => r[xColumn] != null && r[yColumn] != null).sort((a, b) => {
@@ -669,15 +692,27 @@ function LineView({ records, xColumn, yColumn, data: presetData, style }) {
       data: sorted.map((r) => ({ x: String(r[xColumn]), y: Number(r[yColumn]) || 0 }))
     }];
   }, [records, xColumn, yColumn, presetData]);
-  const data = presetData || computed;
+  const shaped = presetData || computed;
+  const data = react.useMemo(
+    () => timed ? shaped.map((serie) => ({ ...serie, data: serie.data.map((d) => ({ ...d, x: toDate(d.x) })) })) : shaped,
+    [shaped, timed]
+  );
   const s = withStyleDefaults(style);
   const { frameClass, frameStyle, margin } = chartSizing(style, { top: 20, right: 20, bottom: 60, left: 60 });
+  const yTickFormat = yFormat ? (v) => yFormat(Number(v)) : void 0;
   const colorById = new Map(data.map((serie, i) => [
     serie.id,
     serie.color ?? (s.seriesColors.length || data.length > 1 ? seriesColor(i, s) : "rgba(96, 165, 250, 0.9)")
   ]));
   const longest = data.reduce((a, b) => b.data.length > a.data.length ? b : a, { id: "", data: [] });
-  const tickValues = thinTicks(longest.data.map((d) => d.x), s.maxXTicks);
+  const tickValues = timed ? void 0 : thinTicks(longest.data.map((d) => d.x), s.maxXTicks);
+  const axisBottom = (() => {
+    const base = makeAxis(style, "x", xColumn);
+    if (!timed) return { ...base, ...tickValues ? { tickValues } : {} };
+    delete base.renderTick;
+    return { ...base, tickRotation: s.xTickRotation, format: clock, ...s.maxXTicks > 0 ? { tickValues: s.maxXTicks } : {} };
+  })();
+  const nivoXScale = timed ? { type: "time", format: "native", precision: "millisecond", useUTC: false, min: xDomain?.[0] ?? "auto", max: xDomain?.[1] ?? "auto" } : { type: "point" };
   let yScale = { type: "linear", min: "auto", max: "auto" };
   if (s.yFromZero) {
     const dataMax = Math.max(0, ...data.flatMap((serie) => serie.data.map((d) => Math.max(d.y ?? 0, d.hi ?? d.y ?? 0))));
@@ -708,7 +743,8 @@ function LineView({ records, xColumn, yColumn, data: presetData, style }) {
     {
       data,
       margin,
-      xScale: { type: "point" },
+      xScale: nivoXScale,
+      xFormat: timed ? (v) => clock(v) : void 0,
       yScale,
       curve: "monotoneX",
       enableArea: s.areaOpacity > 0,
@@ -719,8 +755,9 @@ function LineView({ records, xColumn, yColumn, data: presetData, style }) {
       pointBorderWidth: 2,
       pointBorderColor: { from: "serieColor" },
       enableGridX: false,
-      axisBottom: { ...makeAxis(style, "x", xColumn), ...tickValues ? { tickValues } : {} },
-      axisLeft: makeAxis(style, "y", yColumn, { numeric: true }),
+      axisBottom,
+      axisLeft: makeAxis(style, "y", yColumn, { numeric: true, format: yTickFormat }),
+      yFormat: yTickFormat,
       useMesh: true,
       layers: ["grid", "markers", "axes", "areas", bandsLayer, linesLayer, "crosshair", "slices", "mesh", "legends"],
       animate: s.animate,
@@ -737,7 +774,7 @@ function niceCeil(v) {
   }
   return 10 * mag;
 }
-function SparklineView({ data, height = 56, color = "#3987e5", showValue = false, format }) {
+function SparklineView({ data, height = 56, color = "#3987e5", showValue = false, format, yFormat }) {
   const gradientId = react.useId();
   const width = 260;
   const pts = data && data.length ? data : [0];
@@ -747,7 +784,8 @@ function SparklineView({ data, height = 56, color = "#3987e5", showValue = false
   const line = pts.map((v, i) => `${i === 0 ? "M" : "L"} ${xy(v, i)[0].toFixed(1)} ${xy(v, i)[1].toFixed(1)}`).join(" ");
   const area = `${line} L ${width} ${height} L 0 ${height} Z`;
   const current = pts[pts.length - 1];
-  const readout = format ? format(current) : current.toLocaleString(void 0, { maximumFractionDigits: 1 });
+  const fmt = format ?? yFormat;
+  const readout = fmt ? fmt(current) : current.toLocaleString(void 0, { maximumFractionDigits: 1 });
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative", children: [
     /* @__PURE__ */ jsxRuntime.jsxs("svg", { viewBox: `0 0 ${width} ${height}`, height, className: "w-full", preserveAspectRatio: "none", children: [
       /* @__PURE__ */ jsxRuntime.jsx("defs", { children: /* @__PURE__ */ jsxRuntime.jsxs("linearGradient", { id: gradientId, x1: "0", y1: "0", x2: "0", y2: "1", children: [
@@ -3080,6 +3118,7 @@ exports.buildChartSQL = buildChartSQL;
 exports.buildNivoTheme = buildNivoTheme;
 exports.chartSizing = chartSizing;
 exports.compileWhere = compileWhere;
+exports.formatBytes = formatBytes;
 exports.groupBy = groupBy;
 exports.heatColor = heatColor;
 exports.heatLabelColor = heatLabelColor;