npm - @falkordb/canvas - Versions diffs - 0.0.3 - Mend

@falkordb/canvas 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE +21 -0
package/README.md +189 -0
package/package.json +52 -0
package/src/falkordb-canvas-types.ts +90 -0
package/src/falkordb-canvas-utils.ts +201 -0
package/src/falkordb-canvas.ts +786 -0
package/src/index.ts +43 -0

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 FalkorDB
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,189 @@
+# FalkorDB Canvas
+A standalone web component for visualizing FalkorDB graphs using force-directed layouts.
+## Features
+- 🎨 **Force-directed graph layout** - Automatic positioning using D3 force simulation
+- 🎯 **Interactive** - Click, hover, and right-click interactions
+- 🌓 **Theme support** - Light and dark mode compatible
+- ⚡ **Performance** - Optimized rendering with canvas
+- 💀 **Loading states** - Built-in skeleton loading with pulse animation
+- 🎨 **Customizable** - Colors, sizes, and behaviors
+## Installation
+```bash
+npm install falkordb-canvas
+```
+## Quick Start
+### HTML
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>FalkorDB Canvas Example</title>
+</head>
+<body>
+  <falkordb-canvas id="graph" style="width: 100%; height: 600px;"></falkordb-canvas>
+  <script type="module">
+    import 'falkordb-canvas';
+    const canvas = document.getElementById('graph');
+    // Set data
+    canvas.setData({
+      nodes: [
+        { id: 1, labels: ['Person'], color: '#FF6B6B', visible: true, data: { name: 'Alice' } },
+        { id: 2, labels: ['Person'], color: '#4ECDC4', visible: true, data: { name: 'Bob' } }
+      ],
+      links: [
+        { id: 1, relationship: 'KNOWS', color: '#999', source: 1, target: 2, visible: true, data: {} }
+      ]
+    });
+    // Configure
+    canvas.setConfig({
+      width: 800,
+      height: 600,
+      backgroundColor: '#FFFFFF',
+      foregroundColor: '#1A1A1A',
+      onNodeClick: (node) => console.log('Clicked:', node)
+    });
+  </script>
+</body>
+</html>
+```
+## API
+### Methods
+#### `setData(data: Data)`
+Set the graph data (nodes and links).
+```typescript
+canvas.setData({
+  nodes: [
+    { id: 1, labels: ['Person'], color: '#FF6B6B', visible: true, data: { name: 'Alice' } }
+  ],
+  links: [
+    { id: 1, relationship: 'KNOWS', color: '#999', source: 1, target: 2, visible: true, data: {} }
+  ]
+});
+```
+#### `getData(): Data`
+Get the current graph data.
+#### `setConfig(config: ForceGraphConfig)`
+Configure the graph visualization and behavior.
+```typescript
+canvas.setConfig({
+  width: 800,
+  height: 600,
+  backgroundColor: '#FFFFFF',
+  foregroundColor: '#1A1A1A',
+  displayTextPriority: [
+    { name: 'name', ignore: false },
+    { name: 'title', ignore: false }
+  ],
+  cooldownTicks: 300,
+  isLoading: false,
+  onNodeClick: (node, event) => {},
+  onNodeRightClick: (node, event) => {},
+  onLinkRightClick: (link, event) => {},
+  onNodeHover: (node) => {},
+  onLinkHover: (link) => {},
+  onBackgroundClick: (event) => {},
+  onEngineStop: () => {},
+  isNodeSelected: (node) => false,
+  isLinkSelected: (link) => false
+});
+```
+#### `getGraph(): ForceGraphInstance | undefined`
+Get the underlying force-graph instance for advanced control.
+### Configuration Options
+| Option | Type | Description |
+|--------|------|-------------|
+| `width` | `number` | Canvas width in pixels |
+| `height` | `number` | Canvas height in pixels |
+| `backgroundColor` | `string` | Background color (hex or CSS color) |
+| `foregroundColor` | `string` | Foreground color for borders and text |
+| `displayTextPriority` | `TextPriority[]` | Priority order for displaying node text |
+| `cooldownTicks` | `number \| undefined` | Number of simulation ticks before stopping |
+| `isLoading` | `boolean` | Show/hide loading skeleton |
+| `onNodeClick` | `function` | Callback when a node is clicked |
+| `onNodeRightClick` | `function` | Callback when a node is right-clicked |
+| `onLinkRightClick` | `function` | Callback when a link is right-clicked |
+| `onNodeHover` | `function` | Callback when hovering over a node |
+| `onLinkHover` | `function` | Callback when hovering over a link |
+| `onBackgroundClick` | `function` | Callback when clicking the background |
+| `onEngineStop` | `function` | Callback when the force simulation stops |
+| `isNodeSelected` | `function` | Function to determine if a node is selected |
+| `isLinkSelected` | `function` | Function to determine if a link is selected |
+### Data Types
+#### Node
+```typescript
+{
+  id: number;
+  labels: string[];
+  color: string;
+  visible: boolean;
+  data: Record<string, any>;
+}
+```
+#### Link
+```typescript
+{
+  id: number;
+  relationship: string;
+  color: string;
+  source: number;  // Node ID
+  target: number;  // Node ID
+  visible: boolean;
+  data: Record<string, any>;
+}
+```
+## Development
+```bash
+# Install dependencies
+npm install
+# Build
+npm run build
+# Watch mode
+npm run dev
+# Run example
+npm run example
+# Then open http://localhost:8080/examples/falkordb-canvas.example.html
+```
+## Browser Support
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+## License
+MIT
+## Contributing
+Contributions are welcome! Please feel free to submit a Pull Request.

package/package.json ADDED Viewed

@@ -0,0 +1,52 @@
+{
+  "name": "@falkordb/canvas",
+  "version": "0.0.3",
+  "description": "A standalone web component for visualizing FalkorDB graphs using force-directed layouts",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist",
+    "dev": "tsc --watch",
+    "example": "python3 -m http.server 8080",
+    "clean": "rm -rf dist",
+    "lint": "eslint ."
+  },
+  "keywords": [
+    "falkordb",
+    "graph",
+    "visualization",
+    "web-component",
+    "force-directed",
+    "canvas"
+  ],
+  "author": "FalkorDB",
+  "license": "MIT",
+  "dependencies": {
+    "@types/react": "^19.2.7",
+    "d3": "^7.9.0",
+    "force-graph": "^1.44.4",
+    "react": "^19.2.3"
+  },
+  "devDependencies": {
+    "@types/d3": "^7.4.3",
+    "@typescript-eslint/eslint-plugin": "^8.18.2",
+    "@typescript-eslint/parser": "^8.18.2",
+    "eslint": "^9.17.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}

package/src/falkordb-canvas-types.ts ADDED Viewed

@@ -0,0 +1,90 @@
+import { NodeObject } from "force-graph";
+export interface ForceGraphConfig {
+  width?: number;
+  height?: number;
+  backgroundColor?: string;
+  foregroundColor?: string;
+  displayTextPriority?: TextPriority[];
+  onNodeClick?: (node: GraphNode, event: MouseEvent) => void;
+  onLinkClick?: (link: GraphLink, event: MouseEvent) => void;
+  onNodeRightClick?: (node: GraphNode, event: MouseEvent) => void;
+  onLinkRightClick?: (link: GraphLink, event: MouseEvent) => void;
+  onNodeHover?: (node: GraphNode | null) => void;
+  onLinkHover?: (link: GraphLink | null) => void;
+  onBackgroundClick?: (event: MouseEvent) => void;
+  onEngineStop?: () => void;
+  onLoadingChange?: (loading: boolean) => void;
+  cooldownTicks?: number | undefined;
+  cooldownTime?: number;
+  isLinkSelected?: (link: GraphLink) => boolean;
+  isNodeSelected?: (node: GraphNode) => boolean;
+  isLoading?: boolean;
+}
+export type GraphNode = NodeObject & {
+  id: number;
+  labels: string[];
+  color: string;
+  visible: boolean;
+  displayName: [string, string];
+  data: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+  };
+  x?: number;
+  y?: number;
+  vx?: number;
+  vy?: number;
+  fx?: number;
+  fy?: number;
+};
+export type GraphLink = {
+  id: number;
+  relationship: string;
+  color: string;
+  source: GraphNode;
+  target: GraphNode;
+  visible: boolean;
+  curve: number;
+  data: {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    [key: string]: any;
+  };
+};
+export interface GraphData {
+  nodes: GraphNode[];
+  links: GraphLink[];
+}
+export type Node = Omit<
+  GraphNode,
+  "x" | "y" | "vx" | "vy" | "fx" | "fy" | "displayName"
+>;
+export type Link = Omit<GraphLink, "curve" | "source" | "target"> & {
+  source: number;
+  target: number;
+};
+export interface Data {
+  nodes: Node[];
+  links: Link[];
+}
+export type TextPriority = {
+  name: string;
+  ignore: boolean;
+};
+export type ViewportState = {
+  zoom: number;
+  centerX: number;
+  centerY: number;
+} | undefined;
+// Force graph instance type from force-graph library
+// The instance is created by calling ForceGraph as a function with a container element
+export type ForceGraphInstance = import("force-graph").default<GraphNode, GraphLink> | undefined;

package/src/falkordb-canvas-utils.ts ADDED Viewed

@@ -0,0 +1,201 @@
+import {
+  Data,
+  GraphData,
+  Node,
+  Link,
+  GraphNode,
+  GraphLink,
+  TextPriority,
+} from "./falkordb-canvas-types.js";
+/**
+ * Converts Data format to GraphData format
+ * Adds runtime properties (x, y, vx, vy, fx, fy, displayName, curve)
+ */
+export function dataToGraphData(data: Data): GraphData {
+  const nodes: GraphNode[] = data.nodes.map((node) => ({
+    ...node,
+    displayName: ["", ""] as [string, string],
+    x: undefined,
+    y: undefined,
+    vx: undefined,
+    vy: undefined,
+    fx: undefined,
+    fy: undefined,
+  }));
+  // Create a Map for O(1) node lookups by id
+  const nodeMap = new Map<number, GraphNode>();
+  nodes.forEach((node) => {
+    nodeMap.set(node.id, node);
+  });
+  const links: GraphLink[] = data.links.map((link) => {
+    const sourceNode = nodeMap.get(link.source);
+    const targetNode = nodeMap.get(link.target);
+    return {
+      ...link,
+      source: sourceNode!,
+      target: targetNode!,
+      curve: 0,
+    };
+  });
+  return { nodes, links };
+}
+/**
+ * Converts GraphData format to Data format
+ * Removes runtime properties (x, y, vx, vy, fx, fy, displayName, curve)
+ */
+export function graphDataToData(graphData: GraphData): Data {
+  const nodes: Node[] = graphData.nodes.map((node) => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { x, y, vx, vy, fx, fy, displayName, ...rest } = node;
+    return rest;
+  });
+  const links: Link[] = graphData.links.map((link) => {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { curve, source, target, ...rest } = link;
+    return {
+      ...rest,
+      source: source.id,
+      target: target.id,
+    };
+  });
+  return { nodes, links };
+}
+export const getNodeDisplayText = (
+  node: Node,
+  displayTextPriority: TextPriority[]
+) => {
+  const { data: nodeData } = node;
+  const displayText = displayTextPriority.find(({ name, ignore }) => {
+    const key = ignore
+      ? Object.keys(nodeData).find(
+        (k) => k.toLowerCase() === name.toLowerCase()
+      )
+      : name;
+    return (
+      key &&
+      nodeData[key] &&
+      typeof nodeData[key] === "string" &&
+      nodeData[key].trim().length > 0
+    );
+  });
+  if (displayText) {
+    const key = displayText.ignore
+      ? Object.keys(nodeData).find(
+        (k) => k.toLowerCase() === displayText.name.toLowerCase()
+      )
+      : displayText.name;
+    if (key) {
+      return String(nodeData[key]);
+    }
+  }
+  return String(node.id);
+};
+export const getNodeDisplayKey = (
+  node: Node,
+  displayTextPriority: TextPriority[]
+) => {
+  const { data: nodeData } = node;
+  const displayText = displayTextPriority.find(({ name, ignore }) => {
+    const key = ignore
+      ? Object.keys(nodeData).find(
+        (k) => k.toLowerCase() === name.toLowerCase()
+      )
+      : name;
+    return (
+      key &&
+      nodeData[key] &&
+      typeof nodeData[key] === "string" &&
+      nodeData[key].trim().length > 0
+    );
+  });
+  if (displayText) {
+    const key = displayText.ignore
+      ? Object.keys(nodeData).find(
+        (k) => k.toLowerCase() === displayText.name.toLowerCase()
+      )
+      : displayText.name;
+    if (key) {
+      return key;
+    }
+  }
+  return String(node.id);
+};
+/**
+ * Wraps text into two lines with ellipsis handling for circular nodes
+ */
+export const wrapTextForCircularNode = (
+  ctx: CanvasRenderingContext2D,
+  text: string,
+  maxRadius: number
+): [string, string] => {
+  const ellipsis = "...";
+  const ellipsisWidth = ctx.measureText(ellipsis).width;
+  const halfTextHeight = 1.125;
+  const availableRadius = Math.sqrt(
+    Math.max(0, maxRadius * maxRadius - halfTextHeight * halfTextHeight)
+  );
+  const lineWidth = availableRadius * 2;
+  const words = text.split(/\s+/);
+  let line1 = "";
+  let line2 = "";
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    const testLine = line1 ? `${line1} ${word}` : word;
+    const testWidth = ctx.measureText(testLine).width;
+    if (testWidth <= lineWidth) {
+      line1 = testLine;
+    } else if (!line1) {
+      let partialWord = word;
+      while (
+        partialWord.length > 0 &&
+        ctx.measureText(partialWord).width > lineWidth
+      ) {
+        partialWord = partialWord.slice(0, -1);
+      }
+      line1 = partialWord;
+      const remainingWords = [
+        word.slice(partialWord.length),
+        ...words.slice(i + 1),
+      ];
+      line2 = remainingWords.join(" ");
+      break;
+    } else {
+      line2 = words.slice(i).join(" ");
+      break;
+    }
+  }
+  if (line2 && ctx.measureText(line2).width > lineWidth) {
+    while (
+      line2.length > 0 &&
+      ctx.measureText(line2).width + ellipsisWidth > lineWidth
+    ) {
+      line2 = line2.slice(0, -1);
+    }
+    line2 += ellipsis;
+  }
+  return [line1, line2 || ""];
+};

package/src/falkordb-canvas.ts ADDED Viewed

@@ -0,0 +1,786 @@
+/* eslint-disable no-param-reassign */
+import ForceGraph from "force-graph";
+import * as d3 from "d3";
+import {
+  Data,
+  ForceGraphInstance,
+  GraphData,
+  GraphLink,
+  GraphNode,
+  ForceGraphConfig,
+  ViewportState,
+} from "./falkordb-canvas-types.js";
+import {
+  dataToGraphData,
+  getNodeDisplayText,
+  graphDataToData,
+  wrapTextForCircularNode,
+} from "./falkordb-canvas-utils.js";
+const NODE_SIZE = 6;
+const PADDING = 2;
+// Force constants
+const LINK_DISTANCE = 50;
+const MAX_LINK_DISTANCE = 80;
+const LINK_STRENGTH = 0.5;
+const MIN_LINK_STRENGTH = 0.3;
+const COLLISION_STRENGTH = 1.35;
+const CHARGE_STRENGTH = -5;
+const CENTER_STRENGTH = 0.4;
+const COLLISION_BASE_RADIUS = NODE_SIZE * 2;
+const HIGH_DEGREE_PADDING = 1.25;
+const DEGREE_STRENGTH_DECAY = 15;
+const CROWDING_THRESHOLD = 20;
+// Create styles for the web component
+function createStyles(): HTMLStyleElement {
+  const style = document.createElement("style");
+  style.textContent = `
+    :host {
+      display: block;
+      width: 100%;
+      height: 100%;
+    }
+    @keyframes pulse {
+      0%, 100% {
+        opacity: 1;
+      }
+      50% {
+        opacity: 0.5;
+      }
+    }
+  `;
+  return style;
+}
+class FalkorDBCanvas extends HTMLElement {
+  private graph: ForceGraphInstance;
+  private container: HTMLDivElement | null = null;
+  private loadingOverlay: HTMLDivElement | null = null;
+  private data: GraphData = { nodes: [], links: [] };
+  private config: ForceGraphConfig = {};
+  private nodeDegreeMap: Map<number, number> = new Map();
+  private relationshipsTextCache: Map<
+    string,
+    {
+      textWidth: number;
+      textHeight: number;
+      textAscent: number;
+      textDescent: number;
+    }
+  > = new Map();
+  private viewport: ViewportState;
+  constructor() {
+    super();
+    this.attachShadow({ mode: "open" });
+  }
+  connectedCallback() {
+    this.render();
+  }
+  disconnectedCallback() {
+    if (this.graph) {
+      // eslint-disable-next-line no-underscore-dangle
+      this.graph._destructor();
+    }
+  }
+  setConfig(config: Partial<ForceGraphConfig>) {
+    Object.assign(this.config, config);
+    // Update event handlers if they were provided
+    if (config.onNodeClick || config.onNodeRightClick || config.onLinkRightClick ||
+      config.onNodeHover || config.onLinkHover || config.onBackgroundClick ||
+      config.onEngineStop || config.isNodeSelected || config.isLinkSelected) {
+      this.updateEventHandlers();
+    }
+  }
+  setWidth(width: number) {
+    if (this.config.width === width) return;
+    this.config.width = width;
+    if (this.graph) {
+      this.graph.width(width);
+    }
+  }
+  setHeight(height: number) {
+    if (this.config.height === height) return;
+    this.config.height = height;
+    if (this.graph) {
+      this.graph.height(height);
+    }
+  }
+  setBackgroundColor(color: string) {
+    if (this.config.backgroundColor === color) return;
+    this.config.backgroundColor = color;
+    if (this.graph) {
+      this.graph.backgroundColor(color);
+    }
+    if (this.loadingOverlay) {
+      this.loadingOverlay.style.background = color;
+    }
+  }
+  setForegroundColor(color: string) {
+    if (this.config.foregroundColor === color) return;
+    this.config.foregroundColor = color;
+    this.triggerRender();
+  }
+  setIsLoading(isLoading: boolean) {
+    if (this.config.isLoading === isLoading) return;
+    this.config.isLoading = isLoading;
+    this.updateLoadingState();
+  }
+  setCooldownTicks(ticks: number | undefined) {
+    if (this.config.cooldownTicks === ticks) return;
+    this.config.cooldownTicks = ticks;
+    if (this.graph) {
+      this.graph.cooldownTicks(ticks ?? Infinity);
+    }
+  }
+  setDisplayTextPriority(priority: ForceGraphConfig['displayTextPriority']) {
+    this.config.displayTextPriority = priority;
+    this.triggerRender();
+  }
+  getData(): Data {
+    return graphDataToData(this.data);
+  }
+  setData(data: Data) {
+    this.data = dataToGraphData(data);
+    this.config.cooldownTicks = this.data.nodes.length > 0 ? undefined : 0;
+    this.config.isLoading = this.data.nodes.length > 0;
+    this.config.onLoadingChange?.(this.config.isLoading);
+    // Initialize graph if it hasn't been initialized yet
+    if (!this.graph && this.container) {
+      this.initGraph();
+    }
+    if (!this.graph) return;
+    this.calculateNodeDegree();
+    // Update graph data and properties
+    this.graph
+      .graphData(this.data)
+      .cooldownTicks(this.config.cooldownTicks ?? Infinity);
+    this.updateLoadingState();
+    this.setupForces();
+  }
+  getViewport(): ViewportState {
+    if (!this.graph) return undefined;
+    const { x: centerX, y: centerY } = this.graph.centerAt();
+    const zoom = this.graph.zoom();
+    return {
+      zoom,
+      centerX,
+      centerY,
+    };
+  }
+  setViewport(viewport: ViewportState) {
+    this.viewport = viewport;
+  }
+  getGraphData(): GraphData {
+    return this.data;
+  }
+  setGraphData(data: GraphData) {
+    this.data = data;
+    this.config.cooldownTicks = 0;
+    this.config.isLoading = false;
+    if (!this.graph) return;
+    this.calculateNodeDegree();
+    this.graph
+      .graphData(this.data)
+      .cooldownTicks(this.config.cooldownTicks ?? Infinity);
+    if (this.viewport) {
+      this.graph.zoom(this.viewport.zoom, 0);
+      this.graph.centerAt(this.viewport.centerX, this.viewport.centerY, 0);
+      this.viewport = undefined;
+    }
+    this.updateLoadingState();
+    this.setupForces();
+  }
+  getGraph(): ForceGraphInstance | undefined {
+    return this.graph;
+  }
+  public getZoom(): number {
+    return this.graph?.zoom() || 0;
+  }
+  public zoom(zoomLevel: number): ForceGraphInstance | undefined {
+    if (!this.graph) return;
+    return this.graph.zoom(zoomLevel);
+  }
+  public zoomToFit(paddingMultiplier = 1, filter?: (node: GraphNode) => boolean) {
+    if (!this.graph || !this.shadowRoot) return;
+    // Get canvas from shadow DOM
+    const canvas = this.shadowRoot.querySelector("canvas") as HTMLCanvasElement;
+    if (!canvas) return;
+    const rect = canvas.getBoundingClientRect();
+    // Calculate padding as 10% of the smallest canvas dimension
+    const minDimension = Math.min(rect.width, rect.height);
+    const padding = minDimension * 0.1;
+    // Use the force-graph's built-in zoomToFit method
+    this.graph.zoomToFit(500, padding * paddingMultiplier, filter);
+  }
+  private triggerRender() {
+    if (!this.graph || this.graph.cooldownTicks() !== 0) return;
+    // If simulation is stopped (0), trigger one tick to re-render
+    this.graph.cooldownTicks(1);
+  }
+  private calculateNodeDegree() {
+    this.nodeDegreeMap.clear();
+    const { nodes, links } = this.data;
+    nodes.forEach((node) => this.nodeDegreeMap.set(node.id, 0));
+    links.forEach((link) => {
+      const sourceId = link.source.id;
+      const targetId = link.target.id;
+      this.nodeDegreeMap.set(
+        sourceId,
+        (this.nodeDegreeMap.get(sourceId) || 0) + 1
+      );
+      this.nodeDegreeMap.set(
+        targetId,
+        (this.nodeDegreeMap.get(targetId) || 0) + 1
+      );
+    });
+  }
+  private createLoadingOverlay(): HTMLDivElement {
+    const overlay = document.createElement("div");
+    overlay.style.cssText = `
+      position: absolute;
+      inset: 0;
+      display: none;
+      align-items: center;
+      justify-content: center;
+      background: ${this.config.backgroundColor || "#FFFFFF"};
+      z-index: 10;
+    `;
+    // Create skeleton loading structure (matching Spinning component pattern)
+    const skeletonContainer = document.createElement("div");
+    skeletonContainer.style.cssText = `
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+    `;
+    // Create circular skeleton (matching h-12 w-12 rounded-full)
+    const circle = document.createElement("div");
+    circle.style.cssText = `
+      height: 3rem;
+      width: 3rem;
+      border-radius: 9999px;
+      background-color: #CCCCCC;
+      animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+    `;
+    // Create lines container (matching space-y-2)
+    const linesContainer = document.createElement("div");
+    linesContainer.style.cssText = `
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+    `;
+    // Create first line (matching h-4 w-[250px])
+    const line1 = document.createElement("div");
+    line1.style.cssText = `
+      height: 1rem;
+      width: 250px;
+      border-radius: 0.375rem;
+      background-color: #CCCCCC;
+      animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+    `;
+    // Create second line (matching h-4 w-[200px])
+    const line2 = document.createElement("div");
+    line2.style.cssText = `
+      height: 1rem;
+      width: 200px;
+      border-radius: 0.375rem;
+      background-color: #CCCCCC;
+      animation: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+    `;
+    linesContainer.appendChild(line1);
+    linesContainer.appendChild(line2);
+    skeletonContainer.appendChild(circle);
+    skeletonContainer.appendChild(linesContainer);
+    overlay.appendChild(skeletonContainer);
+    return overlay;
+  }
+  private render() {
+    if (!this.shadowRoot) return;
+    // Create container
+    this.container = document.createElement("div");
+    this.container.style.width = "100%";
+    this.container.style.height = "100%";
+    this.container.style.position = "relative";
+    // Create loading overlay
+    this.loadingOverlay = this.createLoadingOverlay();
+    // Add styles using standalone function
+    const style = createStyles();
+    this.shadowRoot.appendChild(style);
+    this.shadowRoot.appendChild(this.container);
+    this.initGraph();
+    this.container.appendChild(this.loadingOverlay);
+  }
+  private initGraph() {
+    if (!this.container) return;
+    this.calculateNodeDegree();
+    // Initialize force-graph
+    // Cast to any for the factory call pattern, result is properly typed as ForceGraphInstance
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    this.graph = (ForceGraph as any)()(this.container)
+      .width(this.config.width || 800)
+      .height(this.config.height || 600)
+      .backgroundColor(this.config.backgroundColor || "#FFFFFF")
+      .graphData(this.data)
+      .nodeRelSize(NODE_SIZE)
+      .nodeCanvasObjectMode(() => "after")
+      .linkCanvasObjectMode(() => "after")
+      .nodeLabel((node: GraphNode) =>
+        getNodeDisplayText(node, this.config.displayTextPriority || [])
+      )
+      .linkLabel((link: GraphLink) => link.relationship)
+      .linkDirectionalArrowRelPos(1)
+      .linkDirectionalArrowLength((link: GraphLink) => {
+        if (link.source === link.target) return 0;
+        return this.config.isLinkSelected?.(link) ? 4 : 2;
+      })
+      .linkDirectionalArrowColor((link: GraphLink) => link.color)
+      .linkWidth((link: GraphLink) =>
+        this.config.isLinkSelected?.(link) ? 2 : 1
+      )
+      .linkCurvature("curve")
+      .linkVisibility("visible")
+      .nodeVisibility("visible")
+      .cooldownTicks(this.config.cooldownTicks ?? Infinity) // undefined = infinite
+      .cooldownTime(this.config.cooldownTime ?? 1000)
+      .enableNodeDrag(true)
+      .enableZoomInteraction(true)
+      .enablePanInteraction(true)
+      .onNodeClick((node: GraphNode, event: MouseEvent) => {
+        if (this.config.onNodeClick) {
+          this.config.onNodeClick(node, event);
+        }
+      })
+      .onLinkClick((link: GraphLink, event: MouseEvent) => {
+        if (this.config.onLinkClick) {
+          this.config.onLinkClick(link, event);
+        }
+      })
+      .onNodeRightClick((node: GraphNode, event: MouseEvent) => {
+        if (this.config.onNodeRightClick) {
+          this.config.onNodeRightClick(node, event);
+        }
+      })
+      .onLinkRightClick((link: GraphLink, event: MouseEvent) => {
+        if (this.config.onLinkRightClick) {
+          this.config.onLinkRightClick(link, event);
+        }
+      })
+      .onNodeHover((node: GraphNode | null) => {
+        if (this.config.onNodeHover) {
+          this.config.onNodeHover(node);
+        }
+      })
+      .onLinkHover((link: GraphLink | null) => {
+        if (this.config.onLinkHover) {
+          this.config.onLinkHover(link);
+        }
+      })
+      .onBackgroundClick((event: MouseEvent) => {
+        if (this.config.onBackgroundClick) {
+          this.config.onBackgroundClick(event);
+        }
+      })
+      .onEngineStop(() => {
+        this.handleEngineStop();
+        if (this.config.onEngineStop) {
+          this.config.onEngineStop();
+        }
+      })
+      .nodeCanvasObject((node: GraphNode, ctx: CanvasRenderingContext2D) => {
+        this.drawNode(node, ctx);
+      })
+      .linkCanvasObject((link: GraphLink, ctx: CanvasRenderingContext2D) => {
+        this.drawLink(link, ctx);
+      });
+    // Setup forces
+    this.setupForces();
+  }
+  private setupForces() {
+    const linkForce = this.graph?.d3Force("link");
+    if (!linkForce) return;
+    if (!this.graph) return;
+    // Link force with dynamic distance and strength
+    linkForce
+      .distance((link: GraphLink) => {
+        const sourceId = link.source.id;
+        const targetId = link.target.id;
+        const sourceDegree = this.nodeDegreeMap.get(sourceId) || 0;
+        const targetDegree = this.nodeDegreeMap.get(targetId) || 0;
+        const maxDegree = Math.max(sourceDegree, targetDegree);
+        if (maxDegree >= CROWDING_THRESHOLD) {
+          const extraDistance = Math.min(
+            MAX_LINK_DISTANCE - LINK_DISTANCE,
+            (maxDegree - CROWDING_THRESHOLD) * 1.5
+          );
+          return LINK_DISTANCE + extraDistance;
+        }
+        return LINK_DISTANCE;
+      })
+      .strength((link: GraphLink) => {
+        const sourceId = link.source.id;
+        const targetId = link.target.id;
+        const sourceDegree = this.nodeDegreeMap.get(sourceId) || 0;
+        const targetDegree = this.nodeDegreeMap.get(targetId) || 0;
+        const maxDegree = Math.max(sourceDegree, targetDegree);
+        if (maxDegree <= DEGREE_STRENGTH_DECAY) {
+          return LINK_STRENGTH;
+        }
+        const strengthReduction = Math.max(
+          0,
+          (maxDegree - DEGREE_STRENGTH_DECAY) / DEGREE_STRENGTH_DECAY
+        );
+        const scaledStrength =
+          MIN_LINK_STRENGTH +
+          (LINK_STRENGTH - MIN_LINK_STRENGTH) * Math.exp(-strengthReduction);
+        return Math.max(MIN_LINK_STRENGTH, scaledStrength);
+      });
+    // Collision force
+    this.graph.d3Force(
+      "collision",
+      d3
+        .forceCollide((node: GraphNode) => {
+          const degree = this.nodeDegreeMap.get(node.id) || 0;
+          return (
+            COLLISION_BASE_RADIUS + Math.sqrt(degree) * HIGH_DEGREE_PADDING
+          );
+        })
+        .strength(COLLISION_STRENGTH)
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        .iterations(2) as any
+    );
+    // Center force
+    const centerForce = this.graph.d3Force("center");
+    if (centerForce) {
+      centerForce.strength(CENTER_STRENGTH);
+    }
+    // Charge force
+    const chargeForce = this.graph.d3Force("charge");
+    if (chargeForce) {
+      chargeForce.strength(CHARGE_STRENGTH).distanceMax(300);
+    }
+  }
+  private drawNode(node: GraphNode, ctx: CanvasRenderingContext2D) {
+    if (!node.x || !node.y) {
+      node.x = 0;
+      node.y = 0;
+    }
+    ctx.lineWidth = this.config.isNodeSelected?.(node) ? 1.5 : 0.5;
+    ctx.strokeStyle = this.config.foregroundColor || "#1A1A1A";
+    ctx.beginPath();
+    ctx.arc(node.x, node.y, NODE_SIZE, 0, 2 * Math.PI, false);
+    ctx.fillStyle = node.color;
+    ctx.fill();
+    ctx.stroke();
+    // Draw text
+    ctx.fillStyle = "black";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.font = "400 2px SofiaSans";
+    let [line1, line2] = node.displayName || ["", ""];
+    if (!line1 && !line2) {
+      const text = getNodeDisplayText(
+        node,
+        this.config.displayTextPriority || []
+      );
+      const textRadius = NODE_SIZE - PADDING / 2;
+      [line1, line2] = wrapTextForCircularNode(ctx, text, textRadius);
+      node.displayName = [line1, line2];
+    }
+    const textMetrics = ctx.measureText(line1);
+    const textHeight =
+      textMetrics.actualBoundingBoxAscent +
+      textMetrics.actualBoundingBoxDescent;
+    const halfTextHeight = (textHeight / 2) * 1.5;
+    if (line1) {
+      ctx.fillText(line1, node.x, line2 ? node.y - halfTextHeight : node.y);
+    }
+    if (line2) {
+      ctx.fillText(line2, node.x, node.y + halfTextHeight);
+    }
+  }
+  private drawLink(link: GraphLink, ctx: CanvasRenderingContext2D) {
+    const start = link.source;
+    const end = link.target;
+    if (!start.x || !start.y || !end.x || !end.y) {
+      start.x = 0;
+      start.y = 0;
+      end.x = 0;
+      end.y = 0;
+    }
+    let textX;
+    let textY;
+    let angle;
+    if (start.id === end.id) {
+      const radius = NODE_SIZE * (link.curve || 0) * 6.2;
+      const angleOffset = -Math.PI / 4;
+      textX = start.x + radius * Math.cos(angleOffset);
+      textY = start.y + radius * Math.sin(angleOffset);
+      angle = -angleOffset;
+    } else {
+      const dx = end.x - start.x;
+      const dy = end.y - start.y;
+      const distance = Math.sqrt(dx * dx + dy * dy);
+      const perpX = dy / distance;
+      const perpY = -dx / distance;
+      const curvature = link.curve || 0;
+      const controlX =
+        (start.x + end.x) / 2 + perpX * curvature * distance * 1.0;
+      const controlY =
+        (start.y + end.y) / 2 + perpY * curvature * distance * 1.0;
+      const t = 0.5;
+      const oneMinusT = 1 - t;
+      textX =
+        oneMinusT * oneMinusT * start.x +
+        2 * oneMinusT * t * controlX +
+        t * t * end.x;
+      textY =
+        oneMinusT * oneMinusT * start.y +
+        2 * oneMinusT * t * controlY +
+        t * t * end.y;
+      const tangentX =
+        2 * oneMinusT * (controlX - start.x) + 2 * t * (end.x - controlX);
+      const tangentY =
+        2 * oneMinusT * (controlY - start.y) + 2 * t * (end.y - controlY);
+      angle = Math.atan2(tangentY, tangentX);
+      if (angle > Math.PI / 2) angle = -(Math.PI - angle);
+      if (angle < -Math.PI / 2) angle = -(-Math.PI - angle);
+    }
+    ctx.font = "400 2px SofiaSans";
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    let cached = this.relationshipsTextCache.get(link.relationship);
+    if (!cached) {
+      const { width, actualBoundingBoxAscent, actualBoundingBoxDescent } =
+        ctx.measureText(link.relationship);
+      cached = {
+        textWidth: width,
+        textHeight: actualBoundingBoxAscent + actualBoundingBoxDescent,
+        textAscent: actualBoundingBoxAscent,
+        textDescent: actualBoundingBoxDescent,
+      };
+      this.relationshipsTextCache.set(link.relationship, cached);
+    }
+    const { textWidth, textHeight, textAscent, textDescent } = cached;
+    ctx.save();
+    ctx.translate(textX, textY);
+    ctx.rotate(angle);
+    // Draw background
+    ctx.fillStyle = this.config.backgroundColor || "#FFFFFF";
+    const backgroundHeight = textHeight * 0.7;
+    // Move background up to align with text that appears at top of bg
+    // Use the actual text metrics to calculate proper vertical offset
+    const bgOffsetY = -(textAscent - textDescent) - 0.18;
+    ctx.fillRect(
+      -textWidth / 2,
+      -backgroundHeight / 2 + bgOffsetY,
+      textWidth,
+      backgroundHeight
+    );
+    // Draw text
+    ctx.fillStyle = this.config.foregroundColor || "#1A1A1A";
+    ctx.textBaseline = "middle";
+    ctx.fillText(link.relationship, 0, 0);
+    ctx.restore();
+  }
+  private updateLoadingState() {
+    if (!this.loadingOverlay) return;
+    if (this.config.isLoading) {
+      this.loadingOverlay.style.display = "flex";
+    } else {
+      this.loadingOverlay.style.display = "none";
+    }
+  }
+  private handleEngineStop() {
+    if (!this.graph) return;
+    // If already stopped, don't do anything
+    if (this.config.cooldownTicks === 0) return;
+    // Zoom to fit using the same logic as handleZoomToFit from utils
+    const nodeCount = this.data.nodes.length;
+    const paddingMultiplier = nodeCount < 2 ? 4 : 1;
+    this.zoomToFit(paddingMultiplier);
+    // Stop the force simulation after centering (like it was in ForceGraph.tsx)
+    setTimeout(() => {
+      if (!this.graph) return;
+      // Stop loading
+      this.config.isLoading = false;
+      this.config.onLoadingChange?.(this.config.isLoading);
+      this.updateLoadingState();
+      this.config.cooldownTicks = 0;
+      this.graph.cooldownTicks(0);
+    }, 1000);
+  }
+  private updateEventHandlers() {
+    if (!this.graph) return;
+    this.graph
+      .onNodeClick((node: GraphNode, event: MouseEvent) => {
+        if (this.config.onNodeClick) {
+          this.config.onNodeClick(node, event);
+        }
+      })
+      .onLinkClick((link: GraphLink, event: MouseEvent) => {
+        if (this.config.onLinkClick) {
+          this.config.onLinkClick(link, event);
+        }
+      })
+      .onNodeRightClick((node: GraphNode, event: MouseEvent) => {
+        if (this.config.onNodeRightClick) {
+          this.config.onNodeRightClick(node, event);
+        }
+      })
+      .onLinkRightClick((link: GraphLink, event: MouseEvent) => {
+        if (this.config.onLinkRightClick) {
+          this.config.onLinkRightClick(link, event);
+        }
+      })
+      .onNodeHover((node: GraphNode | null) => {
+        if (this.config.onNodeHover) {
+          this.config.onNodeHover(node);
+        }
+      })
+      .onLinkHover((link: GraphLink | null) => {
+        if (this.config.onLinkHover) {
+          this.config.onLinkHover(link);
+        }
+      })
+      .onBackgroundClick((event: MouseEvent) => {
+        if (this.config.onBackgroundClick) {
+          this.config.onBackgroundClick(event);
+        }
+      })
+      .onEngineStop(() => {
+        this.handleEngineStop();
+        if (this.config.onEngineStop) {
+          this.config.onEngineStop();
+        }
+      })
+      .nodeCanvasObject((node: GraphNode, ctx: CanvasRenderingContext2D) => {
+        this.drawNode(node, ctx);
+      })
+      .linkCanvasObject((link: GraphLink, ctx: CanvasRenderingContext2D) => {
+        this.drawLink(link, ctx);
+      });
+  }
+}
+// Define the custom element
+if (typeof window !== "undefined" && !customElements.get("falkordb-canvas")) {
+  customElements.define("falkordb-canvas", FalkorDBCanvas);
+}
+export default FalkorDBCanvas;

package/src/index.ts ADDED Viewed

@@ -0,0 +1,43 @@
+import FalkorDBCanvas from "./falkordb-canvas.js";
+import type React from "react";
+declare global {
+  interface HTMLElementTagNameMap {
+    "falkordb-canvas": FalkorDBCanvas;
+  }
+  namespace JSX {
+    interface IntrinsicElements {
+      "falkordb-canvas": React.DetailedHTMLProps<
+        React.HTMLAttributes<FalkorDBCanvas>,
+        FalkorDBCanvas
+      >;
+    }
+  }
+}
+// Main canvas class
+export { FalkorDBCanvas as default, FalkorDBCanvas };
+// Types
+export type {
+  ForceGraphConfig,
+  GraphNode,
+  GraphLink,
+  GraphData,
+  Node,
+  Link,
+  Data,
+  TextPriority,
+  ViewportState,
+  ForceGraphInstance,
+} from "./falkordb-canvas-types.js";
+// Utils
+export {
+  dataToGraphData,
+  graphDataToData,
+  getNodeDisplayText,
+  getNodeDisplayKey,
+  wrapTextForCircularNode,
+} from "./falkordb-canvas-utils.js";