@fasl-work/caos-app-shell 0.9.4 → 0.10.0

package/chart.css

@@ -16,7 +16,9 @@
 .caos-chart-swatch { flex: none; width: 16px; height: 0; border-top: 2px solid var(--swatch); }
 .caos-chart-key[data-dash] .caos-chart-swatch { border-top-style: dashed; }
 .caos-chart-key[data-mode="points"] .caos-chart-swatch { width: 7px; height: 7px; border: 0; border-radius: 50%; background: var(--swatch); }
-/* A parity plot is square and centred in its box; a chart whose points can be picked shows a pointer. */
+/* A parity plot is square and centred in its box, across and, when it fills a box taller than it is wide, down (it
+   sat at the top with the spare height under it until 0.10.0); a chart whose points can be picked shows a pointer. */
 .caos-chart[data-parity] .uplot { margin-inline: auto; }
+.caos-chart.fill[data-parity] > .caos-chart-plot { display: flex; align-items: center; justify-content: center; }
 .caos-chart[data-pick] .u-over { cursor: pointer; }
 .caos-chart .u-cursor-x, .caos-chart .u-cursor-y { border-color: var(--color-fg-faint) !important; }

package/dist/chart.d.ts

@@ -14,6 +14,8 @@ interface ChartSeries {
     dash?: number[];
     /** `points` draws markers only (a scatter of cases over a curve); `null` values are simply absent. */
     mode?: 'line' | 'points';
+    /** The marker diameter of a `points` series, in CSS pixels (9 by default): a larger one rings the selected case. */
+    size?: number;
 }
 interface ChartAxis {
     label: BiText;
@@ -38,17 +40,31 @@ interface UPlotChartProps {
         x: number;
         label: BiText;
     }[];
+    /** Horizontal reference lines at y values, labelled at their right end (a null model's constant prediction, a
+     * target, a limit). */
+    yMarks?: {
+        y: number;
+        label: BiText;
+    }[];
     /** Height in pixels, or `fill` to take the container's height (inside `PlotCard fill`); the width is always the
      * container's. */
     height?: number | 'fill';
     /** Called with the index under the cursor (or null), for linked views; the index is the caller's, before any
      * sorting by x. */
     onCursor?: (index: number | null) => void;
-    /** Called with the caller's index of the point under the cursor when the plot is clicked (select a case, a blast). */
+    /** Called with the caller's index of the point under the cursor when the plot is clicked (select a case, a blast).
+     * On a chart whose series are all `points` (a scatter, a parity plot) the point under the cursor is the one nearest
+     * the pointer in the plane, not the one nearest in x. */
     onPick?: (index: number) => void;
     /** A parity plot: predicted (the series) against observed (x) on one shared range, in a square box, with the
-     * identity line. Unsorted x is allowed (the chart sorts it and maps every index back). */
+     * identity line. Unsorted x is allowed (the chart sorts it and maps every index back). The range takes in the
+     * reference lines (`yMarks`), so a null model's level is always in view. */
     parity?: boolean;
+    /** The readout under the plot for the point under the cursor (the caller's index), in place of the list of values:
+     * a scatter names its case ("Mg1, Murgul: measured 23.0 cm, predicted 25.1 cm"). */
+    readout?: (index: number) => string;
+    /** The readout at rest; by default "Hover the chart to read the values". */
+    hint?: BiText;
 }
 /** The colour and dash of a series: its own, or the rotation's; when the rotation comes round (a seventh series
  * repeats the first colour) the repeat is dashed, so two series never look the same (CAOS_Fragmenta drew this for
@@ -96,6 +112,24 @@ declare function drawMarks(u: uPlot, marks: {
     halo: string;
     family: string;
 }): void;
+/**
+ * The horizontal reference lines of a chart and their labels: a dashed line across the plot, its label at the right
+ * end above the line (below it when the line runs along the top), inside the plot, haloed; a label that would overlap
+ * the one placed before it moves left of it. A line outside the y range is not drawn.
+ */
+declare function drawYMarks(u: uPlot, marks: {
+    y: number;
+    label: string;
+}[], style: {
+    color: string;
+    halo: string;
+    family: string;
+}): void;
+/**
+ * The index of the point nearest (left, top) in the plane, over every series, or null when no point has a value.
+ * `xs` and every column of `ys` are positions in the same pixels as (left, top); a null position is no point.
+ */
+declare function nearestPoint(xs: readonly number[], ys: readonly (readonly (number | null)[])[], left: number, top: number): number | null;
 /**
  * The house chart (S12 of the 2026-10-04 requirements; uPlot, ADR on interactive charts). It is built only once its
  * box has a size; it resolves the theme's colours to concrete values and rebuilds when the theme or language changes
@@ -107,6 +141,6 @@ declare function drawMarks(u: uPlot, marks: {
  * (known shell defect 17). An axis with fixed decimals ticks only where its labels differ (`tickSteps`). The host
  * declares `data-series`, `data-axis-titles`, `data-ticks-cut`, `data-ticks-repeat` and `data-drawn` for the gate.
  */
-declare function UPlotChart({ x, y, series, marks, height, onCursor, onPick, parity }: UPlotChartProps): react.JSX.Element;
+declare function UPlotChart({ x, y, series, marks, yMarks, height, onCursor, onPick, parity, readout, hint }: UPlotChartProps): react.JSX.Element;
 
-export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, drawMarks, logDecades, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };
+export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, drawMarks, drawYMarks, logDecades, nearestPoint, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };

package/dist/chart.js

@@ -57,6 +57,7 @@ var DECADE_AXIS = {
   splits: (_u, _i, min, max) => logDecades(min, max),
   filter: (_u, splits) => splits
 };
+var PARITY_TICK_SPACE = 40;
 function repeatedLabels(labels) {
   let n = 0;
   for (let i = 1; i < labels.length; i++) if (labels[i] && labels[i] === labels[i - 1]) n++;
@@ -102,7 +103,66 @@ function drawMarks(u, marks, style) {
   }
   ctx.restore();
 }
-function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parity }) {
+function drawYMarks(u, marks, style) {
+  const ctx = u.ctx;
+  const pr = uPlot.pxRatio || 1;
+  const left = u.bbox.left;
+  const right = u.bbox.left + u.bbox.width;
+  const top = u.bbox.top;
+  const bottom = u.bbox.top + u.bbox.height;
+  const gap = 4 * pr;
+  const textH = 11 * pr;
+  const placed = [];
+  ctx.save();
+  ctx.font = `${Math.round(11 * pr)}px ${style.family}`;
+  ctx.textBaseline = "alphabetic";
+  ctx.lineJoin = "round";
+  for (const m of [...marks].sort((a, b) => b.y - a.y)) {
+    const py = u.valToPos(m.y, "y", true);
+    if (!Number.isFinite(py) || py < top - 0.5 || py > bottom + 0.5) continue;
+    ctx.strokeStyle = style.color;
+    ctx.lineWidth = Math.max(1, pr);
+    ctx.setLineDash([2 * pr, 4 * pr]);
+    ctx.beginPath();
+    ctx.moveTo(left, py);
+    ctx.lineTo(right, py);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    const w = ctx.measureText(m.label).width;
+    const base = py - gap - textH < top ? py + gap + textH : py - gap;
+    let x1 = right - gap;
+    while (placed.some((p) => x1 - w < p.x1 + gap && x1 > p.x0 - gap && base - textH < p.y1 && base > p.y0)) {
+      x1 = Math.min(...placed.filter((p) => base - textH < p.y1 && base > p.y0).map((p) => p.x0)) - 2 * gap;
+    }
+    const x0 = Math.max(left + gap, x1 - w);
+    placed.push({ x0, x1: x0 + w, y0: base - textH, y1: base });
+    ctx.textAlign = "left";
+    ctx.lineWidth = 3 * pr;
+    ctx.strokeStyle = style.halo;
+    ctx.strokeText(m.label, x0, base);
+    ctx.fillStyle = style.color;
+    ctx.fillText(m.label, x0, base);
+  }
+  ctx.restore();
+}
+function nearestPoint(xs, ys, left, top) {
+  let best = null;
+  let bestD = Infinity;
+  for (let i = 0; i < xs.length; i++) {
+    if (!Number.isFinite(xs[i])) continue;
+    for (const col of ys) {
+      const y = col[i];
+      if (y === null || y === void 0 || !Number.isFinite(y)) continue;
+      const d = (xs[i] - left) ** 2 + (y - top) ** 2;
+      if (d < bestD) {
+        bestD = d;
+        best = i;
+      }
+    }
+  }
+  return best;
+}
+function UPlotChart({ x, y, series, marks, yMarks, height = 280, onCursor, onPick, parity, readout, hint }) {
   const lang = useShellLang();
   const theme = useThemeStore((s) => s.theme);
   const fill = height === "fill";
@@ -124,12 +184,14 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   onCursorRef.current = onCursor;
   const onPickRef = useRef(onPick);
   onPickRef.current = onPick;
+  const pickedRef = useRef(null);
   const order = useMemo(() => sortOrder(x.values), [x.values]);
   const orderRef = useRef(order);
   orderRef.current = order;
   const xs = useMemo(() => order ? order.map((i) => x.values[i]) : x.values, [order, x.values]);
   const ys = useMemo(() => series.map((s) => order ? order.map((i) => s.values[i] ?? null) : s.values), [order, series]);
-  const range = useMemo(() => parity ? parityRange(xs, ...ys) : null, [parity, xs, ys]);
+  const levels = useMemo(() => (yMarks ?? []).map((m) => m.y), [yMarks]);
+  const range = useMemo(() => parity ? parityRange(xs, ...ys, levels) : null, [parity, xs, ys, levels]);
   const tiny = useMemo(
     () => ({
       x: Boolean(x.log) && smallestPositive([xs], range) < LOG_TABLE_FLOOR,
@@ -142,18 +204,20 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   const xUnit = x.unit ? pick(x.unit, lang) : "";
   const yUnit = y.unit ? pick(y.unit, lang) : "";
   const structure = JSON.stringify({
-    s: series.map((s, i) => [pick(s.label, lang), seriesStyle(s, i), s.width ?? 2, s.mode ?? "line"]),
+    s: series.map((s, i) => [pick(s.label, lang), seriesStyle(s, i), s.width ?? 2, s.mode ?? "line", s.size ?? 9]),
     x: [xLabel, xUnit, Boolean(x.time), Boolean(x.log), x.format ?? null, tiny.x],
     p: range,
     pick: Boolean(onPick),
     y: [yLabel, yUnit, Boolean(y.log), y.range ?? null, y.format ?? null, tiny.y],
     m: (marks ?? []).map((m) => [m.x, pick(m.label, lang)]),
+    ym: (yMarks ?? []).map((m) => [m.y, pick(m.label, lang)]),
     theme,
     lang,
     h,
     w: width
   });
   const data = useMemo(() => [xs, ...ys], [xs, ys]);
+  const scatter = series.length > 0 && series.every((s) => s.mode === "points");
   useEffect(() => {
     const el = plotRef.current;
     if (!el || width <= 0 || h <= 0) return;
@@ -167,14 +231,30 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
       const labels = formatTicks(vals, lang, fmt ?? { digits: 4 });
       repeats[axis] = repeatedLabels(labels);
       hostRef.current?.setAttribute("data-ticks-repeat", String(repeats.x + repeats.y));
+      hostRef.current?.setAttribute(`data-ticks-${axis}`, String(labels.filter((l) => l).length));
       return labels;
     };
+    const near = { left: NaN, top: NaN, idx: null };
+    const nearest = (u) => {
+      const { left, top } = u.cursor;
+      if (left === void 0 || top === void 0 || left < 0 || top < 0) return null;
+      if (left !== near.left || top !== near.top) {
+        const d = u.data;
+        const px = d[0].map((v) => v === null ? NaN : u.valToPos(v, "x"));
+        const py = d.slice(1).map((col) => col.map((v) => v === null ? null : u.valToPos(v, "y")));
+        near.left = left;
+        near.top = top;
+        near.idx = nearestPoint(px, py, left, top);
+      }
+      return near.idx;
+    };
     const xSteps = x.time || x.log ? void 0 : tickSteps(x.format);
     const ySteps = y.log ? void 0 : tickSteps(y.format);
     const opts = {
       width,
       height: h,
       legend: { show: false },
+      ...scatter ? { cursor: { dataIdx: (u, sIdx, closest) => sIdx === 0 ? closest : nearest(u) ?? closest } } : {},
       // a log axis labels the ticks uPlot keeps and passes null for the rest, which formatTicks leaves blank
       scales: {
         // a log x axis spans the data, not the decades around it (uPlot rounds out to the next decade, which left an
@@ -196,6 +276,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
           labelFont: font,
           values: x.time ? void 0 : tick(x.format, "x"),
           ...xSteps ? { incrs: xSteps } : {},
+          ...range ? { space: PARITY_TICK_SPACE } : {},
           ...tiny.x ? DECADE_AXIS : {}
         },
         {
@@ -207,6 +288,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
           labelFont: font,
           values: tick(y.format, "y"),
           ...ySteps ? { incrs: ySteps } : {},
+          ...range ? { space: PARITY_TICK_SPACE } : {},
           ...tiny.y ? DECADE_AXIS : {},
           // Sized to the longest tick label. uPlot draws in device pixels with a font scaled by its pixel ratio, so the
           // label is measured in that font and divided back (measuring the unscaled font and dividing by the ratio
@@ -225,13 +307,14 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
         ...series.map((s, i) => {
           const style = seriesStyle(s, i);
           const stroke = resolveToken(style.color, "#4a8");
-          return s.mode === "points" ? { label: pick(s.label, lang), stroke, width: 1.5, paths: () => null, points: { show: true, space: 0, size: 9, fill: stroke } } : { label: pick(s.label, lang), stroke, width: s.width ?? 2, dash: style.dash, spanGaps: false, points: { show: false } };
+          return s.mode === "points" ? { label: pick(s.label, lang), stroke, width: 1.5, paths: () => null, points: { show: true, space: 0, size: s.size ?? 9, fill: stroke } } : { label: pick(s.label, lang), stroke, width: s.width ?? 2, dash: style.dash, spanGaps: false, points: { show: false } };
         })
       ],
       hooks: {
         setCursor: [
           (u) => {
-            const idx = u.cursor.idx ?? null;
+            const idx = scatter ? nearest(u) : u.cursor.idx ?? null;
+            pickedRef.current = idx;
             setCursor(idx);
             onCursorRef.current?.(idx === null ? null : orderRef.current ? orderRef.current[idx] : idx);
           }
@@ -239,7 +322,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
         ready: [
           (u) => {
             u.over.addEventListener("click", () => {
-              const idx = u.cursor.idx;
+              const idx = pickedRef.current;
               if (idx === null || idx === void 0 || !onPickRef.current) return;
               onPickRef.current(orderRef.current ? orderRef.current[idx] : idx);
             });
@@ -260,12 +343,9 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
               ctx.stroke();
               ctx.restore();
             }
-            if (!marks?.length) return;
-            drawMarks(u, marks.map((m) => ({ x: m.x, label: pick(m.label, lang) })), {
-              color: resolveToken("--color-warn", "#c80"),
-              halo: surface,
-              family
-            });
+            const markStyle = { color: resolveToken("--color-warn", "#c80"), halo: surface, family };
+            if (yMarks?.length) drawYMarks(u, yMarks.map((m) => ({ y: m.y, label: pick(m.label, lang) })), markStyle);
+            if (marks?.length) drawMarks(u, marks.map((m) => ({ x: m.x, label: pick(m.label, lang) })), markStyle);
           }
         ]
       }
@@ -280,12 +360,10 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   useEffect(() => {
     uRef.current?.setData(data);
   }, [data]);
-  const read = cursor !== null ? [
+  const read = cursor !== null && readout ? readout(order ? order[cursor] : cursor) : cursor !== null ? [
     `${xLabel} ${formatNumber(xs[cursor], lang, x.format ?? { digits: 4 })}${xUnit ? `${NBSP}${xUnit}` : ""}`,
-    ...series.map(
-      (s, k) => `${pick(s.label, lang)} ${formatNumber(ys[k][cursor] ?? null, lang, y.format ?? { digits: 4 })}${yUnit ? `${NBSP}${yUnit}` : ""}`
-    )
-  ].join(" \xB7 ") : lang === "es" ? "Pase el cursor sobre el gr\xE1fico para leer los valores" : "Hover the chart to read the values";
+    ...series.map((s, k) => ({ s, v: ys[k][cursor] ?? null })).filter(({ v }) => !scatter || v !== null).map(({ s, v }) => `${pick(s.label, lang)} ${formatNumber(v, lang, y.format ?? { digits: 4 })}${yUnit ? `${NBSP}${yUnit}` : ""}`)
+  ].join(" \xB7 ") : hint ? pick(hint, lang) : lang === "es" ? "Pase el cursor sobre el gr\xE1fico para leer los valores" : "Hover the chart to read the values";
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -299,6 +377,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
       "data-parity": parity ? "1" : void 0,
       "data-log-x": x.log ? "1" : void 0,
       "data-pick": onPick ? "1" : void 0,
+      "data-y-marks": yMarks?.length ? String(yMarks.length) : void 0,
       children: [
         /* @__PURE__ */ jsx("div", { ref: setPlot, className: "caos-chart-plot" }),
         series.length > 1 && /* @__PURE__ */ jsx("ul", { className: "caos-chart-legend", "aria-label": lang === "es" ? "Series del gr\xE1fico" : "Series of the chart", children: series.map((s, i) => /* @__PURE__ */ jsxs("li", { className: "caos-chart-key", "data-mode": s.mode ?? "line", "data-dash": seriesStyle(s, i).dash ? "1" : void 0, children: [
@@ -311,4 +390,4 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   );
 }
 
-export { LOG_TABLE_FLOOR, UPlotChart, drawMarks, logDecades, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };
+export { LOG_TABLE_FLOOR, UPlotChart, drawMarks, drawYMarks, logDecades, nearestPoint, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Shared web-app shell, workbench primitives, content primitives, design system and measured gate for the CAOS / Faena public apps (ADR-0016, ADR-0017, ADR-0071).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",