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

package/dist/index.js

@@ -10557,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,
@@ -10577,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) {
@@ -11606,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`,
@@ -11622,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`,
@@ -18925,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;
@@ -18964,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) {
@@ -18994,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) {
@@ -19009,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;
@@ -19037,6 +19150,7 @@ function resolveNodeVisuals(nodes, encoding, edges, theme, nodeOverrides) {
       label,
       labelPriority: finalLabelPriority,
       community: void 0,
+      opacity,
       data
     };
   });
@@ -19069,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] ?? ""));
@@ -19080,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";
   }
@@ -19141,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,
@@ -19156,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 = [];
@@ -19190,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) {
@@ -19216,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);
@@ -19225,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;
@@ -19250,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 = [
@@ -19273,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,
@@ -19312,7 +19556,12 @@ function compileGraph(spec, options) {
       height: options.height
     },
     simulationConfig,
-    watermark
+    watermark,
+    animation,
+    interaction,
+    legendField,
+    initialHighlight,
+    edgeLegend
   };
 }
 var DEFAULT_COLLISION_PADDING = 5;
@@ -23739,6 +23988,7 @@ export {
   EXIT_DEFAULTS,
   UPDATE_DEFAULTS,
   buildAreaPath,
+  buildEdgeTooltip,
   buildLinePath,
   clampStaggerDelay,
   clearRenderers,