@vkcha/svg-core 0.1.0 → 0.1.2

package/src/canvas/PanZoomCanvas.ts

@@ -0,0 +1,302 @@
+import { svgEl } from "../utils/dom";
+
+export type PanZoomState = {
+  zoom: number;
+  panX: number; // screen px
+  panY: number; // screen px
+};
+
+export type PanZoomListener = (state: Readonly<PanZoomState>) => void;
+
+export type PanZoomWheelMode = "zoom" | "pan";
+
+export type PanZoomOptions = {
+  /** Default: "pan" (current behavior). Figma/Mac trackpad feel often uses "pan". */
+  wheelMode: PanZoomWheelMode;
+  /** If true, zooming via wheel requires Ctrl/Cmd (pinch on macOS typically sets ctrlKey=true). */
+  zoomRequiresCtrlKey: boolean;
+  /** If true, panning via pointer drag requires holding Space (Figma-like). */
+  panRequiresSpaceKey: boolean;
+  /** Zoom limits. */
+  minZoom: number;
+  maxZoom: number;
+  /** Zoom speed multiplier for wheel (higher = faster). */
+  zoomSpeed: number;
+  /** If true, invert wheel direction for zoom. */
+  invertZoom: boolean;
+  /** If true, invert wheel direction for pan. */
+  invertPan: boolean;
+};
+
+export const DEFAULT_PANZOOM_OPTIONS: PanZoomOptions = {
+  wheelMode: "pan",
+  zoomRequiresCtrlKey: false,
+  panRequiresSpaceKey: false,
+  minZoom: 0.2,
+  maxZoom: 8,
+  zoomSpeed: 1,
+  invertZoom: false,
+  invertPan: false,
+};
+
+/**
+ * Minimal SVG "canvas" with pan/zoom.
+ *
+ * - Wheel: zoom around cursor
+ * - Pointer drag: pan
+ *
+ * This is intentionally tiny and standalone so the project can restart from a clean base.
+ */
+export class PanZoomCanvas {
+  readonly svg: SVGSVGElement;
+  readonly world: SVGGElement;
+
+  state: PanZoomState = { zoom: 1, panX: 0, panY: 0 };
+  options: PanZoomOptions = { ...DEFAULT_PANZOOM_OPTIONS };
+
+  private listeners = new Set<PanZoomListener>();
+  private notifyScheduled = false;
+
+  private dragPointerId: number | null = null;
+  private panStart: { panX: number; panY: number; x: number; y: number } | null = null;
+  private isSpaceDown = false;
+
+  private windowKeyDownHandler: ((e: KeyboardEvent) => void) | null = null;
+  private windowKeyUpHandler: ((e: KeyboardEvent) => void) | null = null;
+  private svgWheelHandler: ((e: WheelEvent) => void) | null = null;
+  private svgPointerDownHandler: ((e: PointerEvent) => void) | null = null;
+  private svgPointerMoveHandler: ((e: PointerEvent) => void) | null = null;
+  private svgPointerUpHandler: ((e: PointerEvent) => void) | null = null;
+  private svgPointerCancelHandler: ((e: PointerEvent) => void) | null = null;
+  private svgPointerLeaveHandler: (() => void) | null = null;
+
+  constructor(svg: SVGSVGElement, opts: Partial<PanZoomOptions> = {}) {
+    this.svg = svg;
+    this.world = svgEl("g");
+    this.world.dataset.layer = "world";
+    this.svg.replaceChildren(this.world);
+
+    this.setOptions(opts);
+
+    // Disable browser gestures on the SVG surface.
+    this.svg.style.touchAction = "none";
+    this.svg.style.userSelect = "none";
+
+    this.attach();
+    this.render();
+  }
+
+  setOptions(next: Partial<PanZoomOptions>) {
+    this.options = { ...DEFAULT_PANZOOM_OPTIONS, ...this.options, ...next };
+  }
+
+  /**
+   * Subscribe to pan/zoom state changes (event-driven, no polling).
+   *
+   * Optimized:
+   * - multiple updates within a frame are coalesced into a single notification via rAF
+   */
+  subscribe(fn: PanZoomListener): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  setState(next: Partial<PanZoomState>) {
+    const merged = { ...this.state, ...next };
+    if (
+      merged.zoom === this.state.zoom &&
+      merged.panX === this.state.panX &&
+      merged.panY === this.state.panY
+    ) {
+      return;
+    }
+
+    this.state = merged;
+    this.render();
+    this.scheduleNotify();
+  }
+
+  reset() {
+    this.setState({ zoom: 1, panX: 0, panY: 0 });
+  }
+
+  /**
+   * Clean up all event listeners and resources.
+   * Call this when the canvas is no longer needed to prevent memory leaks.
+   */
+  destroy() {
+    // Remove window listeners
+    if (this.windowKeyDownHandler) {
+      window.removeEventListener("keydown", this.windowKeyDownHandler);
+      this.windowKeyDownHandler = null;
+    }
+    if (this.windowKeyUpHandler) {
+      window.removeEventListener("keyup", this.windowKeyUpHandler);
+      this.windowKeyUpHandler = null;
+    }
+
+    // Remove SVG listeners
+    if (this.svgWheelHandler) {
+      this.svg.removeEventListener("wheel", this.svgWheelHandler);
+      this.svgWheelHandler = null;
+    }
+    if (this.svgPointerDownHandler) {
+      this.svg.removeEventListener("pointerdown", this.svgPointerDownHandler);
+      this.svgPointerDownHandler = null;
+    }
+    if (this.svgPointerMoveHandler) {
+      this.svg.removeEventListener("pointermove", this.svgPointerMoveHandler);
+      this.svgPointerMoveHandler = null;
+    }
+    if (this.svgPointerUpHandler) {
+      this.svg.removeEventListener("pointerup", this.svgPointerUpHandler);
+      this.svgPointerUpHandler = null;
+    }
+    if (this.svgPointerCancelHandler) {
+      this.svg.removeEventListener("pointercancel", this.svgPointerCancelHandler);
+      this.svgPointerCancelHandler = null;
+    }
+    if (this.svgPointerLeaveHandler) {
+      this.svg.removeEventListener("pointerleave", this.svgPointerLeaveHandler);
+      this.svgPointerLeaveHandler = null;
+    }
+
+    // Release pointer capture if active
+    if (this.dragPointerId !== null) {
+      try {
+        this.svg.releasePointerCapture(this.dragPointerId);
+      } catch {
+        // Ignore errors if pointer is already released
+      }
+      this.dragPointerId = null;
+    }
+
+    // Clear state
+    this.panStart = null;
+    this.isSpaceDown = false;
+    this.listeners.clear();
+  }
+
+  private scheduleNotify() {
+    if (this.notifyScheduled) return;
+    this.notifyScheduled = true;
+    requestAnimationFrame(() => {
+      this.notifyScheduled = false;
+      for (const fn of this.listeners) fn(this.state);
+    });
+  }
+
+  private attach() {
+    // Track Space key for "Figma-like" panning.
+    this.windowKeyDownHandler = (e: KeyboardEvent) => {
+      if (e.code === "Space") this.isSpaceDown = true;
+    };
+    this.windowKeyUpHandler = (e: KeyboardEvent) => {
+      if (e.code === "Space") this.isSpaceDown = false;
+    };
+    window.addEventListener("keydown", this.windowKeyDownHandler);
+    window.addEventListener("keyup", this.windowKeyUpHandler);
+
+    this.svgWheelHandler = (e: WheelEvent) => {
+      e.preventDefault();
+
+      const pt = this.svgPoint(e.clientX, e.clientY);
+      const { wheelMode, zoomRequiresCtrlKey, invertZoom, invertPan } = this.options;
+
+      const ctrl = e.ctrlKey || e.metaKey;
+
+      // Desired behavior:
+      // - wheelMode="zoom" (default): wheel zooms. If zoomRequiresCtrlKey=true, only zoom when ctrl/cmd is pressed.
+      // - wheelMode="pan": wheel pans by default. ctrl/cmd (pinch gesture on macOS) zooms instead.
+      if (wheelMode === "pan" && !ctrl) {
+        const k = invertPan ? -1 : 1;
+        this.setState({
+          panX: this.state.panX - e.deltaX * k,
+          panY: this.state.panY - e.deltaY * k,
+        });
+        return;
+      }
+
+      if (wheelMode === "zoom" && zoomRequiresCtrlKey && !ctrl) {
+        return;
+      }
+
+      const worldBefore = this.screenToWorld(pt.x, pt.y);
+      const dy = invertZoom ? -e.deltaY : e.deltaY;
+      const zoomFactor = Math.exp(-dy * 0.001 * this.options.zoomSpeed);
+      const nextZoom = clamp(
+        this.state.zoom * zoomFactor,
+        this.options.minZoom,
+        this.options.maxZoom,
+      );
+
+      // Keep world point under cursor stable:
+      // screen = world * zoom + pan  =>  pan = screen - world * zoom
+      const nextPanX = pt.x - worldBefore.x * nextZoom;
+      const nextPanY = pt.y - worldBefore.y * nextZoom;
+
+      this.setState({ zoom: nextZoom, panX: nextPanX, panY: nextPanY });
+    };
+    this.svg.addEventListener("wheel", this.svgWheelHandler, { passive: false });
+
+    this.svgPointerDownHandler = (e: PointerEvent) => {
+      if (this.dragPointerId !== null) return;
+      if (this.options.panRequiresSpaceKey && !this.isSpaceDown) return;
+      this.dragPointerId = e.pointerId;
+      this.svg.setPointerCapture(e.pointerId);
+
+      const pt = this.svgPoint(e.clientX, e.clientY);
+      this.panStart = { panX: this.state.panX, panY: this.state.panY, x: pt.x, y: pt.y };
+    };
+    this.svg.addEventListener("pointerdown", this.svgPointerDownHandler);
+
+    this.svgPointerMoveHandler = (e: PointerEvent) => {
+      if (this.dragPointerId === null) return;
+      if (e.pointerId !== this.dragPointerId) return;
+      if (!this.panStart) return;
+
+      const pt = this.svgPoint(e.clientX, e.clientY);
+      const dx = pt.x - this.panStart.x;
+      const dy = pt.y - this.panStart.y;
+      this.setState({ panX: this.panStart.panX + dx, panY: this.panStart.panY + dy });
+    };
+    this.svg.addEventListener("pointermove", this.svgPointerMoveHandler);
+
+    const end = (e: PointerEvent) => {
+      if (this.dragPointerId === null) return;
+      if (e.pointerId !== this.dragPointerId) return;
+      this.dragPointerId = null;
+      this.panStart = null;
+    };
+
+    this.svgPointerUpHandler = end;
+    this.svgPointerCancelHandler = end;
+    this.svgPointerLeaveHandler = () => {
+      this.dragPointerId = null;
+      this.panStart = null;
+    };
+
+    this.svg.addEventListener("pointerup", this.svgPointerUpHandler);
+    this.svg.addEventListener("pointercancel", this.svgPointerCancelHandler);
+    this.svg.addEventListener("pointerleave", this.svgPointerLeaveHandler);
+  }
+
+  private render() {
+    const { zoom, panX, panY } = this.state;
+    this.world.setAttribute("transform", `matrix(${zoom} 0 0 ${zoom} ${panX} ${panY})`);
+  }
+
+  private svgPoint(clientX: number, clientY: number) {
+    const r = this.svg.getBoundingClientRect();
+    return { x: clientX - r.left, y: clientY - r.top };
+  }
+
+  private screenToWorld(x: number, y: number) {
+    const { zoom, panX, panY } = this.state;
+    return { x: (x - panX) / zoom, y: (y - panY) / zoom };
+  }
+}
+
+function clamp(v: number, min: number, max: number) {
+  return Math.max(min, Math.min(max, v));
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { SvgCore } from "./SvgCore";
+export type { CullingOptions, CullingStats, InitOptions } from "./SvgCore";
+
+export { PanZoomCanvas } from "./canvas/PanZoomCanvas";
+export type { PanZoomOptions, PanZoomState, PanZoomWheelMode } from "./canvas/PanZoomCanvas";
+
+export { Node } from "./scene/Node";
+export type { NodeId, NodeOptions } from "./scene/Node";
+
+export { measureFragmentMetrics } from "./scene/fragment";
+export type { FragmentMetrics } from "./scene/fragment";

package/src/scene/Node.ts

@@ -0,0 +1,66 @@
+export type NodeId = string;
+
+export type NodeOptions = {
+  /** Required unique id for the node. Used for selective redraw and removal. */
+  id: NodeId;
+  /** SVG fragment markup (no outer <svg> wrapper). */
+  fragment: string;
+  /** World-space position (top-left of the node bounds). Default: (0, 0). */
+  x?: number;
+  y?: number;
+  /**
+   * Optional explicit node bounds (in world units). If omitted, the core may derive
+   * bounds from the fragment's measured bbox.
+   */
+  width?: number;
+  height?: number;
+  /** Optional UI callbacks (hit-tested by the core on the root SVG). */
+  onClick?: (node: Node) => void;
+  onDoubleClick?: (node: Node) => void;
+  onRightClick?: (node: Node) => void;
+};
+
+/**
+ * A scene-graph "node" for the SVG core.
+ */
+export class Node {
+  readonly id: NodeId;
+  fragment: string;
+  x: number;
+  y: number;
+  width: number | null;
+  height: number | null;
+  onClick?: NodeOptions["onClick"];
+  onDoubleClick?: NodeOptions["onDoubleClick"];
+  onRightClick?: NodeOptions["onRightClick"];
+
+  /** Backing element (created lazily by the core). */
+  private _el: SVGGElement | null = null;
+
+  constructor(opts: NodeOptions) {
+    if (!opts || typeof opts.id !== "string" || opts.id === "") {
+      throw new Error("Node requires a non-empty 'id' property");
+    }
+    this.id = opts.id;
+    this.fragment = opts.fragment ?? "";
+    this.x = Number.isFinite(opts?.x) ? (opts?.x as number) : 0;
+    this.y = Number.isFinite(opts?.y) ? (opts?.y as number) : 0;
+    const w = opts?.width;
+    const h = opts?.height;
+    this.width = typeof w === "number" && Number.isFinite(w) && w > 0 ? w : null;
+    this.height = typeof h === "number" && Number.isFinite(h) && h > 0 ? h : null;
+
+    this.onClick = opts?.onClick;
+    this.onDoubleClick = opts?.onDoubleClick;
+    this.onRightClick = opts?.onRightClick;
+  }
+
+  get el(): SVGGElement {
+    if (!this._el) {
+      const el = document.createElementNS("http://www.w3.org/2000/svg", "g");
+      el.dataset.nodeId = this.id;
+      this._el = el;
+    }
+    return this._el;
+  }
+}

package/src/scene/fragment.ts

@@ -0,0 +1,146 @@
+type BBox = { x: number; y: number; width: number; height: number };
+export type FragmentMetrics = { bbox: BBox; pad: number };
+
+// Cache fragment -> metrics so we only measure when the fragment changes.
+const metricsCache = new Map<string, FragmentMetrics>();
+
+let measureSvg: SVGSVGElement | null = null;
+let measureG: SVGGElement | null = null;
+
+function ensureMeasureDom(): { svg: SVGSVGElement; g: SVGGElement } {
+  if (measureSvg && measureG) return { svg: measureSvg, g: measureG };
+
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("width", "0");
+  svg.setAttribute("height", "0");
+  svg.style.position = "absolute";
+  svg.style.left = "-10000px";
+  svg.style.top = "-10000px";
+  svg.style.visibility = "hidden";
+  svg.style.pointerEvents = "none";
+
+  const g = document.createElementNS("http://www.w3.org/2000/svg", "g");
+  svg.appendChild(g);
+
+  measureSvg = svg;
+  measureG = g;
+  return { svg, g };
+}
+
+function attachMeasureDom(svg: SVGSVGElement) {
+  // getBBox() requires the element to be in the document.
+  if (!svg.isConnected) document.body.appendChild(svg);
+}
+
+function detachMeasureDom(svg: SVGSVGElement) {
+  // Avoid leaving hidden measurement DOM nodes around permanently.
+  if (svg.isConnected) svg.remove();
+}
+
+function stripXmlnsDeep(el: Element) {
+  // Remove redundant XML namespace declarations from fragments inserted into an existing <svg>.
+  if (el.hasAttribute("xmlns")) el.removeAttribute("xmlns");
+  for (const attr of Array.from(el.attributes)) {
+    if (attr.name.startsWith("xmlns:")) el.removeAttribute(attr.name);
+  }
+  for (const child of Array.from(el.children)) stripXmlnsDeep(child);
+}
+
+export function sanitizeFragment(markup: string): string {
+  const s = markup.trim();
+  if (!s) return "";
+  const wrapped = `<svg xmlns="http://www.w3.org/2000/svg">${s}</svg>`;
+  try {
+    const doc = new DOMParser().parseFromString(wrapped, "image/svg+xml");
+    const svg = doc.documentElement as unknown as SVGSVGElement;
+    if (!svg || svg.nodeName.toLowerCase() !== "svg") return "";
+
+    doc.querySelectorAll("script, foreignObject").forEach((n) => n.remove());
+    doc.querySelectorAll("*").forEach((el) => {
+      for (const attr of Array.from(el.attributes)) {
+        if (attr.name.toLowerCase().startsWith("on")) el.removeAttribute(attr.name);
+        // We insert fragments into an existing <svg>, so explicit xmlns declarations are redundant.
+        if (attr.name === "xmlns" || attr.name.startsWith("xmlns:")) el.removeAttribute(attr.name);
+      }
+    });
+
+    // Prefer innerHTML to avoid browsers sprinkling xmlns="..." on every serialized element.
+    const inner = (svg as any).innerHTML as string | undefined;
+    if (typeof inner === "string") return inner.trim();
+    return new XMLSerializer()
+      .serializeToString(svg)
+      .replace(/^<svg[^>]*>|<\/svg>$/g, "")
+      .trim();
+  } catch {
+    return "";
+  }
+}
+
+export function parseFragmentElements(markup: string): Element[] {
+  const s = markup.trim();
+  if (!s) return [];
+  const wrapped = `<svg xmlns="http://www.w3.org/2000/svg">${s}</svg>`;
+  try {
+    const doc = new DOMParser().parseFromString(wrapped, "image/svg+xml");
+    const svg = doc.documentElement as unknown as SVGSVGElement;
+    if (!svg || svg.nodeName.toLowerCase() !== "svg") return [];
+
+    // Sanitize in DOM (no string re-serialization for canvas nodes).
+    doc.querySelectorAll("script, foreignObject").forEach((n) => n.remove());
+    doc.querySelectorAll("*").forEach((el) => {
+      for (const attr of Array.from(el.attributes)) {
+        if (attr.name.toLowerCase().startsWith("on")) el.removeAttribute(attr.name);
+        if (attr.name === "xmlns" || attr.name.startsWith("xmlns:")) el.removeAttribute(attr.name);
+      }
+    });
+
+    // Import into the live document so we don't carry XML serializer artifacts (like xmlns on every node).
+    const imported = Array.from(svg.children).map((el) => document.importNode(el, true) as Element);
+    for (const el of imported) stripXmlnsDeep(el);
+    return imported;
+  } catch {
+    return [];
+  }
+}
+
+export function measureFragmentMetrics(markup: string): FragmentMetrics | null {
+  const key = sanitizeFragment(markup);
+  if (!key) return null;
+  const cached = metricsCache.get(key);
+  if (cached) return cached;
+
+  const { svg, g } = ensureMeasureDom();
+  attachMeasureDom(svg);
+  g.replaceChildren();
+
+  const els = parseFragmentElements(key);
+  for (const el of els) g.appendChild(el.cloneNode(true));
+
+  try {
+    const b = g.getBBox();
+    // getBBox() does NOT include stroke, so compute a padding based on computed stroke-width.
+    let maxStrokeWidth = 0;
+    g.querySelectorAll("*").forEach((node) => {
+      try {
+        const cs = getComputedStyle(node as any);
+        const stroke = (cs as any).stroke as string | undefined;
+        if (!stroke || stroke === "none" || stroke === "transparent") return;
+        const sw = Number.parseFloat(((cs as any).strokeWidth as string | undefined) ?? "0");
+        if (Number.isFinite(sw) && sw > maxStrokeWidth) maxStrokeWidth = sw;
+      } catch {
+        // ignore
+      }
+    });
+    const pad = Math.max(0, maxStrokeWidth / 2);
+
+    const bbox = { x: b.x, y: b.y, width: b.width, height: b.height };
+    const metrics = { bbox, pad };
+    metricsCache.set(key, metrics);
+    return metrics;
+  } catch {
+    return null;
+  } finally {
+    // Detach measurement DOM even when getBBox throws.
+    detachMeasureDom(svg);
+  }
+}

package/src/utils/dom.ts

@@ -0,0 +1,17 @@
+export function svgEl<K extends keyof SVGElementTagNameMap>(
+  tag: K,
+  attrs: Record<string, string> = {}
+): SVGElementTagNameMap[K] {
+  const el = document.createElementNS("http://www.w3.org/2000/svg", tag);
+  for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+  return el;
+}
+
+export function setSvgAttrs(el: Element, attrs: Record<string, string | number | null | undefined>) {
+  for (const [k, v] of Object.entries(attrs)) {
+    if (v === null || v === undefined) el.removeAttribute(k);
+    else el.setAttribute(k, String(v));
+  }
+}
+
+