@vkcha/svg-core 0.1.0 → 0.1.2

package/src/SvgCore.ts

@@ -0,0 +1,623 @@
+import type { PanZoomListener, PanZoomOptions, PanZoomState } from "./canvas/PanZoomCanvas";
+import { PanZoomCanvas } from "./canvas/PanZoomCanvas";
+import type { Node } from "./scene/Node";
+import { measureFragmentMetrics, parseFragmentElements, sanitizeFragment } from "./scene/fragment";
+
+export type CullingStats = {
+  visible: number;
+  hidden: number;
+  total: number;
+};
+
+export type CullingOptions = {
+  /** Default: true */
+  enabled?: boolean;
+  /** Default: 30 */
+  overscanPx?: number;
+};
+
+export type InitOptions = {
+  panZoom?: Partial<PanZoomOptions>;
+  culling?: boolean | CullingOptions;
+};
+
+/**
+ * SvgCore entrypoint.
+ *
+ * Usage:
+ *   const v = new SvgCore(svgElement)
+ */
+export class SvgCore {
+  private canvas: PanZoomCanvas;
+  private nodesLayer: SVGGElement;
+
+  private nodes: Node[] = [];
+  private nodeIdToIndex = new Map<string, number>();
+  private nodeBounds: Array<{
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+  }> | null = null;
+
+  private cullingEnabled = true;
+  private cullingOverscanPx = 30;
+  private resizeObserver: ResizeObserver | null = null;
+  private unsubPanZoom: (() => void) | null = null;
+  private unsubSvgEvents: (() => void) | null = null;
+  private svgClickTimer: number | null = null;
+  private suppressNextClick = false;
+  private dragWatch: {
+    pointerId: number;
+    startClientX: number;
+    startClientY: number;
+    moved: boolean;
+  } | null = null;
+
+  private cullingListeners = new Set<(stats: Readonly<CullingStats>) => void>();
+  private lastCullingStats: CullingStats = { visible: 0, hidden: 0, total: 0 };
+  private cullingNotifyScheduled = false;
+
+  /** SVG root passed to the constructor. */
+  get svg(): SVGSVGElement {
+    return this.canvas.svg;
+  }
+
+  /** World layer (<g>) that you draw into. */
+  get world(): SVGGElement {
+    return this.canvas.world;
+  }
+
+  /** Current pan/zoom state. */
+  get state(): PanZoomState {
+    return this.canvas.state;
+  }
+
+  /** Current pan/zoom options (includes minZoom/maxZoom). */
+  get panZoomOptions(): Readonly<PanZoomOptions> {
+    return this.canvas.options;
+  }
+
+  constructor(svg: SVGSVGElement, opts?: InitOptions) {
+    this.canvas = new PanZoomCanvas(svg, opts?.panZoom);
+
+    this.nodesLayer = document.createElementNS("http://www.w3.org/2000/svg", "g");
+    this.nodesLayer.dataset.layer = "nodes";
+    this.world.appendChild(this.nodesLayer);
+    this.world.style.pointerEvents = "none";
+
+    const c = opts?.culling;
+    if (typeof c === "boolean") {
+      this.cullingEnabled = c;
+    } else if (c) {
+      if (typeof c.enabled === "boolean") this.cullingEnabled = c.enabled;
+      if (typeof c.overscanPx === "number") this.cullingOverscanPx = Math.max(0, c.overscanPx);
+    }
+
+    // Core-owned: keep culling in sync with pan/zoom changes.
+    this.unsubPanZoom = this.canvas.subscribe(() => this.applyCulling());
+
+    // Core-owned: keep culling correct when viewport size changes.
+    this.resizeObserver = new ResizeObserver(() => this.applyCulling());
+    this.resizeObserver.observe(this.svg);
+
+    // Core-owned: basic SVG interaction events (for now just log).
+    // Notes:
+    // - Drag-to-pan emits a "click" after pointerup; we suppress that when movement exceeds a threshold.
+    // - We do NOT use the native "dblclick" event. Instead:
+    //   - 1st click starts a short timer
+    //   - 2nd click within that window becomes "doubleclick" and cancels the pending single-click
+    const CLICK_DELAY_MS = 300;
+    const DRAG_THRESHOLD_PX = 5;
+
+    const clearClickTimer = () => {
+      if (this.svgClickTimer !== null) {
+        window.clearTimeout(this.svgClickTimer);
+        this.svgClickTimer = null;
+      }
+    };
+
+    const onPointerDown = (e: PointerEvent) => {
+      // Only track left-button drags for click suppression.
+      if (e.button !== 0) return;
+      this.dragWatch = {
+        pointerId: e.pointerId,
+        startClientX: e.clientX,
+        startClientY: e.clientY,
+        moved: false,
+      };
+    };
+
+    const onPointerMove = (e: PointerEvent) => {
+      const w = this.dragWatch;
+      if (!w) return;
+      if (e.pointerId !== w.pointerId) return;
+      // Only while left button is held.
+      if ((e.buttons & 1) !== 1) return;
+
+      const dx = e.clientX - w.startClientX;
+      const dy = e.clientY - w.startClientY;
+      if (!w.moved && Math.hypot(dx, dy) >= DRAG_THRESHOLD_PX) w.moved = true;
+    };
+
+    const onPointerEnd = (e: PointerEvent) => {
+      const w = this.dragWatch;
+      if (!w) return;
+      if (e.pointerId !== w.pointerId) return;
+      this.dragWatch = null;
+      if (w.moved) {
+        this.suppressNextClick = true;
+        clearClickTimer();
+      }
+    };
+
+    const onClick = (e: MouseEvent) => {
+      if (this.suppressNextClick) {
+        this.suppressNextClick = false;
+        return;
+      }
+      if (this.svgClickTimer !== null) {
+        // Second click within the window => treat as "doubleclick".
+        clearClickTimer();
+        const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+        if (hit?.onDoubleClick) {
+          hit.onDoubleClick(hit);
+        }
+        return;
+      }
+      // First click => delay, so a potential second click can convert it to "doubleclick".
+      this.svgClickTimer = window.setTimeout(() => {
+        this.svgClickTimer = null;
+        const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+        if (hit?.onClick) {
+          hit.onClick(hit);
+        }
+      }, CLICK_DELAY_MS);
+    };
+
+    const onRightClick = (e: MouseEvent) => {
+      e.preventDefault(); // treat this as "rightclick" without opening the context menu
+      clearClickTimer();
+      const hit = this.hitTestVisibleNodeAtClient(e.clientX, e.clientY);
+      if (hit?.onRightClick) {
+        hit.onRightClick(hit);
+      }
+    };
+
+    this.svg.addEventListener("click", onClick);
+    this.svg.addEventListener("contextmenu", onRightClick);
+    this.svg.addEventListener("pointerdown", onPointerDown);
+    this.svg.addEventListener("pointermove", onPointerMove);
+    this.svg.addEventListener("pointerup", onPointerEnd);
+    this.svg.addEventListener("pointercancel", onPointerEnd);
+    this.unsubSvgEvents = () => {
+      this.svg.removeEventListener("click", onClick);
+      this.svg.removeEventListener("contextmenu", onRightClick);
+      this.svg.removeEventListener("pointerdown", onPointerDown);
+      this.svg.removeEventListener("pointermove", onPointerMove);
+      this.svg.removeEventListener("pointerup", onPointerEnd);
+      this.svg.removeEventListener("pointercancel", onPointerEnd);
+      clearClickTimer();
+    };
+  }
+
+  /**
+   * Set zoom while keeping a chosen screen-space anchor stable.
+   * By default anchors at the viewport center.
+   */
+  setZoom(nextZoom: number, anchor?: { x: number; y: number }) {
+    const minZ = this.canvas.options.minZoom;
+    const maxZ = this.canvas.options.maxZoom;
+    const z = Math.min(maxZ, Math.max(minZ, nextZoom));
+
+    const r = this.svg.getBoundingClientRect();
+    const ax = anchor?.x ?? Math.max(1, r.width) / 2;
+    const ay = anchor?.y ?? Math.max(1, r.height) / 2;
+
+    const cur = this.state;
+    // screen = world * zoom + pan  => world = (screen - pan) / zoom
+    const worldX = (ax - cur.panX) / Math.max(1e-9, cur.zoom);
+    const worldY = (ay - cur.panY) / Math.max(1e-9, cur.zoom);
+
+    // keep world point under anchor stable:
+    // pan = screen - world * zoom
+    const nextPanX = ax - worldX * z;
+    const nextPanY = ay - worldY * z;
+
+    this.setState({ zoom: z, panX: nextPanX, panY: nextPanY });
+  }
+
+  /**
+   * Convert a pointer position (client px) into canvas/world coordinates,
+   * using the current pan/zoom state.
+   */
+  clientToCanvas(clientX: number, clientY: number): { x: number; y: number } {
+    const r = this.svg.getBoundingClientRect();
+    const sx = clientX - r.left;
+    const sy = clientY - r.top;
+    const { panX, panY, zoom } = this.state;
+    const z = Math.max(1e-9, zoom);
+    return { x: (sx - panX) / z, y: (sy - panY) / z };
+  }
+
+  /**
+   * Fast hit-test using the culling output: only checks nodes currently attached to `nodesLayer`
+   * (i.e. the visible subset after culling).
+   *
+   * Returns the topmost hit node (based on render order), or null.
+   */
+  hitTestVisibleNodeAtClient(clientX: number, clientY: number): Node | null {
+    if (!this.nodeBounds || this.nodes.length === 0) return null;
+    const p = this.clientToCanvas(clientX, clientY);
+    const kids = this.nodesLayer.children;
+    // Scan from topmost to bottommost: last child is visually on top.
+    for (let k = kids.length - 1; k >= 0; k--) {
+      const el = kids.item(k) as SVGGElement | null;
+      if (!el) continue;
+      const id = el.dataset.nodeId;
+      if (!id) continue;
+      const idx = this.nodeIdToIndex.get(id);
+      if (idx === undefined) continue;
+      const b = this.nodeBounds[idx];
+      if (!b) continue;
+      if (p.x >= b.x0 && p.x <= b.x1 && p.y >= b.y0 && p.y <= b.y1) return this.nodes[idx];
+    }
+    return null;
+  }
+
+  zoomBy(factor: number, anchor?: { x: number; y: number }) {
+    const f = Number.isFinite(factor) ? factor : 1;
+    if (f <= 0) return;
+    this.setZoom(this.state.zoom * f, anchor);
+  }
+
+  setState(next: Partial<PanZoomState>) {
+    this.canvas.setState(next);
+  }
+
+  resetView() {
+    this.canvas.reset();
+  }
+
+  configurePanZoom(opts: Partial<PanZoomOptions>) {
+    this.canvas.setOptions(opts);
+  }
+
+  setNodes(nodes: Node[]) {
+    // Warn if node IDs are not unique
+    const seenIds = new Set<string>();
+    const duplicateIds = new Set<string>();
+    for (let i = 0; i < nodes.length; i++) {
+      const id = nodes[i].id;
+      if (seenIds.has(id)) {
+        duplicateIds.add(id);
+      } else {
+        seenIds.add(id);
+      }
+    }
+    if (duplicateIds.size > 0) {
+      console.warn(
+        `Duplicate node ids found: ${Array.from(duplicateIds)
+          .map((id) => `"${id}"`)
+          .join(", ")}. Each node should have a unique id.`,
+      );
+    }
+
+    this.nodes = nodes;
+    this.nodeIdToIndex.clear();
+    // Build map of node id to index for fast lookup.
+    // Note: If there are duplicate IDs, the last occurrence will overwrite previous ones.
+    for (let i = 0; i < nodes.length; i++) {
+      this.nodeIdToIndex.set(nodes[i].id, i);
+    }
+    this.redraw();
+  }
+
+  /**
+   * Redraw the currently assigned nodes.
+   *
+   * Call this if you mutate node properties in-place (e.g. `node.x = ...` or `node.fragment = ...`).
+   *
+   * @param ids Optional array of node ids to redraw. If provided, only these nodes will be redrawn.
+   *            If not provided, all nodes will be redrawn.
+   */
+  redraw(ids?: string[]) {
+    if (Array.isArray(ids) && ids.length > 0) {
+      this.renderNodes(ids);
+      // After selective render, we still need to apply culling to all nodes
+      this.applyCulling();
+    } else {
+      this.renderNodes();
+      this.applyCulling();
+    }
+  }
+
+  setCullingEnabled(enabled: boolean) {
+    this.cullingEnabled = enabled;
+    this.applyCulling();
+  }
+
+  setCullingOverscanPx(px: number) {
+    this.cullingOverscanPx = Math.max(0, px);
+    this.applyCulling();
+  }
+
+  /** Subscribe to culling stats updates (event-driven). */
+  onCullingStatsChange(fn: (stats: Readonly<CullingStats>) => void): () => void {
+    this.cullingListeners.add(fn);
+    fn(this.lastCullingStats);
+    return () => this.cullingListeners.delete(fn);
+  }
+
+  /** Subscribe to pan/zoom updates (event-driven). */
+  onPanZoomChange(fn: PanZoomListener): () => void {
+    return this.canvas.subscribe(fn);
+  }
+
+  /**
+   * Remove nodes from the scene.
+   *
+   * @param ids Optional array of node ids to remove. If not provided, removes all nodes.
+   */
+  remove(ids?: string[]) {
+    if (!ids || ids.length === 0) {
+      // Remove all nodes
+      this.nodes = [];
+      this.nodeIdToIndex.clear();
+      this.nodesLayer.replaceChildren();
+      this.nodeBounds = null;
+      this.setCullingStats({ visible: 0, hidden: 0, total: 0 });
+      return;
+    }
+
+    // Remove specific nodes by ids
+    const indicesToRemove = new Set<number>();
+
+    for (const id of ids) {
+      const idx = this.nodeIdToIndex.get(id);
+      if (idx !== undefined) {
+        indicesToRemove.add(idx);
+      }
+    }
+
+    if (indicesToRemove.size === 0) return;
+
+    // Remove nodes in reverse order to maintain indices
+    const sortedIndices = Array.from(indicesToRemove).sort((a, b) => b - a);
+    for (const idx of sortedIndices) {
+      const node = this.nodes[idx];
+      if (node) {
+        // Remove from DOM
+        if (node.el.parentElement) {
+          node.el.remove();
+        }
+        // Remove from map
+        this.nodeIdToIndex.delete(node.id);
+      }
+      this.nodes.splice(idx, 1);
+    }
+
+    // Rebuild index map
+    this.nodeIdToIndex.clear();
+    for (let i = 0; i < this.nodes.length; i++) {
+      this.nodeIdToIndex.set(this.nodes[i].id, i);
+    }
+
+    // Rebuild bounds array
+    if (this.nodeBounds) {
+      const newBounds: Array<{ x0: number; y0: number; x1: number; y1: number }> = [];
+      for (let i = 0; i < this.nodes.length; i++) {
+        const node = this.nodes[i];
+        const metrics = measureFragmentMetrics(node.fragment);
+        const bbox = metrics?.bbox ?? { x: 0, y: 0, width: 240, height: 160 };
+        const pad = metrics?.pad ?? 0;
+        const w = node.width ?? Math.max(1, bbox.width + pad * 2);
+        const h = node.height ?? Math.max(1, bbox.height + pad * 2);
+        newBounds.push({ x0: node.x, y0: node.y, x1: node.x + w, y1: node.y + h });
+      }
+      this.nodeBounds = newBounds;
+    }
+
+    this.applyCulling();
+  }
+
+  destroy() {
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+    this.unsubPanZoom?.();
+    this.unsubPanZoom = null;
+    this.unsubSvgEvents?.();
+    this.unsubSvgEvents = null;
+    this.cullingListeners.clear();
+    this.canvas.destroy();
+  }
+
+  private renderNodes(ids?: string[]) {
+    // If ids are provided, only update those specific nodes
+    if (ids && ids.length > 0) {
+      for (const id of ids) {
+        const idx = this.nodeIdToIndex.get(id);
+        if (idx === undefined) continue;
+        const node = this.nodes[idx];
+        if (!node) continue;
+
+        const g = node.el;
+        g.replaceChildren();
+        g.setAttribute("transform", `translate(${node.x} ${node.y})`);
+
+        const cleaned = sanitizeFragment(node.fragment);
+        if (cleaned) {
+          const children = parseFragmentElements(cleaned);
+          const metrics = measureFragmentMetrics(cleaned);
+          const bbox = metrics?.bbox ?? { x: 0, y: 0, width: 240, height: 160 };
+          const pad = metrics?.pad ?? 0;
+          const w = Math.max(1, bbox.width + pad * 2);
+          const h = Math.max(1, bbox.height + pad * 2);
+          const offsetX = -bbox.x + pad;
+          const offsetY = -bbox.y + pad;
+
+          const inner = document.createElementNS("http://www.w3.org/2000/svg", "g");
+          inner.setAttribute("transform", `translate(${offsetX} ${offsetY})`);
+          for (const child of children) inner.appendChild(child.cloneNode(true));
+          g.appendChild(inner);
+
+          // Update bounds
+          if (this.nodeBounds) {
+            const nodeW = node.width ?? w;
+            const nodeH = node.height ?? h;
+            this.nodeBounds[idx] = {
+              x0: node.x,
+              y0: node.y,
+              x1: node.x + nodeW,
+              y1: node.y + nodeH,
+            };
+          }
+        }
+
+        // Ensure node is attached if it's not already
+        if (!g.parentElement) {
+          this.nodesLayer.appendChild(g);
+        }
+      }
+      return; // Culling will be applied by redraw()
+    }
+
+    // Full render: clear and rebuild everything
+    this.nodesLayer.replaceChildren();
+    this.nodeBounds = null;
+    if (this.nodes.length === 0) return;
+
+    // Cache fragment -> parsed children and metrics.
+    // This allows each node to carry its own fragment while still keeping render fast.
+    const fragmentCache = new Map<
+      string,
+      {
+        children: Element[];
+        w: number;
+        h: number;
+        offsetX: number;
+        offsetY: number;
+      }
+    >();
+
+    for (const node of this.nodes) {
+      const cleaned = sanitizeFragment(node.fragment);
+      if (!cleaned) continue;
+      if (fragmentCache.has(cleaned)) continue;
+      const children = parseFragmentElements(cleaned);
+      const metrics = measureFragmentMetrics(cleaned);
+      const bbox = metrics?.bbox ?? { x: 0, y: 0, width: 240, height: 160 };
+      const pad = metrics?.pad ?? 0;
+      const w = Math.max(1, bbox.width + pad * 2);
+      const h = Math.max(1, bbox.height + pad * 2);
+      // Normalize fragment so its bbox starts at (0,0) with padding applied.
+      const offsetX = -bbox.x + pad;
+      const offsetY = -bbox.y + pad;
+      fragmentCache.set(cleaned, { children, w, h, offsetX, offsetY });
+    }
+
+    const count = this.nodes.length;
+
+    const frag = document.createDocumentFragment();
+    const bounds: Array<{ x0: number; y0: number; x1: number; y1: number }> = new Array(count);
+    for (let i = 0; i < count; i++) {
+      const node = this.nodes[i];
+      const g = node.el;
+      g.replaceChildren();
+      g.setAttribute("transform", `translate(${node.x} ${node.y})`);
+      const cleaned = sanitizeFragment(node.fragment);
+      const cached = cleaned ? fragmentCache.get(cleaned) : null;
+      if (cached) {
+        // Insert the fragment content directly into the node group (no nested <svg>),
+        // but normalize it to (0,0) using a wrapper group.
+        const inner = document.createElementNS("http://www.w3.org/2000/svg", "g");
+        inner.setAttribute("transform", `translate(${cached.offsetX} ${cached.offsetY})`);
+        for (const child of cached.children) inner.appendChild(child.cloneNode(true));
+        g.appendChild(inner);
+      }
+      const w = node.width ?? cached?.w ?? 240;
+      const h = node.height ?? cached?.h ?? 160;
+      bounds[i] = { x0: node.x, y0: node.y, x1: node.x + w, y1: node.y + h };
+      frag.appendChild(g);
+    }
+    this.nodesLayer.appendChild(frag);
+    this.nodeBounds = bounds;
+  }
+
+  private applyCulling() {
+    if (!this.nodeBounds) {
+      this.setCullingStats({ visible: 0, hidden: 0, total: this.nodes.length });
+      return;
+    }
+    const count = this.nodes.length;
+
+    // If disabled, ensure everything is visible/attached.
+    if (!this.cullingEnabled) {
+      this.nodesLayer.replaceChildren(...this.nodes.map((n) => n.el));
+      for (const n of this.nodes) n.el.removeAttribute("display");
+      this.setCullingStats({ visible: count, hidden: 0, total: count });
+      return;
+    }
+
+    const vp = this.getWorldViewport(this.state, this.cullingOverscanPx);
+    const visibleNodes: SVGGElement[] = [];
+    for (let i = 0; i < count; i++) {
+      const rect = this.nodeBounds[i];
+      if (rect && this.rectsIntersect(rect, vp)) {
+        const el = this.nodes[i].el;
+        el.removeAttribute("display");
+        visibleNodes.push(el);
+      }
+    }
+    this.nodesLayer.replaceChildren(...visibleNodes);
+    this.setCullingStats({
+      visible: visibleNodes.length,
+      hidden: count - visibleNodes.length,
+      total: count,
+    });
+  }
+
+  private setCullingStats(next: CullingStats) {
+    const prev = this.lastCullingStats;
+    if (prev.visible === next.visible && prev.hidden === next.hidden && prev.total === next.total)
+      return;
+    this.lastCullingStats = next;
+    this.scheduleCullingNotify();
+  }
+
+  private scheduleCullingNotify() {
+    if (this.cullingNotifyScheduled) return;
+    this.cullingNotifyScheduled = true;
+    requestAnimationFrame(() => {
+      this.cullingNotifyScheduled = false;
+      for (const fn of this.cullingListeners) fn(this.lastCullingStats);
+    });
+  }
+
+  private rectsIntersect(
+    a: { x0: number; y0: number; x1: number; y1: number },
+    b: {
+      x0: number;
+      y0: number;
+      x1: number;
+      y1: number;
+    },
+  ) {
+    return !(a.x1 < b.x0 || a.x0 > b.x1 || a.y1 < b.y0 || a.y0 > b.y1);
+  }
+
+  private getWorldViewport(s: PanZoomState, overscanPx: number) {
+    const r = this.svg.getBoundingClientRect();
+    const w = Math.max(1, r.width);
+    const h = Math.max(1, r.height);
+    const z = Math.max(1e-9, s.zoom);
+
+    // screen = world * zoom + pan
+    const o = Math.max(0, overscanPx) / z; // expand in world units
+    const x0 = -s.panX / z - o;
+    const y0 = -s.panY / z - o;
+    const x1 = (w - s.panX) / z + o;
+    const y1 = (h - s.panY) / z + o;
+    return { x0, y0, x1, y1 };
+  }
+}