@opendata-ai/openchart-engine 6.2.1 → 6.4.1

package/dist/index.js

@@ -209,6 +209,7 @@ function resolveTextAnnotation(annotation, scales, chartArea, isDark) {
   };
   return {
     type: "text",
+    id: annotation.id,
     label,
     stroke: annotation.stroke,
     fill: annotation.fill,
@@ -261,6 +262,7 @@ function resolveRangeAnnotation(annotation, scales, chartArea, isDark) {
   const defaultOpacity = isDark ? 0.2 : DEFAULT_RANGE_OPACITY;
   return {
     type: "range",
+    id: annotation.id,
     rect,
     label,
     fill: annotation.fill ?? DEFAULT_RANGE_FILL,
@@ -314,6 +316,7 @@ function resolveRefLineAnnotation(annotation, scales, chartArea, isDark) {
   const defaultStroke = isDark ? DARK_REFLINE_STROKE : LIGHT_REFLINE_STROKE;
   return {
     type: "refline",
+    id: annotation.id,
     line: { start, end },
     label,
     stroke: annotation.stroke ?? defaultStroke,
@@ -388,7 +391,7 @@ function nudgeAnnotationFromObstacles(annotation, originalAnnotation, scales, ch
     if (stillCollides) continue;
     const labelCenterX = candidateBounds.x + candidateBounds.width / 2;
     const labelCenterY = candidateBounds.y + candidateBounds.height / 2;
-    const inBounds = labelCenterX >= chartArea.x && labelCenterX <= chartArea.x + chartArea.width + 100 && labelCenterY >= chartArea.y - fontSize && labelCenterY <= chartArea.y + chartArea.height + fontSize * 3;
+    const inBounds = labelCenterX >= chartArea.x && labelCenterX <= chartArea.x + chartArea.width + 10 && labelCenterY >= chartArea.y - fontSize && labelCenterY <= chartArea.y + chartArea.height + fontSize * 3;
     if (inBounds) {
       if (candidateLabel.connector && dx === 0 && dy !== 0) {
         candidateLabel.connector = {
@@ -436,7 +439,7 @@ function resolveAnnotationCollisions(annotations, originalSpecs, scales, chartAr
             if (stillCollides) continue;
             const labelCenterX = candidateBounds.x + candidateBounds.width / 2;
             const labelCenterY = candidateBounds.y + candidateBounds.height / 2;
-            const inBounds = labelCenterX >= chartArea.x && labelCenterX <= chartArea.x + chartArea.width + 100 && labelCenterY >= chartArea.y - fontSize && labelCenterY <= chartArea.y + chartArea.height + fontSize;
+            const inBounds = labelCenterX >= chartArea.x && labelCenterX <= chartArea.x + chartArea.width + 10 && labelCenterY >= chartArea.y - fontSize && labelCenterY <= chartArea.y + chartArea.height + fontSize;
             if (inBounds) {
               let newConnector = annotation.label.connector;
               if (newConnector) {
@@ -470,7 +473,54 @@ function resolveAnnotationCollisions(annotations, originalSpecs, scales, chartAr
     placedBounds.push(estimateLabelBounds(annotation.label));
   }
 }
-function computeAnnotations(spec, scales, chartArea, strategy, isDark = false, obstacles = []) {
+var CLAMP_MARGIN = 4;
+function clampAnnotationsToBounds(annotations, svgWidth, svgHeight) {
+  for (const annotation of annotations) {
+    if (annotation.type !== "text" || !annotation.label) continue;
+    const bounds = estimateLabelBounds(annotation.label);
+    let dx = 0;
+    let dy = 0;
+    if (bounds.x + bounds.width > svgWidth - CLAMP_MARGIN) {
+      dx = svgWidth - CLAMP_MARGIN - (bounds.x + bounds.width);
+    }
+    if (bounds.x + dx < CLAMP_MARGIN) {
+      dx = CLAMP_MARGIN - bounds.x;
+    }
+    if (bounds.y < CLAMP_MARGIN) {
+      dy = CLAMP_MARGIN - bounds.y;
+    }
+    if (bounds.y + bounds.height + dy > svgHeight - CLAMP_MARGIN) {
+      dy = svgHeight - CLAMP_MARGIN - (bounds.y + bounds.height);
+    }
+    if (dx === 0 && dy === 0) continue;
+    const newX = annotation.label.x + dx;
+    const newY = annotation.label.y + dy;
+    let newConnector = annotation.label.connector;
+    if (newConnector) {
+      const fontSize = annotation.label.style.fontSize ?? DEFAULT_ANNOTATION_FONT_SIZE;
+      const fontWeight = annotation.label.style.fontWeight ?? DEFAULT_ANNOTATION_FONT_WEIGHT;
+      const connStyle = newConnector.style === "curve" ? "curve" : "straight";
+      const newFrom = computeConnectorOrigin(
+        newX,
+        newY,
+        annotation.label.text,
+        fontSize,
+        fontWeight,
+        newConnector.to.x,
+        newConnector.to.y,
+        connStyle
+      );
+      newConnector = { ...newConnector, from: newFrom };
+    }
+    annotation.label = {
+      ...annotation.label,
+      x: newX,
+      y: newY,
+      connector: newConnector
+    };
+  }
+}
+function computeAnnotations(spec, scales, chartArea, strategy, isDark = false, obstacles = [], svgDimensions) {
   if (strategy.annotationPosition === "tooltip-only") {
     return [];
   }
@@ -496,6 +546,9 @@ function computeAnnotations(spec, scales, chartArea, strategy, isDark = false, o
     }
   }
   resolveAnnotationCollisions(annotations, spec.annotations, scales, chartArea);
+  if (svgDimensions) {
+    clampAnnotationsToBounds(annotations, svgDimensions.width, svgDimensions.height);
+  }
   annotations.sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
   return annotations;
 }
@@ -772,6 +825,24 @@ import {
   estimateTextWidth as estimateTextWidth2,
   resolveCollisions
 } from "@opendata-ai/openchart-core";
+var SUFFIX_MULTIPLIERS = {
+  K: 1e3,
+  M: 1e6,
+  B: 1e9,
+  T: 1e12
+};
+function parseDisplayNumber(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed) return NaN;
+  const last = trimmed[trimmed.length - 1].toUpperCase();
+  const multiplier = SUFFIX_MULTIPLIERS[last];
+  if (multiplier) {
+    const numPart = trimmed.slice(0, -1).replace(/,/g, "");
+    const n = Number(numPart);
+    return Number.isNaN(n) ? NaN : n * multiplier;
+  }
+  return Number(trimmed.replace(/,/g, ""));
+}
 var LABEL_FONT_SIZE = 11;
 var LABEL_FONT_WEIGHT = 600;
 var LABEL_PADDING = 6;
@@ -780,6 +851,7 @@ function computeBarLabels(marks, _chartArea, density = "auto", labelFormat) {
   if (density === "none") return [];
   const targetMarks = density === "endpoints" && marks.length > 1 ? [marks[0], marks[marks.length - 1]] : marks;
   const candidates = [];
+  const fitsInSegment = [];
   const formatter = buildD3Formatter(labelFormat);
   for (const mark of targetMarks) {
     const ariaLabel = mark.aria.label;
@@ -788,7 +860,7 @@ function computeBarLabels(marks, _chartArea, density = "auto", labelFormat) {
     if (!rawValue) continue;
     let valuePart = rawValue;
     if (formatter) {
-      const num = Number(rawValue.replace(/[^0-9.-]/g, ""));
+      const num = parseDisplayNumber(rawValue);
       if (!Number.isNaN(num)) valuePart = formatter(num);
     }
     const textWidth = estimateTextWidth2(valuePart, LABEL_FONT_SIZE, LABEL_FONT_WEIGHT);
@@ -812,6 +884,8 @@ function computeBarLabels(marks, _chartArea, density = "auto", labelFormat) {
       textAnchor = "start";
     }
     const anchorY = mark.y + mark.height / 2;
+    const fits = !(isStacked && textWidth > mark.width - 2 * LABEL_PADDING);
+    fitsInSegment.push(fits);
     candidates.push({
       text: valuePart,
       anchorX,
@@ -832,15 +906,40 @@ function computeBarLabels(marks, _chartArea, density = "auto", labelFormat) {
   }
   if (candidates.length === 0) return [];
   if (density === "all") {
-    return candidates.map((c) => ({
+    return candidates.map((c, i) => ({
       text: c.text,
       x: c.anchorX,
       y: c.anchorY,
       style: c.style,
-      visible: true
+      visible: fitsInSegment[i] !== false
     }));
   }
-  return resolveCollisions(candidates);
+  const fittingCandidates = [];
+  const unfittingIndices = /* @__PURE__ */ new Set();
+  for (let i = 0; i < candidates.length; i++) {
+    if (fitsInSegment[i] === false) {
+      unfittingIndices.add(i);
+    } else {
+      fittingCandidates.push(candidates[i]);
+    }
+  }
+  const resolved = resolveCollisions(fittingCandidates);
+  const results = [];
+  let resolvedIdx = 0;
+  for (let i = 0; i < candidates.length; i++) {
+    if (unfittingIndices.has(i)) {
+      results.push({
+        text: candidates[i].text,
+        x: candidates[i].anchorX,
+        y: candidates[i].anchorY,
+        style: candidates[i].style,
+        visible: false
+      });
+    } else {
+      results.push(resolved[resolvedIdx++]);
+    }
+  }
+  return results;
 }
 
 // src/charts/bar/index.ts
@@ -2487,7 +2586,11 @@ function _getMidValue(rows, field) {
 }
 
 // src/charts/line/labels.ts
-import { estimateTextWidth as estimateTextWidth5, resolveCollisions as resolveCollisions4 } from "@opendata-ai/openchart-core";
+import {
+  EXTENDED_OFFSET_STRATEGIES,
+  estimateTextWidth as estimateTextWidth5,
+  resolveCollisions as resolveCollisions4
+} from "@opendata-ai/openchart-core";
 var LABEL_FONT_SIZE4 = 11;
 var LABEL_FONT_WEIGHT4 = 600;
 var LABEL_OFFSET_X2 = 6;
@@ -2541,7 +2644,7 @@ function computeLineLabels(marks, strategy, density = "auto", labelOffsets) {
     }
     return result;
   }
-  const resolved = resolveCollisions4(candidates);
+  const resolved = resolveCollisions4(candidates, EXTENDED_OFFSET_STRATEGIES);
   for (let i = 0; i < resolved.length; i++) {
     const seriesKey = seriesOrder[i];
     const label = resolved[i];
@@ -5494,6 +5597,30 @@ function sequential() {
 var DEFAULT_POINT_RADIUS2 = 5;
 var MIN_BUBBLE_RADIUS = 3;
 var MAX_BUBBLE_RADIUS = 30;
+function resolvePosition2(value, channelType, scale) {
+  switch (channelType) {
+    case "nominal":
+    case "ordinal": {
+      const s = String(value);
+      if ("bandwidth" in scale && typeof scale.bandwidth === "function") {
+        const bw = scale.bandwidth();
+        const pos = scale(s);
+        if (pos === void 0) return void 0;
+        return bw > 0 ? pos + bw / 2 : pos;
+      }
+      return scale(s);
+    }
+    case "temporal": {
+      const px = scale(new Date(value));
+      return Number.isNaN(px) ? void 0 : px;
+    }
+    default: {
+      const num = Number(value);
+      if (!Number.isFinite(num)) return void 0;
+      return scale(num);
+    }
+  }
+}
 function computeScatterMarks(spec, scales, _chartArea, _strategy) {
   const encoding = spec.encoding;
   const xChannel = encoding.x;
@@ -5503,6 +5630,8 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
   }
   const xScale = scales.x.scale;
   const yScale = scales.y.scale;
+  const xType = xChannel.type;
+  const yType = yChannel.type;
   const colorEnc = encoding.color && "field" in encoding.color ? encoding.color : void 0;
   const isSequentialColor = colorEnc?.type === "quantitative";
   const colorField = colorEnc?.field;
@@ -5516,11 +5645,11 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
   }
   const marks = [];
   for (const row of spec.data) {
-    const xVal = Number(row[xChannel.field]);
-    const yVal = Number(row[yChannel.field]);
-    if (!Number.isFinite(xVal) || !Number.isFinite(yVal)) continue;
-    const cx = xScale(xVal);
-    const cy = yScale(yVal);
+    const rawX = row[xChannel.field];
+    const rawY = row[yChannel.field];
+    const cx = resolvePosition2(rawX, xType, xScale);
+    const cy = resolvePosition2(rawY, yType, yScale);
+    if (cx === void 0 || cy === void 0) continue;
     const category = colorField && !isSequentialColor ? String(row[colorField] ?? "") : void 0;
     let color2;
     if (isSequentialColor && colorField) {
@@ -5536,7 +5665,7 @@ function computeScatterMarks(spec, scales, _chartArea, _strategy) {
         radius = sizeScale(sizeVal);
       }
     }
-    const labelParts = [`${xChannel.field}=${xVal}`, `${yChannel.field}=${yVal}`];
+    const labelParts = [`${xChannel.field}=${rawX}`, `${yChannel.field}=${rawY}`];
     if (category) labelParts.push(`${colorField}=${category}`);
     if (sizeField && row[sizeField] != null) {
       labelParts.push(`${sizeField}=${row[sizeField]}`);
@@ -6026,6 +6155,38 @@ function validateChartSpec(spec, errors) {
   }
   for (const [channel, channelSpec] of Object.entries(encoding)) {
     if (!channelSpec || typeof channelSpec !== "object") continue;
+    if (channel === "tooltip" && Array.isArray(channelSpec)) {
+      for (let i = 0; i < channelSpec.length; i++) {
+        const elem = channelSpec[i];
+        if (!elem || typeof elem !== "object") continue;
+        if (!elem.field || typeof elem.field !== "string") {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}] must have a "field" string`,
+            path: `encoding.tooltip[${i}].field`,
+            code: "MISSING_FIELD",
+            suggestion: `Add a field name from your data columns: ${availableColumns}`
+          });
+          continue;
+        }
+        if (!dataColumns.has(elem.field) && !transformFields.has(elem.field)) {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}].field "${elem.field}" does not exist in data. Available columns: ${availableColumns}`,
+            path: `encoding.tooltip[${i}].field`,
+            code: "DATA_FIELD_MISSING",
+            suggestion: `Use one of the available data columns: ${availableColumns}`
+          });
+        }
+        if (elem.type && !VALID_FIELD_TYPES.has(elem.type)) {
+          errors.push({
+            message: `Spec error: encoding.tooltip[${i}].type "${elem.type}" is not valid. Must be one of: ${[...VALID_FIELD_TYPES].join(", ")}`,
+            path: `encoding.tooltip[${i}].type`,
+            code: "INVALID_VALUE",
+            suggestion: `Use one of: ${[...VALID_FIELD_TYPES].join(", ")}`
+          });
+        }
+      }
+      continue;
+    }
     const channelObj = channelSpec;
     const channelRule = rules[channel];
     if ("condition" in channelObj) continue;
@@ -7276,7 +7437,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy) {
     }
   }
   if (encoding.y && !isRadial) {
-    if (spec.markType === "bar" || spec.markType === "circle" || encoding.y.type === "nominal" || encoding.y.type === "ordinal") {
+    if (spec.markType === "bar" || spec.markType === "circle" || spec.markType === "lollipop" || encoding.y.type === "nominal" || encoding.y.type === "ordinal") {
       const yField = encoding.y.field;
       let maxLabelWidth = 0;
       for (const row of spec.data) {
@@ -7658,7 +7819,7 @@ function buildPositionalScale(channel, data, rangeStart, rangeEnd, chartType, ax
       return buildLinearScale(channel, data, rangeStart, rangeEnd);
     case "nominal":
     case "ordinal":
-      if (chartType === "bar" || chartType === "circle" && axis === "y") {
+      if (chartType === "bar" || (chartType === "circle" || chartType === "lollipop") && axis === "y") {
         return buildBandScale(channel, data, rangeStart, rangeEnd);
       }
       return buildPointScale(channel, data, rangeStart, rangeEnd);
@@ -7779,6 +7940,7 @@ function swatchShapeForType(markType) {
       return "line";
     case "point":
     case "circle":
+    case "lollipop":
       return "circle";
     default:
       return "square";
@@ -7881,10 +8043,11 @@ function computeLegend(spec, strategy, theme, chartArea) {
     const entryHeight = Math.max(SWATCH_SIZE2, labelStyle.fontSize * labelStyle.lineHeight);
     const maxHeightRatio = strategy.legendMaxHeight > 0 ? strategy.legendMaxHeight : RIGHT_LEGEND_MAX_HEIGHT_RATIO;
     const maxLegendHeight = chartArea.height * maxHeightRatio;
-    const maxEntries = Math.max(
+    const maxFromSpace = Math.max(
       1,
       Math.floor((maxLegendHeight - LEGEND_PADDING * 2) / (entryHeight + 4))
     );
+    const maxEntries = spec.legend?.symbolLimit != null ? Math.min(Math.max(1, spec.legend.symbolLimit), maxFromSpace) : maxFromSpace;
     if (entries.length > maxEntries) {
       entries = truncateEntries(entries, maxEntries);
     }
@@ -7909,7 +8072,14 @@ function computeLegend(spec, strategy, theme, chartArea) {
     };
   }
   const availableWidth = chartArea.width - LEGEND_PADDING * 2 - BRAND_RESERVE_WIDTH;
-  const maxFit = entriesThatFit(entries, availableWidth, TOP_LEGEND_MAX_ROWS, labelStyle);
+  if (spec.legend?.symbolLimit != null) {
+    const limit = Math.max(1, spec.legend.symbolLimit);
+    if (limit < entries.length) {
+      entries = truncateEntries(entries, limit);
+    }
+  }
+  const maxRows = spec.legend?.columns != null ? Math.ceil(entries.length / spec.legend.columns) : TOP_LEGEND_MAX_ROWS;
+  const maxFit = entriesThatFit(entries, availableWidth, maxRows, labelStyle);
   if (maxFit < entries.length) {
     entries = truncateEntries(entries, maxFit);
   }
@@ -8602,7 +8772,17 @@ function formatValue(value, fieldType, format2) {
   }
   return String(value);
 }
+function buildExplicitTooltipFields(row, channels) {
+  return channels.map((ch) => ({
+    label: ch.axis?.label ?? ch.field,
+    value: formatValue(row[ch.field], ch.type, ch.axis?.format)
+  }));
+}
 function buildFields(row, encoding, color2) {
+  if (encoding.tooltip) {
+    const channels = Array.isArray(encoding.tooltip) ? encoding.tooltip : [encoding.tooltip];
+    return buildExplicitTooltipFields(row, channels);
+  }
   const fields = [];
   if (encoding.y) {
     fields.push({
@@ -8922,6 +9102,8 @@ var builtinRenderers = {
   // old 'donut'
   circle: dotRenderer,
   // old 'dot'
+  lollipop: dotRenderer,
+  // semantic alias for dot/circle
   text: textRenderer,
   rule: ruleRenderer,
   tick: tickRenderer,
@@ -9157,7 +9339,8 @@ function compileChart(spec, options) {
     chartArea,
     strategy,
     theme.isDark,
-    obstacles
+    obstacles,
+    { width: dims.total.width, height: dims.total.height }
   );
   const tooltipDescriptors = computeTooltipDescriptors(chartSpec, marks);
   const altText = generateAltText(