polly-graph 0.1.2 → 0.1.4

package/dist/index.js

@@ -3671,41 +3671,44 @@ function y_default2(y3) {
 }
 
 // src/core/create-graph-layers.ts
-function createGraphLayers(svg) {
-  while (svg.firstChild) {
-    svg.removeChild(svg.firstChild);
-  }
-  const createGroup = (className) => {
+function createGraphLayers(host) {
+  host.innerHTML = "";
+  const rootContainer = document.createElement("div");
+  rootContainer.className = "pg-root";
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("class", "pg-canvas");
+  const overlay = document.createElement("div");
+  overlay.className = "pg-overlay";
+  rootContainer.appendChild(svg);
+  rootContainer.appendChild(overlay);
+  host.appendChild(rootContainer);
+  const createGroup = (layerName) => {
     const group = document.createElementNS("http://www.w3.org/2000/svg", "g");
-    group.setAttribute("class", className);
-    group.setAttribute("data-layer", className);
+    group.setAttribute("class", `pg-layer-${layerName}`);
+    group.setAttribute("data-layer", layerName);
     return group;
   };
   const interactionLayer = createGroup("interaction-layer");
   const interactionRect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
-  const interactionAttributes = {
-    class: "interaction-surface",
-    width: "100%",
-    height: "100%",
-    fill: "transparent",
-    "pointer-events": "all"
-  };
-  Object.entries(interactionAttributes).forEach(([key, value]) => {
-    interactionRect.setAttribute(key, value);
-  });
+  interactionRect.setAttribute("class", "pg-interaction-surface");
+  interactionRect.setAttribute("fill", "transparent");
+  interactionRect.setAttribute("pointer-events", "all");
   interactionLayer.appendChild(interactionRect);
-  const root2 = createGroup("knowledge-graph-root");
+  const graphRoot = createGroup("viewport");
   const layers = {
+    svg,
+    overlay,
     interactionLayer,
     interactionRect,
-    root: root2,
+    root: graphRoot,
+    // These keys now match your ctx.root.select('[data-layer="..."]') calls
     links: createGroup("links"),
     linkLabels: createGroup("link-labels"),
     nodeRings: createGroup("node-rings"),
     nodes: createGroup("nodes"),
     nodeLabels: createGroup("node-labels")
   };
-  root2.append(
+  graphRoot.append(
     layers.links,
     layers.linkLabels,
     layers.nodeRings,
@@ -3713,7 +3716,7 @@ function createGraphLayers(svg) {
     layers.nodeLabels
   );
   svg.appendChild(interactionLayer);
-  svg.appendChild(root2);
+  svg.appendChild(graphRoot);
   return layers;
 }
 
@@ -3783,6 +3786,171 @@ function createGraphSimulation(config) {
   return { simulation };
 }
 
+// src/controls/graph-controls.utils.ts
+function resolveControlsPosition(position) {
+  return position ?? "bottom-left";
+}
+function resolveControlsOrientation(orientation) {
+  return orientation ?? "vertical";
+}
+function shouldRenderControl(config, key) {
+  const show = config.show;
+  if (!show) {
+    return true;
+  }
+  const value = show[key];
+  if (value === void 0) {
+    return true;
+  }
+  return value;
+}
+
+// src/assets/plus.svg?raw
+var plus_default = '<svg\n  xmlns="http://www.w3.org/2000/svg"\n  viewBox="0 0 24 24"\n  fill="none"\n  stroke="currentColor"\n  stroke-width="2"\n  stroke-linecap="round"\n  stroke-linejoin="round"\n>\n  <path d="M5 12h14m-7-7v14" />\n</svg>';
+
+// src/assets/minus.svg?raw
+var minus_default = '<svg\n  xmlns="http://www.w3.org/2000/svg"\n  viewBox="0 0 24 24"\n  fill="none"\n  stroke="currentColor"\n  stroke-width="2"\n  stroke-linecap="round"\n  stroke-linejoin="round"\n>\n  <path d="M19 12H5" />\n</svg>';
+
+// src/assets/fit.svg?raw
+var fit_default = '<svg\n  xmlns="http://www.w3.org/2000/svg"\n  viewBox="0 0 24 24"\n  fill="none"\n  stroke="currentColor"\n  stroke-width="2"\n  stroke-linecap="round"\n  stroke-linejoin="round"\n>\n  <path d="M5 9V5H9" />\n  <path d="M19 9V5H15" />\n  <path d="M5 15V19H9" />\n  <path d="M19 15V19H15" />\n</svg>';
+
+// src/assets/reset.svg?raw
+var reset_default = '<svg\n  xmlns="http://www.w3.org/2000/svg"\n  viewBox="0 0 24 24"\n  fill="none"\n  stroke="currentColor"\n  stroke-width="2"\n  stroke-linecap="round"\n  stroke-linejoin="round"\n>\n  <path d="M20 12a8 8 0 1 1-2.3-5.7" />\n  <path d="M20 4.5v4h-4" />\n</svg>';
+
+// src/controls/graph-controls.icons.ts
+var ICON_MAP = {
+  "zoom-in": plus_default,
+  "zoom-out": minus_default,
+  fit: fit_default,
+  reset: reset_default
+};
+function getControlIcon(icon) {
+  const raw = ICON_MAP[icon];
+  if (!raw) {
+    throw new Error(`Icon not found: ${icon}`);
+  }
+  return raw.replace("<svg", '<svg class="pg-icon"');
+}
+
+// src/controls/create-graph-controls.ts
+function createGraphControls(overlay, graph, config) {
+  let root2 = null;
+  function mount() {
+    if (!config.enabled) {
+      return;
+    }
+    root2 = document.createElement("div");
+    root2.className = "pg-controls";
+    const position = resolveControlsPosition(config.position);
+    root2.classList.add(`pg-pos-${position}`);
+    const orientation = resolveControlsOrientation(config.orientation);
+    root2.classList.add(`pg-orient-${orientation}`);
+    if (config.offset) {
+      root2.style.setProperty("--pg-controls-offset-x", `${config.offset.x}px`);
+      root2.style.setProperty("--pg-controls-offset-y", `${config.offset.y}px`);
+    }
+    appendControls(root2, config, graph);
+    overlay.appendChild(root2);
+  }
+  function appendControls(root3, config2, graph2) {
+    const actions = [
+      { key: "zoomIn", icon: "zoom-in", label: "Zoom in", fn: graph2.zoomIn.bind(graph2) },
+      { key: "zoomOut", icon: "zoom-out", label: "Zoom out", fn: graph2.zoomOut.bind(graph2) },
+      { key: "fit", icon: "fit", label: "Fit view", fn: graph2.fitView.bind(graph2) },
+      { key: "reset", icon: "reset", label: "Reset view", fn: graph2.resetView.bind(graph2) }
+    ];
+    actions.forEach((action) => {
+      if (shouldRenderControl(config2, action.key)) {
+        root3.appendChild(createButton(action.icon, action.label, action.fn));
+      }
+    });
+  }
+  function createButton(type, label, onClick) {
+    const button = document.createElement("button");
+    button.className = "pg-control-btn";
+    button.type = "button";
+    button.setAttribute("aria-label", label);
+    const wrapper = document.createElement("div");
+    wrapper.className = "pg-icon-wrapper";
+    wrapper.innerHTML = getControlIcon(type);
+    const svg = wrapper.querySelector("svg");
+    if (svg) {
+      svg.classList.add("pg-icon");
+      button.appendChild(svg);
+    }
+    button.addEventListener("click", onClick);
+    return button;
+  }
+  function destroy() {
+    if (!root2) {
+      return;
+    }
+    if (root2.parentNode === overlay) {
+      overlay.removeChild(root2);
+    }
+    root2 = null;
+  }
+  return { mount, destroy };
+}
+
+// src/assets/caret.svg?raw
+var caret_default = '<svg\n  xmlns="http://www.w3.org/2000/svg"\n  viewBox="0 0 24 24"\n  fill="none"\n  stroke="currentColor"\n  stroke-width="2"\n  stroke-linecap="round"\n  stroke-linejoin="round"\n>\n  <path d="M9 20L16.5 12L9 4" />\n</svg>';
+
+// src/legends/graph-legend-icon.ts
+var LEGEND_ICON_MAP = { caret: caret_default };
+function getLegendIcon(icon) {
+  const raw = LEGEND_ICON_MAP[icon];
+  if (!raw) {
+    throw new Error(`Legend icon not found: ${icon}`);
+  }
+  return raw.replace("<svg", '<svg class="pg-icon"');
+}
+
+// src/legends/create-graph-legends.ts
+function createGraphLegend(overlay, config) {
+  const legendWrapper = document.createElement("div");
+  legendWrapper.className = "pg-legend";
+  const position = config.position || "bottom-right";
+  legendWrapper.classList.add(`pg-pos-${position}`);
+  if (config.defaultExpanded === false) {
+    legendWrapper.classList.add("pg-is-collapsed");
+  }
+  if (config.collapsible) {
+    const toggleBtn = document.createElement("button");
+    toggleBtn.className = "pg-legend-toggle";
+    toggleBtn.type = "button";
+    toggleBtn.innerHTML = getLegendIcon("caret");
+    toggleBtn.onclick = (e) => {
+      e.stopPropagation();
+      legendWrapper.classList.toggle("pg-is-collapsed");
+    };
+    legendWrapper.appendChild(toggleBtn);
+  }
+  const body = document.createElement("div");
+  body.className = "pg-legend-body";
+  const list = document.createElement("ul");
+  list.className = "pg-legend-list";
+  config.items.forEach((item) => {
+    const listItem = document.createElement("li");
+    listItem.className = "pg-legend-item";
+    const swatch = document.createElement("span");
+    swatch.className = `pg-legend-swatch is-${item.shape || "circle"}`;
+    swatch.style.backgroundColor = item.color;
+    const label = document.createElement("span");
+    label.className = "pg-legend-label";
+    label.innerText = item.label;
+    listItem.appendChild(swatch);
+    listItem.appendChild(label);
+    list.appendChild(listItem);
+  });
+  body.appendChild(list);
+  legendWrapper.appendChild(body);
+  overlay.appendChild(legendWrapper);
+  return () => {
+    if (legendWrapper.parentNode === overlay) overlay.removeChild(legendWrapper);
+  };
+}
+
 // src/utils/resolve-link-style.ts
 var DEFAULT_LINK_STYLE = {
   stroke: "#94a3b8",
@@ -4013,7 +4181,7 @@ function getLinkKey2(link) {
 }
 function renderLinkLabels(params, links) {
   const renderableLinks = createRenderableLinks2(params, links);
-  const labelSelection = params.root.select(".link-labels").selectAll(".link-label").data(renderableLinks, (item) => getLinkKey2(item.link)).join("g").attr("class", "link-label").attr("pointer-events", "auto").attr("cursor", "pointer");
+  const labelSelection = params.root.select('[data-layer="link-labels"]').selectAll(".link-label").data(renderableLinks, (item) => getLinkKey2(item.link)).join("g").attr("class", "link-label").attr("pointer-events", "auto").attr("cursor", "pointer");
   labelSelection.selectAll("rect").data((item) => [item]).join("rect").attr("rx", (item) => item.style.label.borderRadius).attr("ry", (item) => item.style.label.borderRadius).attr("height", (item) => item.style.label.height).attr("fill", (item) => item.style.label.backgroundFill).attr("stroke", (item) => item.style.label.borderColor).attr("stroke-width", (item) => item.style.label.borderWidth);
   labelSelection.selectAll("text").data((item) => [item]).join("text").attr("text-anchor", "middle").attr("dominant-baseline", "middle").attr("font-size", (item) => item.style.label.fontSize).attr("fill", (item) => item.style.label.textColor).text((item) => item.link.label ?? "");
   return labelSelection;
@@ -4298,10 +4466,11 @@ function observeResize(element, onResize) {
       if (!entry) {
         return;
       }
-      onResize(
-        entry.contentRect.width,
-        entry.contentRect.height
-      );
+      const width = entry.borderBoxSize?.[0]?.inlineSize ?? entry.contentRect.width;
+      const height = entry.borderBoxSize?.[0]?.blockSize ?? entry.contentRect.height;
+      if (width > 0 && height > 0) {
+        onResize(width, height);
+      }
     }
   );
   observer.observe(element);
@@ -4334,53 +4503,85 @@ function getLinkTargetPoint(link) {
   };
 }
 
+// src/utils/export-graph.ts
+import html2canvas from "html2canvas";
+async function captureAndDownloadGraph(container, options = {}) {
+  const {
+    fileName = `graph-export-${Date.now()}.png`,
+    backgroundColor = "#ffffff",
+    pixelRatio = 2
+  } = options;
+  const root2 = container.querySelector(".pg-root");
+  if (!root2) return;
+  const controls = root2.querySelector(".pg-controls");
+  const legendToggle = root2.querySelector(".pg-legend-toggle");
+  const interactionLayer = root2.querySelector(".pg-interaction-layer");
+  const legend = root2.querySelector(".pg-legend");
+  const wasCollapsed = legend?.classList.contains("pg-is-collapsed");
+  if (controls) controls.style.display = "none";
+  if (legendToggle) legendToggle.style.display = "none";
+  if (interactionLayer) interactionLayer.style.display = "none";
+  if (legend && wasCollapsed) {
+    legend.classList.remove("pg-is-collapsed");
+  }
+  try {
+    const canvas = await html2canvas(root2, {
+      scale: pixelRatio,
+      backgroundColor,
+      useCORS: true,
+      logging: false
+    });
+    const dataUrl = canvas.toDataURL("image/png");
+    const link = document.createElement("a");
+    link.download = fileName;
+    link.href = dataUrl;
+    link.click();
+  } finally {
+    if (controls) controls.style.display = "flex";
+    if (legendToggle) legendToggle.style.display = "flex";
+    if (interactionLayer) interactionLayer.style.display = "block";
+    if (legend && wasCollapsed) {
+      legend.classList.add("pg-is-collapsed");
+    }
+  }
+}
+
 // src/create-graph.ts
 function createGraph(config) {
   let cleanupResize = null;
   let cleanupZoom = null;
   let tooltipBinding = null;
+  let controls = null;
+  let legendCleanup = null;
   let dimensions = { width: 0, height: 0 };
   let rootGroup = null;
+  let svgElement = null;
   let zoomBehavior = null;
   let simulation = null;
   function render() {
     destroy();
     const layers = createGraphLayers(config.container);
+    svgElement = layers.svg;
     rootGroup = layers.root;
-    cleanupResize = observeResize(
-      config.container,
-      (width, height) => {
-        dimensions = { width, height };
-        layers.interactionRect.setAttribute("width", String(width));
-        layers.interactionRect.setAttribute("height", String(height));
-        simulation?.force("x", x_default2(width / 2).strength(0.03));
-        simulation?.force("y", y_default2(height / 2).strength(0.03));
-        simulation?.alpha(0.25).restart();
-      }
-    );
+    cleanupResize = observeResize(config.container, (width, height) => {
+      dimensions = { width, height };
+      layers.svg.setAttribute("width", String(width));
+      layers.svg.setAttribute("height", String(height));
+      layers.interactionRect.setAttribute("width", String(width));
+      layers.interactionRect.setAttribute("height", String(height));
+      simulation?.force("x", x_default2(width / 2).strength(0.03));
+      simulation?.force("y", y_default2(height / 2).strength(0.03));
+      simulation?.alpha(0.25).restart();
+    });
     const zoomResult = createZoom({
-      /**
-       * D3 zoom must be attached to SVG
-       * because it requires:
-       *
-       * width.baseVal
-       * height.baseVal
-       */
-      svg: config.container,
-      /**
-       * Used for pointer semantics /
-       * pan filtering only
-       */
+      svg: layers.svg,
       interactionLayer: layers.interactionLayer,
-      /**
-       * Actual graph transform target
-       */
       root: layers.root
     });
     zoomBehavior = zoomResult.behavior;
     cleanupZoom = zoomResult.cleanup;
     const root2 = select_default2(layers.root);
-    const renderContext = { svg: config.container, root: root2, interaction: config.interaction };
+    const renderContext = { svg: layers.svg, root: root2, interaction: config.interaction };
     const linkSelection = renderLinks(renderContext, config.links);
     const linkLabelSelection = renderLinkLabels(renderContext, config.links);
     const nodeSelection = renderNodes(renderContext, config.nodes);
@@ -4393,40 +4594,35 @@ function createGraph(config) {
     };
     const simulationResult = createGraphSimulation(simulationConfig);
     simulation = simulationResult.simulation;
-    simulation.on(
-      "tick",
-      () => {
-        linkSelection.attr("x1", (item) => item.link.source.x ?? 0).attr("y1", (item) => item.link.source.y ?? 0).attr("x2", (item) => getShortenedTargetPoint(item.link, item.style).x).attr("y2", (item) => getShortenedTargetPoint(item.link, item.style).y);
-        linkLabelSelection.attr("transform", (item) => {
-          const link = item.link;
-          const source = link.source;
-          const targetPoint = getLinkTargetPoint(link);
-          const x3 = ((source.x ?? 0) + targetPoint.x) / 2;
-          const y3 = ((source.y ?? 0) + targetPoint.y) / 2;
-          return `translate(${x3}, ${y3})`;
-        }).each(function() {
-          const group = this;
-          const text = group.querySelector("text");
-          const rect = group.querySelector("rect");
-          if (!text || !rect) {
-            return;
-          }
-          const bBox = text.getBBox();
-          const padding = 6;
-          rect.setAttribute("x", String(bBox.x - padding));
-          rect.setAttribute("y", String(bBox.y - padding));
-          rect.setAttribute("width", String(bBox.width + padding * 2));
-          rect.setAttribute("height", String(bBox.height + padding * 2));
-        });
-        nodeSelection.attr("cx", (d) => d.x ?? 0).attr("cy", (d) => d.y ?? 0);
-        labelSelection.attr("x", (d) => d.x ?? 0).attr("y", (d) => d.y ?? 0);
-        tooltipBinding?.reposition();
-      }
-    );
+    simulation.on("tick", () => {
+      linkSelection.attr("x1", (item) => item.link.source.x ?? 0).attr("y1", (item) => item.link.source.y ?? 0).attr("x2", (item) => getShortenedTargetPoint(item.link, item.style).x).attr("y2", (item) => getShortenedTargetPoint(item.link, item.style).y);
+      linkLabelSelection.attr("transform", (item) => {
+        const link = item.link;
+        const source = link.source;
+        const targetPoint = getLinkTargetPoint(link);
+        const x3 = ((source.x ?? 0) + targetPoint.x) / 2;
+        const y3 = ((source.y ?? 0) + targetPoint.y) / 2;
+        return `translate(${x3}, ${y3})`;
+      }).each(function() {
+        const group = this;
+        const text = group.querySelector("text");
+        const rect = group.querySelector("rect");
+        if (!text || !rect) return;
+        const bBox = text.getBBox();
+        const padding = 6;
+        rect.setAttribute("x", String(bBox.x - padding));
+        rect.setAttribute("y", String(bBox.y - padding));
+        rect.setAttribute("width", String(bBox.width + padding * 2));
+        rect.setAttribute("height", String(bBox.height + padding * 2));
+      });
+      nodeSelection.attr("cx", (d) => d.x ?? 0).attr("cy", (d) => d.y ?? 0);
+      labelSelection.attr("x", (d) => d.x ?? 0).attr("y", (d) => d.y ?? 0);
+      tooltipBinding?.reposition();
+    });
     if (config.interaction?.hover?.enabled) {
       if (config.interaction?.hover?.tooltip?.enabled) {
         tooltipBinding = bindNodeTooltip({
-          container: config.container.parentElement,
+          container: config.container,
           selection: nodeSelection,
           tooltipConfig: config.interaction.hover.tooltip
         });
@@ -4436,60 +4632,47 @@ function createGraph(config) {
     if (config.interaction?.drag?.enabled !== false) {
       nodeSelection.call(createDragBehavior(simulation));
     }
-    if (config.interaction?.selection?.enabled) {
+    if (config.controls?.enabled) {
+      controls = createGraphControls(
+        layers.overlay,
+        { zoomIn, zoomOut, resetView, fitView, destroy, render, exportGraph },
+        config.controls
+      );
+      controls.mount();
+    }
+    if (config.legend?.enabled) {
+      legendCleanup = createGraphLegend(layers.overlay, config.legend);
     }
   }
   function resetView() {
-    if (!zoomBehavior) {
-      return;
-    }
-    select_default2(config.container).transition().call(
-      zoomBehavior.transform,
-      identity2
-    );
+    if (!zoomBehavior || !svgElement) return;
+    select_default2(svgElement).transition().call(zoomBehavior.transform, identity2);
   }
   function fitView() {
-    if (!zoomBehavior || !rootGroup || dimensions.width === 0 || dimensions.height === 0) {
-      return;
-    }
+    if (!zoomBehavior || !rootGroup || !svgElement || dimensions.width === 0 || dimensions.height === 0) return;
     const bounds = rootGroup.getBBox();
-    if (bounds.width === 0 || bounds.height === 0) {
-      return;
-    }
-    const width = dimensions.width;
-    const height = dimensions.height;
-    const scale = Math.min(
-      width / bounds.width,
-      height / bounds.height
-    ) * 0.9;
-    const translateX = (width - bounds.width * scale) / 2 - bounds.x * scale;
-    const translateY = (height - bounds.height * scale) / 2 - bounds.y * scale;
-    const transform2 = identity2.translate(
-      translateX,
-      translateY
-    ).scale(scale);
-    select_default2(config.container).transition().call(
-      zoomBehavior.transform,
-      transform2
-    );
+    if (bounds.width === 0 || bounds.height === 0) return;
+    const scale = Math.min(dimensions.width / bounds.width, dimensions.height / bounds.height) * 0.9;
+    const translateX = (dimensions.width - bounds.width * scale) / 2 - bounds.x * scale;
+    const translateY = (dimensions.height - bounds.height * scale) / 2 - bounds.y * scale;
+    const transform2 = identity2.translate(translateX, translateY).scale(scale);
+    select_default2(svgElement).transition().call(zoomBehavior.transform, transform2);
   }
   function zoomIn() {
-    if (!zoomBehavior) {
-      return;
-    }
-    select_default2(config.container).transition().call(
-      zoomBehavior.scaleBy,
-      1.2
-    );
+    if (!zoomBehavior || !svgElement) return;
+    select_default2(svgElement).transition().call(zoomBehavior.scaleBy, 1.2);
   }
   function zoomOut() {
-    if (!zoomBehavior) {
-      return;
-    }
-    select_default2(config.container).transition().call(
-      zoomBehavior.scaleBy,
-      0.8
-    );
+    if (!zoomBehavior || !svgElement) return;
+    select_default2(svgElement).transition().call(zoomBehavior.scaleBy, 0.8);
+  }
+  async function exportGraph(fileName) {
+    fitView();
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    await captureAndDownloadGraph(config.container, {
+      fileName,
+      pixelRatio: 2
+    });
   }
   function destroy() {
     if (cleanupResize) {
@@ -4508,13 +4691,22 @@ function createGraph(config) {
       simulation.stop();
       simulation = null;
     }
+    if (controls) {
+      controls.destroy();
+      controls = null;
+    }
+    if (legendCleanup) {
+      legendCleanup();
+      legendCleanup = null;
+    }
     rootGroup = null;
+    svgElement = null;
     zoomBehavior = null;
     while (config.container.firstChild) {
       config.container.removeChild(config.container.firstChild);
     }
   }
-  return { render, zoomIn, zoomOut, resetView, fitView, destroy };
+  return { render, zoomIn, zoomOut, resetView, fitView, destroy, exportGraph };
 }
 export {
   createGraph

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polly-graph",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Reusable D3-based graph visualization SDK with configurable nodes, links, labels, interactions, and layout behaviors.",
   "license": "MIT",
   "author": "Badal",
@@ -47,15 +47,16 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --watch --format esm,cjs --dts",
+    "build": "tsup",
+    "dev": "tsup",
     "lint": "eslint \"src/**/*.ts\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests",
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
-    "d3": "7.9.0"
+    "d3": "7.9.0",
+    "html2canvas": "^1.4.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",