@k2b/ui 0.49.0 → 0.51.0

package/dist/browser/content/chart-inspection-core.js

@@ -1,11 +1,8 @@
 import { positionTooltipSurface } from "../feedback/tooltip-position";
-export const sameChartDatum = (a, b) => a.role === b.role && a.index === b.index && a.seriesIndex === b.seriesIndex;
-const object = value => typeof value === "object" && value !== null;
-const pair = value => Array.isArray(value) && value.length === 2 && value.every(n => typeof n === "number" && Number.isFinite(n));
-const roles = new Set(["point", "item", "bin", "box", "outlier", "value", "cell", "interval"]);
-export function isChartDatum(value) {
-  return object(value) && Number.isInteger(value.index) && typeof value.index === "number" && value.index >= 0 && (value.seriesIndex === undefined || typeof value.seriesIndex === "number" && Number.isInteger(value.seriesIndex) && value.seriesIndex >= 0) && typeof value.role === "string" && roles.has(value.role) && pair(value.anchor) && (value.grid === undefined || pair(value.grid)) && (value.label === undefined || typeof value.label === "string") && Array.isArray(value.values) && value.values.every(field => object(field) && typeof field.key === "string" && (typeof field.value === "string" || typeof field.value === "number" && Number.isFinite(field.value)) && (field.formatted === undefined || typeof field.formatted === "string"));
-}
+export { isChartDatum, sameChartDatum } from "../charts/core/inspection";
+import { isChartDatum, sameChartDatum } from "../charts/core/inspection";
+
+/** Host policy for inspecting an overflowing drawing. */
 
 /** Adds or removes only the tooltip id, keeping descriptions the host put on the container. */
 const describe = (container, id, on) => {
@@ -14,6 +11,14 @@ const describe = (container, id, on) => {
   if (ids.length) container.setAttribute("aria-describedby", ids.join(" "));else container.removeAttribute("aria-describedby");
 };
 
+/** Mark roles that stand for a whole category: hovering anywhere in its column (or row) inspects it. */
+const rowLayout = container => Boolean(container?.querySelector('svg[data-bar-layout="rows"]'));
+const categoryRoles = {
+  bar: "item",
+  waterfall: "item",
+  histogram: "bin",
+  boxplot: "box"
+};
 /** Enhances existing SVG nodes. Pointer/focus changes never rebuild the chart. */
 export function createChartInspector(options) {
   const source = Symbol("chart cursor");
@@ -58,7 +63,7 @@ export function createChartInspector(options) {
     // Read the actual paint before applying inspection styles, including
     // custom series and threshold colors. Invisible points use their line.
     const point = item.element.querySelector(".stdlib-chart-inspection-point");
-    const source = point ? options.container()?.querySelector(options.kind() === "line" ? `.stdlib-chart-line.stdlib-chart-series-${(item.datum.seriesIndex ?? 0) % 8}` : ".stdlib-chart-sparkline, .stdlib-chart-stat-sparkline") : item.element.querySelector(".stdlib-chart-bar-gauge-fill, .stdlib-chart-gauge-fill, .stdlib-chart-stat-value") ?? item.element.querySelector("rect, path, circle");
+    const source = point ? options.container()?.querySelector(options.kind() === "line" ? `.stdlib-chart-line.stdlib-chart-series-${(item.datum.seriesIndex ?? 0) % 8}` : ".stdlib-chart-sparkline, .stdlib-chart-stat-sparkline") : item.element.querySelector(".stdlib-chart-bar-gauge-fill, .stdlib-chart-gauge-fill, .stdlib-chart-stat-value") ?? item.element.querySelector(":is(rect, path, circle):not(.k2b-chart-category-band)");
     const paint = source ? source.ownerDocument.defaultView?.getComputedStyle(source) : undefined;
     const color = (point || item.element.hasAttribute("data-chart-reference") ? paint?.stroke : paint?.fill) || `var(--stdlib-chart-c${(item.datum.seriesIndex ?? 0) % 8 + 1})`;
     return `color-mix(in srgb, ${color} 72%, var(--k2b-chart-highlight-mix))`;
@@ -107,7 +112,23 @@ export function createChartInspector(options) {
     });
   };
   const rawX = entry => entry.datum.values.find(field => field.key === "x")?.value;
-  const seriesChart = () => options.kind() === "line" || options.kind() === "sparkline";
+  const category = entry => options.kind() === "area" ? entry.datum.index : rawX(entry);
+  const groupedSeriesChart = () => options.kind() === "line" || options.kind() === "area";
+  const seriesChart = () => groupedSeriesChart() || options.kind() === "sparkline";
+  const updateLegend = items => {
+    const root = options.legend?.() ?? options.container();
+    for (const node of root?.querySelectorAll("[data-chart-legend-value]") ?? []) {
+      if (!items) {
+        node.textContent = node.getAttribute("data-default") ?? "";
+        continue;
+      }
+      const series = node.dataset.seriesIndex;
+      const field = items.find(item => item.datum.seriesIndex?.toString() === series)?.datum.values.find(field => field.key === node.getAttribute("data-field"));
+      node.textContent = field ? field.formatted ?? (typeof field.value === "number" ? new Intl.NumberFormat(options.locale?.() ?? "en", {
+        maximumFractionDigits: 6
+      }).format(field.value) : field.value) : "—";
+    }
+  };
   const clearHighlight = () => {
     for (const entry of highlighted) {
       entry.element.removeAttribute("data-inspected");
@@ -123,11 +144,17 @@ export function createChartInspector(options) {
     options.container()?.removeAttribute("data-cursor-source");
     pinned = false;
     active = undefined;
+    updateLegend(undefined);
     clearHighlight();
     const container = options.container(),
       id = options.tooltip()?.id;
     if (container && id) describe(container, id, false);
     options.container()?.removeAttribute("data-inspecting");
+    const inspected = options.container();
+    if (inspected) {
+      for (const name of ["left", "top", "width", "height"]) inspected.style.removeProperty(`--k2b-chart-band-${name}`);
+      if (!inspected.getAttribute("style")) inspected.removeAttribute("style");
+    }
     const tooltip = options.tooltip();
     if (tooltip) {
       try {
@@ -150,21 +177,25 @@ export function createChartInspector(options) {
     byElement.clear();
     receive(options.cursor?.()?.read() ?? null);
   };
-  const show = (entry, broadcast = true) => {
+  const show = (entry, broadcast = true, hover = false) => {
     const x = rawX(entry);
     if (broadcast && options.kind() === "line" && typeof x === "number") options.cursor?.()?.move(source, x);
     const tooltip = options.tooltip(),
       anchor = options.anchor(),
       container = options.container();
     if (!tooltip || !anchor || !container || !options.enabled()) return;
-    if (active === entry && tooltip.matches(":popover-open")) return;
+    if ((active === entry || seriesChart() && active && category(active) === category(entry)) && tooltip.matches(":popover-open")) {
+      for (const item of highlighted) item.element.setAttribute("data-inspected", hover ? "hover" : "true");
+      return;
+    }
     clearHighlight();
     active = entry;
-    highlighted = options.kind() === "line" ? records().filter(candidate => rawX(candidate) === rawX(entry)) : [entry];
+    highlighted = groupedSeriesChart() ? records().filter(candidate => category(candidate) === category(entry)) : [entry];
     for (const item of highlighted) {
       item.element.style.setProperty("--k2b-chart-inspection-color", highlightColor(item));
-      item.element.setAttribute("data-inspected", "true");
+      item.element.setAttribute("data-inspected", hover ? "hover" : "true");
     }
+    updateLegend(highlighted);
     const document = tooltip.ownerDocument;
     const contents = highlighted.map(item => ({
       item,
@@ -190,35 +221,32 @@ export function createChartInspector(options) {
       }
       contents.sort((a, b) => (a.item.datum.seriesIndex ?? 0) - (b.item.datum.seriesIndex ?? 0));
     }
+    if (options.kind() === "area") contents.reverse();
     tooltip.replaceChildren();
     const sharedTitle = typeof x === "number" ? options.cursor?.()?.formatX?.(x) : undefined;
     const commonTitle = sharedTitle ?? (contents.every(({
       content
     }) => content.title === contents[0]?.content.title) ? contents[0]?.content.title : undefined);
-    if (commonTitle) {
+    const appendTitle = text => {
       const title = document.createElement("strong");
       title.className = "k2b-chart__tooltip-title";
-      title.textContent = commonTitle;
+      title.textContent = text;
       tooltip.append(title);
-    }
+    };
+    if (commonTitle) appendTitle(commonTitle);
     for (const {
       item,
       content,
       missing
     } of contents) {
-      if (content.title && !commonTitle) {
-        const title = document.createElement("strong");
-        title.className = "k2b-chart__tooltip-title";
-        title.textContent = content.title;
-        tooltip.append(title);
-      }
+      if (content.title && !commonTitle) appendTitle(content.title);
       for (const row of content.rows) {
         const line = document.createElement("span");
         line.className = "k2b-chart__tooltip-row";
-        if (options.kind() === "line") {
+        if (groupedSeriesChart()) {
           const swatch = document.createElement("i");
           swatch.setAttribute("aria-hidden", "true");
-          const series = container.querySelector(`.stdlib-chart-line.stdlib-chart-series-${(item.datum.seriesIndex ?? 0) % 8}`);
+          const series = container.querySelector(`.stdlib-chart-line.stdlib-chart-series-${(item.datum.seriesIndex ?? 0) % 8}, .k2b-area-edge-${(item.datum.seriesIndex ?? 0) % 8}`);
           swatch.style.background = series ? getComputedStyle(series).stroke : `var(--stdlib-chart-c${(item.datum.seriesIndex ?? 0) % 8 + 1})`;
           line.append(swatch);
         }
@@ -230,13 +258,38 @@ export function createChartInspector(options) {
         tooltip.append(line);
       }
     }
+    if (options.kind() === "area") {
+      const total = entry.datum.values.find(field => field.key === "total");
+      const totalLabel = container.querySelector("svg[data-chart-total-label]")?.getAttribute("data-chart-total-label");
+      if (total && totalLabel) {
+        const line = document.createElement("span");
+        line.className = "k2b-chart__tooltip-row";
+        const label = document.createElement("span");
+        label.textContent = `${totalLabel}: `;
+        const value = document.createElement("b");
+        value.textContent = total.formatted ?? String(total.value);
+        line.append(label, value);
+        tooltip.append(line);
+      }
+    }
     const rect = container.getBoundingClientRect(),
       point = screenPoint(entry);
-    anchor.style.left = `${point.x - rect.left}px`;
-    anchor.style.top = `${point.y - rect.top}px`;
+    const slot = categoryBands().find(candidate => candidate.entry === entry);
+    // A renderer that draws its own band inside the category's mark keeps it; the overlay only fills the others.
+    const band = slot && !entry.element.querySelector(".k2b-chart-category-band") ? slot : undefined;
+    const rows = rowLayout(container);
+    // A column's tooltip waits at the top of the plot, so it stays put while the pointer moves within the column.
+    anchor.style.left = `${(slot && !rows ? (slot.left + slot.right) / 2 : point.x) - rect.left + container.scrollLeft}px`;
+    anchor.style.top = `${(slot && !rows ? slot.top : point.y) - rect.top + container.scrollTop}px`;
     updatePlotBounds();
-    container.style.setProperty("--k2b-chart-inspection-x", `${point.x - rect.left}px`);
-    container.setAttribute("data-inspecting", seriesChart() ? "series" : "datum");
+    container.style.setProperty("--k2b-chart-inspection-x", `${point.x - rect.left + container.scrollLeft}px`);
+    if (band) {
+      container.style.setProperty("--k2b-chart-band-left", `${band.left - rect.left + container.scrollLeft}px`);
+      container.style.setProperty("--k2b-chart-band-top", `${band.top - rect.top + container.scrollTop}px`);
+      container.style.setProperty("--k2b-chart-band-width", `${band.right - band.left}px`);
+      container.style.setProperty("--k2b-chart-band-height", `${band.bottom - band.top}px`);
+    }
+    container.setAttribute("data-inspecting", seriesChart() ? "series" : band ? "category" : "datum");
     describe(container, tooltip.id, true);
     try {
       if (!tooltip.matches(":popover-open")) tooltip.showPopover();
@@ -245,6 +298,50 @@ export function createChartInspector(options) {
       /* SVG titles remain available without the Popover API. */
     }
   };
+  /**
+   * The screen slot of every category, halfway to its neighbours. A light band fills the inspected slot instead of
+   * dimming other marks or outlining a bar, and the pointer anywhere in a slot keeps the same category.
+   */
+  const categoryBands = () => {
+    const role = categoryRoles[options.kind()];
+    const container = options.container();
+    if (!role || !container) return [];
+    const rows = rowLayout(container);
+    const slots = records().filter(entry => entry.datum.role === role).map(entry => ({
+      entry,
+      rect: entry.element.getBoundingClientRect()
+    }));
+    if (!slots.length) return [];
+    const guides = Array.from(container.querySelectorAll(".stdlib-chart-grid, .stdlib-chart-axis")).map(node => node.getBoundingClientRect());
+    // The band spans the plot across the categories: grid lines and every mark, so rows without value ticks, whose
+    // only guide is one vertical baseline, still get a band from the baseline to the longest bar.
+    const spans = [...guides, ...slots.map(slot => slot.rect)];
+    const start = Math.min(...spans.map(rect => rows ? rect.left : rect.top));
+    const end = Math.max(...spans.map(rect => rows ? rect.right : rect.bottom));
+    const center = rect => rows ? rect.top + rect.height / 2 : rect.left + rect.width / 2;
+    slots.sort((a, b) => center(a.rect) - center(b.rect));
+    return slots.map((slot, index) => {
+      const middle = center(slot.rect);
+      const previous = slots[index - 1],
+        next = slots[index + 1];
+      const half = previous || next ? Math.abs(center((next ?? previous).rect) - middle) / 2 : (rows ? slot.rect.height : slot.rect.width) * 0.75;
+      const low = previous ? (center(previous.rect) + middle) / 2 : middle - half;
+      const high = next ? (center(next.rect) + middle) / 2 : middle + half;
+      return rows ? {
+        entry: slot.entry,
+        left: start,
+        right: end,
+        top: low,
+        bottom: high
+      } : {
+        entry: slot.entry,
+        left: low,
+        right: high,
+        top: start,
+        bottom: end
+      };
+    });
+  };
   const updatePlotBounds = () => {
     const container = options.container();
     if (!container) return;
@@ -293,6 +390,27 @@ export function createChartInspector(options) {
     const direct = target?.closest("[data-chart-datum]");
     const hit = direct ? byElement.get(direct) : undefined;
     if (hit && nodes.includes(hit)) return hit;
+    const bands = categoryBands();
+    if (bands.length) {
+      // Marks of their own inside a category, such as box-plot outliers, keep their forgiving hit radius.
+      const role = categoryRoles[options.kind()];
+      let loose,
+        gap = 24;
+      for (const entry of nodes) {
+        if (entry.datum.role === role) continue;
+        const point = screenPoint(entry);
+        const distance = Math.hypot(point.x - x, point.y - y);
+        if (distance <= gap) {
+          gap = distance;
+          loose = entry;
+        }
+      }
+      if (loose) return loose;
+      const rows = rowLayout(options.container());
+      const frame = options.container()?.getBoundingClientRect();
+      const inside = frame && x >= frame.left && x <= frame.right && y >= frame.top && y <= frame.bottom;
+      return inside ? bands.find(band => rows ? y >= band.top && y <= band.bottom : x >= band.left && x <= band.right)?.entry : undefined;
+    }
     if (seriesChart()) {
       const plot = updatePlotBounds();
       // SVG transforms and DOM rectangles can round the same painted edge
@@ -343,7 +461,7 @@ export function createChartInspector(options) {
   };
   const move = event => {
     if (event.target instanceof Node && options.tooltip()?.contains(event.target)) return;
-    if (pointerStart && Math.hypot(event.clientX - pointerStart.x, event.clientY - pointerStart.y) > 6) moved = true;
+    if (pointerStart && Math.hypot(event.clientX - pointerStart.x, event.clientY - pointerStart.y) > 8) moved = true;
     if (!options.enabled() || pinned || event.pointerType === "touch" || event.buttons) return;
     pending = {
       x: event.clientX,
@@ -358,7 +476,7 @@ export function createChartInspector(options) {
       if (!sample) return;
       const entry = nearest(sample.x, sample.y, sample.target);
       if (entry) {
-        show(entry);
+        show(entry, true, true);
         if (seriesChart()) {
           const container = options.container();
           container?.setAttribute("data-cursor-source", "true");
@@ -367,14 +485,20 @@ export function createChartInspector(options) {
       } else close();
     });
   };
+  let pointerFocusing = false;
   const down = event => {
+    pointerFocusing = true;
     pointerStart = {
       x: event.clientX,
       y: event.clientY
     };
     moved = false;
   };
+  const up = () => {
+    pointerFocusing = false;
+  };
   const click = event => {
+    pointerFocusing = false;
     if (!options.enabled() || moved || event.target instanceof Element && event.target.closest("button,a")) return;
     const entry = nearest(event.clientX, event.clientY, event.target instanceof Element ? event.target : null);
     if (!entry) {
@@ -390,8 +514,12 @@ export function createChartInspector(options) {
   };
   const focus = event => {
     if (event.target !== options.container() || !options.enabled()) return;
+    if (pointerFocusing && options.nav?.()?.pointer === false) {
+      pointerFocusing = false;
+      return;
+    }
     const nodes = visibleRecords();
-    const first = options.kind() === "line" ? sortedPoints.at(-1) : nodes[0];
+    const first = options.nav?.()?.last ? nodes.at(-1) : options.kind() === "line" ? sortedPoints.at(-1) : nodes[0];
     if (first) show(first);
   };
   const key = event => {
@@ -422,10 +550,10 @@ export function createChartInspector(options) {
     if (!["Home", "End", "ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.key)) return false;
     let nodes = visibleRecords();
     if (seriesChart()) nodes = [...nodes].sort((a, b) => a.datum.anchor[0] - b.datum.anchor[0]);
-    if (options.kind() === "line") {
+    if (groupedSeriesChart()) {
       const seen = new Set();
       nodes = nodes.filter(entry => {
-        const x = rawX(entry);
+        const x = category(entry);
         if (seen.has(x)) return false;
         seen.add(x);
         return true;
@@ -434,7 +562,7 @@ export function createChartInspector(options) {
     if (!nodes.length) return false;
     event.preventDefault();
     pinned = false;
-    let index = active ? options.kind() === "line" ? nodes.findIndex(entry => rawX(entry) === rawX(active)) : nodes.indexOf(active) : -1;
+    let index = active ? groupedSeriesChart() ? nodes.findIndex(entry => category(entry) === category(active)) : nodes.indexOf(active) : -1;
     if (event.key === "Home") index = 0;else if (event.key === "End") index = nodes.length - 1;else if (active?.datum.grid && ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"].includes(event.key)) {
       const [x, y] = active.datum.grid;
       const dx = event.key === "ArrowLeft" ? -1 : event.key === "ArrowRight" ? 1 : 0;
@@ -442,7 +570,9 @@ export function createChartInspector(options) {
       const next = nodes.filter(entry => entry.datum.grid && (dx ? entry.datum.grid[1] === y && (entry.datum.grid[0] - x) * dx > 0 : entry.datum.grid[0] === x && (entry.datum.grid[1] - y) * dy > 0)).sort((a, b) => Math.abs(a.datum.grid[0] - x) + Math.abs(a.datum.grid[1] - y) - Math.abs(b.datum.grid[0] - x) - Math.abs(b.datum.grid[1] - y))[0];
       if (next) index = nodes.indexOf(next);
     } else index += event.key === "ArrowLeft" || event.key === "ArrowUp" ? -1 : 1;
-    show(nodes[Math.max(0, Math.min(nodes.length - 1, index))]);
+    const next = nodes[Math.max(0, Math.min(nodes.length - 1, index))];
+    options.nav?.()?.reveal?.(next.element);
+    show(next);
     return true;
   };
   return {
@@ -452,6 +582,7 @@ export function createChartInspector(options) {
     destroy: () => close(false),
     move,
     down,
+    up,
     click,
     focus,
     key,
@@ -469,6 +600,7 @@ export function closeChartInspectionOnOutside(options) {
     if (event.target instanceof Node && !options.container()?.contains(event.target)) options.close();
   };
   const scroll = event => {
+    if (event.target === options.container() && options.keepScroll?.()) return;
     if (event.target instanceof Node && options.tooltip()?.contains(event.target)) return;
     options.close();
   };
@@ -502,25 +634,27 @@ export function inspectChart(container, options) {
   if (addedTabindex) container.setAttribute("tabindex", "0");
   const inspector = createChartInspector({
     container: () => container,
+    locale: () => options.locale ?? "en",
+    legend: () => options.legend,
     cursor: () => options.cursor,
     tooltip: () => tooltip,
     anchor: () => anchor,
     kind: () => options.kind,
+    nav: () => options.nav,
     enabled: () => true,
     format: options.format,
     select: selection => options.select?.(selection)
   });
-  container.addEventListener("pointerdown", inspector.down);
-  container.addEventListener("pointermove", inspector.move);
-  container.addEventListener("click", inspector.click);
-  container.addEventListener("pointerleave", inspector.leave);
-  container.addEventListener("focusin", inspector.focus);
-  container.addEventListener("focusout", inspector.close);
-  container.addEventListener("keydown", inspector.key);
+  const listen = (name, listener) => {
+    container.addEventListener(name, listener);
+    return () => container.removeEventListener(name, listener);
+  };
+  const removeListeners = [listen("pointerdown", inspector.down), listen("pointerup", inspector.up), listen("pointercancel", inspector.up), listen("pointermove", inspector.move), listen("click", inspector.click), listen("pointerleave", inspector.leave), listen("focusin", inspector.focus), listen("focusout", inspector.close), listen("keydown", inspector.key)];
   const removeOutside = closeChartInspectionOnOutside({
     container: () => container,
     tooltip: () => tooltip,
-    close: inspector.close
+    close: inspector.close,
+    keepScroll: () => options.nav?.keepScroll
   });
   const unlinkCursor = inspector.linkCursor(options.cursor);
   let destroyed = false;
@@ -534,13 +668,7 @@ export function inspectChart(container, options) {
     destroy() {
       if (destroyed) return;
       destroyed = true;
-      container.removeEventListener("pointerdown", inspector.down);
-      container.removeEventListener("pointermove", inspector.move);
-      container.removeEventListener("click", inspector.click);
-      container.removeEventListener("pointerleave", inspector.leave);
-      container.removeEventListener("focusin", inspector.focus);
-      container.removeEventListener("focusout", inspector.close);
-      container.removeEventListener("keydown", inspector.key);
+      for (const remove of removeListeners) remove();
       removeOutside();
       unlinkCursor();
       inspector.destroy();