@opendata-ai/openchart-engine 8.4.0 → 8.5.0

package/dist/index.js

@@ -6,7 +6,7 @@ import {
   generateAltText,
   generateDataTable,
   getBreakpoint as getBreakpoint3,
-  getHeightClass,
+  getHeightClass as getHeightClass3,
   getLayoutStrategy,
   isAxislessMark as isAxislessMark3,
   MAX_SR_TABLE_ROWS,
@@ -839,6 +839,7 @@ var OBSTACLE_WEIGHTS = {
   "data-label": 8,
   "endpoint-label": 8,
   legend: 6,
+  chrome: 6,
   watermark: 6,
   "axis-band": 6,
   "area-fill": 1.5
@@ -1207,7 +1208,7 @@ function resolveAnnotationCollisions(annotations, originalSpecs, scales, chartAr
     placedBounds.push(annotation.bounds ?? annotationBlockBounds(annotation, label, measure));
   }
 }
-function clampAnnotationsToBounds(annotations, svgWidth, svgHeight, measure = heuristicMeasure) {
+function clampAnnotationsToBounds(annotations, svgWidth, svgHeight, measure = heuristicMeasure, topBound = CLAMP_MARGIN) {
   for (const annotation of annotations) {
     if (annotation.type !== "text" || !annotation.label) continue;
     const label = annotation.label;
@@ -1220,8 +1221,8 @@ function clampAnnotationsToBounds(annotations, svgWidth, svgHeight, measure = he
     if (bounds.x + dx < CLAMP_MARGIN) {
       dx = CLAMP_MARGIN - bounds.x;
     }
-    if (bounds.y < CLAMP_MARGIN) {
-      dy = CLAMP_MARGIN - bounds.y;
+    if (bounds.y < topBound) {
+      dy = topBound - bounds.y;
     }
     if (bounds.y + bounds.height + dy > svgHeight - CLAMP_MARGIN) {
       dy = svgHeight - CLAMP_MARGIN - (bounds.y + bounds.height);
@@ -1667,7 +1668,7 @@ function computeAnnotations(spec, scalesOrCtx, chartArea, strategy, isDark, obst
     autoQueue.length > 0 ? (i) => autoIndices.has(i) : void 0
   );
   if (ctx.svg.width > 0 && ctx.svg.height > 0) {
-    clampAnnotationsToBounds(annotations, ctx.svg.width, ctx.svg.height, ctx.measure);
+    clampAnnotationsToBounds(annotations, ctx.svg.width, ctx.svg.height, ctx.measure, ctx.topBound);
   }
   annotations.sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
   return annotations;
@@ -2867,6 +2868,7 @@ function computeBarLabels(marks, chartArea, density = "auto", labelFormatter, la
   const candidates = [];
   const fitsInSegment = [];
   const displayAnchorX = [];
+  const haloFlags = [];
   const formatter = labelFormatter ?? null;
   for (const mark of targetMarks) {
     let valuePart;
@@ -2928,6 +2930,7 @@ function computeBarLabels(marks, chartArea, density = "auto", labelFormatter, la
     const anchorY = centerY - textHeight / 2;
     const leftEdgeX = textAnchor === "end" ? anchorX - textWidth : textAnchor === "middle" ? anchorX - textWidth / 2 : anchorX;
     const fits = !(isStacked2 && textWidth > mark.width - 2 * LABEL_PADDING);
+    haloFlags.push(!isInside);
     displayAnchorX.push(anchorX);
     fitsInSegment.push(fits);
     candidates.push({
@@ -2972,7 +2975,8 @@ function computeBarLabels(marks, chartArea, density = "auto", labelFormatter, la
         x: displayAnchorX[i],
         y: candidates[i].anchorY + halfHeight,
         style: candidates[i].style,
-        visible: false
+        visible: false,
+        ...haloFlags[i] ? {} : { halo: false }
       });
     } else {
       const r = resolvedByOrig.get(i);
@@ -2981,6 +2985,7 @@ function computeBarLabels(marks, chartArea, density = "auto", labelFormatter, la
       const { index: _index, ...rest } = r;
       results.push({
         ...rest,
+        ...haloFlags[i] ? {} : { halo: false },
         x: r.x + dx,
         y: r.y + halfHeight,
         connector: r.connector ? {
@@ -3774,6 +3779,7 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormatter
   const targetMarks = filterByDensity(marks, density);
   const formatter = labelFormatter ?? null;
   const candidates = [];
+  const haloFlags = [];
   const fitsInSegment = [];
   for (const mark of targetMarks) {
     let valuePart;
@@ -3813,6 +3819,7 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormatter
       fill = labelColor ?? getRepresentativeColor3(mark.fill);
     }
     fitsInSegment.push(!(isStacked2 && textHeight > mark.height - 2 * LABEL_PADDING_Y));
+    haloFlags.push(!isStacked2);
     candidates.push({
       text: valuePart,
       anchorX,
@@ -3854,7 +3861,8 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormatter
         x: candidates[i].anchorX,
         y: candidates[i].anchorY + ascent,
         style: candidates[i].style,
-        visible: false
+        visible: false,
+        ...haloFlags[i] ? {} : { halo: false }
       });
       continue;
     }
@@ -3863,6 +3871,7 @@ function computeColumnLabels(marks, _chartArea, density = "auto", labelFormatter
     const { index: _index, ...rest } = r;
     results.push({
       ...rest,
+      ...haloFlags[i] ? {} : { halo: false },
       y: r.y + ascent,
       // The connector originates at the label; shift its start to the baseline
       // too so the leader stays glued to the shifted text.
@@ -7421,7 +7430,8 @@ function normalizeGraphSpec(spec, warnings) {
     watermark: spec.watermark ?? true,
     animation: spec.animation,
     interaction: spec.interaction,
-    legend: spec.legend
+    legend: spec.legend,
+    dimensions: spec.dimensions
   };
 }
 function normalizeTileMapSpec(spec, warnings) {
@@ -10271,6 +10281,7 @@ import {
   computeXAxisExtentFromLabels as computeXAxisExtentFromLabels2,
   defaultNumberFormatter as defaultNumberFormatter6,
   estimateTextWidth as estimateTextWidth16,
+  getHeightClass,
   HPAD_COMPACT_FRACTION,
   HPAD_COMPACT_MIN,
   isAxislessMark,
@@ -12268,6 +12279,7 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
   if (renderSpec.display === "sparkline" && !renderSpec.userExplicit?.chrome) {
     chromeMode = "hidden";
   }
+  const crampedTitle = getHeightClass(height) === "cramped";
   if (renderSpec.display === "sparkline" || isRadial) {
     const legendContent = computeLegendContent(
       chartSpec,
@@ -12287,7 +12299,8 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
       chromeMode,
       padding,
       watermark,
-      bottomLegendReservation
+      bottomLegendReservation,
+      crampedTitle
     );
     return {
       leftGutter: hPad,
@@ -12411,7 +12424,8 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
       chromeMode,
       padding,
       watermark,
-      bottomLegendReservation
+      bottomLegendReservation,
+      crampedTitle
     );
     let effectiveXTickAngle = xTickAngle;
     if (xTickAngle === void 0 && xLabels.length > 1) {
@@ -13550,6 +13564,54 @@ function topologyBBox(topology) {
 var OVERLAY_LEGEND_INSET = 18;
 var NO_DATA_SWATCH_GAP = 12;
 var NO_DATA_LABEL_GAP = 5;
+var CATEGORICAL_SWATCH_SIZE = 10;
+var CATEGORICAL_SWATCH_GAP = 6;
+var CATEGORICAL_ENTRY_GAP = 16;
+var CATEGORICAL_ROW_HEIGHT = CATEGORICAL_SWATCH_SIZE + 6;
+function categoricalLegendLabelStyle(theme) {
+  return {
+    fontFamily: theme.fonts.family,
+    fontSize: 11,
+    fontWeight: 400,
+    fill: theme.colors.text,
+    lineHeight: 1.2
+  };
+}
+function categoricalEntryWidth(label, labelStyle) {
+  return CATEGORICAL_SWATCH_SIZE + CATEGORICAL_SWATCH_GAP + estimateTextWidth18(label, labelStyle.fontSize, labelStyle.fontWeight) + CATEGORICAL_ENTRY_GAP;
+}
+function noDataBlockWidth(labelStyle) {
+  return CATEGORICAL_SWATCH_SIZE + NO_DATA_LABEL_GAP + estimateTextWidth18("No data", labelStyle.fontSize, labelStyle.fontWeight);
+}
+function wrapCategoricalEntries(widths, legendWidth) {
+  const placed = [];
+  let x = 0;
+  let row = 0;
+  for (let i = 0; i < widths.length; i++) {
+    if (i > 0 && x + widths[i] > legendWidth) {
+      x = 0;
+      row += 1;
+    }
+    placed.push({ x, row });
+    x += widths[i];
+  }
+  return placed;
+}
+function collectCategories(rows, field, domain) {
+  const categories = Array.isArray(domain) ? domain.map((c) => String(c)) : [];
+  const seen = new Set(categories);
+  for (const row of rows) {
+    const raw = row[field];
+    if (raw != null) {
+      const cat = String(raw);
+      if (!seen.has(cat)) {
+        seen.add(cat);
+        categories.push(cat);
+      }
+    }
+  }
+  return categories;
+}
 function legendTitleFor(colorEncoding) {
   const base = colorEncoding.title ?? colorEncoding.field;
   if (!base) return void 0;
@@ -13678,7 +13740,16 @@ function compileGeoMap(spec, options) {
   }
   if (legendBlockHeight === 0 && showChoroplethLegend && colorEncoding && !isQuantitative) {
     const labelHeight = Math.ceil(theme.fonts.sizes.small * 1.3);
-    legendBlockHeight = Math.max(10, labelHeight) + 6;
+    const labelStyle = categoricalLegendLabelStyle(theme);
+    const widths = collectCategories(
+      mapSpec.data,
+      colorEncoding.field,
+      colorEncoding.scale?.domain
+    ).map((cat) => categoricalEntryWidth(cat, labelStyle));
+    widths.push(noDataBlockWidth(labelStyle));
+    const placed = wrapCategoricalEntries(widths, fullArea.width);
+    const rows = placed.length > 0 ? placed[placed.length - 1].row + 1 : 1;
+    legendBlockHeight = rows * (Math.max(10, labelHeight) + 6);
   }
   if (showLegend && !pointLegendOverlay && mapSpec.points?.color) {
     if (mapSpec.points.color.type === "quantitative") {
@@ -13747,6 +13818,11 @@ function compileGeoMap(spec, options) {
   const droppedFeatures = [];
   const formatter = buildD3Formatter2(mapSpec.encoding?.color?.format ?? mapSpec.valueFormat) ?? formatNumber3;
   const neutralFill = isDarkMode ? theme.colors.neutral[800] : theme.colors.neutral[100];
+  const noDataPattern = {
+    type: "diagonal",
+    base: neutralFill,
+    line: isDarkMode ? theme.colors.neutral[600] : theme.colors.neutral[300]
+  };
   let featureMarks;
   let continuousLegend = null;
   let categoricalLegend = null;
@@ -13765,6 +13841,7 @@ function compileGeoMap(spec, options) {
       colorField: colorEncoding.field,
       classScale,
       neutralFill,
+      noDataPattern,
       formatter,
       droppedFeatures
     });
@@ -13799,16 +13876,21 @@ function compileGeoMap(spec, options) {
         height: continuousContent.barHeight
       };
       const labelY = bar.y + bar.height + CONTINUOUS_LABEL_GAP + labelStyle.fontSize;
-      const hasUnmatched = featureMarks.some((m) => {
-        const raw = m.data?.[colorEncoding.field];
-        return raw == null || Number.isNaN(Number(raw));
-      });
+      const hasUnmatched = featureMarks.some((m) => m.noData);
       const noDataX = bar.x + bar.width + NO_DATA_SWATCH_GAP;
-      const noData = hasUnmatched && noDataX + bar.height + NO_DATA_LABEL_GAP < fullArea.x + fullArea.width ? {
+      const noDataLabelWidth = estimateTextWidth18(
+        "No data",
+        labelStyle.fontSize,
+        labelStyle.fontWeight
+      );
+      const noData = hasUnmatched && noDataX + bar.height + NO_DATA_LABEL_GAP + noDataLabelWidth < fullArea.x + fullArea.width ? {
         x: noDataX,
         y: bar.y,
         size: bar.height,
         fill: neutralFill,
+        // Same hatch the no-data features carry, so the key matches what
+        // is on the map rather than a neutral the ramp's center mimics.
+        pattern: noDataPattern,
         label: "No data",
         labelX: noDataX + bar.height + NO_DATA_LABEL_GAP,
         labelY: bar.y + bar.height
@@ -13839,6 +13921,7 @@ function compileGeoMap(spec, options) {
       colorScale: colorEncoding.scale,
       isDarkMode: !!isDarkMode,
       neutralFill,
+      noDataPattern,
       theme,
       fullArea,
       mapAreaHeight,
@@ -14290,6 +14373,7 @@ function buildQuantitativeMarks(opts) {
     colorField,
     classScale,
     neutralFill,
+    noDataPattern,
     formatter,
     droppedFeatures
   } = opts;
@@ -14307,13 +14391,17 @@ function buildQuantitativeMarks(opts) {
     const hasData = dataRow !== null;
     let fill = neutralFill;
     let binIndex;
-    if (hasData && classScale) {
+    let hasValue = false;
+    if (hasData) {
       const raw = dataRow[colorField];
       if (raw != null) {
         const v = Number(raw);
         if (!Number.isNaN(v)) {
-          fill = classScale.color(v);
-          binIndex = classScale.binIndex(v);
+          hasValue = true;
+          if (classScale) {
+            fill = classScale.color(v);
+            binIndex = classScale.binIndex(v);
+          }
         }
       }
     }
@@ -14344,7 +14432,8 @@ function buildQuantitativeMarks(opts) {
       animationIndex: animIndex++,
       bounds,
       centroid: [cx, cy],
-      binIndex
+      binIndex,
+      ...hasValue ? {} : { noData: true, pattern: noDataPattern }
     });
   }
   return { marks };
@@ -14358,6 +14447,7 @@ function buildCategoricalMarks(opts) {
     colorScale: scaleConfig,
     isDarkMode,
     neutralFill,
+    noDataPattern,
     theme,
     fullArea,
     mapAreaHeight,
@@ -14366,24 +14456,7 @@ function buildCategoricalMarks(opts) {
     showLegend,
     droppedFeatures
   } = opts;
-  const categories = [];
-  const explicitDomain = scaleConfig?.domain;
-  if (explicitDomain && Array.isArray(explicitDomain)) {
-    for (const cat of explicitDomain) {
-      categories.push(String(cat));
-    }
-  }
-  const seen = new Set(categories);
-  for (const row of joined.values()) {
-    const raw = row[colorField];
-    if (raw != null) {
-      const cat = String(raw);
-      if (!seen.has(cat)) {
-        seen.add(cat);
-        categories.push(cat);
-      }
-    }
-  }
+  const categories = collectCategories(joined.values(), colorField, scaleConfig?.domain);
   const explicitRange = scaleConfig?.range;
   const colorSource = explicitRange && Array.isArray(explicitRange) ? explicitRange : CATEGORICAL_PALETTE2;
   const categoryColors = /* @__PURE__ */ new Map();
@@ -14403,10 +14476,12 @@ function buildCategoricalMarks(opts) {
     const dataRow = joined.get(featureId) ?? null;
     const hasData = dataRow !== null;
     let fill = neutralFill;
+    let hasValue = false;
     if (hasData) {
       const raw = dataRow[colorField];
       if (raw != null) {
         const cat = String(raw);
+        hasValue = true;
         fill = categoryColors.get(cat) ?? neutralFill;
       }
     }
@@ -14436,18 +14511,13 @@ function buildCategoricalMarks(opts) {
       },
       animationIndex: animIndex++,
       bounds,
-      centroid: [cx, cy]
+      centroid: [cx, cy],
+      ...hasValue ? {} : { noData: true, pattern: noDataPattern }
     });
   }
   let legend = null;
   if (showLegend && categories.length > 0) {
-    const labelStyle = {
-      fontFamily: theme.fonts.family,
-      fontSize: 11,
-      fontWeight: 400,
-      fill: theme.colors.text,
-      lineHeight: 1.2
-    };
+    const labelStyle = categoricalLegendLabelStyle(theme);
     const entries = categories.map((cat) => ({
       label: cat,
       color: categoryColors.get(cat),
@@ -14456,19 +14526,67 @@ function buildCategoricalMarks(opts) {
     const legendX = fullArea.x;
     const legendY = legendPosition === "bottom" ? fullArea.y + mapAreaHeight + legendReserveGap : fullArea.y + legendReserveGap;
     const legendWidth = fullArea.width;
-    const swatchSize = 10;
-    const swatchGap = 6;
-    const entryGap = 16;
+    const swatchSize = CATEGORICAL_SWATCH_SIZE;
+    const swatchGap = CATEGORICAL_SWATCH_GAP;
+    const entryGap = CATEGORICAL_ENTRY_GAP;
+    const entryWidths = entries.map((e) => categoricalEntryWidth(e.label, labelStyle));
+    const placed = wrapCategoricalEntries(entryWidths, legendWidth);
+    const entryPositions = placed.map((p, i) => {
+      const x = legendX + p.x;
+      const y = legendY + p.row * CATEGORICAL_ROW_HEIGHT;
+      return {
+        x,
+        y,
+        labelX: x + swatchSize + swatchGap,
+        labelY: y + swatchSize / 2,
+        width: entryWidths[i],
+        row: p.row
+      };
+    });
+    let rows = placed.length > 0 ? placed[placed.length - 1].row + 1 : 1;
+    const hasUnmatched = marks.some((m) => m.noData);
+    const last = placed[placed.length - 1];
+    const blockWidth = noDataBlockWidth(labelStyle);
+    let noDataOffsetX = last ? last.x + entryWidths[entryWidths.length - 1] : 0;
+    let noDataRow = last ? last.row : 0;
+    if (noDataOffsetX + blockWidth > legendWidth) {
+      noDataOffsetX = 0;
+      noDataRow += 1;
+    }
+    const noDataX = legendX + noDataOffsetX;
+    const noDataY = legendY + noDataRow * CATEGORICAL_ROW_HEIGHT;
+    const chipSize = Math.round(swatchSize * 0.6);
+    const noData = hasUnmatched && blockWidth <= legendWidth ? {
+      x: noDataX + (swatchSize - chipSize) / 2,
+      y: noDataY + swatchSize / 2 - chipSize / 2,
+      size: chipSize,
+      fill: neutralFill,
+      // The same hatch the no-data features carry, so the key matches
+      // what is on the map.
+      pattern: noDataPattern,
+      label: "No data",
+      labelX: noDataX + swatchSize + NO_DATA_LABEL_GAP,
+      labelY: noDataY + swatchSize / 2
+    } : void 0;
+    if (noData) rows = Math.max(rows, noDataRow + 1);
     legend = {
       type: "categorical",
       position: legendPosition,
-      bounds: { x: legendX, y: legendY, width: legendWidth, height: swatchSize + 6 },
+      bounds: {
+        x: legendX,
+        y: legendY,
+        width: legendWidth,
+        height: rows * CATEGORICAL_ROW_HEIGHT
+      },
       labelStyle,
       entries,
+      entryPositions,
+      rowHeight: CATEGORICAL_ROW_HEIGHT,
       swatchSize,
       swatchGap,
       entryGap,
-      swatchChipFill: isDarkMode ? "rgba(255,255,255,0.06)" : "rgba(0,0,0,0.04)"
+      swatchChipFill: isDarkMode ? "rgba(255,255,255,0.06)" : "rgba(0,0,0,0.04)",
+      noData
     };
   }
   return { marks, legend };
@@ -14992,6 +15110,9 @@ function resolveGraphInteraction(cfg) {
   };
 }
 
+// src/graphs/types.ts
+var MAX_3D_NODES = 2e3;
+
 // src/graphs/compile-graph.ts
 var graphNumberFormatter = defaultNumberFormatter8({ allIntegers: false, surface: "chart" });
 function mergeOverrides(...layers) {
@@ -15147,6 +15268,7 @@ function compileGraph(spec, options) {
     );
   }
   const graphSpec = normalized;
+  const numDimensions = resolveNumDimensions(graphSpec, options.onWarn);
   for (const [name, ch] of [
     ["nodeColor", graphSpec.encoding.nodeColor],
     ["edgeColor", graphSpec.encoding.edgeColor]
@@ -15288,9 +15410,39 @@ function compileGraph(spec, options) {
     legendField,
     initialHighlight,
     seedNodeIds,
-    edgeLegend
+    edgeLegend,
+    numDimensions
   };
 }
+function resolveNumDimensions(spec, onWarn) {
+  const requested = spec.dimensions;
+  if (requested !== void 0 && requested !== 2 && requested !== 3) {
+    throw new Error(
+      `Spec error: graph "dimensions" must be 2 or 3, received ${JSON.stringify(requested)}.`
+    );
+  }
+  if (requested !== 3) return 2;
+  if (spec.nodes.length > MAX_3D_NODES) {
+    onWarn?.(
+      `dimensions: 3 is unavailable for ${spec.nodes.length} nodes (the limit is ${MAX_3D_NODES}); rendering in 2D.`
+    );
+    return 2;
+  }
+  if (spec.interaction?.cursorRepulsion) {
+    onWarn?.("interaction.cursorRepulsion is not supported in 3D; it will be ignored.");
+  }
+  if (spec.interaction?.springyDrag) {
+    onWarn?.("interaction.springyDrag is not supported in 3D; it will be ignored.");
+  }
+  const hasStroke = (o) => o?.stroke !== void 0 || o?.strokeWidth !== void 0;
+  const strokeOverrides = Object.values(spec.nodeOverrides ?? {}).some(hasStroke) || hasStroke(spec.seedNode?.style);
+  if (strokeOverrides) {
+    onWarn?.(
+      "nodeOverrides/seedNode.style stroke and strokeWidth are not supported in 3D; they will be ignored."
+    );
+  }
+  return 3;
+}
 var DEFAULT_COLLISION_PADDING = 5;
 
 // src/layout/dimensions.ts
@@ -15302,6 +15454,7 @@ import {
   computeFieldFormatContext as computeFieldFormatContext6,
   defaultNumberFormatter as defaultNumberFormatter9,
   estimateTextWidth as estimateTextWidth20,
+  getHeightClass as getHeightClass2,
   HPAD_COMPACT_FRACTION as HPAD_COMPACT_FRACTION3,
   HPAD_COMPACT_MIN as HPAD_COMPACT_MIN3,
   isAxislessMark as isAxislessMark2,
@@ -15414,6 +15567,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     chromeMode = "hidden";
   }
   const bottomLegendReservation = plan ? hasLegendContent(plan.legendContent) && plan.legendContent.position === "bottom" ? plan.legendContent.height + legendGap(width) : 0 : legendLayoutHasContent(legendLayout) && legendLayout.position === "bottom" ? legendLayout.bounds.height + legendGap(width) : 0;
+  const isCrampedHeight = getHeightClass2(height) === "cramped";
   const chrome = plan?.chrome ?? computeChrome5(
     chromeToInput(spec.chrome),
     theme,
@@ -15422,7 +15576,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     chromeMode,
     padding,
     watermark,
-    bottomLegendReservation
+    bottomLegendReservation,
+    isCrampedHeight
   );
   const chromeLayout = resolveChromeLayout(spec, options);
   const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
@@ -15460,7 +15615,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       margins: margins2,
       theme,
       xAxisHeight: xAxisSpace,
-      effectiveAxisGap: 0
+      effectiveAxisGap: 0,
+      topPad: padding
     };
   }
   const total = { x: 0, y: 0, width, height: effectiveHeight };
@@ -15497,9 +15653,9 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
   const inlineTickOverhang = yIsInlinePre ? theme.fonts.sizes.axisTick + INLINE_TICK_OVERHANG_PAD : 0;
   const topAxisGap = isRadial && chrome.topHeight === 0 ? 0 : axisMargin + inlineTickOverhang;
   const topPad = width < NARROW_VIEWPORT_MAX3 ? padding + TOP_PAD_EXTRA_NARROW2 : padding;
-  const wantsMetrics = !!spec.metrics && spec.metrics.length > 0 && chromeMode !== "hidden";
+  const wantsMetrics = !!spec.metrics && spec.metrics.length > 0 && chromeMode !== "hidden" && !isCrampedHeight;
   const tentativeMetricsHeight = wantsMetrics ? metricBarHeight(metricFonts(theme)) : 0;
-  const wantsSearch = !!spec.seriesSearch && chromeMode !== "hidden";
+  const wantsSearch = !!spec.seriesSearch && chromeMode !== "hidden" && !isCrampedHeight;
   const searchReservation = wantsSearch ? SERIES_SEARCH_INPUT_HEIGHT + SERIES_SEARCH_GAP : 0;
   const margins = {
     top: topPad + chrome.topHeight + tentativeMetricsHeight + searchReservation,
@@ -15757,6 +15913,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         ) : void 0,
         xAxisHeight,
         effectiveAxisGap: fallbackEffectiveAxisGap,
+        topPad,
         chromeStripped: true
       };
     }
@@ -15781,7 +15938,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     metrics: resolvedMetrics,
     seriesSearch: wantsSearch ? resolveSeriesSearch(spec, metricsTopY + (resolvedMetrics?.height ?? 0), metricsArea) : void 0,
     xAxisHeight,
-    effectiveAxisGap
+    effectiveAxisGap,
+    topPad
   };
 }
 function resolveSeriesSearch(spec, y, area3) {
@@ -17063,40 +17221,73 @@ function inferAlignment(col, type) {
   if (col.align) return col.align;
   return type === "quantitative" ? "right" : "left";
 }
-function estimateColumnWidth(col, data, fontSize) {
+function cellPaddingX(density) {
+  if (density === "condensed") return 24;
+  if (density === "relaxed") return 40;
+  return 32;
+}
+function estimateColumnWidth(col, data, fontSize, paddingX) {
   const MIN_WIDTH = 60;
-  const PADDING = 24;
   if (col.sparkline) return 140;
-  if (col.image) return (col.image.width ?? 24) + PADDING;
+  if (col.image) return (col.image.width ?? 24) + paddingX;
   if (col.flag) return 60;
   const label = col.label ?? col.key;
-  const headerWidth = estimateTextWidth22(label, fontSize, 600) + PADDING;
+  const headerWidth = estimateTextWidth22(label, fontSize, 600) + paddingX;
   const sampleSize = Math.min(100, data.length);
   let maxDataWidth = 0;
   for (let i = 0; i < sampleSize; i++) {
     const val = data[i][col.key];
     const text = val == null ? "" : String(val);
-    const width = estimateTextWidth22(text, fontSize, 400) + PADDING;
+    const width = estimateTextWidth22(text, fontSize, 400) + paddingX;
     if (width > maxDataWidth) maxDataWidth = width;
   }
   return Math.max(MIN_WIDTH, headerWidth, maxDataWidth);
 }
-function resolveColumns(columns, data, totalWidth, theme) {
+var MIN_COLUMN_WIDTH = 60;
+function resolveColumns(columns, data, totalWidth, theme, density, warnings = []) {
   const fontSize = theme.fonts.sizes.body;
-  const isFixed = columns.map((col) => !!(col.sparkline || col.image || col.flag));
+  const paddingX = cellPaddingX(density);
+  const isFixed = columns.map((col) => !!(col.sparkline || col.image || col.flag || col.width));
   const naturalWidths = columns.map((col) => {
     if (col.width) {
       if (col.width.endsWith("px")) {
         return parseInt(col.width, 10) || 100;
       }
       if (col.width.endsWith("%")) {
-        return parseFloat(col.width) / 100 * totalWidth || 100;
+        return Math.round(parseFloat(col.width) / 100 * totalWidth) || 100;
       }
       return parseInt(col.width, 10) || 100;
     }
-    return estimateColumnWidth(col, data, fontSize);
+    return estimateColumnWidth(col, data, fontSize, paddingX);
   });
-  const fixedTotal = naturalWidths.reduce((sum, w, i) => sum + (isFixed[i] ? w : 0), 0);
+  const explicitIndices = columns.map((_, i) => i).filter((i) => isFixed[i] && !!columns[i].width);
+  const visualFixedTotal = columns.reduce(
+    (sum, col, i) => sum + (isFixed[i] && !col.width ? naturalWidths[i] : 0),
+    0
+  );
+  const explicitTotal = explicitIndices.reduce((sum, i) => sum + naturalWidths[i], 0);
+  const budgetForExplicit = totalWidth - visualFixedTotal;
+  const scaledExplicitWidths = /* @__PURE__ */ new Map();
+  if (explicitTotal > 0 && budgetForExplicit > 0 && explicitTotal > budgetForExplicit) {
+    const scale = budgetForExplicit / explicitTotal;
+    let cumulative = 0;
+    let cumulativeTarget = 0;
+    let floored = false;
+    for (const i of explicitIndices) {
+      cumulativeTarget += naturalWidths[i] * scale;
+      const target = Math.round(cumulativeTarget) - cumulative;
+      const width = Math.max(MIN_COLUMN_WIDTH, target);
+      if (width > target) floored = true;
+      scaledExplicitWidths.set(i, width);
+      cumulative += width;
+    }
+    const outcome = floored ? `scaled proportionally down, but at least one column hit the ${MIN_COLUMN_WIDTH}px minimum, so the table will still overflow.` : "scaled proportionally to fit.";
+    warnings.push(
+      `[openchart] TABLE_WIDTH_OVERFLOW: explicit column widths summed to ${explicitTotal}px, exceeding the ${budgetForExplicit}px available in a ${totalWidth}px-wide table; ${outcome}`
+    );
+  }
+  const resolvedFixedWidths = naturalWidths.map((w, i) => scaledExplicitWidths.get(i) ?? w);
+  const fixedTotal = resolvedFixedWidths.reduce((sum, w, i) => sum + (isFixed[i] ? w : 0), 0);
   const flexTotal = naturalWidths.reduce((sum, w, i) => sum + (isFixed[i] ? 0 : w), 0);
   const remainingWidth = totalWidth - fixedTotal;
   const flexScale = flexTotal > 0 && remainingWidth > 0 ? remainingWidth / flexTotal : 1;
@@ -17105,7 +17296,10 @@ function resolveColumns(columns, data, totalWidth, theme) {
     return {
       key: col.key,
       label: col.label ?? col.key,
-      width: Math.max(60, isFixed[i] ? naturalWidths[i] : Math.round(naturalWidths[i] * flexScale)),
+      width: Math.max(
+        MIN_COLUMN_WIDTH,
+        isFixed[i] ? resolvedFixedWidths[i] : Math.round(naturalWidths[i] * flexScale)
+      ),
       sortable: col.sortable ?? true,
       align: inferAlignment(col, type),
       type,
@@ -17228,6 +17422,8 @@ function buildTotalRow(label, columns, resolvedColumns, rows) {
       style: {},
       cellType: "text"
     };
+    const col = columns[i];
+    if (col.total === false) return blank;
     if (resolved.type !== "quantitative" || !SUMMABLE.has(resolved.cellType)) return blank;
     let sum = 0;
     let seen = false;
@@ -17251,7 +17447,17 @@ function buildTotalRow(label, columns, resolvedColumns, rows) {
 function compileTableLayout(spec, options, theme) {
   const data = spec.data;
   const darkMode = theme.isDark;
-  const resolvedColumns = resolveColumns(spec.columns, data, options.width, theme);
+  const columnWarnings = [];
+  const resolvedColumns = resolveColumns(
+    spec.columns,
+    data,
+    options.width,
+    theme,
+    // The deprecated `compact` flag renders condensed padding too.
+    spec.density ?? (spec.compact ? "condensed" : void 0),
+    columnWarnings
+  );
+  emitSpecWarnings(columnWarnings, options.onWarn);
   const sort = resolveSort(spec, resolvedColumns, options.sort);
   const searchIndex = spec.search ? buildSearchIndex(data, spec.columns) : /* @__PURE__ */ new Map();
   let currentData = data;
@@ -17578,8 +17784,8 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
     const hasEmptyTiles = tiles.some((t) => !t.hasData);
     const noDataLabel = "No data";
     const noDataLabelWidth = estimateTextWidth23(noDataLabel, 11);
-    const noDataBlockWidth = hasEmptyTiles ? NO_DATA_BAR_GAP + legendBarHeight + NO_DATA_LABEL_GAP2 + noDataLabelWidth : 0;
-    const barWidth = Math.max(0, legendWidth - noDataBlockWidth);
+    const noDataBlockWidth2 = hasEmptyTiles ? NO_DATA_BAR_GAP + legendBarHeight + NO_DATA_LABEL_GAP2 + noDataLabelWidth : 0;
+    const barWidth = Math.max(0, legendWidth - noDataBlockWidth2);
     const noDataX = legendX + barWidth + NO_DATA_BAR_GAP;
     gradientLegend = {
       type: "gradient",
@@ -18991,7 +19197,7 @@ function compileChart(spec, optionsInput) {
     chartSpec = { ...chartSpec, data: runTransforms(chartSpec.data, rawTransforms) };
   }
   const breakpoint = getBreakpoint3(options.width);
-  const heightClass = getHeightClass(options.height);
+  const heightClass = getHeightClass3(options.height);
   let strategy = getLayoutStrategy(breakpoint, heightClass);
   const economy = resolveChromeEconomy(options.width, options.height);
   const rawSpec = expandedSpec;
@@ -19135,7 +19341,7 @@ function compileChart(spec, optionsInput) {
     watermark = false;
     chartSpec = { ...chartSpec, watermark: false };
   }
-  if (heightClass === "cramped" && !chartSpec.userExplicit.watermark) {
+  if ((heightClass === "minimal" || heightClass === "cramped") && !chartSpec.userExplicit.watermark) {
     watermark = false;
     chartSpec = { ...chartSpec, watermark: false };
   }
@@ -19333,6 +19539,16 @@ function compileChart(spec, optionsInput) {
   if (endpointLabels.entries.length > 0 && endpointLabels.bounds.width > 0) {
     obstacles.push({ ...endpointLabels.bounds, kind: "endpoint-label" });
   }
+  const chromeBottomY = dims.topPad + dims.chrome.topHeight;
+  if (dims.chrome.topHeight > 0) {
+    obstacles.push({
+      x: 0,
+      y: 0,
+      width: dims.total.width,
+      height: chromeBottomY,
+      kind: "chrome"
+    });
+  }
   const annotationMeasure = options.measureText ? (text, font) => options.measureText(text, font.fontSize, font.fontWeight).width : heuristicMeasure;
   let annotations = computeAnnotations(chartSpec, {
     scales,
@@ -19343,7 +19559,10 @@ function compileChart(spec, optionsInput) {
     svg: { width: dims.total.width, height: dims.total.height },
     measure: annotationMeasure,
     fontFamily: theme.fonts.family,
-    autoThin: chartSpec.autoThin
+    autoThin: chartSpec.autoThin,
+    // Hand-placed blocks skip every nudge pass, so the clamp is the only lever
+    // that keeps an author's offset from parking a callout on the title.
+    topBound: dims.chrome.topHeight > 0 ? chromeBottomY : void 0
   });
   if (options.dev) {
     emitSpecWarnings(
@@ -19609,7 +19828,8 @@ function compileFaceted(chartSpec, renderSpec, facetChannel, facetDirection, opt
       svg: { width: options.width, height: options.height },
       measure: annotationMeasure,
       fontFamily: theme.fonts.family,
-      autoThin: panelSpecWithDomains.autoThin
+      autoThin: panelSpecWithDomains.autoThin,
+      topBound: dims.chrome.topHeight > 0 ? dims.topPad + dims.chrome.topHeight : void 0
     });
     if (chartSpec.autoThin && panelAnnotations.length > 1) {
       const thinned = thinAnnotations(
@@ -19785,6 +20005,7 @@ export {
   DEFAULT_LINE_HEIGHT,
   ENTER_DEFAULTS,
   EXIT_DEFAULTS,
+  MAX_3D_NODES,
   UPDATE_DEFAULTS,
   buildArcPath,
   buildAreaPath,