@k2b/ui 0.51.0 → 0.52.0

package/dist/browser/charts/core/svg-common.js

@@ -0,0 +1,1065 @@
+// Ported from @k2b/stdlib 0.30.0 (ISC); retain SVG and numeric algorithms until parity proves changes.
+// ==========================
+// SVG Chart Generation
+// ==========================
+//
+// Pure-native SVG generation for the four basic chart types: scatter, line,
+// bar, and pie/donut. Returns SVG strings — inject directly into the DOM,
+// write to disk, or send over the wire. No peer dependencies.
+//
+// Charts ship with embedded default CSS using semantic class names and CSS
+// custom properties for colors. Consumers override styles via class selectors
+// (their CSS wins on specificity) or CSS variables (`--stdlib-chart-c1` ...
+// `--stdlib-chart-c8`). Axes and labels use `currentColor` so parent `color`
+// drives theming (dark mode "just works").
+
+import { DEFAULT_STYLES } from "./default-styles";
+
+// ==========================
+// PUBLIC TYPES
+// ==========================
+
+/** Marker shapes for `scatter` data points. Auto-cycles per series when
+ *  `autoVariant` is enabled on the chart. */
+
+/** Line dash patterns for `line` series. Auto-cycles per series when
+ *  `autoVariant` is enabled. */
+
+export const itemColorIndex = (item, fallback) => {
+  const index = item.colorIndex ?? fallback;
+  if (!Number.isInteger(index) || index < 0) throw new RangeError("Chart colorIndex must be a nonnegative integer");
+  return index % 8;
+};
+/** One selectable datum in an inspected SVG. Indices refer to the source arrays.
+ * `anchor` uses the containing SVG coordinate system, including nested map SVGs.
+ * Values are raw data; `formatted` contains the renderer's axis/value formatting.
+ */
+
+/** Wrap renderer-owned geometry with escaped, inert inspection metadata. */
+export const chartDatumSvg = (svg, datum, inspect, titleText) => {
+  if (!inspect || !datum.anchor.every(Number.isFinite)) return svg;
+  const title = titleText ?? [datum.label, ...datum.values.map(field => `${field.key}: ${field.formatted ?? field.value}`)].filter(Boolean).join(" · ");
+  return `<g data-chart-role="${escapeXml(datum.role)}" data-chart-datum="${escapeXml(JSON.stringify(datum))}"><title>${escapeXml(title)}</title>${svg}</g>`;
+};
+export const inspectionPoint = (datum, inspect) => inspect ? chartDatumSvg(`<circle class="stdlib-chart-inspection-point" cx="${fmt(datum.anchor[0])}" cy="${fmt(datum.anchor[1])}" r="3" fill="transparent" stroke="none"/>`, datum, true) : "";
+export const pointValues = (p, xAxis, yAxis) => [{
+  key: "x",
+  value: p.x,
+  formatted: xAxis?.format?.(p.x)
+}, {
+  key: "y",
+  value: p.y,
+  formatted: yAxis?.format?.(p.y)
+}, ...Object.entries(p).filter(([key, value]) => key !== "x" && key !== "y" && typeof value === "number" && Number.isFinite(value)).map(([key, value]) => ({
+  key,
+  value
+}))];
+
+/**
+ * A horizontal or vertical reference line drawn on a cartesian chart, e.g.
+ * for thresholds, targets, or averages.
+ */
+
+/** Internal shared attributes for raw cartesian charts and UI bar layouts. */
+export const referenceLineAttributes = (ref, label = false) => {
+  const declarations = [];
+  if (!label && ref.style !== undefined) {
+    const styles = {
+      solid: "none",
+      dashed: "4 4",
+      dotted: "1 3"
+    };
+    const dash = styles[ref.style];
+    if (typeof dash !== "string") throw new RangeError("Invalid reference line style");
+    declarations.push(`stroke-dasharray:${dash}`);
+    if (ref.style === "dotted") declarations.push("stroke-linecap:round");
+  }
+  if (ref.tone !== undefined) {
+    const tones = {
+      neutral: "currentColor",
+      info: "var(--k2b-info-text,#1d4ed8)",
+      success: "var(--k2b-success-text,#047857)",
+      warning: "var(--k2b-warning-text,#92400e)",
+      danger: "var(--k2b-danger-text,#b91c1c)"
+    };
+    const color = tones[ref.tone];
+    if (typeof color !== "string") throw new RangeError("Invalid reference line tone");
+    declarations.push(`color:${color}`);
+  }
+  return declarations.length ? ` style="${declarations.join(";")}"` : "";
+};
+
+// ==========================
+// CONSTANTS
+// ==========================
+
+export const DEFAULT_WIDTH = 400;
+export const DEFAULT_HEIGHT = 240;
+const DEFAULT_PADDING = {
+  top: 16,
+  right: 16,
+  bottom: 32,
+  left: 40
+};
+const DEFAULT_TICKS = 5;
+export const DEFAULT_MARKERS = ["circle", "square", "triangle", "diamond", "plus", "cross"];
+export const DEFAULT_LINE_STYLES = ["solid", "dashed", "dotted", "dashdot"];
+
+/** SVG `stroke-dasharray` values per line style. Empty string = no dasharray. */
+export const LINE_DASH_PATTERNS = {
+  solid: "",
+  dashed: "6 4",
+  dotted: "2 3",
+  dashdot: "6 3 2 3"
+};
+
+// ==========================
+// HELPERS (pure)
+// ==========================
+
+/** XML-escape a string for safe inclusion in attribute values or text content. */
+export const escapeXml = s => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+
+/** Normalize a `Padding` input (number or partial object) to a full `Padding`. */
+export const normalizePadding = p => {
+  if (p === undefined) return {
+    ...DEFAULT_PADDING
+  };
+  if (typeof p === "number") return {
+    top: p,
+    right: p,
+    bottom: p,
+    left: p
+  };
+  return {
+    top: p.top ?? DEFAULT_PADDING.top,
+    right: p.right ?? DEFAULT_PADDING.right,
+    bottom: p.bottom ?? DEFAULT_PADDING.bottom,
+    left: p.left ?? DEFAULT_PADDING.left
+  };
+};
+
+/**
+ * Compute `[min, max]` from a list of numeric values, ignoring non-finite
+ * entries. Returns `[0, 1]` for an empty/all-non-finite list and pads ±1
+ * around a single finite value.
+ */
+export const computeDomain = values => {
+  let min = Number.POSITIVE_INFINITY;
+  let max = Number.NEGATIVE_INFINITY;
+  for (const v of values) {
+    if (!Number.isFinite(v)) continue;
+    if (v < min) min = v;
+    if (v > max) max = v;
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return [0, 1];
+  if (min === max) return [min - 1, max + 1];
+  return [min, max];
+};
+
+/**
+ * Pick a "nice" axis step (1, 2, 5, 10, 20, 50, ...) that splits `range`
+ * into roughly `target` intervals. Avoids ugly tick labels like 0.473.
+ */
+export const niceStep = (range, target) => {
+  if (range <= 0 || target <= 0) return 1;
+  const rough = range / target;
+  const mag = Math.pow(10, Math.floor(Math.log10(rough)));
+  const norm = rough / mag;
+  const nice = norm < 1.5 ? 1 : norm < 3 ? 2 : norm < 7 ? 5 : 10;
+  return nice * mag;
+};
+
+/** The most ticks one linear axis counts, the same budget as a time axis; more never fit a readable axis. */
+export const MAX_AXIS_TICKS = 1_000;
+
+/**
+ * Round `min` down and `max` up to the nearest multiples of `step`, so the
+ * domain edges fall on tick boundaries. Returns the extended domain plus the
+ * tick values within it (inclusive of both ends).
+ */
+export const extendDomainToNice = (min, max, step) => {
+  const lo = Math.floor(min / step) * step;
+  const hi = Math.ceil(max / step) * step;
+  const ticks = [];
+  // Use rounding to avoid floating-point drift at tick positions.
+  const decimals = Math.max(0, -Math.floor(Math.log10(step)));
+  const round = v => Number(v.toFixed(Math.min(decimals + 2, 12)));
+  // A step below the float spacing of large values never advances, and a tiny step counts without end: keep the ends.
+  const ends = {
+    domain: [lo, hi],
+    ticks: [...new Set([round(lo), round(hi)])]
+  };
+  if ((hi - lo) / step > MAX_AXIS_TICKS) return ends;
+  for (let v = lo; v <= hi + step / 2;) {
+    ticks.push(round(v));
+    const next = v + step;
+    if (next <= v) return ends;
+    v = next;
+  }
+  return {
+    domain: [lo, hi],
+    ticks
+  };
+};
+
+/** Linear map of `value` from input domain `[d0, d1]` to output range `[r0, r1]`. */
+export const mapRange = (value, [d0, d1], [r0, r1]) => {
+  if (d1 === d0) return (r0 + r1) / 2;
+  return r0 + (value - d0) / (d1 - d0) * (r1 - r0);
+};
+
+/**
+ * Logarithmic (base-10) map of `value` from input domain `[d0, d1]` to
+ * output range `[r0, r1]`. Both domain endpoints must be strictly positive.
+ * Non-positive values are clamped to a small epsilon to avoid `-Infinity`.
+ */
+export const mapLog = (value, [d0, d1], [r0, r1]) => {
+  if (d0 <= 0 || d1 <= 0) return (r0 + r1) / 2;
+  const v = Math.max(value, 1e-300);
+  const logD0 = Math.log10(d0);
+  const logD1 = Math.log10(d1);
+  if (logD0 === logD1) return (r0 + r1) / 2;
+  return r0 + (Math.log10(v) - logD0) / (logD1 - logD0) * (r1 - r0);
+};
+
+/**
+ * Compute logarithmic ticks (powers of 10) within `[min, max]`. The
+ * returned array always includes both decade boundaries enclosing the
+ * domain so the axis line spans the data.
+ */
+export const niceLogTicks = (min, max) => {
+  const safeMin = Math.max(min, 1e-300);
+  const safeMax = Math.max(max, safeMin);
+  // Clamp the log-tick range to a finite, SVG-safe span so callers passing
+  // Number.MAX_VALUE (or non-finite extremes) don't trigger an infinite loop.
+  // 1e-30 .. 1e30 covers every real-world scientific magnitude.
+  const MIN_EXP = -30;
+  const MAX_EXP = 30;
+  const loExp = Math.max(MIN_EXP, Math.floor(Math.log10(safeMin)));
+  const hiExp = Math.min(MAX_EXP, Math.ceil(Math.log10(safeMax)));
+  const lo = Math.pow(10, loExp);
+  const hi = Math.pow(10, Math.max(loExp, hiExp));
+  const ticks = [];
+  // Iterate by exponent to avoid floating-point drift at extreme ranges.
+  for (let e = loExp; e <= Math.max(loExp, hiExp); e++) {
+    ticks.push(Math.pow(10, e));
+  }
+  return {
+    domain: [lo, hi],
+    ticks
+  };
+};
+
+/**
+ * Least-squares linear regression. Returns slope, intercept, and r² for the
+ * regression line `y = slope * x + intercept`. Returns null for fewer than
+ * two finite points or all-x-equal input.
+ */
+export const linearRegression = points => {
+  const finite = points.filter(p => Number.isFinite(p.x) && Number.isFinite(p.y));
+  const n = finite.length;
+  if (n < 2) return null;
+  let sumX = 0;
+  let sumY = 0;
+  for (const p of finite) {
+    sumX += p.x;
+    sumY += p.y;
+  }
+  const meanX = sumX / n;
+  const meanY = sumY / n;
+  let num = 0;
+  let denom = 0;
+  let totalSS = 0;
+  for (const p of finite) {
+    const dx = p.x - meanX;
+    const dy = p.y - meanY;
+    num += dx * dy;
+    denom += dx * dx;
+    totalSS += dy * dy;
+  }
+  if (denom === 0) return null;
+  const slope = num / denom;
+  const intercept = meanY - slope * meanX;
+  // r² via 1 - SSres / SStot
+  let resSS = 0;
+  for (const p of finite) {
+    const predicted = slope * p.x + intercept;
+    const resid = p.y - predicted;
+    resSS += resid * resid;
+  }
+  const r2 = totalSS === 0 ? 1 : 1 - resSS / totalSS;
+  return {
+    slope,
+    intercept,
+    r2
+  };
+};
+
+/**
+ * Compute box-plot statistics for a set of observations:
+ * min/max, quartiles (q1/q2/q3 via R-7 linear interpolation), Tukey whiskers
+ * (1.5×IQR rule clamped to data extents), and outliers beyond the whiskers.
+ *
+ * Returns null for an empty/all-non-finite input.
+ */
+export const computeBoxStats = values => {
+  const finite = values.filter(v => Number.isFinite(v));
+  if (finite.length === 0) return null;
+  const sorted = [...finite].sort((a, b) => a - b);
+  const quantile = q => {
+    // R-7 (linear interpolation between consecutive order statistics).
+    const pos = q * (sorted.length - 1);
+    const lo = Math.floor(pos);
+    const hi = Math.ceil(pos);
+    if (lo === hi) return sorted[lo];
+    return sorted[lo] + (pos - lo) * (sorted[hi] - sorted[lo]);
+  };
+  const q1 = quantile(0.25);
+  const q2 = quantile(0.5);
+  const q3 = quantile(0.75);
+  const iqr = q3 - q1;
+  const fenceLow = q1 - 1.5 * iqr;
+  const fenceHigh = q3 + 1.5 * iqr;
+  // Whiskers extend to the most-extreme data point still inside the fences.
+  let whiskerLow = q1;
+  let whiskerHigh = q3;
+  for (const v of sorted) {
+    if (v >= fenceLow && v < whiskerLow) whiskerLow = v;
+    if (v <= fenceHigh && v > whiskerHigh) whiskerHigh = v;
+  }
+  const outliers = sorted.filter(v => v < fenceLow || v > fenceHigh);
+  return {
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    q1,
+    q2,
+    q3,
+    whiskerLow,
+    whiskerHigh,
+    outliers
+  };
+};
+
+/**
+ * Bin a numeric dataset into a histogram. `bins` may be:
+ * - undefined → Sturges' formula `ceil(log2(n)) + 1`
+ * - a number → that many equal-width bins
+ * - an array of edges (length k+1 → k bins)
+ *
+ * Non-finite input values are filtered. Returns bin edges and per-bin counts.
+ */
+export const autoBin = (values, bins) => {
+  const finite = values.filter(v => Number.isFinite(v));
+  if (finite.length === 0) return {
+    edges: [0, 1],
+    counts: [0]
+  };
+
+  // Cap bin count so a malicious / mistyped `bins: 1e9` doesn't allocate
+  // gigabytes. 1024 is generous: 30 is Sturges' for 1e9 samples.
+  const MAX_BINS = 1024;
+  let edges;
+  if (Array.isArray(bins)) {
+    const sorted = [...bins].filter(e => Number.isFinite(e)).sort((a, b) => a - b);
+    if (sorted.length >= 2) {
+      edges = sorted;
+    } else {
+      // Empty or single-edge input → fall back to a single auto-bin span over
+      // the data so we never emit `[undefined, NaN]` edges.
+      const dmin = Math.min(...finite);
+      const dmax = Math.max(...finite);
+      edges = dmin === dmax ? [dmin - 0.5, dmin + 0.5] : [dmin, dmax];
+    }
+  } else {
+    // Single-loop min/max — `Math.min(...arr)` fails with RangeError on huge
+    // arrays (call-stack overflow) and is also O(n) anyway.
+    let min = Infinity;
+    let max = -Infinity;
+    for (const v of finite) {
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+    const range = max - min;
+    let k;
+    if (typeof bins === "number" && bins > 0) {
+      k = Math.min(MAX_BINS, Math.floor(bins));
+    } else {
+      k = Math.max(1, Math.min(MAX_BINS, Math.ceil(Math.log2(finite.length)) + 1));
+    }
+    if (range === 0) {
+      edges = [min - 0.5, min + 0.5];
+    } else {
+      const step = range / k;
+      edges = Array.from({
+        length: k + 1
+      }, (_, i) => min + i * step);
+    }
+  }
+  const counts = new Array(edges.length - 1).fill(0);
+  for (const v of finite) {
+    // Right-open intervals [e_i, e_{i+1}); last bin closed-closed.
+    let bin = -1;
+    for (let i = 0; i < counts.length; i++) {
+      const isLast = i === counts.length - 1;
+      if (v >= edges[i] && (isLast ? v <= edges[i + 1] : v < edges[i + 1])) {
+        bin = i;
+        break;
+      }
+    }
+    if (bin >= 0) counts[bin] += 1;
+  }
+  return {
+    edges,
+    counts
+  };
+};
+
+// ==========================
+// SVG SKELETON
+// ==========================
+
+export const computePlotArea = (width, height, padding, hasXAxisLabel, hasYAxisLabel, headerHeight = 0, legendHeight = 0) => {
+  // Reserve extra space when axis labels are present.
+  const extraBottom = hasXAxisLabel ? 14 : 0;
+  const extraLeft = hasYAxisLabel ? 14 : 0;
+  return {
+    x0: padding.left + extraLeft,
+    y0: padding.top + headerHeight,
+    x1: width - padding.right,
+    y1: height - padding.bottom - extraBottom - legendHeight
+  };
+};
+
+/**
+ * Render an optional centered header (title + subtitle) at the top of an
+ * SVG. Returns the SVG fragment plus the pixel height it consumed so the
+ * caller can shift the plot area down accordingly.
+ */
+export const renderHeader = (width, title, subtitle) => {
+  if (!title && !subtitle) return {
+    svg: "",
+    height: 0
+  };
+  const cx = width / 2;
+  const parts = [];
+  let y = 16;
+  if (title) {
+    parts.push(`<text class="stdlib-chart-title" x="${fmt(cx)}" y="${fmt(y)}" text-anchor="middle">${escapeXml(title)}</text>`);
+    y += 14;
+  }
+  if (subtitle) {
+    parts.push(`<text class="stdlib-chart-subtitle" x="${fmt(cx)}" y="${fmt(y)}" text-anchor="middle">${escapeXml(subtitle)}</text>`);
+    y += 6;
+  }
+  return {
+    svg: parts.join(""),
+    height: y
+  };
+};
+
+/**
+ * Render reference lines (horizontal or vertical thresholds) within the plot
+ * area. Out-of-domain values are silently skipped. Honors per-axis scale
+ * (linear or log).
+ */
+export const renderReferenceLines = (refs, xAxis, yAxis, area) => {
+  const xMap = pickMapper(xAxis.scale);
+  const yMap = pickMapper(yAxis.scale);
+  const parts = [];
+  for (const ref of refs) {
+    if (!Number.isFinite(ref.value)) continue;
+    const axis = ref.axis ?? "y";
+    if (axis === "y") {
+      if (ref.value < yAxis.domain[0] || ref.value > yAxis.domain[1]) continue;
+      const y = yMap(ref.value, yAxis.domain, [area.y1, area.y0]);
+      parts.push(`<line class="stdlib-chart-reference"${referenceLineAttributes(ref)} x1="${fmt(area.x0)}" y1="${fmt(y)}" x2="${fmt(area.x1)}" y2="${fmt(y)}"/>`);
+      if (ref.label) {
+        parts.push(`<text class="stdlib-chart-reference-label"${referenceLineAttributes(ref, true)} x="${fmt(area.x1 - 4)}" y="${fmt(y - 4)}" text-anchor="end">${escapeXml(ref.label)}</text>`);
+      }
+    } else {
+      if (ref.value < xAxis.domain[0] || ref.value > xAxis.domain[1]) continue;
+      const x = xMap(ref.value, xAxis.domain, [area.x0, area.x1]);
+      parts.push(`<line class="stdlib-chart-reference"${referenceLineAttributes(ref)} x1="${fmt(x)}" y1="${fmt(area.y0)}" x2="${fmt(x)}" y2="${fmt(area.y1)}"/>`);
+      if (ref.label) {
+        parts.push(`<text class="stdlib-chart-reference-label"${referenceLineAttributes(ref, true)} x="${fmt(x + 4)}" y="${fmt(area.y0 + 12)}">${escapeXml(ref.label)}</text>`);
+      }
+    }
+  }
+  return parts.join("");
+};
+
+/**
+ * Resolve a point's effective error extents into `[low, high]` magnitudes
+ * (relative deltas, both ≥ 0). Asymmetric `errYHigh`/`errYLow` take precedence
+ * over symmetric `errY`. Returns null when no error info is set.
+ */
+export const resolveErrorY = p => {
+  const high = p.errYHigh ?? p.errY;
+  const low = p.errYLow ?? p.errY;
+  if (high === undefined && low === undefined) return null;
+  return [Number.isFinite(low) ? Math.abs(low) : 0, Number.isFinite(high) ? Math.abs(high) : 0];
+};
+const resolveErrorX = p => {
+  const high = p.errXHigh ?? p.errX;
+  const low = p.errXLow ?? p.errX;
+  if (high === undefined && low === undefined) return null;
+  return [Number.isFinite(low) ? Math.abs(low) : 0, Number.isFinite(high) ? Math.abs(high) : 0];
+};
+
+/** Build the SVG fragment for the per-point error bars across all series. */
+export const renderErrorBars = (series, xAxis, yAxis, area) => {
+  const xMap = pickMapper(xAxis.scale);
+  const yMap = pickMapper(yAxis.scale);
+  const CAP = 4; // half-width of error bar caps in pixels
+  const parts = [];
+  for (const s of series) {
+    for (const p of s.data) {
+      if (!Number.isFinite(p.x) || !Number.isFinite(p.y)) continue;
+      const cx = xMap(p.x, xAxis.domain, [area.x0, area.x1]);
+      const cy = yMap(p.y, yAxis.domain, [area.y1, area.y0]);
+      const yErr = resolveErrorY(p);
+      if (yErr) {
+        const [low, high] = yErr;
+        const yHi = yMap(p.y + high, yAxis.domain, [area.y1, area.y0]);
+        const yLo = yMap(p.y - low, yAxis.domain, [area.y1, area.y0]);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(cx)}" y1="${fmt(yHi)}" x2="${fmt(cx)}" y2="${fmt(yLo)}"/>`);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(cx - CAP)}" y1="${fmt(yHi)}" x2="${fmt(cx + CAP)}" y2="${fmt(yHi)}"/>`);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(cx - CAP)}" y1="${fmt(yLo)}" x2="${fmt(cx + CAP)}" y2="${fmt(yLo)}"/>`);
+        // Mark we need cy to match data point — ensure we use it (silences unused warnings if any).
+        void cy;
+      }
+      const xErr = resolveErrorX(p);
+      if (xErr) {
+        const [low, high] = xErr;
+        const xHi = xMap(p.x + high, xAxis.domain, [area.x0, area.x1]);
+        const xLo = xMap(p.x - low, xAxis.domain, [area.x0, area.x1]);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(xLo)}" y1="${fmt(cy)}" x2="${fmt(xHi)}" y2="${fmt(cy)}"/>`);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(xLo)}" y1="${fmt(cy - CAP)}" x2="${fmt(xLo)}" y2="${fmt(cy + CAP)}"/>`);
+        parts.push(`<line class="stdlib-chart-errorbar" x1="${fmt(xHi)}" y1="${fmt(cy - CAP)}" x2="${fmt(xHi)}" y2="${fmt(cy + CAP)}"/>`);
+      }
+    }
+  }
+  return parts.join("");
+};
+
+/** Collect all values relevant for axis-domain computation, including error
+ *  extents so error bars don't get clipped. */
+export const collectAxisValues = (series, axis) => {
+  const out = [];
+  for (const s of series) {
+    for (const p of s.data) {
+      const v = axis === "x" ? p.x : p.y;
+      if (!Number.isFinite(v)) continue;
+      out.push(v);
+      const err = axis === "x" ? resolveErrorX(p) : resolveErrorY(p);
+      if (err) {
+        out.push(v - err[0]);
+        out.push(v + err[1]);
+      }
+    }
+  }
+  return out;
+};
+
+/**
+ * Render a single-row centered legend at the bottom of the SVG. Returns the
+ * SVG fragment plus the height it consumed so callers can shift the plot
+ * area up accordingly. Empty input yields height 0.
+ */
+export const renderLegend = (items, width, yTop) => {
+  if (items.length === 0) return {
+    svg: "",
+    height: 0
+  };
+  const ROW_HEIGHT = 20;
+  const ITEM_GAP = 16;
+  const SWATCH = 8;
+  const SWATCH_GAP = 4;
+  const SIDE_PADDING = 4;
+  // Approximate text width per character at 11px — good enough for centering.
+  const charWidth = 6.5;
+  const itemWidths = items.map(it => SWATCH + SWATCH_GAP + Math.max(it.label.length, 1) * charWidth);
+
+  // Greedy line-break: pack items into rows so each row fits inside the
+  // available width. Single-row legends (≤ a few short labels) still render
+  // on one line — no visual change for the line/scatter/bar callers that
+  // typically have only 2-4 series. Pie/donut with long "Label (XX%)" entries
+  // and 5+ slices wrap to multiple rows instead of overflowing the viewBox.
+  const availableWidth = Math.max(40, width - 2 * SIDE_PADDING);
+  const rows = [];
+  let cur = [];
+  let curW = 0;
+  items.forEach((item, i) => {
+    const w = itemWidths[i];
+    const projected = cur.length === 0 ? w : curW + ITEM_GAP + w;
+    if (cur.length > 0 && projected > availableWidth) {
+      rows.push({
+        items: cur,
+        widths: cur.map((_, j) => itemWidths[i - cur.length + j]),
+        totalWidth: curW
+      });
+      cur = [item];
+      curW = w;
+    } else {
+      cur = [...cur, item];
+      curW = projected;
+    }
+  });
+  if (cur.length > 0) {
+    rows.push({
+      items: cur,
+      widths: cur.map((_, j) => itemWidths[items.length - cur.length + j]),
+      totalWidth: curW
+    });
+  }
+  const parts = [`<g class="stdlib-chart-legend">`];
+  rows.forEach((row, rowIdx) => {
+    let cursor = Math.max(SIDE_PADDING, (width - row.totalWidth) / 2);
+    const baseY = yTop + ROW_HEIGHT / 2 + rowIdx * ROW_HEIGHT;
+    row.items.forEach((item, i) => {
+      parts.push(`<g class="stdlib-chart-legend-item stdlib-chart-series-${item.seriesIndex % 8}">`);
+      parts.push(`<rect class="stdlib-chart-legend-swatch" x="${fmt(cursor)}" y="${fmt(baseY - SWATCH / 2)}" width="${SWATCH}" height="${SWATCH}" rx="1"/>`);
+      parts.push(`<text class="stdlib-chart-legend-label" x="${fmt(cursor + SWATCH + SWATCH_GAP)}" y="${fmt(baseY)}" dominant-baseline="middle">${escapeXml(item.label)}</text>`);
+      parts.push(`</g>`);
+      cursor += row.widths[i] + ITEM_GAP;
+    });
+  });
+  parts.push(`</g>`);
+  return {
+    svg: parts.join(""),
+    height: rows.length * ROW_HEIGHT
+  };
+};
+
+/** Measure the total height a legend with `items` will consume in `width`,
+ *  without actually rendering. Used by chart functions to reserve vertical
+ *  space before computing the plot area. */
+export const measureLegendHeight = (items, width) => {
+  if (items.length === 0) return 0;
+  const ROW_HEIGHT = 20;
+  const ITEM_GAP = 16;
+  const SWATCH = 8;
+  const SWATCH_GAP = 4;
+  const charWidth = 6.5;
+  const availableWidth = Math.max(40, width - 8);
+  let curW = 0;
+  let rows = 1;
+  items.forEach((it, i) => {
+    const w = SWATCH + SWATCH_GAP + Math.max(it.label.length, 1) * charWidth;
+    const projected = i === 0 ? w : curW + ITEM_GAP + w;
+    if (i > 0 && projected > availableWidth) {
+      rows++;
+      curW = w;
+    } else {
+      curW = projected;
+    }
+  });
+  return rows * ROW_HEIGHT;
+};
+
+/** Wrap chart body in a root `<svg>` with embedded default styles. */
+export const svgRoot = (opts, body) => {
+  const cls = opts.className ? `stdlib-chart ${escapeXml(opts.className)}` : "stdlib-chart";
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${opts.width} ${opts.height}" class="${cls}"><style>${DEFAULT_STYLES}</style>${body}</svg>`;
+};
+
+// ==========================
+// GEOMETRY HELPERS
+// ==========================
+
+/** Format an SVG path `d` attribute for a polyline through `points`. */
+export const linePathD = points => {
+  if (points.length === 0) return "";
+  let d = `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+  for (let i = 1; i < points.length; i++) {
+    d += ` L ${fmt(points[i].x)} ${fmt(points[i].y)}`;
+  }
+  return d;
+};
+
+/**
+ * Format an SVG path `d` for a smooth curve through `points` using cubic
+ * Bezier segments with Catmull-Rom-derived vertical control points.
+ *
+ * Vertical control points use neighboring `points[i-1]` and `points[i+2]`
+ * (reflecting the end points at boundaries) with the standard Catmull-Rom
+ * tension factor of 1/6. Horizontal control points stay at the segment's
+ * thirds, so x progresses linearly and never doubles back when point spacing
+ * is uneven.
+ */
+export const smoothPathD = points => {
+  const n = points.length;
+  if (n === 0) return "";
+  if (n === 1) return `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+  if (n === 2) return linePathD(points);
+  let d = `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+  for (let i = 0; i < n - 1; i++) {
+    const p0 = i > 0 ? points[i - 1] : points[i];
+    const p1 = points[i];
+    const p2 = points[i + 1];
+    const p3 = i + 2 < n ? points[i + 2] : points[i + 1];
+    const dx = p2.x - p1.x;
+    const cp1x = p1.x + dx / 3;
+    const cp1y = p1.y + (p2.y - p0.y) / 6;
+    const cp2x = p2.x - dx / 3;
+    const cp2y = p2.y - (p3.y - p1.y) / 6;
+    d += ` C ${fmt(cp1x)} ${fmt(cp1y)} ${fmt(cp2x)} ${fmt(cp2y)} ${fmt(p2.x)} ${fmt(p2.y)}`;
+  }
+  return d;
+};
+
+/**
+ * Build an SVG path `d` attribute for a pie slice (or donut sector).
+ *
+ * Angles are in radians, measured from the +X axis. Slices grow clockwise,
+ * which in SVG's y-down coordinate space means `a1 > a0` produces a clockwise
+ * arc when drawn with the large-arc and sweep flags set appropriately.
+ *
+ * Full-circle (a1 - a0 ≈ 2π) is split into two 180° arcs because a single
+ * `A` command can't draw a complete circle unambiguously.
+ */
+export const arcPathD = (cx, cy, r, a0, a1, innerR = 0) => {
+  const sweep = a1 - a0;
+  // Full circle: split into two halves to avoid degenerate `A` command.
+  if (sweep >= Math.PI * 2 - 1e-9) {
+    const aMid = a0 + Math.PI;
+    if (innerR <= 0) {
+      const ox0 = cx + r * Math.cos(a0),
+        oy0 = cy + r * Math.sin(a0);
+      const oxM = cx + r * Math.cos(aMid),
+        oyM = cy + r * Math.sin(aMid);
+      return `M ${fmt(ox0)} ${fmt(oy0)} A ${fmt(r)} ${fmt(r)} 0 0 1 ${fmt(oxM)} ${fmt(oyM)} A ${fmt(r)} ${fmt(r)} 0 0 1 ${fmt(ox0)} ${fmt(oy0)} Z`;
+    }
+    const ox0 = cx + r * Math.cos(a0),
+      oy0 = cy + r * Math.sin(a0);
+    const oxM = cx + r * Math.cos(aMid),
+      oyM = cy + r * Math.sin(aMid);
+    const ix0 = cx + innerR * Math.cos(a0),
+      iy0 = cy + innerR * Math.sin(a0);
+    const ixM = cx + innerR * Math.cos(aMid),
+      iyM = cy + innerR * Math.sin(aMid);
+    // Outer ring CW, inner ring CCW (using even-odd fill rule via SVG default).
+    return `M ${fmt(ox0)} ${fmt(oy0)} A ${fmt(r)} ${fmt(r)} 0 0 1 ${fmt(oxM)} ${fmt(oyM)} A ${fmt(r)} ${fmt(r)} 0 0 1 ${fmt(ox0)} ${fmt(oy0)} Z` + ` M ${fmt(ix0)} ${fmt(iy0)} A ${fmt(innerR)} ${fmt(innerR)} 0 0 0 ${fmt(ixM)} ${fmt(iyM)} A ${fmt(innerR)} ${fmt(innerR)} 0 0 0 ${fmt(ix0)} ${fmt(iy0)} Z`;
+  }
+  const large = sweep > Math.PI ? 1 : 0;
+  const ox0 = cx + r * Math.cos(a0),
+    oy0 = cy + r * Math.sin(a0);
+  const ox1 = cx + r * Math.cos(a1),
+    oy1 = cy + r * Math.sin(a1);
+  if (innerR <= 0) {
+    return `M ${fmt(cx)} ${fmt(cy)} L ${fmt(ox0)} ${fmt(oy0)} A ${fmt(r)} ${fmt(r)} 0 ${large} 1 ${fmt(ox1)} ${fmt(oy1)} Z`;
+  }
+  const ix0 = cx + innerR * Math.cos(a0),
+    iy0 = cy + innerR * Math.sin(a0);
+  const ix1 = cx + innerR * Math.cos(a1),
+    iy1 = cy + innerR * Math.sin(a1);
+  return `M ${fmt(ox0)} ${fmt(oy0)} A ${fmt(r)} ${fmt(r)} 0 ${large} 1 ${fmt(ox1)} ${fmt(oy1)} L ${fmt(ix1)} ${fmt(iy1)} A ${fmt(innerR)} ${fmt(innerR)} 0 ${large} 0 ${fmt(ix0)} ${fmt(iy0)} Z`;
+};
+
+/**
+ * SVG path `d` for a marker shape centered at `(cx, cy)` with circumradius `r`.
+ *
+ * The shapes are sized so a typical visual radius matches `r`:
+ *  - circle: full radius
+ *  - square: side = sqrt(2)·r so the diagonal equals 2·r (visually balanced
+ *    next to a circle of the same r)
+ *  - triangle: equilateral pointing up, circumradius r
+ *  - diamond: square rotated 45°, half-diagonal = r
+ *  - plus: cross-shape at thickness r·0.5
+ *  - cross: X-shape at thickness r·0.4
+ */
+export const markerPath = (shape, cx, cy, r) => {
+  switch (shape) {
+    case "circle":
+      // Single arc command pair to draw a closed circle.
+      return `M ${fmt(cx - r)} ${fmt(cy)} A ${fmt(r)} ${fmt(r)} 0 1 0 ${fmt(cx + r)} ${fmt(cy)} A ${fmt(r)} ${fmt(r)} 0 1 0 ${fmt(cx - r)} ${fmt(cy)} Z`;
+    case "square":
+      {
+        const s = r * Math.SQRT2 / 2; // half-side
+        return `M ${fmt(cx - s)} ${fmt(cy - s)} L ${fmt(cx + s)} ${fmt(cy - s)} L ${fmt(cx + s)} ${fmt(cy + s)} L ${fmt(cx - s)} ${fmt(cy + s)} Z`;
+      }
+    case "triangle":
+      {
+        // Equilateral pointing up. Circumradius r.
+        const h = r * Math.sin(Math.PI / 3) * 1.5; // altitude from base to apex
+        return `M ${fmt(cx)} ${fmt(cy - r)} L ${fmt(cx + h * Math.cos(Math.PI / 6))} ${fmt(cy + r * 0.5)} L ${fmt(cx - h * Math.cos(Math.PI / 6))} ${fmt(cy + r * 0.5)} Z`;
+      }
+    case "diamond":
+      return `M ${fmt(cx)} ${fmt(cy - r)} L ${fmt(cx + r)} ${fmt(cy)} L ${fmt(cx)} ${fmt(cy + r)} L ${fmt(cx - r)} ${fmt(cy)} Z`;
+    case "plus":
+      {
+        const t = r * 0.32; // half-thickness
+        return `M ${fmt(cx - r)} ${fmt(cy - t)} L ${fmt(cx - t)} ${fmt(cy - t)} L ${fmt(cx - t)} ${fmt(cy - r)} L ${fmt(cx + t)} ${fmt(cy - r)} L ${fmt(cx + t)} ${fmt(cy - t)} L ${fmt(cx + r)} ${fmt(cy - t)} L ${fmt(cx + r)} ${fmt(cy + t)} L ${fmt(cx + t)} ${fmt(cy + t)} L ${fmt(cx + t)} ${fmt(cy + r)} L ${fmt(cx - t)} ${fmt(cy + r)} L ${fmt(cx - t)} ${fmt(cy + t)} L ${fmt(cx - r)} ${fmt(cy + t)} Z`;
+      }
+    case "cross":
+      {
+        // X shape — same as plus rotated 45°. Build by composing two oriented bars.
+        const a = r * 0.7;
+        const t = r * 0.28;
+        return `M ${fmt(cx - a + t)} ${fmt(cy - a - t)} L ${fmt(cx - a - t)} ${fmt(cy - a + t)} L ${fmt(cx + a - t)} ${fmt(cy + a + t)} L ${fmt(cx + a + t)} ${fmt(cy + a - t)} Z` + ` M ${fmt(cx + a - t)} ${fmt(cy - a - t)} L ${fmt(cx + a + t)} ${fmt(cy - a + t)} L ${fmt(cx - a + t)} ${fmt(cy + a + t)} L ${fmt(cx - a - t)} ${fmt(cy + a - t)} Z`;
+      }
+  }
+};
+
+/**
+ * SVG path `d` for a step (stair) line. `mode` controls where the vertical
+ * step happens relative to the data points:
+ *  - `before` — vertical step at the new x BEFORE the value updates (state
+ *    machine "Mealy" style: change at input)
+ *  - `after`  — value updates at the data point's x and persists until next x
+ *  - `middle` — vertical step at the midpoint between consecutive x-values
+ */
+export const stepPathD = (points, mode) => {
+  if (points.length === 0) return "";
+  if (points.length === 1) return `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+  let d = `M ${fmt(points[0].x)} ${fmt(points[0].y)}`;
+  for (let i = 1; i < points.length; i++) {
+    const p = points[i];
+    const prev = points[i - 1];
+    if (mode === "before") {
+      // step at next-x: extend horizontally to new x at OLD y, then jump to new y.
+      d += ` L ${fmt(p.x)} ${fmt(prev.y)} L ${fmt(p.x)} ${fmt(p.y)}`;
+    } else if (mode === "after") {
+      // step at current-x: jump to new y immediately, persist until next x.
+      d += ` L ${fmt(prev.x)} ${fmt(p.y)} L ${fmt(p.x)} ${fmt(p.y)}`;
+    } else {
+      // middle: step at midpoint of x.
+      const mx = (prev.x + p.x) / 2;
+      d += ` L ${fmt(mx)} ${fmt(prev.y)} L ${fmt(mx)} ${fmt(p.y)} L ${fmt(p.x)} ${fmt(p.y)}`;
+    }
+  }
+  return d;
+};
+
+/** Format a number for SVG attributes — short, no scientific notation. */
+export const fmt = n => {
+  if (!Number.isFinite(n)) return "0";
+  // 2 decimals is enough for sub-pixel precision at typical sizes.
+  const rounded = Math.round(n * 100) / 100;
+  return Number.isInteger(rounded) ? `${rounded}` : `${rounded}`;
+};
+export const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+export const normalizeMinMax = (min, max) => {
+  const lo = Number.isFinite(min) ? min : 0;
+  const hi = Number.isFinite(max) ? max : 100;
+  return lo === hi ? [lo, lo + 1] : lo < hi ? [lo, hi] : [hi, lo];
+};
+export const formatNumberValue = (value, format, unit = "") => {
+  if (!Number.isFinite(value)) return "";
+  return `${format ? format(value) : fmt(value)}${unit}`;
+};
+export const thresholdFillAttr = color => color ? ` fill="${escapeXml(color)}"` : "";
+export const thresholdStrokeAttr = color => color ? ` stroke="${escapeXml(color)}"` : "";
+
+// ==========================
+// AXIS RENDERERS
+// ==========================
+
+export const pickMapper = scale => scale === "log" ? mapLog : mapRange;
+
+/**
+ * Whether a value is renderable on the given axis. Log axes reject zero and
+ * negative values (since `log(<=0)` is undefined). Used to filter data
+ * points before rendering so we don't emit huge off-plot SVG coordinates.
+ */
+export const isOnAxis = (axis, v) => Number.isFinite(v) && (axis.scale !== "log" || v > 0);
+
+/**
+ * Compute the domain, major ticks, and (optional) minor ticks for an axis,
+ * choosing linear or log scale per `axisOpts`. Filters non-positive values
+ * out under log scale and falls back to `[1, 10]` if none remain.
+ */
+export const computeAxisScale = (values, axisOpts, fallbackTicks = DEFAULT_TICKS) => {
+  const scale = axisOpts?.scale === "log" ? "log" : "linear";
+  if (axisOpts?.domain) {
+    const [lo, hi] = axisOpts.domain;
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || lo >= hi || !Number.isFinite(hi - lo) || scale === "log" && lo <= 0) {
+      throw new RangeError("Chart axis domain must have finite increasing bounds (positive for log scales)");
+    }
+    if (values.some(v => Number.isFinite(v) && (scale !== "log" || v > 0) && (v < lo || v > hi))) {
+      throw new RangeError("Chart axis domain must contain all plotted values and bounds");
+    }
+    const ticks = [];
+    if (scale === "log") {
+      for (let exponent = Math.floor(Math.log10(lo)); exponent <= Math.ceil(Math.log10(hi)); exponent++) {
+        const value = 10 ** exponent;
+        if (value > lo && value < hi) ticks.push(value);
+      }
+    } else {
+      const step = niceStep(hi - lo, axisOpts.ticks ?? fallbackTicks);
+      // At extreme magnitudes the step may be smaller than one representable
+      // increment. Keep endpoint ticks instead of entering a non-advancing loop.
+      if (step > 0 && Number.isFinite(step) && (hi - lo) / step <= MAX_AXIS_TICKS) {
+        for (let value = Math.ceil(lo / step) * step; value < hi;) {
+          if (value > lo && (!axisOpts.insetEndpointLabels || value - lo >= step && hi - value >= step)) ticks.push(value);
+          const next = value + step;
+          if (next <= value) break;
+          value = next;
+        }
+      }
+    }
+    return {
+      domain: [lo, hi],
+      ticks: [...new Set([lo, ...ticks.filter(v => v > lo && v < hi), hi])],
+      minorTicks: [],
+      scale
+    };
+  }
+  if (scale === "log") {
+    const positive = values.filter(v => Number.isFinite(v) && v > 0);
+    if (positive.length === 0) {
+      return {
+        domain: [1, 10],
+        ticks: [1, 10],
+        minorTicks: [],
+        scale
+      };
+    }
+    const min = Math.min(...positive);
+    const max = Math.max(...positive);
+    const r = niceLogTicks(min, max);
+    const minorTicks = [];
+    if (axisOpts?.minorTicks) {
+      for (let i = 0; i < r.ticks.length - 1; i++) {
+        const decade = r.ticks[i];
+        for (let m = 2; m <= 9; m++) minorTicks.push(decade * m);
+      }
+    }
+    return {
+      domain: r.domain,
+      ticks: r.ticks,
+      minorTicks,
+      scale
+    };
+  }
+  const [minRaw, maxRaw] = computeDomain(values);
+  const step = niceStep(maxRaw - minRaw, axisOpts?.ticks ?? fallbackTicks);
+  const r = extendDomainToNice(minRaw, maxRaw, step);
+  const minorTicks = [];
+  if (axisOpts?.minorTicks && r.ticks.length > 1) {
+    const SUBDIVISIONS = 5;
+    for (let i = 0; i < r.ticks.length - 1; i++) {
+      const a = r.ticks[i];
+      const b = r.ticks[i + 1];
+      const sub = (b - a) / SUBDIVISIONS;
+      for (let m = 1; m < SUBDIVISIONS; m++) minorTicks.push(a + sub * m);
+    }
+  }
+  return {
+    domain: r.domain,
+    ticks: r.ticks,
+    minorTicks,
+    scale
+  };
+};
+export const renderYAxis = (axis, area, opts) => {
+  const format = opts?.format ?? (v => String(v));
+  const map = pickMapper(axis.scale);
+  const parts = [];
+  for (const t of axis.ticks) {
+    const y = map(t, axis.domain, [area.y1, area.y0]);
+    parts.push(`<line class="stdlib-chart-grid" x1="${fmt(area.x0)}" y1="${fmt(y)}" x2="${fmt(area.x1)}" y2="${fmt(y)}"/>`);
+    parts.push(`<text class="stdlib-chart-tick-label" x="${fmt(area.x0 - 6)}" y="${fmt(y + 3)}" text-anchor="end">${escapeXml(format(t))}</text>`);
+  }
+  for (const mt of axis.minorTicks) {
+    const y = map(mt, axis.domain, [area.y1, area.y0]);
+    parts.push(`<line class="stdlib-chart-minor-tick" x1="${fmt(area.x0 - 3)}" y1="${fmt(y)}" x2="${fmt(area.x0)}" y2="${fmt(y)}"/>`);
+  }
+  parts.push(`<line class="stdlib-chart-axis" x1="${fmt(area.x0)}" y1="${fmt(area.y0)}" x2="${fmt(area.x0)}" y2="${fmt(area.y1)}"/>`);
+  if (opts?.label) {
+    const cx = 12;
+    const cy = (area.y0 + area.y1) / 2;
+    parts.push(`<text class="stdlib-chart-axis-label" x="${fmt(cx)}" y="${fmt(cy)}" text-anchor="middle" transform="rotate(-90 ${fmt(cx)} ${fmt(cy)})">${escapeXml(opts.label)}</text>`);
+  }
+  return parts.join("");
+};
+export const renderXAxisNumeric = (axis, area, height, opts) => {
+  const format = opts?.format ?? (v => String(v));
+  const map = pickMapper(axis.scale);
+  const parts = [];
+  for (const t of axis.ticks) {
+    const x = map(t, axis.domain, [area.x0, area.x1]);
+    const anchor = opts?.domain && opts.insetEndpointLabels ? t === axis.domain[0] ? "start" : t === axis.domain[1] ? "end" : "middle" : "middle";
+    parts.push(`<text class="stdlib-chart-tick-label" x="${fmt(x)}" y="${fmt(area.y1 + 14)}" text-anchor="${anchor}">${escapeXml(format(t))}</text>`);
+  }
+  for (const mt of axis.minorTicks) {
+    const x = map(mt, axis.domain, [area.x0, area.x1]);
+    parts.push(`<line class="stdlib-chart-minor-tick" x1="${fmt(x)}" y1="${fmt(area.y1)}" x2="${fmt(x)}" y2="${fmt(area.y1 + 3)}"/>`);
+  }
+  parts.push(`<line class="stdlib-chart-axis" x1="${fmt(area.x0)}" y1="${fmt(area.y1)}" x2="${fmt(area.x1)}" y2="${fmt(area.y1)}"/>`);
+  if (opts?.label) {
+    parts.push(`<text class="stdlib-chart-axis-label" x="${fmt((area.x0 + area.x1) / 2)}" y="${fmt(height - 4)}" text-anchor="middle">${escapeXml(opts.label)}</text>`);
+  }
+  return parts.join("");
+};
+export const renderXAxisCategorical = (labels, area, height, axisLabel) => {
+  const parts = [];
+  if (labels.length > 0) {
+    const step = (area.x1 - area.x0) / labels.length;
+    for (let i = 0; i < labels.length; i++) {
+      const cx = area.x0 + step * (i + 0.5);
+      parts.push(`<text class="stdlib-chart-tick-label" x="${fmt(cx)}" y="${fmt(area.y1 + 14)}" text-anchor="middle">${escapeXml(labels[i])}</text>`);
+    }
+  }
+  parts.push(`<line class="stdlib-chart-axis" x1="${fmt(area.x0)}" y1="${fmt(area.y1)}" x2="${fmt(area.x1)}" y2="${fmt(area.y1)}"/>`);
+  if (axisLabel) {
+    parts.push(`<text class="stdlib-chart-axis-label" x="${fmt((area.x0 + area.x1) / 2)}" y="${fmt(height - 4)}" text-anchor="middle">${escapeXml(axisLabel)}</text>`);
+  }
+  return parts.join("");
+};
+export const emptyChart = (width, height, className, message = "no data") => svgRoot({
+  width,
+  height,
+  className
+}, `<text class="stdlib-chart-empty-text" x="${fmt(width / 2)}" y="${fmt(height / 2)}" text-anchor="middle" dominant-baseline="middle">${escapeXml(message)}</text>`);
+
+// ==========================
+// CHART FUNCTIONS
+// ==========================
+
+export const collectSeriesLegend = opts => {
+  if (!opts.legend) return [];
+  return opts.series.map((s, i) => ({
+    label: s.label && s.label.length > 0 ? s.label : `Series ${i + 1}`,
+    seriesIndex: i
+  }));
+};
+
+// ==========================
+// BAR
+// ==========================
+
+// ==========================
+// PIE / DONUT
+// ==========================
+
+// ==========================
+// HISTOGRAM
+// ==========================
+
+// ==========================
+// BOX PLOT
+// ==========================
+
+// ==========================
+// DASHBOARD PANELS
+// ==========================
+
+export const thresholdIndexForValue = (value, thresholds, min, max) => {
+  if (!thresholds || thresholds.length === 0) return 0;
+  const sorted = [...thresholds].filter(t => Number.isFinite(t.value)).sort((a, b) => a.value - b.value);
+  const clamped = clamp(value, min, max);
+  const idx = sorted.findIndex(t => clamped <= t.value);
+  return idx >= 0 ? idx : Math.max(0, sorted.length - 1);
+};
+export const thresholdForIndex = (thresholds, index) => {
+  if (!thresholds || thresholds.length === 0) return undefined;
+  const sorted = [...thresholds].filter(t => Number.isFinite(t.value)).sort((a, b) => a.value - b.value);
+  return sorted[index];
+};
+
+// ==========================
+// SPARKLINE
+// ==========================
+//# sourceMappingURL=svg-common.js.map