@opendata-ai/openchart-engine 8.0.0-rc.11 → 8.0.0-rc.13

package/dist/index.js

@@ -10482,6 +10482,7 @@ function normalizeChartSpec(spec, warnings) {
     data: spec.data,
     encoding,
     chrome: normalizeChrome(spec.chrome),
+    chromeLayout: spec.chromeLayout,
     metrics: spec.metrics,
     seriesSearch: normalizeSeriesSearch(spec, encoding, warnings),
     youDrawIt: normalizeYouDrawIt(spec),
@@ -10556,15 +10557,10 @@ function normalizeSankeySpec(spec, _warnings) {
   };
 }
 function normalizeGraphSpec(spec) {
-  const defaultLayout = {
+  const layout = {
     type: "force",
-    chargeStrength: -300,
-    linkDistance: 30
-  };
-  const layout = spec.layout ? {
-    ...defaultLayout,
     ...spec.layout
-  } : defaultLayout;
+  };
   return {
     type: "graph",
     nodes: spec.nodes,
@@ -10576,7 +10572,10 @@ function normalizeGraphSpec(spec) {
     annotations: normalizeAnnotations(spec.annotations),
     theme: spec.theme ?? {},
     darkMode: spec.darkMode ?? "off",
-    watermark: spec.watermark ?? true
+    watermark: spec.watermark ?? true,
+    animation: spec.animation,
+    interaction: spec.interaction,
+    legend: spec.legend
   };
 }
 function normalizeTileMapSpec(spec, warnings) {
@@ -11605,14 +11604,22 @@ function validateGraphSpec(spec, errors) {
   }
   if (spec.encoding && typeof spec.encoding === "object") {
     const encoding = spec.encoding;
-    const firstNode = nodes[0];
-    const firstEdge = edges.length > 0 ? edges[0] : null;
-    const nodeFields = firstNode ? new Set(Object.keys(firstNode)) : /* @__PURE__ */ new Set();
-    const edgeFields = firstEdge ? new Set(Object.keys(firstEdge)) : /* @__PURE__ */ new Set();
-    const nodeChannels = ["nodeColor", "nodeSize", "nodeLabel"];
+    const nodeFields = /* @__PURE__ */ new Set();
+    for (const node of nodes) {
+      if (node && typeof node === "object") {
+        for (const key of Object.keys(node)) nodeFields.add(key);
+      }
+    }
+    const edgeFields = /* @__PURE__ */ new Set();
+    for (const edge of edges) {
+      if (edge && typeof edge === "object") {
+        for (const key of Object.keys(edge)) edgeFields.add(key);
+      }
+    }
+    const nodeChannels = ["nodeColor", "nodeSize", "nodeOpacity", "nodeLabel"];
     for (const channel of nodeChannels) {
       const ch = encoding[channel];
-      if (ch?.field && typeof ch.field === "string" && !nodeFields.has(ch.field)) {
+      if (ch?.field && typeof ch.field === "string" && nodes.length > 0 && !nodeFields.has(ch.field)) {
         errors.push({
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on nodes. Available fields: ${[...nodeFields].join(", ")}`,
           path: `encoding.${channel}.field`,
@@ -11621,10 +11628,10 @@ function validateGraphSpec(spec, errors) {
         });
       }
     }
-    const edgeChannels = ["edgeColor", "edgeWidth"];
+    const edgeChannels = ["edgeColor", "edgeWidth", "edgeStyle"];
     for (const channel of edgeChannels) {
       const ch = encoding[channel];
-      if (ch?.field && typeof ch.field === "string" && firstEdge && !edgeFields.has(ch.field)) {
+      if (ch?.field && typeof ch.field === "string" && edges.length > 0 && !edgeFields.has(ch.field)) {
         errors.push({
           message: `Spec error: encoding.${channel}.field "${ch.field}" does not exist on edges. Available fields: ${[...edgeFields].join(", ")}`,
           path: `encoding.${channel}.field`,
@@ -12348,6 +12355,36 @@ ${errorMessages}`);
   return { spec: normalized, warnings };
 }
 
+// src/layout/shared.ts
+function chromeToInput(chrome) {
+  return {
+    eyebrow: chrome.eyebrow,
+    title: chrome.title,
+    subtitle: chrome.subtitle,
+    source: chrome.source,
+    byline: chrome.byline,
+    footer: chrome.footer,
+    brand: chrome.brand
+  };
+}
+function scalePadding(basePadding, width, height) {
+  const minDim = Math.min(width, height);
+  if (minDim >= 500) return basePadding;
+  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
+  const t = (minDim - 200) / 300;
+  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
+}
+function bottomMargin(bottomHeight, padding, xAxisHeight) {
+  return padding + bottomHeight + xAxisHeight;
+}
+var INLINE_TICK_OVERHANG_PAD = 6;
+function resolveChromeLayout(spec, options) {
+  const encoding = spec?.encoding;
+  const isFaceted = !!(encoding?.facet || encoding?.row || encoding?.column);
+  if (isFaceted) return "subtract";
+  return spec?.chromeLayout ?? options?.chromeLayout ?? "subtract";
+}
+
 // src/barlist/compile-barlist.ts
 var DEFAULT_ROW_GAP = 8;
 var LABEL_BAR_GAP = 12;
@@ -12395,14 +12432,19 @@ function compileBarList(spec, options) {
     watermark
   );
   const padding = theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
+  const grownHeight = chromeLayout === "grow" ? options.height + chrome.topHeight + chrome.bottomHeight : options.height;
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
-    return emptyLayout2(chrome, theme, options, watermark);
+    return emptyLayout2(chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const labelField = barlistSpec.encoding.label.field;
   const valueField = barlistSpec.encoding.value.field;
@@ -12587,7 +12629,7 @@ function compileBarList(spec, options) {
     a11y,
     theme,
     width: options.width,
-    height: options.height,
+    height: grownHeight,
     animation: resolvedAnimation,
     watermark,
     measureText
@@ -14881,30 +14923,6 @@ function computeAxes(scales, chartArea, strategy, theme, measureText, dataContex
   return result;
 }
 
-// src/layout/shared.ts
-function chromeToInput(chrome) {
-  return {
-    eyebrow: chrome.eyebrow,
-    title: chrome.title,
-    subtitle: chrome.subtitle,
-    source: chrome.source,
-    byline: chrome.byline,
-    footer: chrome.footer,
-    brand: chrome.brand
-  };
-}
-function scalePadding(basePadding, width, height) {
-  const minDim = Math.min(width, height);
-  if (minDim >= 500) return basePadding;
-  if (minDim <= 200) return Math.max(Math.round(basePadding * 0.5), 4);
-  const t = (minDim - 200) / 300;
-  return Math.max(Math.round(basePadding * (0.5 + t * 0.5)), 4);
-}
-function bottomMargin(bottomHeight, padding, xAxisHeight) {
-  return padding + bottomHeight + xAxisHeight;
-}
-var INLINE_TICK_OVERHANG_PAD = 6;
-
 // src/layout/plan.ts
 function createMeasureFn(measureText) {
   if (measureText) {
@@ -15126,7 +15144,9 @@ function resolveLayoutPlan(chartSpec, renderSpec, options, theme, strategy, wate
     if (hasTopLegend) topMargin += TOP_LEGEND_GAP_ABOVE + legendContent.height + gap;
     topMargin += effectiveTopAxisGap;
     const bMargin = bottomMargin(chrome.bottomHeight, padding, xAxisExtent);
-    const chartHeight = Math.max(0, height - topMargin - bMargin);
+    const chromeLayout = resolveChromeLayout(renderSpec, options);
+    const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
+    const chartHeight = Math.max(0, effectiveHeight - topMargin - bMargin);
     const rightMargin = hPad + (isRadial ? hPad : axisMargin);
     const rightAxisReserve = options.rightAxisReserve ?? 0;
     const provisionalArea = {
@@ -18006,11 +18026,15 @@ function compileMap(spec, options) {
     watermark
   );
   const padding = getBreakpoint(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN2, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION2)) : theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
     return emptyLayout3(chrome, theme, options, watermark);
@@ -18907,6 +18931,65 @@ import {
   resolveTheme as resolveTheme4
 } from "@opendata-ai/openchart-core";
 
+// src/graphs/animation.ts
+var ENTER_DEFAULT = {
+  duration: 600,
+  ease: "smooth",
+  stagger: true,
+  cameraFit: true
+};
+var UPDATE_DEFAULT = { duration: 300, ease: "smooth" };
+var EXIT_DEFAULT = { duration: 300, ease: "smooth" };
+var CAMERA_DEFAULT = { duration: "auto", ease: "smooth" };
+var HOVER_DEFAULT = { duration: 150, ease: "smooth" };
+function fullDefaults() {
+  return {
+    enter: { ...ENTER_DEFAULT },
+    update: { ...UPDATE_DEFAULT },
+    exit: { ...EXIT_DEFAULT },
+    camera: { ...CAMERA_DEFAULT },
+    hover: { ...HOVER_DEFAULT }
+  };
+}
+function resolveGraphAnimation(spec) {
+  if (spec === void 0 || spec === true) return fullDefaults();
+  if (spec === false) return void 0;
+  return {
+    enter: resolveEnter(spec.enter),
+    update: resolveDurationPhase(spec.update, UPDATE_DEFAULT),
+    exit: resolveDurationPhase(spec.exit, EXIT_DEFAULT),
+    camera: resolveCamera(spec.camera),
+    hover: resolveDurationPhase(spec.hover, HOVER_DEFAULT)
+  };
+}
+function resolveEnter(phase) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true) return { ...ENTER_DEFAULT };
+  return {
+    duration: phase.duration ?? ENTER_DEFAULT.duration,
+    ease: phase.ease ?? ENTER_DEFAULT.ease,
+    stagger: phase.stagger !== false,
+    cameraFit: ENTER_DEFAULT.cameraFit
+  };
+}
+function resolveDurationPhase(phase, defaults) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true)
+    return { duration: defaults.duration, ease: defaults.ease };
+  return {
+    duration: phase.duration ?? defaults.duration,
+    ease: phase.ease ?? defaults.ease
+  };
+}
+function resolveCamera(phase) {
+  if (phase === false) return null;
+  if (phase === void 0 || phase === true) return { ...CAMERA_DEFAULT };
+  return {
+    duration: phase.duration ?? CAMERA_DEFAULT.duration,
+    ease: phase.ease ?? CAMERA_DEFAULT.ease
+  };
+}
+
 // src/graphs/encoding.ts
 var DEFAULT_NODE_RADIUS = 5;
 var MIN_NODE_RADIUS = 3;
@@ -18946,16 +19029,42 @@ function computeDegrees(nodes, edges) {
   }
   return degrees2;
 }
+function resolveCategoricalDomain(values, sort, scaleDomain) {
+  if (Array.isArray(scaleDomain) && scaleDomain.length > 0) {
+    return scaleDomain.map((v) => String(v));
+  }
+  const seen = [];
+  const set = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (!set.has(v)) {
+      set.add(v);
+      seen.push(v);
+    }
+  }
+  if (sort === null) return seen;
+  if (Array.isArray(sort)) {
+    const pinned = sort.filter((v) => set.has(v));
+    const pinnedSet = new Set(pinned);
+    const rest = seen.filter((v) => !pinnedSet.has(v));
+    return [...pinned, ...rest];
+  }
+  const sorted = [...seen].sort((a, b) => a.localeCompare(b));
+  return sort === "descending" ? sorted.reverse() : sorted;
+}
 function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
   const degrees2 = computeDegrees(nodes, edges);
   const maxDegree = Math.max(1, ...degrees2.values());
   let sizeScale;
   if (encoding.nodeSize?.field) {
     const field = encoding.nodeSize.field;
+    const scaleConfig = encoding.nodeSize.scale;
     const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
     const sizeMin = min(values) ?? 0;
     const sizeMax = max(values) ?? 1;
-    sizeScale = sqrt().domain([sizeMin, sizeMax]).range([MIN_NODE_RADIUS, MAX_NODE_RADIUS]);
+    const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [sizeMin, sizeMax];
+    const range3 = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [MIN_NODE_RADIUS, MAX_NODE_RADIUS];
+    const ctor = scaleConfig?.type === "linear" ? linear2 : sqrt;
+    sizeScale = ctor().domain(domain).range(range3);
   }
   let colorFn;
   if (encoding.nodeColor?.field) {
@@ -18976,13 +19085,28 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
         return Number.isFinite(val) ? colorScale(val) : theme.colors.categorical[0];
       };
     } else {
-      const domain = scaleConfig?.domain && Array.isArray(scaleConfig.domain) ? scaleConfig.domain : [...new Set(nodes.map((n) => String(n[field] ?? "")))];
+      const domain = resolveCategoricalDomain(
+        nodes.map((n) => String(n[field] ?? "")),
+        encoding.nodeColor.sort,
+        scaleConfig?.domain
+      );
       const range3 = scaleConfig?.range && scaleConfig.range.length > 0 ? scaleConfig.range : theme.colors.categorical;
       const ordinalScale = ordinal().domain(domain).range(range3);
       colorFn = (node) => ordinalScale(String(node[field] ?? ""));
     }
   }
   const defaultColor = theme.colors.categorical[0];
+  let opacityScale;
+  if (encoding.nodeOpacity?.field) {
+    const field = encoding.nodeOpacity.field;
+    const scaleConfig = encoding.nodeOpacity.scale;
+    const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+    const opMin = min(values) ?? 0;
+    const opMax = max(values) ?? 1;
+    const domain = scaleConfig?.domain && scaleConfig.domain.length === 2 ? scaleConfig.domain : [opMin, opMax];
+    const range3 = scaleConfig?.range && scaleConfig.range.length >= 2 ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])] : [0.25, 1];
+    opacityScale = linear2().domain(domain).range(range3);
+  }
   return nodes.map((node) => {
     let radius = DEFAULT_NODE_RADIUS;
     if (sizeScale && encoding.nodeSize?.field) {
@@ -18991,6 +19115,13 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
         radius = sizeScale(val);
       }
     }
+    let opacity = 1;
+    if (opacityScale && encoding.nodeOpacity?.field) {
+      const val = Number(node[encoding.nodeOpacity.field]);
+      if (Number.isFinite(val)) {
+        opacity = opacityScale(val);
+      }
+    }
     const fill = colorFn ? colorFn(node) : defaultColor;
     const stroke = darkenColor(fill);
     let label;
@@ -19019,6 +19150,7 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
       label,
       labelPriority: finalLabelPriority,
       community: void 0,
+      opacity,
       data
     };
   });
@@ -19051,7 +19183,11 @@ function resolveEdgeVisuals(edges, encoding, theme) {
         return Number.isFinite(val) ? colorScale(val) : hexWithOpacity(theme.colors.axis, 0.4);
       };
     } else {
-      const domain = scaleConfig?.domain && Array.isArray(scaleConfig.domain) ? scaleConfig.domain : [...new Set(edges.map((e) => String(e[field] ?? "")))];
+      const domain = resolveCategoricalDomain(
+        edges.map((e) => String(e[field] ?? "")),
+        encoding.edgeColor.sort,
+        scaleConfig?.domain
+      );
       const range3 = scaleConfig?.range && scaleConfig.range.length > 0 ? scaleConfig.range : theme.colors.categorical;
       const ordinalScale = ordinal().domain(domain).range(range3);
       edgeColorFn = (edge) => ordinalScale(String(edge[field] ?? ""));
@@ -19062,10 +19198,14 @@ function resolveEdgeVisuals(edges, encoding, theme) {
   let styleFn;
   if (encoding.edgeStyle?.field) {
     const field = encoding.edgeStyle.field;
-    const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? "")))];
+    const domain = resolveCategoricalDomain(
+      edges.map((e) => String(e[field] ?? "")),
+      encoding.edgeStyle.sort,
+      encoding.edgeStyle.scale?.domain
+    );
     const styleMap = /* @__PURE__ */ new Map();
-    for (let i = 0; i < uniqueValues.length; i++) {
-      styleMap.set(uniqueValues[i], EDGE_STYLES[i % EDGE_STYLES.length]);
+    for (let i = 0; i < domain.length; i++) {
+      styleMap.set(domain[i], EDGE_STYLES[i % EDGE_STYLES.length]);
     }
     styleFn = (edge) => styleMap.get(String(edge[field] ?? "")) ?? "solid";
   }
@@ -19123,12 +19263,49 @@ function applyCommunityColors(nodes, colorMap) {
   }
 }
 
+// src/graphs/interaction.ts
+var DEFAULT_DIM_OPACITY = 0.15;
+var DEFAULT_CURSOR_RADIUS = 80;
+var DEFAULT_CURSOR_STRENGTH = 30;
+function resolveGraphInteraction(cfg) {
+  const hover = cfg?.hover;
+  const cursor = cfg?.cursorRepulsion;
+  let cursorRepulsion = null;
+  if (cursor === true) {
+    cursorRepulsion = { radius: DEFAULT_CURSOR_RADIUS, strength: DEFAULT_CURSOR_STRENGTH };
+  } else if (cursor && typeof cursor === "object") {
+    cursorRepulsion = {
+      radius: cursor.radius ?? DEFAULT_CURSOR_RADIUS,
+      strength: cursor.strength ?? DEFAULT_CURSOR_STRENGTH
+    };
+  }
+  return {
+    hoverMode: hover?.mode ?? "neighbors",
+    dimOpacity: hover?.dimOpacity ?? DEFAULT_DIM_OPACITY,
+    selectFlyTo: cfg?.select?.flyTo ?? false,
+    cursorRepulsion,
+    springyDrag: cfg?.springyDrag ?? false
+  };
+}
+
 // src/graphs/compile-graph.ts
 var graphNumberFormatter = defaultNumberFormatter8({ allIntegers: false, surface: "chart" });
 var SWATCH_SIZE2 = 12;
 var SWATCH_GAP2 = 6;
 var ENTRY_GAP2 = 16;
-function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeColorField) {
+var ENERGY_PRESETS = {
+  gentle: { chargeStrength: -150, velocityDecay: 0.5 },
+  balanced: { chargeStrength: -300, velocityDecay: 0.4 },
+  energetic: { chargeStrength: -600, velocityDecay: 0.3 }
+};
+var SETTLE_PRESETS = {
+  quick: 0.05,
+  balanced: 0.0228,
+  thorough: 0.01
+};
+var DEFAULT_WARMUP_TICKS = 100;
+var DEFAULT_WARMUP_BUDGET_MS = 250;
+function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeColorField, legendOrder) {
   const labelStyle = {
     fontFamily: theme.fonts.family,
     fontSize: theme.fonts.sizes.small,
@@ -19138,25 +19315,35 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
   };
   let entries;
   if (hasCommunities && communityColorMap.size > 0) {
+    const counts = /* @__PURE__ */ new Map();
+    for (const node of nodes) {
+      if (node.community != null) {
+        counts.set(node.community, (counts.get(node.community) ?? 0) + 1);
+      }
+    }
     entries = [...communityColorMap.entries()].map(([label, color2]) => ({
       label,
       color: color2,
       shape: "circle",
-      active: true
+      active: true,
+      count: counts.get(label) ?? 0
     }));
   } else if (nodeColorField) {
     const categoryColors = /* @__PURE__ */ new Map();
+    const categoryCounts = /* @__PURE__ */ new Map();
     for (const node of nodes) {
       const category = String(node.data[nodeColorField] ?? node.label ?? node.id);
       if (!categoryColors.has(category)) {
         categoryColors.set(category, node.fill);
       }
+      categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
     }
-    entries = categoryColors.size <= 1 ? [] : [...categoryColors.entries()].map(([label, color2]) => ({
+    entries = categoryColors.size <= 1 ? [] : (legendOrder ?? [...categoryColors.keys()]).filter((label) => categoryColors.has(label)).map((label) => ({
       label,
-      color: color2,
+      color: categoryColors.get(label),
       shape: "circle",
-      active: true
+      active: true,
+      count: categoryCounts.get(label) ?? 0
     }));
   } else {
     entries = [];
@@ -19172,6 +19359,30 @@ function buildGraphLegend(nodes, communityColorMap, hasCommunities, theme, nodeC
     swatchChipFill: theme.colors.annotationFill
   };
 }
+function buildEdgeLegend(edges, encoding) {
+  const field = encoding.edgeColor?.field;
+  if (!field || (encoding.edgeColor?.type ?? "nominal") === "quantitative") return void 0;
+  const categoryColors = /* @__PURE__ */ new Map();
+  const categoryCounts = /* @__PURE__ */ new Map();
+  for (const edge of edges) {
+    const category = String(edge.data[field] ?? "");
+    if (!categoryColors.has(category)) categoryColors.set(category, edge.stroke);
+    categoryCounts.set(category, (categoryCounts.get(category) ?? 0) + 1);
+  }
+  if (categoryColors.size <= 1) return void 0;
+  const order = resolveCategoricalDomain(
+    edges.map((e) => String(e.data[field] ?? "")),
+    encoding.edgeColor?.sort,
+    encoding.edgeColor?.scale?.domain
+  );
+  return order.filter((label) => categoryColors.has(label)).map((label) => ({
+    label,
+    color: categoryColors.get(label),
+    shape: "line",
+    active: true,
+    count: categoryCounts.get(label) ?? 0
+  }));
+}
 function buildGraphTooltips(nodes) {
   const descriptors = /* @__PURE__ */ new Map();
   for (const node of nodes) {
@@ -19198,6 +19409,21 @@ function buildGraphTooltips(nodes) {
   }
   return descriptors;
 }
+function buildEdgeTooltip(edge) {
+  const fields = [];
+  for (const [key, value2] of Object.entries(edge.data)) {
+    if (key === "source" || key === "target") continue;
+    if (value2 == null) continue;
+    fields.push({
+      label: key,
+      value: typeof value2 === "number" ? graphNumberFormatter(value2) : String(value2)
+    });
+  }
+  return {
+    title: `${edge.source} \u2192 ${edge.target}`,
+    fields
+  };
+}
 function compileGraph(spec, options) {
   const { spec: normalized, warnings } = compile(spec);
   emitSpecWarnings(warnings, options.onWarn);
@@ -19207,6 +19433,16 @@ function compileGraph(spec, options) {
     );
   }
   const graphSpec = normalized;
+  for (const [name, ch] of [
+    ["nodeColor", graphSpec.encoding.nodeColor],
+    ["edgeColor", graphSpec.encoding.edgeColor]
+  ]) {
+    if (ch?.sort != null && ch.type === "quantitative") {
+      options.onWarn?.(
+        `encoding.${name}.sort is ignored for a quantitative field (sort only orders categorical domains).`
+      );
+    }
+  }
   const rawWatermark = spec.watermark;
   const watermark = rawWatermark !== void 0 ? graphSpec.watermark : options.watermark ?? true;
   const mergedThemeConfig = options.theme ? { ...graphSpec.theme, ...options.theme } : graphSpec.theme;
@@ -19232,13 +19468,30 @@ function compileGraph(spec, options) {
   }
   const compiledEdges = resolveEdgeVisuals(graphSpec.edges, graphSpec.encoding, theme);
   const useCommunitiesForLegend = hasCommunities && !hasNodeColorEncoding;
+  const nodeColorField = graphSpec.encoding.nodeColor?.field;
+  const legendOrder = nodeColorField ? resolveCategoricalDomain(
+    compiledNodes.map((n) => String(n.data[nodeColorField] ?? n.label ?? n.id)),
+    graphSpec.encoding.nodeColor?.sort,
+    graphSpec.encoding.nodeColor?.scale?.domain
+  ) : void 0;
   const legend = buildGraphLegend(
     compiledNodes,
     communityColorMap,
     useCommunitiesForLegend,
     theme,
-    graphSpec.encoding.nodeColor?.field
+    nodeColorField,
+    legendOrder
   );
+  const edgeLegend = buildEdgeLegend(compiledEdges, graphSpec.encoding);
+  const legendField = nodeColorField ?? (useCommunitiesForLegend ? clusteringField ?? null : null);
+  let initialHighlight;
+  if (nodeColorField && graphSpec.encoding.nodeColor?.highlight != null) {
+    const raw = graphSpec.encoding.nodeColor.highlight;
+    const requested = Array.isArray(raw) ? raw : [raw];
+    const available = new Set(legendOrder ?? []);
+    const values = requested.filter((v) => available.has(v));
+    if (values.length > 0) initialHighlight = { field: nodeColorField, values };
+  }
   const tooltipDescriptors = buildGraphTooltips(compiledNodes);
   const communityCount = communityColorMap.size;
   const altParts = [
@@ -19255,17 +19508,26 @@ function compileGraph(spec, options) {
   };
   const collisionPadding = graphSpec.layout.collisionPadding ?? 2;
   const maxRadius = compiledNodes.length > 0 ? Math.max(...compiledNodes.map((n) => n.radius)) : DEFAULT_COLLISION_PADDING;
+  const energyPreset = graphSpec.layout.energy ? ENERGY_PRESETS[graphSpec.layout.energy] : ENERGY_PRESETS.balanced;
+  const settlePreset = graphSpec.layout.settle ? SETTLE_PRESETS[graphSpec.layout.settle] : SETTLE_PRESETS.balanced;
+  const warmupRaw = graphSpec.layout.warmup;
+  const warmupTicks = warmupRaw === false ? 0 : typeof warmupRaw === "number" ? Math.max(0, Math.floor(warmupRaw)) : DEFAULT_WARMUP_TICKS;
   const simulationConfig = {
-    chargeStrength: graphSpec.layout.chargeStrength ?? -300,
+    chargeStrength: graphSpec.layout.chargeStrength ?? energyPreset.chargeStrength,
     linkDistance: graphSpec.layout.linkDistance ?? 30,
     clustering: clusteringField ? { field: clusteringField, strength: 0.5 } : null,
-    alphaDecay: 0.0228,
-    velocityDecay: 0.4,
+    alphaDecay: settlePreset,
+    velocityDecay: energyPreset.velocityDecay,
     collisionRadius: maxRadius + collisionPadding,
     collisionPadding,
     linkStrength: graphSpec.layout.linkStrength,
-    centerForce: graphSpec.layout.centerForce
+    centerForce: graphSpec.layout.centerForce,
+    seed: graphSpec.layout.seed,
+    warmupTicks,
+    warmupBudgetMs: DEFAULT_WARMUP_BUDGET_MS
   };
+  const animation = resolveGraphAnimation(graphSpec.animation);
+  const interaction = resolveGraphInteraction(graphSpec.interaction);
   const chrome = computeChrome4(
     {
       title: graphSpec.chrome.title,
@@ -19294,7 +19556,12 @@ function compileGraph(spec, options) {
       height: options.height
     },
     simulationConfig,
-    watermark
+    watermark,
+    animation,
+    interaction,
+    legendField,
+    initialHighlight,
+    edgeLegend
   };
 }
 var DEFAULT_COLLISION_PADDING = 5;
@@ -19387,6 +19654,7 @@ function legendLayoutHasContent(legendLayout) {
 }
 var MIN_CHART_WIDTH = 60;
 var MIN_CHART_HEIGHT2 = 40;
+var PLOT_SHARE_MAX = 0.4;
 var SERIES_SEARCH_INPUT_HEIGHT = 32;
 var SERIES_SEARCH_GAP = 12;
 function getMinChartDims(display) {
@@ -19429,8 +19697,10 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     watermark,
     bottomLegendReservation
   );
+  const chromeLayout = resolveChromeLayout(spec, options);
+  const effectiveHeight = chromeLayout === "grow" ? height + chrome.topHeight + chrome.bottomHeight : height;
   if (isSparkline) {
-    const total2 = { x: 0, y: 0, width, height };
+    const total2 = { x: 0, y: 0, width, height: effectiveHeight };
     const sparkPad = getSparklinePad(spec);
     const xAxisSpace = userExplicit.xAxis ? 26 : 0;
     const yAxisSpace = userExplicit.yAxis ? 30 : 0;
@@ -19454,7 +19724,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       x: margins2.left,
       y: margins2.top,
       width: Math.max(0, width - margins2.left - margins2.right),
-      height: Math.max(0, height - margins2.top - margins2.bottom)
+      height: Math.max(0, effectiveHeight - margins2.top - margins2.bottom)
     };
     return {
       total: total2,
@@ -19466,7 +19736,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
       effectiveAxisGap: 0
     };
   }
-  const total = { x: 0, y: 0, width, height };
+  const total = { x: 0, y: 0, width, height: effectiveHeight };
   const isRadial = isAxislessMark2(spec.markType);
   const encoding = spec.encoding;
   const xAxisSuppressed = encoding.x?.axis === false;
@@ -19696,10 +19966,11 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     x: margins.left,
     y: margins.top,
     width: Math.max(0, width - margins.left - margins.right),
-    height: Math.max(0, height - margins.top - margins.bottom)
+    height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
   };
   const minDims = getMinChartDims(spec.display);
-  if ((chartArea.width < minDims.width || chartArea.height < minDims.height) && chromeMode !== "hidden") {
+  const chromeEatsPlot = chromeLayout !== "grow" && chrome.topHeight > height * PLOT_SHARE_MAX;
+  if ((chartArea.width < minDims.width || chartArea.height < minDims.height || chromeEatsPlot) && chromeMode !== "hidden") {
     const fallbackMode = chromeMode === "full" ? "compact" : "hidden";
     const fallbackChrome = computeChrome5(
       chromeToInput(spec.chrome),
@@ -19725,7 +19996,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         x: margins.left,
         y: margins.top,
         width: Math.max(0, width - margins.left - margins.right),
-        height: Math.max(0, height - margins.top - margins.bottom)
+        height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
       };
       const fallbackMetricsTopY = topPad + fallbackChrome.topHeight;
       const fallbackMetricsArea = { x: hPad, width: Math.max(0, width - hPad * 2) };
@@ -19742,7 +20013,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
         chartArea = {
           ...chartArea,
           y: margins.top,
-          height: Math.max(0, height - margins.top - margins.bottom)
+          height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
         };
       }
       return {
@@ -19758,7 +20029,8 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
           fallbackMetricsArea
         ) : void 0,
         xAxisHeight,
-        effectiveAxisGap: fallbackEffectiveAxisGap
+        effectiveAxisGap: fallbackEffectiveAxisGap,
+        chromeStripped: true
       };
     }
   }
@@ -19770,7 +20042,7 @@ function computeDimensions(spec, options, legendLayout, theme, strategy, waterma
     chartArea = {
       ...chartArea,
       y: margins.top,
-      height: Math.max(0, height - margins.top - margins.bottom)
+      height: Math.max(0, effectiveHeight - margins.top - margins.bottom)
     };
   }
   return {
@@ -20522,14 +20794,19 @@ function compileSankey(spec, options) {
     watermark
   );
   const padding = theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
+  const grownHeight = chromeLayout === "grow" ? options.height + chrome.topHeight + chrome.bottomHeight : options.height;
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
-    return emptyLayout4(fullArea, chrome, theme, options, watermark);
+    return emptyLayout4(fullArea, chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const sourceField = sankeySpec.encoding.source.field;
   const targetField = sankeySpec.encoding.target.field;
@@ -20569,7 +20846,7 @@ function compileSankey(spec, options) {
     height: fullArea.height - legend.bounds.height - legendGap2
   };
   if (area.height <= 0) {
-    return emptyLayout4(area, chrome, theme, options, watermark);
+    return emptyLayout4(area, chrome, theme, { ...options, height: grownHeight }, watermark);
   }
   const labelFontSize = theme.fonts.sizes.small;
   const labelFontWeight = theme.fonts.weights.normal;
@@ -20721,7 +20998,7 @@ function compileSankey(spec, options) {
     theme,
     dimensions: {
       width: options.width,
-      height: options.height
+      height: grownHeight
     },
     animation: resolvedAnimation,
     watermark,
@@ -21540,6 +21817,10 @@ var LEGEND_ENTRY_GAP = 16;
 function clamp(value2, min4, max4) {
   return Math.min(max4, Math.max(min4, value2));
 }
+function growContentHeight(contentHeight, chromeLayout, budgetHeight, chrome) {
+  if (chromeLayout !== "grow") return contentHeight;
+  return Math.max(contentHeight, budgetHeight + chrome.topHeight + chrome.bottomHeight);
+}
 function compileTileMap(spec, options) {
   const sugarWarnings = [];
   const expandedSpec = spec && typeof spec === "object" && !Array.isArray(spec) ? expandSpecSugar(spec, sugarWarnings) : spec;
@@ -21576,22 +21857,44 @@ function compileTileMap(spec, options) {
     watermark
   );
   const padding = getBreakpoint2(options.width) === "compact" ? Math.max(HPAD_COMPACT_MIN4, Math.round(theme.spacing.padding * HPAD_COMPACT_FRACTION4)) : theme.spacing.padding;
+  const chromeLayout = resolveChromeLayout(
+    spec,
+    options
+  );
   const fullArea = {
     x: padding,
     y: padding + chrome.topHeight,
     width: options.width - padding * 2,
-    height: options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
+    height: chromeLayout === "grow" ? options.height - padding * 2 : options.height - chrome.topHeight - chrome.bottomHeight - padding * 2
   };
   if (fullArea.width <= 0 || fullArea.height <= 0) {
     return emptyLayout5(chrome, theme, options, watermark);
   }
   const isCategorical = tilemapSpec.encoding.color !== void 0 || tilemapSpec.colors !== void 0;
   if (isCategorical) {
-    return compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark);
+    return compileCategorical(
+      tilemapSpec,
+      options,
+      theme,
+      chrome,
+      fullArea,
+      isDarkMode,
+      watermark,
+      chromeLayout
+    );
   }
-  return compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark);
+  return compileQuantitative(
+    tilemapSpec,
+    options,
+    theme,
+    chrome,
+    fullArea,
+    isDarkMode,
+    watermark,
+    chromeLayout
+  );
 }
-function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
+function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark, chromeLayout) {
   const stateField = tilemapSpec.encoding.state.field;
   const valueField = tilemapSpec.encoding.value.field;
   const stateValueMap = /* @__PURE__ */ new Map();
@@ -21692,7 +21995,12 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
   };
   const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
   const padding = fullArea.x;
-  const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
+  const contentHeight = growContentHeight(
+    tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding,
+    chromeLayout,
+    options.height,
+    chrome
+  );
   return {
     area: fullArea,
     chrome,
@@ -21709,7 +22017,7 @@ function compileQuantitative(tilemapSpec, options, theme, chrome, fullArea, isDa
     measureText: options.measureText ?? ((text, fontSize) => ({ width: estimateTextWidth23(text, fontSize), height: fontSize }))
   };
 }
-function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark) {
+function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDarkMode, watermark, chromeLayout) {
   const stateField = tilemapSpec.encoding.state.field;
   const colorField = tilemapSpec.encoding.color?.field ?? tilemapSpec.encoding.value.field;
   const stateCategoryMap = /* @__PURE__ */ new Map();
@@ -21828,7 +22136,12 @@ function compileCategorical(tilemapSpec, options, theme, chrome, fullArea, isDar
   };
   const resolvedAnimation = resolveAnimation(tilemapSpec.animation);
   const padding = fullArea.x;
-  const contentHeight = tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding;
+  const contentHeight = growContentHeight(
+    tileGridOffsetY + tilePositions.gridHeight + legendGap2 + legendTotalHeight + chrome.bottomHeight + padding,
+    chromeLayout,
+    options.height,
+    chrome
+  );
   return {
     area: fullArea,
     chrome,
@@ -23213,7 +23526,10 @@ function compileChart(spec, optionsInput) {
     skipY,
     markType: chartSpec.markType,
     totalWidth: options.width,
-    precomputedYTicks: plan.yTickValues.length > 0 ? plan.yTickValues : void 0
+    // If the guardrail stripped chrome, the plan's y-ticks were sized
+    // against the pre-strip (shorter) plot. Drop them so computeAxes
+    // regenerates against the final (taller) chartArea.
+    precomputedYTicks: !dims.chromeStripped && plan.yTickValues.length > 0 ? plan.yTickValues : void 0
   });
   const xAxisExtent = axes.x?.extent ?? 0;
   dims.chrome.bottomAnchorY = chartArea.y + chartArea.height + xAxisExtent;
@@ -23336,7 +23652,10 @@ function compileChart(spec, optionsInput) {
     theme,
     dimensions: {
       width: options.width,
-      height: options.height
+      // In chromeLayout 'grow' mode, computeDimensions grows total.height by the
+      // chrome height so the plot keeps its full budget. In the default
+      // 'subtract' mode total.height === options.height, so this is a no-op.
+      height: dims.total.height
     },
     animation: resolvedAnimation,
     watermark,
@@ -23669,6 +23988,7 @@ export {
   EXIT_DEFAULTS,
   UPDATE_DEFAULTS,
   buildAreaPath,
+  buildEdgeTooltip,
   buildLinePath,
   clampStaggerDelay,
   clearRenderers,